Skip to main content

HT16K33Segment

Latest Version: 1.2.0

Hardware driver for Adafruit 0.56-inch 4-digit, 7-segment LED display based on the Holtek HT16K33 controller. The LED communicates over any imp I²C bus.

The class incorporates its own (limited) character set, accessed through the following codes:

  • Digits 0 through 9: codes 0 through 9
  • Characters A through F: codes 10 through 15
  • Space character: code 16
  • Minus character: code 17

From version 1.1.0, the methods clearBuffer(), setColon(), writeChar() and writeNumber() return the context object, this, allowing these methods to be chained. For example:

led.clearBuffer(17).setColon(true).writeChar(0, 0x6D).updateDisplay();

You can view the library’s source code on GitHub. Click here to see information on the available versions of this library.

To add this library to your project, add #require "HT16K33Segment.class.nut:1.2.0" to the top of your device code

Class Usage

Constructor: HT16K33Segment(impI2cBus[, i2cAddress][, debug])

To instantiate a HT16K33Segment object pass the I²C bus to which the display is connected and, optionally, its I²C address. If no address is passed, the default value, 0x70 will be used. Pass an alternative address if you have changed the display’s address using the solder pads on rear of the LED’s circuit board.

The third parameter allows you to receive extra debugging information in the log. It defaults to false (no messages).

The passed imp I²C bus must be configured before the HT16K33Segment object is created.

#require "HT16K33Segment.class.nut:1.2.0"

hardware.i2c89.configure(CLOCK_SPEED_400_KHZ);
led <- HT16K33Segment(hardware.i2c89);

Class Methods

clearBuffer([clearChar])

Call clearBuffer() to zero the display buffer. If the optional clearChar parameter is not passed, no characters will be displayed. Pass a character code (see above) to zero the display to a specific character, eg. 0 to zero the display.

clearBuffer() does not update the display, only its buffer. Call updateDisplay() to refresh the LED.

// Set the display to -- --
led.clearBuffer(17)
    .updateDisplay();

setColon(set)

Call setColon() to specify whether the display’s center colon symbol is illuminated (true) or not (false).

// Set the display to --:--
led.clearBuffer(17)
    .setColon(true)
    .updateDisplay();

writeChar(rowNum, charVal[, hasDot])

To write a character that is not in the character set (see above) to a single segment, call writeChar() and pass the segment number (0, 1, 3 or 4) and a character matrix value as its parameters. You can also provide a third, optional parameter: a boolean value indicating whether the decimal point to the right of the specified segment should be illuminated. By default, the decimal point is not lit.

Calculate character matrix values using the following chart. The segment number is the bit that must be set to illuminate it (or unset to keep it unlit):

        0
        _
    5 |   | 1
      |   |
        - <----- 6
    4 |   | 2
      | _ |
        3
// Display 'SYNC' on the LED
local letters = [0x6D, 0x6E, 0x37, 0x39];

foreach (index, character in letters) {
    if (index != 2) led.writeChar(index, character);
}

led.updateDisplay();

writeNumber(rowNum, intVal[, hasDot])

To write a number to a single segment, call writeNumber() and pass the segment number (0, 1, 3 or 4) and the digit value (0 to 9, A to F) as its parameters. You can also provide a third, optional parameter: a boolean value indicating whether the decimal point to the right of the specified segment should be illuminated. By default, the decimal point is not lit.

// Display '42.42' on the LED
led.writeNumber(0, 4)
    .writeNumber(1, 2, true)
    .writeNumber(3, 4)
    .writeNumber(4, 2)
    .updateDisplay();

clearDisplay()

Call clearDisplay() to completely wipe the display, including the colon. Unlike clearBuffer(), this method can’t be used to set all the segments to a specific character, but it does automatically update the display.

updateDisplay()

Call updateDisplay() after changing any or all of the display buffer contents in order to reflect those changes on the display itself.

setBrightness([brightness])

To set the LED’s brightess (its duty cycle), call setBrightness() and pass an integer value between 0 (dim) and 15 (maximum brightness). If you don’t pass a value, the method will default to maximum brightness.

setDisplayFlash(flashInHertz)

This method can be used to flash the display. The value passed into flashInHertz is the flash rate in Hertz. This value must be one of the following values, fixed by the HT16K33 controller: 0.5Hz, 1Hz or 2Hz. You can also pass in 0 to disable flashing, and this is the default value.

// Blink the display every second
led.setDisplayFlag(1);

powerDown()

The display can be turned off by calling powerDown().

powerUp()

The display can be turned on by calling powerup().

Release History

The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.

Version Source Code Notes
1.0.1 GitHub Initial release
1.1.0 GitHub Code improvements; key methods now return this to facilitate method chaining; added clearDisplay() method; added debug flag to constructor
1.2.0 GitHub Add setDisplayFlash(); add return this; missing from writeNumber(); setBrightness() code simplified; code that belongs in init() placed in that method

License

The HTK16K33Segment library is licensed under the MIT License.