Library for utilizing display modules with TM1638 controller. Those modules are available in various hardware equipment as follows. However each variant has 8 digital 7-segment tubes.
-
8 digital 7-segment 0.56" tubes with decimal dots, 8 two-color LEDs red & green, keypad with 8 keys, two 10 pin connectors (usually marked as JY-LKM1368). This module can be cascaded by 10 pin cable, where output connector of a modules is tied with input connector of the next module in a chain. The entire chain is controlled through the input connector of the first module in a chain and particular modules is selected by a corresponding STB pin of that connector.
-
8 digital 7-segment 0.56" tubes with decimal dots, two 10 pin connectors (usually unmarked). This module can be considered as a extension digital tubes only module of the previous one and can be cascaded.
-
8 digital 7-segment 0.36" tubes with decimal dots, 8 red LEDs, keypad with 8 keys, one 5 pin connector (usually marked as LED--KEY, LED&KEY).
The library controls the controller as a state machine with screen buffer in the microcontroller's operating memory, which is transmitted to the controller for displaying.
- Screen buffer is considered as an image of controller's graphical memory.
- Graphical library methods (prefixed with "print") performs all graphical manipulations in the screen buffer, which state reflects the desired image for display.
- Finally the dedicated method display() transmits the content of the screen buffer to the controller and it causes to display the image on the attached display (digital tubes) and LEDs.
- The controller TM1638 can control up to 8 digital tubes each with radix (decimal dot), 8 two-color LEDs, and 24 keys of the keypad, although display modules usually have just 8 or 16 keys in the keypad implemented.
- The library controls 7-segment glyphs (digits) mutual independently from radix 8th segments of digital tubes and LEDs.
- The library implements key scan capabilities of the controller as well for all 24 keys.
- The library inherits from the system library Print, so that all system print operations are available.
- Arduino.h: Main include file for the Arduino SDK version greater or equal to 100.
- WProgram.h: Main include file for the Arduino SDK version less than 100.
- inttypes.h: Integer type conversions. This header file includes the exact-width integer definitions and extends them with additional facilities provided by the implementation.
- Print.h: System library for printing.
The font is an assignment of a glyph definition to particular ASCII code.
- A 7-segment display glyph is defined by a segment mask of the controller.
- Every font is defined as one-dimensional array with the same name gbjFont7segTable, stored in a separate include file with the naming convention font7seg_variant.h in the subfolder
extras. Font variants differentiate from each other by length and content of that array. - The library contains those fonts:
- font7seg_basic.h: Alphanumeric glyphs reasonably recognizable and readable on 7-segment displays.
- font7seg_decnums.h: Decimal digits, space, and minus glyph.
- font7seg_hexnums.h: Hexadecimal digits, space, and minus glyph.
- Despite the font array is one-dimensional one, glyphs are defined by logical group of two bytes in it.
- The first byte of the glyph pair is an ASCII code of a glyph. Usually it is a 7-bit code, but it might be 8-bit one as well, if appropriate segment mask is provided, which can be reasonably displayed on the 7-segment display.
- The second byte of the glyph pair is a segment mask of a glyph with least significant bit (LSB) corresponding to the segment
A. The 8th, most significant bit (MSB) corresponding to the decimal point (DP) is ignored if set, because the library controls radix segments separately, not by fonts.
- Involving ASCII codes to the font definition enables to define just recognizable glyphs by the 7-segment displays or needed by a project and not to waste memory by definition contiguous set of ASCII codes with unused glyphs, although not starting from 0.
- After including a font include file into a sketch, the font is stored in the flash memory of a microcontroller in order to save operational SRAM.
- The library can utilize just one font at a time.
All constants are embedded into the class as static ones including result and error codes except constant defining hardware keypad equipment.
-
gbj_tm1638:VERSION: Name and semantic version of the library.
-
gbj_tm1638::SUCCESS: Result code for successful processing.
-
GBJ_TM1638_KEYS_PRESENT: Really implemented keys in the keypad of a display module. The constant defines the dimension of keys presses history array. Define it in your sketch right before including header file of this library according to your display module, if number of its hardware keys differs from default value of the constant. Redefinition of the constant is enabled in order not to waist memory for not implemented keys and in order to manage different keypads. Default value is 8 keys.
- gbj_tm1638::ERROR_PINS: Error code for incorrectly assigned microcontroller's pins to controller's pins, usually some o them are duplicated.
- gbj_tm1638::ERROR_ACK: Error code for not acknowledged transmission by the controller.
- gbj_tm1638::KEY_CLICK: A key has been clicked once. The delay of key released after its pressing should be a bit longer than at the double click after the first click in order to distinguish between them.
- gbj_tm1638::KEY_CLICK_DOUBLE: A key has been clicked twice, i.e., double clicked with short delay between key presses.
- gbj_tm1638::KEY_HOLD: A key has been clicked and keep pressed a while, then released.
- gbj_tm1638::KEY_HOLD_DOUBLE: A key has been double clicked and keep pressed a while at the second press, then released.
The methods in bold return result or error codes and communicate with the controller directly. The methods for screen buffer manipulation return nothing, just update the content of the screen buffer as an image of controller registers, and must be followed by display() method in order to display the content of the screen buffer.
It is possible to use functions from the parent library Print, which is extended by this library.
- displayClear()
- moduleClear()
- printRadixOn()
- printRadixOff()
- printRadixToggle()
- printDigit()
- printDigitOn()
- printDigitOff()
- printLedOnRed()
- printLedToggleRed()
- printLedOnGreen()
- printLedToggleGreen()
- printLedOff()
- printLedSwap()
- printText()
- printGlyphs()
- placePrint()
- write()
- registerHandler()
- run()
- getLastResult()
- getLastCommand()
- getDigits()
- getDigitsMax()
- getLeds()
- getLedsMax()
- getKeys()
- getKeysMax()
- getContrast()
- getContrastMax()
- getPrint()
- isSuccess()
- isError()
Custom data type determining the template for key action handler procedures.
- The handler method is called then particular action with any key of the keypad is detected. It allows to process and execute some code dedicated to particular key and its action.
- The handler method is registered to the library by the method registerHandler() and should have appropriate input parameters defined.
void (*gbj_tm1638_handler)(uint8_t key, uint8_t action);
-
key: Number of a keypad's key counting from 0, for which action the handler is called.
- Valid values: 0 ~ GBJ_TM1638_KEYS_PRESENT
- Default value: none
-
action: The action with a key, which has been executed recently.
- Valid values: key actions defined by constants for key actions
- Default value: none
None
The constructor method sanitizes and stores physical features of the display and limited ones for the sake of a sketch to the class instance object.
gbj_tm1638(uint8_t pinClk, uint8_t pinDio, uint8_t pinStb, uint8_t digits, uint8_t leds, uint8_t keys);
-
pinClk: Microcontroller pin's number utilized as a serial clock.
- Valid values: non-negative integer (according to a microcontroller datasheet)
- Default value: 2
-
pinDio: Microcontroller pin's number utilized as a data input and output.
- Valid values: non-negative integer (according to a microcontroller datasheet)
- Default value: 3
- digits: Number of 7-segment digital tubes to be controlled.
- Valid values: 0 ~ 8 (getDigitsMax())
- Default value: 8
- leds: Number of LEDs to be controlled.
- Valid values: 0 ~ 8 (getLedsMax())
- Default value: 8
- keys: Number of keypad's keys to be controlled. Default value is aimed for regular display modules.
- Valid values: 0 ~ GBJ_TM1638_KEYS_PRESENT
- Default value: 8
The library instance object for a display module.
The method checks the microcontroller's pins defined in the constructor and performs initial sequence recommended by the data sheet for the controller.
- The method clears all digital tubes including radixes and turns off all LEDs.
- The method sets a display module to the normal operating mode.
- The method checks whether some two pins set by constructor are not mutually equal.
uint8_t begin();
None
Some of result or error codes.
The method transmits current content of the screen buffer to the controller, so that its content is displayed immediately and stays unchanged until another transmission.
- The method utilizes automatic addressing mode of the controller.
uint8_t display();
None
Some of result or error codes.
Particular method either turns on or off the entire display module including digital tubes and LEDs without changing current contrast level.
- Both methods are suitable for making a display module blinking.
uint8_t displayOn();
uint8_t displayOff();
None
Some of result or error codes.
The method turns off all segments including for radixes of all digital tubes and then sets the printing position for subsequent printing.
- It is a wrapper method for subsequent calling methods printDigitOff(), printRadixOff(), and placePrint().
void displayClear(uint8_t digit);
- digit: Number of digital tube counting from 0 where the printing should start after display clearing.
- Valid values: 0 ~ digits - 1 (from constructor)
- Default value: 0
None
The method turns off all segments including for radixes of all digital tubes as well as all LEDs and then sets the printing position for subsequent printing.
- It is a wrapper method for subsequent calling methods printLedOff() and [displayClear()].
void moduleClear(uint8_t digit);
- digit: Number of digital tube counting from 0 where the printing should start after display clearing.
- Valid values: 0 ~ digits - 1 (from constructor)
- Default value: 0
None
The particular method performs corresponding manipulation with radix segment (usually 8th one) of particular glyph without influence on its glyph segments (first 7 segments) in the screen buffer.
- Each method is overloaded. If there is no input parameter provided, the method performs appropriate action on all controlled digital tubes.
void printRadixOn(uint8_t digit);
void printRadixOn();
void printRadixOff(uint8_t digit);
void printRadixOff();
void printRadixToggle(uint8_t digit);
void printRadixToggle();
- digit: controller's digit tube number counting from 0, which radix segment should be manipulated.
- Valid values: 0 ~ digits - 1 (from constructor)
- Default value: none
None
The method sets glyph segments (first 7 ones) of particular digital tube without influence on its radix segment in the screen buffer.
- The method is overloaded. If there is one input parameter provided, it is considered as a segment mask for current print position set at recent printing action.
- The method is useful for writing to the display without any font used.
void printDigit(uint8_t digit, uint8_t segmentMask);
void printDigit(uint8_t segmentMask);
-
digit: controller's digital tube number counting from 0, which glyph segments should be manipulated.
- Valid values: 0 ~ digits - 1 (from constructor)
- Default value: none
-
segmentMask: Bit mask defining what segments should be turned on. Segments marks starting from A to G relate to mask bits 0 to 6 counting from the least significant bit. The 7th bit relates to radix segment and therefore it is ignored.
- Valid values: 0 ~ 127
- Default value: none
None
The particular method performs corresponding manipulation turning on or off with all glyph segments at once of the display without changing glyph radix segments.
- Each method is overloaded. If there is no input parameter provided, the method performs appropriate action on all controlled digital tubes.
void printDigitOn(uint8_t digit);
void printDigitOn();
void printDigitOff(uint8_t digit);
void printDigitOff();
- digit: controller's digit tube number counting from 0, which glyph segments should be manipulated.
- Valid values: 0 ~ digits - 1 (from constructor)
- Default value: none
None
The method prints text starting from provided or default position on digital tubes.
- The method clears the display right before printing.
- It is a wrapper method for subsequent calling methods displayClear() and system method print().
void printText(const char* text, uint8_t digit);
void printText(String text, uint8_t digit);
-
text: Pointer to a text that should be printed.
- Valid values: microcontroller's addressing range
- Default value: none
-
digit: controller's digit tube number counting from 0, where printing should start.
- Valid values: 0 ~ digits - 1 (from constructor)
- Default value: 0
None
The method prints text starting from provided or default position on digital tubes without impact on radixes.
- The method clears digits right before printing leaving radixes intact.
- The method is suitable for displaying data, where radixes are independent of them and are used for another purpose.
- It is a wrapper method for subsequent calling methods printDigitOff(), placePrint(), and system method print().
void printGlyphs(const char* text, uint8_t digit);
void printGlyphs(String text, uint8_t digit);
-
text: Pointer to a text that should be printed.
- Valid values: microcontroller's addressing range
- Default value: none
-
digit: controller's digit tube number counting from 0, where printing should start.
- Valid values: 0 ~ digits - 1 (from constructor)
- Default value: 0
None
The method stores desired position of a digital tube where the subsequent print should start.
- The method should be call right before any printing method, which does not have its input parameter for setting printing position.
void placePrint(uint8_t digit);
- digit: Printing position for starting a print action.
- Valid values: 0 ~ digits - 1 (from constructor)
- Default value: 0
None
The particular method turns on or toggles red or green LEDs without influence on digital tubes in the screen buffer.
- If there is no input LED number provided, the methods manipulates all module's controlled LEDs of corresponding color at once.
- If a display module does not have two-color LEDs implemented, manipulation with green LEDs has no effect, just on red ones has.
void printLedOnRed(uint8_t led);
void printLedOnRed();
void printLedToggleRed(uint8_t led);
void printLedToggleRed();
void printLedOnGreen(uint8_t led);
void printLedOnGreen();
void printLedToggleGreen(uint8_t led);
void printLedToggleGreen();
- led: controller's LED number counting from 0.
- Valid values: 0 ~ leds - 1 (from constructor)
- Default value: none
None
The method turns off LEDs without influence on digital tubes in the screen buffer, i.e., in case of two-color LEDs both colors.
- If there is no input LED number provided, the methods turns off all module's controlled LEDs at once.
void printLedOff(uint8_t led);
void printLedOff();
- led: controller's LED number counting from 0.
- Valid values: 0 ~ leds - 1 (from constructor)
- Default value: none
None
The method swaps colors of a turned on two-color LEDs without influence on digital tubes in the screen buffer, i.e., changes red to green and vice versa.
- The color swapping is realized by negating LED value in the screen buffer.
- The color swapping occurs only if some of colors was turned on right before swapping.
- If a LED was turned off before swapping, both colors are turned on; however, the red has precedence because color mixture is not supported by a display module.
- If a display module has just red LEDs implemented, the swapping has effect of toggling a red LED.
- If there is no input LED number provided, the method swaps all module's controlled LEDs at once.
void printLedSwap(uint8_t led);
void printLedSwap();
- led: controller's LED number counting from 0.
- Valid values: 0 ~ leds - 1 (from constructor)
- Default value: none
None
The library inherits the system Print class, so that all regular print functions can be used.
- Actually all print functions eventually call one of listed write methods, so that all of them should be implemented.
- If some character (ASCII) code is not present in the font table, i.e., it is unknown for the library, that character is ignored and not displayed.
- If unknown character has ASCII code of comma, dot, or colon, the library turns on the radix segments of the recently displayed digit. Thus, the decimal points or colon can be present in displayed string at proper position and does not need to be control separately.
size_t write(uint8_t ascii);
size_t write(const char* text);
size_t write(const uint8_t* buffer, size_t size);
-
ascii: ASCII code of a character that should be displayed at the current print position. The methods is usually utilized internally by system prints.
- Valid values: 0 ~ 255
- Default value: none
-
text: Pointer to a null terminated string that should be displayed from the current print position.
- Valid values: microcontroller's addressing range
- Default value: none
-
buffer: Pointer to a string, which part should be displayed from the current print position.
- Valid values: microcontroller's addressing range
- Default value: none
-
size: Number of characters that should be displayed from the current print position.
- Valid values: microcontroller's addressing range
- Default value: none
None
The method registers a procedure, which is called when particular action with a key of module's keypad has been performed.
- The handler receives a key number and an action defined by appropriate key action constant.
void registerHandler(gbj_tm1638_handler handler);
- handler: Pointer to a handler procedure of type gbj_tm1638_handler.
- Valid values: microcontroller's addressing range
- Default value: none
None
Handler is defined in a sketch as a standalone procedure. Only registering that method makes a handler from it.
gbj_tm1638 Sled = gbj_tm1638();
void keyHandler(uint8_t key, uint8_t action)
{
switch (action)
{
case gbj_tm1638::KEY_CLICK:
Sled.printLedOnRed(key);
break;
case gbj_tm1638::KEY_HOLD:
Sled.printDigitOn(key);
break;
case gbj_tm1638::KEY_CLICK_DOUBLE:
Sled.printLedOff(key);
break;
case gbj_tm1638::KEY_HOLD_DOUBLE:
Sled.printDigitOff(key);
break;
}
}
setup()
{
Sled.begin();
Sled.registerHandler(keyHandler);
}The method processes timing and catches keypad's keys presses and calls a handler if particular action is detected and if some handler is registered.
- The method should be call very often. The best place is in the loop() function of a sketch, which should be without delay() function or other blocking activities.
void run();
None
None
gbj_tm1638 Sled = gbj_tm1638();
setup()
{
Sled.begin();
Sled.registerHandler(keyHandler);
}
loop()
{
Sled.run();
}The method sets internal status of recent processing of a controller code to success with value of constant gbj_tm1638::SUCCESS. It is usually called right before any operation with the controller in order to reset the internal status.
void initLastResult();
None
None
The method sets the internal status of recent processing with controller to input value. Without input parameter it is equivalent to the method initLastResult().
uint8_t setLastResult(uint8_t lastResult);
- lastResult: Desired result code that should be set as a last result code.
- Valid values: Some of result or error codes.
- Default value: gbj_tm1367::SUCCESS
New (actual) result code of recent operation.
The method sets the level of the display contrast.
- The contrast is perceived as the brightness of the display.
- The brightness is technically implemented with PWM of segments power supply.
uint8_t setContrast(uint8_t contrast);
- contrast: Level of contrast/brightness.
- Valid values: 0 ~ 7 (getContrastMax())
- Default value: 3
Some of result or error codes.
The method gathers font parameters for printing characters on 7-segment displays.
- Font definition is usually included to an application sketch from particular include file, while the font table resides in programmatic (flash) memory of a microcontroller in order to save operational memory (SRAM).
- Each glyph of a font consists of the pair of bytes. The first byte determines ASCII code of a glyph and second byte determines segment mask of a glyph. It allows to defined only displayable glyphs on 7-segment displays and suppress need to waste memory for useless characters.
void setFont(const uint8_t* fontTable, uint8_t fontTableSize);
-
fontTable: Pointer to constant byte array with font characters definitions. Because the font table resides in flash memory, it has to be constant.
- Valid values: microcontroller addressing range
- Default value: none
-
fontTableSize: The number of bytes that should be utilized from the font table.
- Because the font table is referenced by a pointer and not as an array, the table size cannot be calculated internally, but has to be defined externally usually by the function
sizeof. - The table size in conjunction with font character pair of bytes determines the number of characters used for printing.
- The size can be smaller than the real size of the table, however, the size should be a multiple of 2.
- Valid values: 0 ~ 255 (maximal 127 different characters)
- Default value: none
- Because the font table is referenced by a pointer and not as an array, the table size cannot be calculated internally, but has to be defined externally usually by the function
None
#include "font7seg_basic.h"
gbj_tm1638 Sled = gbj_tm1638();
setup()
{
Sled.begin();
Sled.setFont(gbjFont7segTable, sizeof(gbjFont7segTable));
}The method returns a result code of the recent operation with controller. It is usually called for error handling in a sketch.
uint8_t getLastResult();
None
Current result code. It is some of expected result or error codes.
The method returns the command code used at recent communication with controller. In conjunction with returned result or error code of particular method it is possible to detect the source or reason of a communication error.
uint8_t getLastCommand();
None
Recently used command code.
The corresponding method returns number of particular controlled equipment items of a display module as it was defined in the corresponding constructor's parameter.
uint8_t getDigits();
uint8_t getLeds();
uint8_t getKeys();
None
Current number of controlled items of corresponding type by a library instance object.
The method returns maximal number of equipment items of a display module that the controller supports.
uint8_t getDigitsMax();
uint8_t getLedsMax();
uint8_t getKeysMax();
None
Maximal number of equipment items of a display module supported by the controller.
The method returns the current contrast/brightness level store in the library instance object.
uint8_t getContrast();
None
Current contrast level counting up to getContrastMax().
The method returns the maximal contrast/brightness level supported by the controller.
uint8_t getContrastMax();
None
Maximal contrast level supported by the controller, which is 7.
The method returns the current print position set by recent print activity.
uint8_t getPrint();
None
Current printing position counting from 0. It may get beyond the maximal controlled or implemented digital tube.
The method returns a flag whether the recent operation with controller was successful.
bool isSuccess();
None
Flag about successful recent processing.
The method returns a flag whether the recent operation with controller failed. The corresponding error code can be obtained by the method [getLastResult()]((#getLastResult), which is one of the error constants.
bool isError();
None
Flag about failing of the recent operation.