Open the editorEditor
ESP32 · TM1637 Display

ESP32 TM1637 Display Simulator: Wiring, Code and a Live Circuit

This is a TM1637 4-digit 7-segment display wired to an ESP32 DevKit, running a minutes and seconds clock live in your browser with the TM1637Display library.

Four wires: power, GND, CLK to GPIO 4 (D4) and DIO to GPIO 5 (D5). Two signal pins drive all 32 segments.

Run it in the editorRead the code
  • 3.3 V logic
  • Library: TM1637Display.h
  • CLK 4, DIO 5
  • Colon for a clock
ESP32 · TM1637 Displaylive0.000 s 0.00x
Click to open it in the editor
The circuit itself, running on the simulator with the sketch below. Press what can be pressed; click anything else to open it in the editor.

Wiring the TM1637 Display to the ESP32

Every connection in the circuit above, with the board’s own pin names.

TM1637 Display pinESP32 pinWhy
VCC3V3The TM1637 runs from 3.3 to 5 V; brighter at 5 V.
GNDGNDCommon ground.
CLKGPIO 4 (D4)Clock. Any digital pin: it is not I2C, despite looking like it.
DIOGPIO 5 (D5)Data, both directions.

On the ESP32 the module runs from 3V3, so CLK and DIO stay at the board’s 3.3 V. The digits are a little dimmer than at 5 V; setBrightness(7) makes up most of it.

Pins to leave alone on the ESP32

GPIO 34, 35, 36 (VP) and 39 (VN) are input only: they cannot drive a pin or take an internal pull-up. GPIO 0, 2, 5, 12 and 15 are strapping pins, read at power-on, and GPIO 6 to 11 are the flash chip.

On a real bench

The thirty-pin DevKit straddles a breadboard with one row of holes free on each side, which is where the TM1637 Display’s jumpers go. Many ESP32 boards are wider and cover both rows; then use two breadboards side by side. Hold BOOT while uploading if the IDE cannot connect.

The code

The sketch the circuit above runs. Open it in the editor, change a line and press Run: it compiles in your browser.

TM1637 clock on ESP32
#include <TM1637Display.h>

const int CLK_PIN = 4;   // GPIO 4 (D4)
const int DIO_PIN = 5;   // GPIO 5 (D5)

TM1637Display display(CLK_PIN, DIO_PIN);

void setup() {
  Serial.begin(115200);
  display.setBrightness(4);         // 0 to 7
  Serial.println("Counting");
}

void loop() {
  // Minutes and seconds since reset, with the colon on.
  unsigned long s = millis() / 1000;
  int mmss = (s / 60) % 100 * 100 + s % 60;
  display.showNumberDecEx(mmss, 0b01000000, true);
  delay(200);
}

TM1637Display display(CLK_PIN, DIO_PIN) names the two pins. The TM1637 chip on the module scans the four digits itself, so the board only sends it a number when something changes.

showNumberDecEx(number, dots, leadingZeros) shows a number up to 9999. The dots mask 0b01000000 lights the colon between the second and third digits, and true keeps the leading zeros, so 1:05 shows as 01:05.

Serial.begin(115200) opens the serial monitor. Serial is UART0 on the USB bridge. ESP32 sketches usually run it at 115200 baud, which this one does.

Common mistakes with the TM1637 Display on the ESP32

Wiring CLK and DIO to the I2C pins

The protocol looks like I2C but is not; it has no address and the Wire library cannot talk to it. Any two digital pins work, and leaving GPIO 21 (D21) and GPIO 22 (D22) free keeps them for a real I2C part.

Expecting decimal points

Most TM1637 clock modules wire only the colon, not the dots under each digit. The dots argument lights them on modules that have them, and the colon on these.

Putting CLK or DIO on an input-only pin

GPIO 34, 35, 36 and 39 on the ESP32 have no output driver at all. pinMode() to OUTPUT on one of them does nothing and the line never moves, which looks exactly like a dead part. GPIO 4 (D4) is a safe choice; so are GPIO 13, 14, 16 to 19, 23, 25 to 27 and 32 to 33.

Questions and answers

Can I simulate a TM1637 display with an ESP32 DevKit?

Yes. The circuit at the top of this page is an ESP32 DevKit with a TM1637 display, running in your browser on a simulated ESP32 (Xtensa LX6). The simulated module decodes the real two-wire protocol, so the digits and the colon show exactly what the library sent. Press Run it in the editor to change the wiring or the code; it is free and needs no account.

How do I show letters?

setSegments() takes a byte per digit, one bit per segment, so letters that fit a 7-segment shape (A, b, C, d, E, F and a few more) can be built by hand.

Can I show negative numbers?

showNumberDec() handles them down to -999, using the first digit for the minus sign.

What about a MAX7219 display?

It is a different chip on a three-wire SPI-style bus, driven with LedControl.h. The simulator has it too; the TM1637 is cheaper and needs one pin fewer.

Build your own TM1637 Display project

Open this circuit in the editor, change the wiring or the code, and keep your version in a free account.

Start building freeOpen the editor