Learn how to use the TM1637 4-Digit 7-Segment Display with the Raspberry Pi Pico programmed with MicroPython. We provide instructions on how to wire the display to the board, install the required library, and we’ll explain the basic commands to control the display.
New to the Raspberry Pi Pico? Check out our eBook: Learn Raspberry Pi Pico/Pico W with MicroPython.
Table of Contents:
- Introducing the TM1637 4-Digit LED 7-Segment Display
- Wiring the TM1637 4-Digit 7-Segment Display to the RPi Pico
- TM1637 MicroPython Library
- Testing the TM1637 Display (Basic Functions)
- TM1637 7-Segment Display with RPi Pico – Display Internal Temperature Sensor
Prerequisites – MicroPython Firmware
To follow this tutorial, you need MicroPython firmware installed on your Raspberry Pi Pico board. You also need an IDE to write and upload the code to your board.
The recommended MicroPython IDE for the Raspberry Pi Pico is Thonny IDE. Follow the next tutorial to learn how to install Thonny IDE, flash MicroPython firmware, and upload code to the board.
If you’re still getting started with the Raspberry Pi Pico, follow one of these getting-started guides:
- Getting Started with Raspberry Pi Pico 2 and Pico 2 W
- Getting Started with Raspberry Pi Pico (and Pico W)
Introducing the TM1637 4-Digit LED 7-Segment Display
The TM1637 4-Digit LED 7-Segment display is a display module that combines four 7-segment digits on a single display that can be controlled via the TM1637 driver. The particular module we’re using here has four digits separated by a colon between the second and third digits.
There are similar modules with dots between the digits.
There are also similar modules with six 7-segment digits. These require a different library from the one we’ll use in this tutorial.
Note: I tried to use my six 7-segment display module, but it seems that there are many of those displays that come faulty by default. I couldn’t make mine work. So, this tutorial will be only about the one with four digits with a colon in the middle.
Where to Buy?
You can check our Maker Advisor Tools page to compare the TM1637 4-Digit 7-Segment Display module price in different stores:
You can use the preceding links or go directly to MakerAdvisor.com/tools to find all the parts for your projects at the best price!
Wiring the TM1637 4-Digit 7-Segment Display to the RPi Pico
Wiring the display to the RPi Pico is quite simple, as it only requires two digital pins: CLK and DI/O.
| TM1637 Display | RPi Pico |
| CLK | Any digital pin (for example: GPIO 21)* |
| DIO | Any digital pin (for example: GPIO 20)* |
| VCC | VIN |
| GND | GND |
* you can use any other suitable GPIOs. Check the RPi Pico Pinout Guide:
TM1637 MicroPython Library
To make it easy to interface with the TM1637 Display, we’ll use a forked version of this TM1637 MicroPython module.
Follow the next steps to install it.
1. Click here to download our forked version of the tm1637.py file.
"""
MicroPython TM1637 quad 7-segment LED display driver
https://github.com/mcauser/micropython-tm1637
MIT License
Copyright (c) 2016-2023 Mike Causer
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
"""
__version__ = '1.3.0'
from micropython import const
from machine import Pin
from time import sleep_us, sleep_ms
TM1637_CMD1 = const(64) # 0x40 data command
TM1637_CMD2 = const(192) # 0xC0 address command
TM1637_CMD3 = const(128) # 0x80 display control command
TM1637_DSP_ON = const(8) # 0x08 display on
TM1637_DELAY = const(10) # 10us delay between clk/dio pulses
TM1637_MSB = const(128) # msb is the decimal point or the colon depending on your display
# 0-9, a-z, blank, dash, star
_SEGMENTS = bytearray(b'\x3F\x06\x5B\x4F\x66\x6D\x7D\x07\x7F\x6F\x77\x7C\x39\x5E\x79\x71\x3D\x76\x06\x1E\x76\x38\x55\x54\x3F\x73\x67\x50\x6D\x78\x3E\x1C\x2A\x76\x6E\x5B\x00\x40\x63')
class TM1637(object):
"""Library for quad 7-segment LED modules based on the TM1637 LED driver."""
def __init__(self, clk, dio, brightness=7):
self.clk = clk
self.dio = dio
if not 0 <= brightness <= 7:
raise ValueError("Brightness out of range")
self._brightness = brightness
self.clk.init(Pin.OUT, value=0)
self.dio.init(Pin.OUT, value=0)
sleep_us(TM1637_DELAY)
self._write_data_cmd()
self._write_dsp_ctrl()
def _start(self):
self.dio(0)
sleep_us(TM1637_DELAY)
self.clk(0)
sleep_us(TM1637_DELAY)
def _stop(self):
self.dio(0)
sleep_us(TM1637_DELAY)
self.clk(1)
sleep_us(TM1637_DELAY)
self.dio(1)
def _write_data_cmd(self):
# automatic address increment, normal mode
self._start()
self._write_byte(TM1637_CMD1)
self._stop()
def _write_dsp_ctrl(self):
# display on, set brightness
self._start()
self._write_byte(TM1637_CMD3 | TM1637_DSP_ON | self._brightness)
self._stop()
def _write_byte(self, b):
for i in range(8):
self.dio((b >> i) & 1)
sleep_us(TM1637_DELAY)
self.clk(1)
sleep_us(TM1637_DELAY)
self.clk(0)
sleep_us(TM1637_DELAY)
self.clk(0)
sleep_us(TM1637_DELAY)
self.clk(1)
sleep_us(TM1637_DELAY)
self.clk(0)
sleep_us(TM1637_DELAY)
def brightness(self, val=None):
"""Set the display brightness 0-7."""
# brightness 0 = 1/16th pulse width
# brightness 7 = 14/16th pulse width
if val is None:
return self._brightness
if not 0 <= val <= 7:
raise ValueError("Brightness out of range")
self._brightness = val
self._write_data_cmd()
self._write_dsp_ctrl()
def write(self, segments, pos=0):
"""Display up to 6 segments moving right from a given position.
The MSB in the 2nd segment controls the colon between the 2nd
and 3rd segments."""
if not 0 <= pos <= 5:
raise ValueError("Position out of range")
self._write_data_cmd()
self._start()
self._write_byte(TM1637_CMD2 | pos)
for seg in segments:
self._write_byte(seg)
self._stop()
self._write_dsp_ctrl()
def encode_digit(self, digit):
"""Convert a character 0-9, a-f to a segment."""
return _SEGMENTS[digit & 0x0f]
def encode_string(self, string):
"""Convert an up to 4 character length string containing 0-9, a-z,
space, dash, star to an array of segments, matching the length of the
source string."""
segments = bytearray(len(string))
for i in range(len(string)):
segments[i] = self.encode_char(string[i])
return segments
def encode_char(self, char):
"""Convert a character 0-9, a-z, space, dash or star to a segment."""
o = ord(char)
if o == 32:
return _SEGMENTS[36] # space
if o == 42:
return _SEGMENTS[38] # star/degrees
if o == 45:
return _SEGMENTS[37] # dash
if o >= 65 and o <= 90:
return _SEGMENTS[o-55] # uppercase A-Z
if o >= 97 and o <= 122:
return _SEGMENTS[o-87] # lowercase a-z
if o >= 48 and o <= 57:
return _SEGMENTS[o-48] # 0-9
raise ValueError("Character out of range: {:d} '{:s}'".format(o, chr(o)))
def hex(self, val):
"""Display a hex value 0x0000 through 0xffff, right aligned."""
string = '{:04x}'.format(val & 0xffff)
self.write(self.encode_string(string))
def number(self, num):
"""Display a numeric value -999 through 9999, right aligned."""
# limit to range -999 to 9999
num = max(-999, min(num, 9999))
string = '{0: >4d}'.format(num)
self.write(self.encode_string(string))
def numbers(self, num1, num2, colon=True):
"""Display two numeric values -9 through 99, with leading zeros
and separated by a colon."""
num1 = max(-9, min(num1, 99))
num2 = max(-9, min(num2, 99))
segments = self.encode_string('{0:0>2d}{1:0>2d}'.format(num1, num2))
if colon:
segments[1] |= 0x80 # colon on
self.write(segments)
def temperature(self, num):
if num < -9:
self.show('lo') # low
elif num > 99:
self.show('hi') # high
else:
string = '{0: >2d}'.format(num)
self.write(self.encode_string(string))
self.write([_SEGMENTS[38], _SEGMENTS[12]], 2) # degrees C
def temperature_f(self, num):
if num < -9:
self.show('lo') # low
elif num > 99:
self.show('hi') # high
else:
string = '{0: >2d}'.format(num)
self.write(self.encode_string(string))
self.write([_SEGMENTS[38], _SEGMENTS[15]], 2) # degrees F
def show(self, string, colon=False):
segments = self.encode_string(string)
if len(segments) > 1 and colon:
segments[1] |= 128
self.write(segments[:4])
def scroll(self, string, delay=250):
segments = string if isinstance(string, list) else self.encode_string(string)
data = [0] * 8
data[4:0] = list(segments)
for i in range(len(segments) + 5):
self.write(data[0+i:4+i])
sleep_ms(delay)
class TM1637Decimal(TM1637):
"""Library for quad 7-segment LED modules based on the TM1637 LED driver.
This class is meant to be used with decimal display modules (modules
that have a decimal point after each 7-segment LED).
"""
def encode_string(self, string):
"""Convert a string to LED segments.
Convert an up to 4 character length string containing 0-9, a-z,
space, dash, star and '.' to an array of segments, matching the length of
the source string."""
segments = bytearray(len(string.replace('.','')))
j = 0
for i in range(len(string)):
if string[i] == '.' and j > 0:
segments[j-1] |= TM1637_MSB
continue
segments[j] = self.encode_char(string[i])
j += 1
return segments
2. Copy the code to a file on Thonny IDE;
3. Go to File > Save as…
4. Select save to “Raspberry Pi Pico“:
5. Save the file with the name tm1637.py (don’t change the name).
With the module loaded to the Pico, now you can use the library functionalities in your code to interface with the TM1637 display.
Testing the TM1637 Display (Basic Functions)
The following example shows most of the functions supported by the library. This is a modified and simplified version of the example provided by the library.
# Rui Santos & Sara Santos - Random Nerd Tutorials
# Complete project details at https://RandomNerdTutorials.com/raspberry-pi-pico-tm1637-micropython/
import tm1637
from machine import Pin
from time import sleep
# Initialize display (adjust pins if needed)
display = tm1637.TM1637(clk=Pin(21), dio=Pin(20))
# Set display brightness
display.brightness(7)
while True:
# all LEDS on "88:88"
display.write([127, 255, 127, 127])
sleep(1)
# all LEDS off
display.write([0, 0, 0, 0])
sleep(1)
# show "0123"
display.write([63, 6, 91, 79])
sleep(1)
# show "COOL"
display.write([0b00111001, 0b00111111, 0b00111111, 0b00111000])
sleep(1)
# show "HELP"
display.show('help')
sleep(1)
# display "dEAd", "bEEF"
display.hex(0xdead)
sleep(1)
display.hex(0xbeef)
sleep(1)
# show "12:59"
display.numbers(12, 59)
sleep(1)
# show "-123"
display.number(-123)
sleep(1)
# show temperature '24*C'
display.temperature(24)
sleep(1)
# show temperature '75*F'
display.temperature_f(75)
sleep(1)
# display scrolling text
display.scroll('Random Nerd Tutorials', delay=500)
sleep(1)
Now, let’s take a quick look at how the code works to understand how to use the library functions to control the display.
Initialize the Display
The following line initializes the display. You can modify it to use different pins.
display = tm1637.TM1637(clk=Pin(21), dio=Pin(20))Set the Brightness
To set the display brightness, you just need to use the brightness() method on the display object. Pass a number between 0 (minimum brightness) and 7 (maximum brightness).
# Set display brightness
display.brightness(7)Writing Segments
You can use the write() method on the display object to control individual segments of each character.
The TM1637 display comes with four 7-segment display digits. You can manually control individual segments of each digit with the write() method on the display object.
One byte (7 lower bits) for each segment. The 8th bit (MSB) is for the colon and only on the 2nd segment.
For example:
| segment | bit |
| A | 0 |
| B | 1 |
| C | 2 |
| D | 3 |
| E | 4 |
| F | 5 |
| G | 6 |
Bit 1 turns a segment ON, and bit 0 turns a segment off.
For example, to turn on segments A, B, and C, you’d have a byte like 0b0000111.
The byte starts with the G and ends with the A. For example:
- 0b0000110 turns segments C and B on.
You can use 0b0000110 or the corresponding hex or decimal number. See the table provided by the library documentation.
The demo shows different examples:
# all LEDS on "88:88"
display.write([127, 255, 127, 127])
sleep(1)
# all LEDS off
display.write([0, 0, 0, 0])
sleep(1)
# show "0123"
display.write([63, 6, 91, 79])
sleep(1)
# show "COOL"
display.write([0b00111001, 0b00111111, 0b00111111, 0b00111000])
sleep(1)Display Strings
To display strings, use the show() method and pass as an argument the string you want to display.
# show "HELP"
display.show('help')Display a Number
Use the numbers() method if you want to display two numbers (with two digits) on each side of the colon. For example:
# show "12:59"
display.numbers(12, 59)To display a number, use the number() method. It accepts negative numbers. The number shouldn’t have more than four digits.
# show "-123"
display.number(-123)Display Temperature Values
If you want to display temperature values (with two digits) with the ºC and ºF symbols, you can use the temperature() and temperature_f() functions on the display object. For example, in the code:
# show temperature '24*C'
display.temperature(24)
sleep(1)
# show temperature '75*F'
display.temperature_f(75)
sleep(1)Display Scrolling Text
There is a very useful function if you want to display text with more than four characters. The scroll() function allows you to scroll a String on the display from right to left with adjustable speed.
The first argument is the string you want to display, and the second argument is the speed offset in milliseconds. For example:
# display scrolling text
display.scroll('Random Nerd Tutorials', delay=500)Demonstration
Upload (File > Save as > Raspbberry Pi Pico > save the file with the name main.py) the code to your board using Thonny IDE.
Or run it directly on the board from the computer using the green run button (with this option, the code will only run when the board is connected to the computer).
Don’t forget that you must have uploaded the tm1637.py library previously.
The display will be running the demo code, showing the different use cases.
TM1637 7-Segment Display with RPi Pico – Display Internal Temperature Sensor
To show you a practical example of using the TM1637 7-Segment display, we’ll create a simple project to display the RPi Pico internal temperature on the screen.
- We get the Pico’s internal temperature.
- The temperature is displayed on the TM1637 display in Celsius degrees.
- The temperature is also displayed in Fahrenheit degrees.
To get readings from the Pico’s internal temperature sensor, we’ll use the pico_temp_sensor class from the picozero package. Follow the next instructions to install the package before proceeding.
Installing the picozero Package
You need to install the picozero package before proceeding.
- Go to Tools > Manage Packages.
- Search for picozero.
- Click on the first picozero @ PyPi option.
- Finally, click Install.
After a few seconds, the package will be installed.
Code
You can upload the following code to your board.
# Rui Santos & Sara Santos - Random Nerd Tutorials
# Complete project details at https://RandomNerdTutorials.com/raspberry-pi-pico-tm1637-micropython/
import tm1637
from picozero import pico_temp_sensor
from machine import Pin, Timer
import time
# Initialize display (adjust pins if needed)
display = tm1637.TM1637(clk=Pin(21), dio=Pin(20))
# Set display brightness
display.brightness(7)
# Convert from celsius to fahrenheit
def celsius_to_fahrenheit(temp_celsius):
temp_fahrenheit = temp_celsius * (9/5) + 32
return temp_fahrenheit
# Get temperature readings
def getTemperature(Timer):
# Declare these variables as globals
global temperature_c, temperature_f
# Reading and printing the internal temperature
temperature_c = pico_temp_sensor.temp
temperature_f = celsius_to_fahrenheit(temperature_c)
print(f'Internal temperature in Celsius: {temperature_c:.2f}')
print(f'Internal temperature in Fahrenheit: {temperature_f:.2f}')
# Get temperature for the first time
getTemperature(0)
# Create a periodic timer that gets new temperature readings
api_timer = Timer()
api_timer.init(mode=Timer.PERIODIC, period=60000, callback=getTemperature)
while True:
display.temperature(round(temperature_c))
time.sleep(5)
display.temperature_f(round(temperature_f))
time.sleep(5)
How Does the Code Work?
Let’s just take a quick look to see how the code works.
Start by including the required libraries.
import tm1637
from picozero import pico_temp_sensor
from machine import Pin, Timer
import timeInitialize the display and set the maximum brightness.
# Initialize display (adjust pins if needed)
display = tm1637.TM1637(clk=Pin(21), dio=Pin(20))
# Set display brightness
display.brightness(7)The getTemperature() function will get the Pico’s internal temperature sensor and save it in the temperature_c and temperature_f global variables.
# Get temperature readings
def getTemperature(Timer):
# Declare these variables as globals
global temperature_c, temperature_f
# Reading and printing the internal temperature
temperature_c = pico_temp_sensor.temp
temperature_f = celsius_to_fahrenheit(temperature_c)
print(f'Internal temperature in Celsius: {temperature_c:.2f}')
print(f'Internal temperature in Fahrenheit: {temperature_f:.2f}')This function will then be called by a timer, which is why we need to add a Timer argument to the function.
After that, we call the getTemperature() function when the code first runs.
# Get temperature for the first time
getTemperature(0)We create a timer that will call the getTemperature() function every 600000 milliseconds (10 minutes) to get the latest Pico’s internal temperature.
# Create a periodic timer that gets new temperature readings
api_timer = Timer()
api_timer.init(mode=Timer.PERIODIC, period=60000, callback=getTemperature)To learn more about timer interrupts with the Raspberry Pi Pico, check out this tutorial: Raspberry Pi Pico with Interrupts: External and Timer Interrupts (MicroPython).
Finally, we create a while True loop to continuously display weather data. We display the temperature in Celsius and in Fahrenheit.
while True:
display.temperature(round(temperature_c))
time.sleep(5)
display.temperature_f(round(temperature_f))
time.sleep(5)To display the temperature in Celsius, we call the temperature() function on the display object. We need to round the temperature because the function only accepts numbers with two digits.
display.temperature(round(temperature_c))Finally, we call the temperature_f() function to display the temperature in Fahrenheit.
display.temperature_f(round(temperature_f))Demonstration
Run or upload (File > Save as > Raspberry Pi Pico > save the file with the name main.py) the code to your board using Thonny IDE.
Don’t forget that you must have uploaded the tm1637.py library previously and installed the picozero package.
You’ll get the current RPi Pico’s internal temperature on the screen in Celsius and Fahrenheit.
You’ll get the same information on the MicroPython Shell.
Wrapping Up
In this tutorial, you learned how to interface the TM1637 4-digit 7-segment display with the Raspberry Pi Pico programmed with MicroPython. As you’ve seen, it is straightforward to display data on the screen thanks to the tm1637.py module.
You can display a wide variety of data on the display, but the most common uses are to display temperature and to create a digital clock or a countdown timer.
We hope you’ve found this guide useful. We have Raspberry Pi Pico guides for other displays that you may be interested in:
- Raspberry Pi Pico with I2C LCD Display (MicroPython)
- Raspberry Pi Pico: SSD1306 OLED Display (MicroPython)
Learn more about programming the Raspberry Pi Pico using MicroPython with our eBook:
