mirror of
https://github.com/RobTillaart/Arduino.git
synced 2024-10-03 18:09:02 -04:00
174 lines
7.1 KiB
Markdown
174 lines
7.1 KiB
Markdown
|
|
[](https://github.com/marketplace/actions/arduino_ci)
|
|
[](https://github.com/RobTillaart/HT16K33/actions/workflows/arduino-lint.yml)
|
|
[](https://github.com/RobTillaart/HT16K33/actions/workflows/jsoncheck.yml)
|
|
[](https://github.com/RobTillaart/HT16K33/blob/master/LICENSE)
|
|
[](https://github.com/RobTillaart/HT16K33/releases)
|
|
|
|
|
|
# HT16K33
|
|
|
|
Arduino Library for HT16K33 I2C 4x7segment display.
|
|
|
|
|
|
## Description
|
|
|
|
This library is for the Adafruit 4x7segment display with HT16K33 driver,
|
|
http://www.adafruit.com/products/1002
|
|
|
|
This library is functionally less capable than Adafruits.
|
|
However as it caches the values written to the display per position
|
|
it is faster for writing on average. The actual gain depends on the
|
|
application and of course the values.
|
|
|
|
|
|
## Perfomance
|
|
|
|
Version 0.3.0 allows one to switch the caching on/off to enforce
|
|
writing all positions e.g. in case of noisy I2C bus.
|
|
|
|
The example **demo_cache.ino** measures the performance gain of caching
|
|
for different I2C bus speeds.
|
|
|
|
```
|
|
Test on UNO, I2C.setClock(100000); // version 0.1.2
|
|
0-9999 integers 3.960 sec
|
|
0-65535 hexadecimal 23.685 sec
|
|
|
|
Test on UNO, I2C.setClock(800000); // version 0.1.2
|
|
0-9999 integers 1.223 sec
|
|
0-65535 hexadecimal 6.350 sec
|
|
|
|
Test on UNO, I2C.setClock(100000); // version 0.3.0
|
|
0-9999 integers 4.092 sec // ~3% slower due to robustness & cache control
|
|
0-65535 hexadecimal 24.336 sec
|
|
```
|
|
|
|
|
|
## Multiple display
|
|
|
|
The library supports only one display. Using multiple displays (cascading) e.g. to
|
|
display more than 4 digits must done by the user - see **demo_dual1.ino**.
|
|
With dual display it is important to **setDigits()** for the displays correctly to
|
|
get leading/trailing zero's correctly.
|
|
|
|
|
|
## Interface
|
|
|
|
|
|
### Setup behaviour
|
|
|
|
- **HT16K33(const uint8_t address)** address is 0x70..0x77 depending on the jumpers A0..A2. **0x70** is default.
|
|
- **bool begin(uint8_t sda, uint8_t scl)** for ESP32, select I2C pins, initialize I2C and calls **reset()**.
|
|
Returns false if device not seen on I2C bus.
|
|
- **bool begin()** initialize I2C and calls **reset()**.
|
|
Returns false if device not seen on I2C bus.
|
|
- **bool isConnected()** Returns false if device not seen on I2C bus.
|
|
- **void reset()** resets display.
|
|
- **void clearCache()** forced clearing of the cache, to be used to switch the cache off just for one write.
|
|
- **void cacheOn()** enable caching, this is default behaviour.
|
|
- **void cacheOff()** disable caching, will force writing to every position.
|
|
- **void displayOn()** enable display.
|
|
- **void displayOff()** disable display, fast way to darken display e.g. for energy consumption.
|
|
- **void brightness(uint8_t value)** values (dim) 0..15 (bright).
|
|
- **void blink(uint8_t value)** values 0..3 0 = off.
|
|
- **void setDigits(uint8_t value)** values 0..4, minimal number of digits shown, mandatory for large numbers on dual display.
|
|
- **uint8_t getAddress()** idem.
|
|
|
|
|
|
### Data types
|
|
|
|
The bool return value indicates that the value displayed is in range.
|
|
|
|
- **void displayClear()** fill display with spaces => results in an empty display.
|
|
- **bool displayInt(int n)** values -999 .. 9999
|
|
- **bool displayHex(uint16_t n)** values 0000 .. FFFF
|
|
- **bool displayDate(uint8_t left, uint8_t right, bool lz = true)** values 00.00..99.99 Date could be {month.day} or {day.hour}
|
|
It uses **.** as separator. Optional the leading zero (lz)
|
|
can be replaced by a space to look more natural e.g 1:54 instead of 01:54
|
|
- **bool displayTime(uint8_t left, uint8_t right, bool colon = true, bool lz = true)** values 00:00..99:99
|
|
Time could be hh:mm or mm:ss or ss:uu (hundreds), it uses **:** as separator.
|
|
Optional the colon is set to false (e.g. to simulate blink) and optional the leading zero (lz)
|
|
can be replaced by a space to look more natural e.g 1:54 instead of 01:54
|
|
- **void displaySeconds(uint16_t seconds, bool colon, bool lz = true)** displays 00:00..99:99 units in seconds (or minutes) - splits % 60 : as separator
|
|
Optional the colon is set to false (to simulate blink).
|
|
Optional the leading zero (lz) can be replaced by a space to look more natural e.g 1:54 instead of 01:54
|
|
- **bool displayFloat(float f, uint8_t decimals = 3)** values -999..0.000..9999
|
|
The number of decimals = 0,1,2,3 = default. When less decimals are displayed, the number will be right aligned.
|
|
|
|
|
|
### Experimental
|
|
|
|
These functions are new and still under investigation.
|
|
|
|
- **bool displayFixedPoint0(float f)** displays values -999 .. 9999 without decimals.
|
|
- **bool displayFixedPoint1(float f)** displays values -99.9 .. 999.9 with 1 decimals.
|
|
- **bool displayFixedPoint2(float f)** displays values -9.99 .. 99.99 with 2 decimals.
|
|
- **bool displayFixedPoint3(float f)** displays values 0.000 .. 9.999 with 3 decimals.
|
|
|
|
|
|
### Special
|
|
|
|
- **bool displayVULeft(uint8_t value)** display used as sort VU meter, values 0..8 Vales > 8 are treated as 8 (but return false).
|
|
- **bool displayVURight(uint8_t value)** display used as sort VU meter, values 0..8 Vales > 8 are treated as 8 (but return false).
|
|
|
|
|
|
### Lower level workers
|
|
|
|
- **void display(uint8_t \* array)** array of 4 bytes to control one 7seg display.
|
|
- **void display(uint8_t \* array, uint8_t point)** idem + point = position of the digit with point (0..3).
|
|
- **void displayColon(uint8_t on)** 0 = off, all values other are on.
|
|
- **void displayRaw(uint8_t \* array, bool colon)** array of 4 bytes to control one 7seg display + colon flag.
|
|
- **void displayExtraLeds(uint8_t value)** switch on extra leds.
|
|
value is in fact a bit mask see table below. 0 = all off.
|
|
|
|
#### Extra Leds table
|
|
|
|
| mask | description |
|
|
|:------:|:--------------|
|
|
| 0x00 | all off
|
|
| 0x02 | colon.
|
|
| 0x04 | upper left point, left of the 1st digit.
|
|
| 0x08 | lower left point, left of the 1st digit.
|
|
| 0x10 | upper point between 3rd and 4th digit.
|
|
|
|
( based upon issue #21 )
|
|
|
|
|
|
### Debugging
|
|
|
|
- **void displayTest(uint8_t del)** debugging / test function.
|
|
- **void dumpSerial(uint8_t \* array, uint8_t point)** debugging equivalent of display.
|
|
|
|
|
|
### Obsolete
|
|
|
|
- **void suppressLeadingZeroPlaces(uint8_t value)** obsolete, replaced by setDigits
|
|
|
|
|
|
## Operation
|
|
|
|
See examples
|
|
|
|
|
|
## Future
|
|
|
|
#### 0.4.0
|
|
|
|
- **bool isDisplayOn()** and similar state functions
|
|
- configuration byte: 4 bits brightness, 1 bit on off flag, 1 bit cache flag, 2 blink rate
|
|
- **void setBrightness()** and **uint8_t getBrightness()**
|
|
- **void setBlink()** and **uint8_t getBlink()**
|
|
- **void getDigits()**
|
|
- **FixedPoint()** regular (experimental in 0.3.2)
|
|
- overflow flag ? or not decision
|
|
- move all code to .cpp file
|
|
- even the small functions.
|
|
|
|
#### unknown
|
|
- VU metering using halve bars allows two VU from 0..8 **new**
|
|
- VU metering using halve bars allows one VU from 0..17. extension of current VUleft/right
|
|
- optimize the math if possible - performance and footprint. +float + int division
|
|
- low level I2C error detection
|
|
|