TM1638plus: the LED&KEY board’s digits, LEDs and buttons
The LED&KEY board carries a TM1638 with eight seven-segment digits, eight red LEDs and eight push buttons, all on three wires: strobe, clock and data. TM1638plus by Gavin Lyons is a library many tutorials use for it, and it handles all three jobs: text and numbers on the digits, the LEDs one at a time or all together, and one call that reads every button.
Built in on Mokxi: #include <TM1638plus.h> and it builds, with nothing to install. Free, and no account needed.
What TM1638plus does
The chip does the hard parts itself. It keeps the picture lit with no help from the board, and it scans the buttons in the background, so the sketch only sends bytes when something changes and asks for the button state when it wants it. readButtons() returns one byte with S1 in bit 0, so a press of S3 reads as 0x04 and two buttons at once simply set two bits.
The same library has classes for other boards: TM1638plus_Model2 for the sixteen-key board, TM1638plus_model3 for the LED&KEY version with two-color LEDs, TM1637plus_modelX for TM1637 displays and MAX7219plus_Model6 for eight-digit MAX7219 modules. Mokxi’s tm1638 part is the model 1 LED&KEY board, so a model 2 sketch lands on it in model 1’s layout.
| Library Manager name | TM1638plus |
|---|---|
| Author | Gavin Lyons |
| Include | #include <TM1638plus.h>#include <TM1638plus_Model2.h>#include <TM1638plus_Model3.h>#include <TM1638plus_common.h> |
| Boards | every board Mokxi compiles for |
| In the simulator | Simulated: it runs against the part the way it does on the bench. |
| Parts it drives | LED and key board, TM1638, Four-digit display, TM1637, Eight-digit display, MAX7219 |
Install it
It builds on every board Mokxi compiles for.
In Mokxi it is built in: #include <TM1638plus.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "TM1638plus" by Gavin Lyons from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add TM1638plus to lib_deps in PlatformIO. Mokxi follows the calls of release 2.2.0, so a sketch written here builds there too.
What to know in the simulator: The font is Mokxi’s own seven-segment table. The tm1638 part is the model 1 board, so model 2’s transposed digits and sixteen keys land on it in model 1’s layout; TM1637plus runs on the tm1637 part and MAX7219plus on the max7219seg part.
- ESP32-C3
- Arduino Uno
- Arduino Nano
- Arduino Mega 2560
- Arduino Leonardo
- SparkFun Pro Micro
- Arduino Micro
- ESP32-C6
- WCH CH32V003
- ATtiny85
- Raspberry Pi Pico
- Raspberry Pi Pico W
- Seeed XIAO SAMD21
- STM32
- STM32 Nucleo-F411RE
- STM32 Blue Pill
- micro:bit V2
- Arduino Uno R4
- ESP32 DevKit
- ESP32-S3-DevKitC-1
- ESP8266 NodeMCU
- Arduino Pro Mini 3.3 V
- Seeed XIAO ESP32-C3
- ESP32-C3 SuperMini
- Seeed XIAO ESP32-C6
- ESP32-DevKitC V4
- LOLIN32 Lite
- Wemos D1 R32
- Cheap Yellow Display
- TTGO T-Display
- Seeed XIAO ESP32-S3
- Arduino Nano ESP32
- Arduino Nano RP2040 Connect
- Seeed XIAO RP2040
- Waveshare RP2040-Zero
- Arduino Uno R4 WiFi
The calls you will use
In the order a sketch meets them.
TM1638plus tm(4, 6, 7)
Makes the board on STB 4, CLK 6 and DIO 7. A fourth argument, true, slows the clock for long wires or fast boards such as the ESP32.
tm.displayBegin()
Sets the pins up, turns the display on and clears every digit and LED. Call it once in setup().
tm.displayText("LED KEY ")
Writes up to eight characters from the left. A period after a character lights that digit’s decimal point instead of using a digit.
tm.displayIntNum(4250, false)
Shows a whole number. The second argument chooses leading zeros; a third, TMAlignTextRight, pushes it to the right.
tm.readButtons()
Returns a byte with one bit per button, S1 in bit 0. Compare with the last value to find which button was just pressed.
uint8_t buttons = tm.readButtons();
uint8_t pressed = buttons & ~lastButtons;
lastButtons = buttons;tm.setLEDs((uint16_t)buttons << 8)
Sets all eight LEDs at once. On the LED&KEY board the LEDs are the upper byte, so shift a button byte left by eight to light the LED over each pressed button.
tm.setLED(0, 1)
Turns one LED on (1) or off (0). Position 0 is the leftmost.
tm.brightness(2)
Sets the brightness from 0 to 7 for the digits and LEDs together.
Example: LED and key
On the Arduino Uno R3. It runs in the browser exactly as printed.
// LED and key: a TM1638 "LED&KEY" board with the TM1638plus library. Each
// button lights the LED above it while held, and the display counts the
// presses and names the last button.
//
// TM1638 STB -> 4, CLK -> 6, DIO -> 7, VCC -> 5 V, GND -> GND
//
// The TM1638 holds the picture itself and scans the buttons itself, so the
// sketch only sends bytes: STB low, then each byte least significant bit
// first, clocked on CLK's rising edge. readButtons() sends 0x42 and the chip
// answers with four bytes on DIO, one bit per button once they are folded
// together.
//
// Things to try. Press two buttons at once. Then change the brightness in
// setup() from 2 to 7, and to 0.
#include <TM1638plus.h>
const int STROBE_PIN = 4;
const int CLOCK_PIN = 6;
const int DATA_PIN = 7;
TM1638plus tm(STROBE_PIN, CLOCK_PIN, DATA_PIN);
uint8_t lastButtons = 0;
unsigned long presses = 0;
void show(int button) {
// "P" and the count on the left, a gap, the button's number on the right.
char text[9] = "P ";
unsigned long n = presses % 100000UL;
int at = 5;
do {
text[at--] = (char)('0' + n % 10);
n /= 10;
} while (n > 0 && at > 0);
text[7] = (char)('0' + button);
tm.displayText(text);
}
void setup() {
Serial.begin(9600);
tm.displayBegin();
tm.brightness(2);
tm.displayText("LED KEY ");
Serial.println("TM1638 ready");
}
void loop() {
uint8_t buttons = tm.readButtons();
if (buttons != lastButtons) {
tm.setLEDs((uint16_t)buttons << 8);
uint8_t pressed = buttons & ~lastButtons;
for (int i = 0; i < 8; i++) {
if (pressed & (1 << i)) {
presses++;
show(i + 1);
Serial.print("S");
Serial.print(i + 1);
Serial.print(" pressed, ");
Serial.print(presses);
Serial.println(" in all");
}
}
lastButtons = buttons;
}
delay(20);
}Open it in the editor, wired and ready to run · LED and key: the project page
Common errors and how to fix them
setLEDs() runs but no LED lights
The value is in the lower byte, which is the second color on the model 3 board. On the LED&KEY the LEDs are the upper eight bits, so shift your pattern left by eight before passing it.
One press is counted many times
readButtons() reports the state, not the change. Keep the last value, and act only on bits that are set now and were clear before, as the project does with buttons & ~lastButtons.
Digits flicker or show random segments on an ESP32
The clock is too fast for the chip or the wires. Pass true as the fourth constructor argument to slow the bit timing, and keep the three signal wires short.
Questions and answers
Can two buttons be read at the same time?
Yes. readButtons() returns all eight in one byte, so two held buttons set two bits. The project lights both LEDs and counts both presses.
Keep going
More displays libraries
Try TM1638plus without installing anything
Open the example, change the sketch, and keep your version in a free account.