Library for utilizing display modules with TM1637 controller. Those modules are available in variants with colon (clock displays) only after the second digit or with decimal point after every digit, usually with 4 digits, although the controller can drive up to 6 digits. The library controls the controller as with cache in 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.
- Library methods prefixed with
printperforms all manipulation in the screen buffer, which state reflects the desired result for display. - Finally the dedicated method display() transmits the content of the screen buffer to the controller and it causes to display result on the attached display (digital tubes).
- The library and controller TM1637 can control up to 6 digital tubes.
- The library can control the TM1636 controller as well, which is binary compatible with TM1637, but controls just 4 tubes.
- The library controls 7-segment glyphs (digits) mutual independently from radix 8th segments of digital tubes.
- The library does not implement key scan capabilities of the controller.
- The library inherits from the system library
Print, so that all systemprintoperations are available.
- Arduino.h: Main include file for the Arduino SDK version greater or equal to 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.
- avr/pgmspace.h: Storing static string in the flash memory using the method
pgm_read_byte. - 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 conventionfont7seg_<variant>.hin the subfolderextras. 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 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.
- VERSION: Name and semantic version of the library.
- SUCCESS: Result code for successful processing.
- ERROR_PINS: Error code for incorrectly assigned microcontroller's pins to controller's pins, usually some of them are duplicated.
- ERROR_ACK: Error code for not acknowledged transmission by the controller.
- The methods in bold return result or error codes and communicate with the controller directly.
- The getters in italic are static and can be called directly from the library without need of their instantiation.
- 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()
- placePrint()
- printDigit()
- printDigitAll()
- printDigitOff()
- printDigitOn()
- printGlyphs()
- printRadixOff()
- printRadixOn()
- printRadixToggle()
- printText()
- write()
- getContrast()
- getContrastMax()
- getContrastMin()
- getDigits()
- getDigitsMax()
- getLastCommand()
- getLastResult()
- getPrint()
- isDisplayOff()
- isDisplayOn()
- isError()
- isSuccess()
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_tm1637(uint8_t pinClk, uint8_t pinDio, uint8_t grids)
-
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. Default value is aimed for clock display with 4 digits as well as for TM1636 controller.
- Valid values: 0 ~ 6 (getDigitsMax() according to attached LED display)
- Default value: 4 (for usual clock and numeric LED displays)
The library instance object for display geometry.
The method checks the microcontroller's pins defined in the constructor and preforms initial sequence recommended by the data sheet for the controller.
- The method checks whether pins set by constructor are not equal.
- The method clears the display and sets it to the normal operating mode.
gbj_tm1637::ResultCodes begin()
None
Result code from Result and error codes.
The method transmits current content of the screen buffer to the driver after potential digit order transformation, so that its content is displayed immediatelly and stays unchanged until another transmission.
- The method utilizes automatic addressing mode of the driver.
- The input transformation table transforms screen buffer digit order to the display hardware digit order. Some 6-digit displays have usually 2 banks of 3-digit digital tubes with hardware order {2, 1, 0, 5, 4, 3}, while the screen buffer is orderer as {0, 1, 2, 3, 4, 5}.
- The referenced input array should be as long as there are digits defined in the constructor at least.
gbj_tm1637::ResultCodes display(uint8_t *digitReorder)
- digitReorder: Array with transformation table where an index defines the screen buffer position and a value defines the display digital tube position.
- Valid values: microcontroller's addressing range
- Default value: 0
Result code from Result and error codes.
const unsigned char TM1637_DIGITS = 6;
gbj_tm1637 disp = gbj_tm1637(2, 3, TM1637_DIGITS);
byte digitReorder[TM1637_DIGITS] = { 2, 1, 0, 5, 4, 3 };
setup()
{
disp.begin();
disp.printText("-Init-");
disp.display(digitReorder);
}displayOn(), displayOn(), displayToggle()
Corresponding method either turns on or off the entire display module or toggles its state without changing current contrast level.
- All methods are suitable for making a display module blinking.
gbj_tm1637::ResultCodes displayOn()
gbj_tm1637::ResultCodes displayOff()
gbj_tm1637::ResultCodes displayToggle()
None
Result code from Result and error codes.
The method set either maximal or minimal constrast level and enables to mimic a display breathing.
gbj_tm1637::ResultCodes displayBreath()
None
Result code from Result and 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
Corresponding 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.
void printDigit(uint8_t segmentMask, uint8_t digit)
-
segmentMask: Bit mask defining what segments should be turned on. Segments 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. By default the method turns on all segments and displays number 8.
- Valid values: 0 ~ 127
- Default value: 0b01111111 (0x7F, 127 * all segments turned on)
-
digit: controller's digital tube number counting from 0, which glyph segments should be manipulated.
- Valid values: 0 ~ digits * 1 (from constructor)
- Default value: 0
None
The method sets glyph segments (first 7 ones) of all digital tubes without influence on its radix segment in the screen buffer, so that it fills a display with provided segment mask.
void printDigitAll(uint8_t segmentMask)
- segmentMask: Bit mask defining what segments should be turned on. Segments 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. By default the method turns on all segments and displays number 8.
- Valid values: 0 ~ 127
- Default value: 0b01111111 (0x7F, 127 * all segments turned on)
None
The coressponding method performs corresponding manipulation by turning on or off 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 called 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 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 controlled 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 corresponding method sets the respective 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.
- The methods for extreme contrasts are just for convenience.
gbj_tm1637::ResultCodes setContrast(uint8_t contrast)
gbj_tm1637::ResultCodes setContrastMax()
gbj_tm1637::ResultCodes setContrastMin()
- contrast: Level of contrast/brightness.
- Valid values: 0 ~ 7 (getContrastExtreme())
- Default value: 3
Result code from Result and 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_tm1637 disp = gbj_tm1637();
setup()
{
disp.begin();
disp.setFont(gbjFont7segTable, sizeof(gbjFont7segTable));
}The method sets or initializes the internal status of recent processing on the one-wire bus to input value.
- Without input parameter the method initializes internal status to success result code with class constant SUCCESS.
- The method without input parameter is usually called right before any operation on the bus in order to reset the internal status or in methods without bus communication.
gbj_tm1367::ResultCodes setLastResult()
gbj_tm1367::ResultCodes setLastResult(gbj_tm1367::ResultCodes result)
- result: Desired result code that should be set as a recent result code.
- Valid values: Some of Result or error codes.
- Default value: SUCCESS
New (actual) result code of recent operation from Result and error codes.
The method returns a result code of the recent operation with controller. It is usually called for error handling in a sketch.
gbj_tm1367::ResultCodes getLastResult()
None
Result code of the recent processing from Result and 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 method returns number of controlled digital tubes of a display module as it was defined in the corresponding constructor's parameter digits.
uint8_t getDigits()
None
Current number of controlled digital tubes by a library instance object.
The method returns maximal number of digital tubes that the controller supports.
uint8_t getDigitsMax()
None
Maximal supported number of digital tubes by the controller, which is 6.
The method returns the current contrast/brightness level stored in the library instance object.
uint8_t getContrast()
None
Current contrast level counting up to getContrastExtreme().
Corresponding method returns maximal or minimal contrast/brightness level supported by the controller.
uint8_t getContrastMax()
uint8_t getContrastMin()
None
Maximal contrast level supported by the controller is 7. Minimal contrast level supported by the controller is 0.
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.
Corresponding method returns a logical flag about current state of the display.
bool isDisplayOn()
bool isDisplayOff()
None
Flag about display state.
displayOn(), displayOff(), displayToggle()
The method returns a logical flag whether the recent operation was successful or failed respectivelly.
- The corresponding result code can be obtained by the method [getLastResult()]((#getLastResult).
bool isSuccess()
bool isError()
None
Flag about successful or failed processing of the recent operation.