TM16xx

Arduino TM16xx library for LED & KEY and LED Matrix modules based on TM1638, TM1637, TM1640 and similar chips. Simply use print() on 7-segment end 14-segment displays and use Adafruit GFX on matrix displays.

TM16xx LEDs and Buttons library

This Arduino library facilitates driving LED/LCD displays using TM16xx driver chips. Members of the TM16xx family by Titan Micro support driving LED displays, LCD displays or LED matrices. Next to built-in high-frequency LED/LCD multiplexing, they offer control of brightness/contrast. Most TM16xx chips also support reading key-scan data for button presses. Using this library you can simply use print() on a 7-segment or 14-segment display or use Adafruit GFX on a LED matrix. Currently this library supports more than 25 different TM16xx chips in various configurations; such as the TM1616, TM1618, TM1620, TM1628, TM1630, TM1637, TM1638, TM1640, TM1650 and TM1652. For a quick look hit the play button in this LIVE DEMO on Wokwi.

Made by Maxint R&D. See https://github.com/maxint-rd/

Initial version was based on the TM1638 library by Ricardo Batista. Further inspiration from the TM1637 library by Avishay, the Max72xxPanel library by Mark Ruys and the OneButton library by Matthias Hertel.

Table of contents

• TM16xx chip features
• Library structure
• Library installation
• Base class usage
• Generic class (TM16xxIC)
• TM16xxDisplay class
• TM16xxMatrix class
• TM16xxMatrixGFX class
• TM16xxButtons class
• New in this library
• Features & limitations
• More information

TM16xx chip features

The TM16xx family is quite large. Several family members found their way to Arduino compatible LED display modules, for instance these:

Type | Segments x digits | Buttons | Interface | Notes ------ | -------------------- | ------------ | ------------|------------- TM1637 | 8 x 6 (CA) | 8 x 2 single | DIO/CLK | TM1638 | 10 x 8 | 8 x 3 multi | DIO/CLK/STB | Anode/Inverted/QYF* TM1640 | 8 x 16 | n/a | DIN/CLK | Anode* TM1650 | 8 x 4 | 7 x 4 multi | DIO/CLK |

^{*) Alternative configurations TM1638QYF/TM1638Anode/InvertedTM1638, TM1618Anode and TM1640Anode are also supported.}

The following chips are fully supported and tested to work: TM1616, TM1618, TM1620, TM1623, TM1624, TM1628, TM1630, TM1637, TM1638, TM1640, TM1650, TM1652, TM1668.

Note that there are similar chips made by other manufacturers that may be compatible with the Titan Micro chips. For instance: the HBS640 by WINRISE is compatible with the TM1640.

As of end 2024 many more chips are supported: TM1620B, TM1623C, TM1626A, TM1616B, TM1628A, TM1629A, TM1629B, TM1629C, TM1629D, TM1636, TM1639, TM1640B, TM1642, TM1643, TM1665, TM1667. Note that while their features are supported via the generic class TM16xxIC, I don't have them all in my collection and they have not all been tested. Please let me know your findings if you have tested one of them.

NEW - In 2025 support was added for the TM1621 and TM1622 LCD drivers, including specific support for the HT1621 based 6 x 7-segment PDC-6X1 module and the TM1622 based DM8BA10 module with 10 x 16-segment alphanumeric digits. The TM1621D was tested with a 3x7-segment mini LCD display. Other variations (TM1621B, TM1621C, TM1622B) were not tested, but may work fine.

For a full overview of all the chips and their current level of support go to TM16xx chips features and support.

See the documents folder for datasheets containing more information about these chips and their pinouts.

Library structure

This library has a layered structure to simplify the support of multiple TM16xx chips. By using a base class that provides a uniform API, your application doesn't need chip specific code. Likewise, the library can offer common functionality in display specific classes that support multiple chips.

The figure below illustrates that concept:

Library installation

The easiest way to install this library is using the Arduino Library Manager. Just search for "TM16xx LEDs and Buttons" and click the install button. You can also download the latest version or select one from the releases as zipfile and use Add .ZIP library in the Arduino IDE.

