ESP32 MicroPython TM1637 4-Digit 7-Segment Display
The ESP32 is a powerful, Wi-Fi-enabled microcontroller widely used in IoT and embedded projects. Paired with MicroPython and the DIYables TM1637 4-Digit 7-Segment Display Module, you can easily show numbers, text, temperature, and time on a bright LED display.
This tutorial walks you through:
- Connecting the TM1637 4-Digit 7-Segment Display to an ESP32 — only 2 data pins needed.
- Displaying integers with optional zero-padding.
- Displaying text and special characters (degree symbol).
- Showing time in HH:MM format with blinking colon separator.
- Controlling display brightness (8 levels).
- Blinking the display using off()/on().
Components Needed
Or you can buy the following kits:
| 1 | × | DIYables ESP32 Starter Kit (ESP32 included) | |
| 1 | × | DIYables Sensor Kit (18 sensors/displays) |
Disclosure: Some of the links provided in this section are Amazon affiliate links. We may receive a commission for any purchases made through these links at no additional cost to you.
Additionally, some of these links are for products from our own brand, DIYables .
Additionally, some of these links are for products from our own brand, DIYables .
The TM1637 4-Digit 7-Segment Display Module
The TM1637 is a dedicated LED driver IC that handles both the multiplexing and segment driving for up to 6 digits. This module uses it to drive a 4-digit 7-segment LED display with a colon separator between the second and third digits, making it ideal for clock and timer applications.
Unlike shift-register-based displays (such as 74HC595), the TM1637 has built-in display memory. Once you write data to the chip, it keeps the display lit automatically — no Timer interrupt or refresh loop is needed. The TM1637 also supports 8 brightness levels (0–7) and uses only 2 GPIO pins (CLK and DIO) for communication.
The module communicates via a 2-wire serial protocol similar to I2C (but not standard I2C). The library handles all protocol details — you just call simple methods like print() and print_time().
Pin Description
| Pin | Purpose | ESP32 Connection |
|---|---|---|
| CLK | Serial clock input | Connect to GPIO21 |
| DIO | Serial data input/output | Connect to GPIO22 |
| VCC | 3.3V to 5V power input | Connect to 3.3V |
| GND | Ground | Connect to GND |
Wiring
The ESP32 operates at 3.3V logic. The TM1637 module works with both 3.3V and 5V, so it is directly compatible with the ESP32 without any level shifter.
| TM1637 Module | ESP32 | Notes |
|---|---|---|
| CLK | GPIO21 | Clock line |
| DIO | GPIO22 | Data I/O line |
| VCC | 3.3V | Power |
| GND | GND | Ground |
This image is created using Fritzing. Click to enlarge image
Tip: You can use any available GPIO pins on the ESP32. Just update the pin numbers in the code.
Detailed Instructions
Here's instructions on how to set up and run your MicroPython code on the ESP32 using Thonny IDE:
- Make sure Thonny IDE is installed on your computer.
- Confirm that MicroPython firmware is loaded on your ESP32 board.
- If this is your first time using an ESP32 with MicroPython, check out the ESP32 MicroPython Getting Started guide for step-by-step instructions.
- Connect the ESP32 board to the TM1637 module according to the provided diagram.
- Connect the ESP32 board to your computer with a USB cable.
- Open Thonny IDE on your computer.
- In Thonny IDE, go to Tools Options.
- Under the Interpreter tab, choose MicroPython (ESP32) from the dropdown menu.
- Make sure the correct port is selected. Thonny IDE usually detects it automatically, but you might need to select it manually (like COM3 on Windows or /dev/ttyUSB0 on Linux).
- Navigate to the Tools Manage packages on the Thonny IDE.
- Search "DIYables-MicroPython-4Digit7Segment-TM1637", then find the TM1637 4-Digit 7-Segment Display library created by DIYables.
- Click on DIYables-MicroPython-4Digit7Segment-TM1637, then click Install button to install the library.
- Copy the provided MicroPython code and paste it into Thonny's editor.
- Save the code to your ESP32 by:
- Clicking the Save button or pressing Ctrl+S.
- In the save dialog, choose MicroPython device.
- Name the file main.py.
- Click the green Run button (or press F5) to execute the script.
- Observe the result — the 4-digit 7-segment display shows numbers, text, or time depending on the example.
Starter Code Template
from DIYables_MicroPython_4Digit7Segment_TM1637 import Display4Digit7SegmentTM1637
import time
display = Display4Digit7SegmentTM1637(clk_pin=21, dio_pin=22)
#Display stays on automatically — no refresh loop needed
display.print(1234)
ESP32 Code — Display Integers
"""
Example: Display integer numbers on 4-digit 7-segment display with TM1637.
Works with: ESP32, Raspberry Pi Pico, Arduino Nano ESP32, Arduino Nano R1 WiFi
Product page: https://diyables.io/products/4-digit-7-segment-display-led-tm1637-with-colon
Wiring guide:
ESP32:
TM1637 Module ESP32
───────────── ──────
CLK -> GPIO21
DIO -> GPIO22
VCC -> 3.3V
GND -> GND
Raspberry Pi Pico:
TM1637 Module Raspberry Pi Pico
───────────── ─────────────────
CLK -> GP1
DIO -> GP0
VCC -> 3.3V (pin 36)
GND -> GND (pin 38)
Arduino Nano ESP32:
TM1637 Module Arduino Nano ESP32
───────────── ──────────────────
CLK -> D21 (GPIO21)
DIO -> D22 (GPIO22)
VCC -> 3.3V
GND -> GND
Arduino Nano RP2040 Connect:
TM1637 Module Arduino Nano RP2040 Connect
───────────── ───────────────────────────
CLK -> D1 (GP1)
DIO -> D0 (GP0)
VCC -> 3.3V
GND -> GND
"""
from DIYables_MicroPython_4Digit7Segment_TM1637 import Display4Digit7SegmentTM1637
import time
# Pin configuration - change the pins to match your wiring and board
# ESP32 / Arduino Nano ESP32: CLK=21, DIO=22
# Raspberry Pi Pico / Nano RP2040: CLK=1, DIO=0
CLK_PIN = 21
DIO_PIN = 22
display = Display4Digit7SegmentTM1637(CLK_PIN, DIO_PIN)
while True:
# Display integers
numbers = [0, 42, 1234, -5, -123, 9999]
for num in numbers:
display.print(num)
time.sleep(2)
# Display with zero padding
display.print(42, zero_pad=True) # Shows "0042"
time.sleep(2)
Try It
- Wire the module, connect the ESP32 via USB.
- Upload the code using Thonny IDE.
- The display cycles through several integers (0, 42, 1234, -5, -123, 9999), then shows zero-padded 42 as "0042".
Integer Display Reference
| Method Call | Display Shows | Notes |
|---|---|---|
| display.print(0) | 0 | Right-aligned single digit |
| display.print(42) | 42 | Right-aligned |
| display.print(1234) | 1234 | All 4 digits used |
| display.print(-5) | -5 | Negative sign + digit |
| display.print(-123) | -123 | Max 3-digit negative |
| display.print(9999) | 9999 | Maximum displayable value |
| display.print(10000) | Err | Overflow error |
| display.print(42, zero_pad=True) | 0042 | Zero-padded to 4 digits |
ESP32 Code — Display Text, Degree, and Temperature
"""
Example: Display text, special characters, and temperature on 4-digit 7-segment display.
Works with: ESP32, Raspberry Pi Pico, Arduino Nano ESP32, Arduino Nano R1 WiFi
Product page: https://diyables.io/products/4-digit-7-segment-display-led-tm1637-with-colon
Wiring guide:
ESP32:
TM1637 Module ESP32
───────────── ──────
CLK -> GPIO21
DIO -> GPIO22
VCC -> 3.3V
GND -> GND
Raspberry Pi Pico:
TM1637 Module Raspberry Pi Pico
───────────── ─────────────────
CLK -> GP1
DIO -> GP0
VCC -> 3.3V (pin 36)
GND -> GND (pin 38)
Arduino Nano ESP32:
TM1637 Module Arduino Nano ESP32
───────────── ──────────────────
CLK -> D21 (GPIO21)
DIO -> D22 (GPIO22)
VCC -> 3.3V
GND -> GND
Arduino Nano RP2040 Connect:
TM1637 Module Arduino Nano RP2040 Connect
───────────── ───────────────────────────
CLK -> D1 (GP1)
DIO -> D0 (GP0)
VCC -> 3.3V
GND -> GND
"""
from DIYables_MicroPython_4Digit7Segment_TM1637 import Display4Digit7SegmentTM1637
import time
# Pin configuration - change the pins to match your wiring and board
# ESP32 / Arduino Nano ESP32: CLK=21, DIO=22
# Raspberry Pi Pico / Nano RP2040: CLK=1, DIO=0
CLK_PIN = 21
DIO_PIN = 22
display = Display4Digit7SegmentTM1637(CLK_PIN, DIO_PIN)
while True:
# Display text strings
texts = ["HELP", "Hi", "COOL", "done"]
for text in texts:
display.print(text)
time.sleep(2)
# Display temperature with degree symbol
display.print_temperature(25, 'C') # Shows "25°C"
time.sleep(2)
display.print_temperature(72, 'F') # Shows "72°F"
time.sleep(2)
# Display string with degree constant
display.print("25" + display.DEGREE + "C") # Same as print_temperature(25, 'C')
time.sleep(2)
Text and Temperature Reference
| Method Call | Display Shows | Notes |
|---|---|---|
| display.print("HELP") | HELP | Text display |
| display.print("Hi") | Hi | Left-aligned, 2 chars |
| display.print("COOL") | COOL | 4 characters |
| display.print_temperature(25, 'C') | 25°C | Celsius with degree symbol |
| display.print_temperature(72, 'F') | 72°F | Fahrenheit |
| display.print_temperature(-5, 'C') | -5°C | Negative temperature |
| display.print_temperature(100) | 100° | 3-digit, no room for unit |
The degree symbol can also be used directly in strings via the display.DEGREE constant.
ESP32 Code — Display Time with Blinking Colon
"""
Example: Display time with blinking colon separator on 4-digit 7-segment display.
This module has a colon separator between digit 1 and digit 2, ideal for clock display.
Works with: ESP32, Raspberry Pi Pico, Arduino Nano ESP32, Arduino Nano R1 WiFi
Product page: https://diyables.io/products/4-digit-7-segment-display-led-tm1637-with-colon
Wiring guide:
ESP32:
TM1637 Module ESP32
───────────── ──────
CLK -> GPIO21
DIO -> GPIO22
VCC -> 3.3V
GND -> GND
Raspberry Pi Pico:
TM1637 Module Raspberry Pi Pico
───────────── ─────────────────
CLK -> GP1
DIO -> GP0
VCC -> 3.3V (pin 36)
GND -> GND (pin 38)
Arduino Nano ESP32:
TM1637 Module Arduino Nano ESP32
───────────── ──────────────────
CLK -> D21 (GPIO21)
DIO -> D22 (GPIO22)
VCC -> 3.3V
GND -> GND
Arduino Nano RP2040 Connect:
TM1637 Module Arduino Nano RP2040 Connect
───────────── ───────────────────────────
CLK -> D1 (GP1)
DIO -> D0 (GP0)
VCC -> 3.3V
GND -> GND
"""
from DIYables_MicroPython_4Digit7Segment_TM1637 import Display4Digit7SegmentTM1637
import time
# Pin configuration - change the pins to match your wiring and board
# ESP32 / Arduino Nano ESP32: CLK=21, DIO=22
# Raspberry Pi Pico / Nano RP2040: CLK=1, DIO=0
CLK_PIN = 21
DIO_PIN = 22
display = Display4Digit7SegmentTM1637(CLK_PIN, DIO_PIN)
hours = 12
minutes = 30
colon_on = True
while True:
display.print_time(hours, minutes, colon=colon_on)
time.sleep(0.5) # Toggle colon every 500ms for blinking effect
colon_on = not colon_on
Time Display Reference
| Method Call | Display Shows | Notes | |
|---|---|---|---|
| display.print_time(12, 30) | 12 | 30 | Colon ON |
| display.print_time(9, 5) | 09 | 05 | Zero-padded hours and minutes |
| display.print_time(12, 30, colon=False) | 12 30 | Colon OFF (for blinking effect) |
Toggle the colon parameter every 500ms to create a blinking colon effect, commonly seen on clock displays.
ESP32 Code — Set Individual Digits and Colon
"""
Example: Set individual digits and colon on 4-digit 7-segment display with TM1637.
Works with: ESP32, Raspberry Pi Pico, Arduino Nano ESP32, Arduino Nano R1 WiFi
Product page: https://diyables.io/products/4-digit-7-segment-display-led-tm1637-with-colon
Wiring guide:
ESP32:
TM1637 Module ESP32
───────────── ──────
CLK -> GPIO21
DIO -> GPIO22
VCC -> 3.3V
GND -> GND
Raspberry Pi Pico:
TM1637 Module Raspberry Pi Pico
───────────── ─────────────────
CLK -> GP1
DIO -> GP0
VCC -> 3.3V (pin 36)
GND -> GND (pin 38)
Arduino Nano ESP32:
TM1637 Module Arduino Nano ESP32
───────────── ──────────────────
CLK -> D21 (GPIO21)
DIO -> D22 (GPIO22)
VCC -> 3.3V
GND -> GND
Arduino Nano RP2040 Connect:
TM1637 Module Arduino Nano RP2040 Connect
───────────── ───────────────────────────
CLK -> D1 (GP1)
DIO -> D0 (GP0)
VCC -> 3.3V
GND -> GND
"""
from DIYables_MicroPython_4Digit7Segment_TM1637 import Display4Digit7SegmentTM1637
import time
# Pin configuration - change the pins to match your wiring and board
# ESP32 / Arduino Nano ESP32: CLK=21, DIO=22
# Raspberry Pi Pico / Nano RP2040: CLK=1, DIO=0
CLK_PIN = 21
DIO_PIN = 22
display = Display4Digit7SegmentTM1637(CLK_PIN, DIO_PIN)
while True:
# Set individual numbers on each digit position
display.clear()
display.set_number(0, 1)
display.set_number(1, 2)
display.set_number(2, 3)
display.set_number(3, 4)
# Display shows "1234"
time.sleep(2)
# Turn colon on — display shows "12:34"
display.set_colon(True)
time.sleep(2)
# Turn colon off — display shows "1234"
display.set_colon(False)
time.sleep(2)
# Set individual characters on each digit position
display.clear()
display.set_char(0, 'H')
display.set_char(1, 'E')
display.set_char(2, 'L')
display.set_char(3, 'P')
# Display shows "HELP"
time.sleep(2)
# Mix characters and numbers with colon
display.clear()
display.set_char(0, 'A')
display.set_number(1, 3)
display.set_char(2, 'b')
display.set_number(3, 7)
display.set_colon(True)
# Display shows "A3:b7"
time.sleep(2)
# Blinking colon effect with individual digits
display.clear()
display.set_number(0, 1)
display.set_number(1, 2)
display.set_number(2, 3)
display.set_number(3, 0)
for _ in range(5): # Blink 5 times
display.set_colon(True)
time.sleep(0.5)
display.set_colon(False)
time.sleep(0.5)
time.sleep(1)
Individual Digits Reference
| Method Call | Description |
|---|---|
| display.set_number(position, number) | Set a single digit (0-9) at position 0-3 |
| display.set_char(position, char) | Set a character at position 0-3 |
| display.set_colon(True) | Turn on the colon between digit 1 and digit 2 |
| display.set_colon(False) | Turn off the colon |
You can mix set_number(), set_char(), and set_colon() to build custom displays digit by digit.
ESP32 Code — Blink Display
"""
Example: Blink integer and text on 4-digit 7-segment display.
Uses off() to stop the display and on() to restart it.
Works with: ESP32, Raspberry Pi Pico, Arduino Nano ESP32, Arduino Nano R1 WiFi
Product page: https://diyables.io/products/4-digit-7-segment-display-led-tm1637-with-colon
Wiring guide:
ESP32:
TM1637 Module ESP32
───────────── ──────
CLK -> GPIO21
DIO -> GPIO22
VCC -> 3.3V
GND -> GND
Raspberry Pi Pico:
TM1637 Module Raspberry Pi Pico
───────────── ─────────────────
CLK -> GP1
DIO -> GP0
VCC -> 3.3V (pin 36)
GND -> GND (pin 38)
Arduino Nano ESP32:
TM1637 Module Arduino Nano ESP32
───────────── ──────────────────
CLK -> D21 (GPIO21)
DIO -> D22 (GPIO22)
VCC -> 3.3V
GND -> GND
Arduino Nano RP2040 Connect:
TM1637 Module Arduino Nano RP2040 Connect
───────────── ───────────────────────────
CLK -> D1 (GP1)
DIO -> D0 (GP0)
VCC -> 3.3V
GND -> GND
"""
from DIYables_MicroPython_4Digit7Segment_TM1637 import Display4Digit7SegmentTM1637
import time
# Pin configuration - change the pins to match your wiring and board
# ESP32 / Arduino Nano ESP32: CLK=21, DIO=22
# Raspberry Pi Pico / Nano RP2040: CLK=1, DIO=0
CLK_PIN = 21
DIO_PIN = 22
display = Display4Digit7SegmentTM1637(CLK_PIN, DIO_PIN)
while True:
# Blink an integer
display.print(1234)
for _ in range(5): # Blink 5 times
display.off()
time.sleep(0.3)
display.on()
time.sleep(0.3)
time.sleep(1)
# Blink text
display.print("HELP")
for _ in range(5): # Blink 5 times
display.off()
time.sleep(0.3)
display.on()
time.sleep(0.3)
time.sleep(1)
Blink Reference
Use display.off() to turn the display off and display.on() to turn it back on. The display data is preserved — on() restores the previous content without needing to call print() again.
Library Reference
See DIYables_MicroPython_4Digit7Segment_TM1637 Library Reference for the complete API documentation including all constructors, methods, and constants.
Next Steps
- Combine with a DS3231 RTC module to build a real-time clock.
- Add a DHT11/DHT22 sensor to display live temperature readings.
- Use buttons to switch between clock mode and temperature mode.