NOTE: AdafruitGFX may need to be installed, even if you don't use TM16xxMatrixGFX. Depending on your compiler you may get compilation errors if AdafruitGFX isn't installed. In such case you can either install AdafruitGFX or remove TM16xxMatrixGFX.h and TM16xxMatrixGFX.cpp from the library directory.

Base class usage (TM1637, TM1638, TM16..)

After installation you can use this library by including the class header that matches the chip on your module and then instantiate the object:

#include <TM1638.h>

TM1638 module(8, 9, 7);   // DIO=8, CLK=9, STB=7

In the setup() function you can initialize and set the intensity of the display, but that's not mandatory:

void setup() {
  module.begin(true, 2);   // on=true, intensity-2 (range 0-7)
  module.setDisplayToString("HALO");    // display simple text
}

In the loop() function you can use basic display methods provided by the TM16xx base class :

void loop() {
  int nTime = ((millis() / 1000) / 60) * 100 + (millis() / 1000) % 60; // convert time to minutes+seconds as integer
  module.setDisplayToDecNumber(nTime, _BV(4)); // display milliseconds with dot on digit 4
}

For the easy to use print() method and more advance display methods you can use the TM16xxDisplay class.

The TM16xx chip makes it easy to see if a button is pressed. To check if a button was pressed you can use the getButtons() method:

  uint32_t dwButtons=module.getButtons();
  Serial.println(dwButtons, HEX);

Please note that while you don't need to write any code for debouncing, the button state may be reset when you display something. For advanced detection of button clicks, double clicks and long presses you can use the TM16xxButtons class.

For detailed documentation of the TM16xx base class go to the TM16xx base class function reference.

Generic class TM16xxIC

NEW - To support a large range of TM16xx chips, the generic class TM16xxIC was added. If your chip has no chip specific header file, your chip has not been tested yet, but may still be supported via the generic class if it has supported chip features. To use it include the generic class header and specify your chip when instantiating the module object:

#include <TM16xxIC.h>

TM16xxIC module(IC_TM1638, 8, 9, 7);   // IC is TM1638, DIO=8, CLK=9, STB=7

These untested chips have supported features: TM1620B, TM1623C, TM1626A, TM1616B, TM1628A, TM1629, TM1629A, TM1629B, TM1629C, TM1629D, TM1636, TM1639, TM1640B, TM1642, TM1643, TM1665, TM1667. For a full overview of all the chips and their level of support go to TM16xx chips features and support

TM16xxDisplay class

The TM16xxDisplay class adds some bytes to the memory footprint, but it provides the familiar easy to use print() and println() functions. Next to that it also provides some more advanced display methods. To use that class on top of the base class, all you need to do is instantiate it, refering to the chip specific class:

TM1638 module(8, 9, 7);   // DIO=8, CLK=9, STB=7
TM16xxDisplay display(&module, 8);    // TM16xx object, 8 digits

Simple print example using the TM16xxDisplay class:

#include <TM1638.h>
#include <TM16xxDisplay.h>

TM1638 module(8, 9, 7);   // DIO=8, CLK=9, STB=7
TM16xxDisplay display(&module, 8);    // TM16xx object, 8 digits

void setup() {
  display.println(F("HELLO !"));
}

int nCount=0;
void loop() {
  delay(1000);
  display.print("Count:");
  display.println(nCount++);
}

If you want you can combine multiple modules into a single TM16xxDisplay object. When combined print() and println() will use all available digits to print the string. See the TM16xxDisplay class reference for detailed documentation of the provided methods.

TM16xxMatrix class

The TM16xxMatrix class provides basic methods for using a single LED-matrix module. For more advanced graphics use the TM16xxMatrixGFX class. To use the TM16xxMatrix class on top of the base class, all you need to do is instantiate it, refering to the chip specific class:

TM1640 module(9, 10);    // DIN=9, CLK=10
#define MATRIX_NUMCOLUMNS 16
#define MATRIX_NUMROWS 8
TM16xxMatrix matrix(&module, MATRIX_NUMCOLUMNS, MATRIX_NUMROWS);    // TM16xx object, columns, rows

Note that the TM1640 has sufficient outputs to drive two 8x8 matrices.

These methods can be u