SENSORS/ACTUATORS

ESP32 MicroPython LED Matrix

This tutorial instructs you how to use ESP32 with LED matrix display modules. In detail, you will learn:

How to connnect ESP32 to 8x8 LED Matrix
How to connnect ESP32 to 32x8 LED Matrix
How to program ESP32 to display text on the LED Matrix
How to program ESP32 to scroll text on the LED Matrix
How to program ESP32 to display custom characters on the LED Matrix

Then, you can easily change the code for different LED matrices such as the 16x8 or 64x8 LED matrix.

Hardware Preparation

1	×	ESP-WROOM-32 Dev Module
1	×	USB Cable Type-C
1	×	FC-16 LED Matrix 32x8
1	×	FC-16 LED Matrix 8x8
1	×	Jumper Wires
1	×	Breadboard
1	×	DC Power Jack
1	×	5V Power Adapter
1	×	(Recommended) Screw Terminal Expansion Board for ESP32

Or you can buy the following sensor kits:

1	×	DIYables Sensor Kit (30 sensors/displays)
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.

Overview of LED Matrix

There are different types of LED matrices, but the MAX7219-based LED matrix is widely used with ESP32. The MAX7219-based LED matrix offers the following features:

The fundamental unit of an LED matrix is a block.
Each block contains an 8x8 LED matrix (64 LEDs) and a MAX7219 driver.
You can create LED matrices using a single block or by chaining multiple blocks together.
Pre-assembled LED matrices with multiple blocks are available, such as 4-in-1 or 8-in-1 configurations.
Alternatively, you can purchase individual blocks and connect them to form a matrix of your preferred size, with the option to chain 1-in-1, 4-in-1, or 8-in-1 LED matrices together.
The size of the LED matrix must be specified in your ESP32 code.

Pinout

A LED Matrix consists of one or more sections. Each section has two types of connectors:

Group of Input Pins:

VCC: Connect to the 5V.
GMD: Connect to the GND.
DIN: This is the Data pin. Connect to the SPI MOSI pin on the ESP32.
CS: Chip Select. Connect to any digital pin on the ESP32.
CLK: Clock pin. Connect to the SPI CLK pin on the ESP32.

Group of Output Pins:

VCC: Connect this to VCC on the next module.
GND: Connect this to GMD on the next module.
DOUT: Data Out. Connect to the DIN pin on the next module.
CS: Connect this to CS on the next module.
CLK: Connect this to CLK on the next module.

Wiring Diagram

Since the display consumes a significant amount of power (up to 1A at maximum brightness), it's recommended to avoid powering it through the 5V pin on the Arduino. Instead, use an external 5V power supply, allowing both the Arduino and the LED matrix to share power from the same 5V adapter.

If the LED matrix has only one block:

Attach the groups of input pins to the ESP32.
Do not connect the groups of output pins.

The wiring diagram between ESP32 MicroPython 8x8 LED matrix FC-16

This image is created using Fritzing. Click to enlarge image

If the LED matrix is already put together into several sections:

Connect the input pins group to the ESP32.
Do not connect the output pins group.

The wiring diagram between ESP32 MicroPython LED matrix display

This image is created using Fritzing. Click to enlarge image

If you put together the LED matrix using different components:

Connect the first block's input pins to the ESP32.
Connect each block's output pins to the next block's input pins.
Do not connect the last block's output pins.

ESP32 MicroPython 32x8 LED matrix wiring FC-16 diagram

This image is created using Fritzing. Click to enlarge image

ESP32 - LED Matrix Code

The below ESP32 MicroPython code is intended for a 32x8 FC-16 LED matrix display with four blocks. However, it can be modified to work with different sizes, such as 8x8, 16x8, 64x8, and others.

Detailed Instructions

Please follow these instructions step by step:

Ensure that Thonny IDE is installed on your computer.
Ensure that MicroPython firmware is installed on your ESP32 board by.
If this is your first time using a ESP32 with MicroPython, refer to the ESP32 MicroPython Getting Started tutorial for detailed instructions.
Connect the ESP32 board to the LED matrix 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 COM12 on Windows or /dev/ttyACM0 on Linux).
Navigate to the Tools Manage packages on the Thonny IDE.
Search “DIYables-MicroPython-LED-Matrix”, then find the LED Matrix library created by DIYables.
Click on DIYables-MicroPython-LED-Matrix, then click Install button to install LED Matrix library.

Copy the above code and paste it to the Thonny IDE's editor.
Save the script to your ESP32 board by:

Click the Save button, or use Ctrl+S keys.
In the save dialog, you will see two sections: This computer and MicroPython device. Select MicroPython device
Save the file as main.py

Click the green Run button (or press F5) to run the script. The script will execute.
Check out the LED matrix. It looks like the below:

ESP32 MicroPython LED matrix display text

The actual display lighting looks much better than in the picture. The camera cannot accurately capture the true colors of the lighting.

ESP32 MicroPython LED Matrix Code – Scrolling Text

When your message is too long for the LED matrix display, you can scroll it across the screen. The MicroPython code below for ESP32 demonstrates how to scroll a message on the LED matrix display.

""" This ESP32 MicroPython code was developed by newbiely.com This ESP32 MicroPython code is made available for public use without any restriction For comprehensive instructions and wiring diagrams, please visit: https://newbiely.com/tutorials/esp32-micropython/esp32-micropython-led-matrix """ from machine import Pin, SPI from time import sleep from DIYables_MicroPython_LED_Matrix import Max7219 # Initialize SPI and CS pin spi = SPI(1, baudrate=10000000, polarity=0, phase=0, sck=Pin(18), mosi=Pin(23)) cs = Pin(21, Pin.OUT) # Initialize the Max7219 class display = Max7219(spi, cs, num_matrices=4) display.set_brightness(15) # Adjust brightness from 0 to 15 def scroll_text(message): # Scroll the message from right to left display.print(message, col = 32) # Text starts from the right (x=32) and moves left for i in range(len(message) * 8 + 32): # Scroll through the entire message display.clear() display.print(message, col = 32 - i) # Move text from right to left display.show() sleep(0.05) # change speed here while True: scroll_text("Hello, DIYables") # Change text as needed

Detailed Instructions

Copy the provided ESP32 MicroPython code and paste it into Thonny's editor.
Save the MicroPython code to your ESP32 board.
Click the green Run button (or press F5) to execute the code.
Check out the LED matrix. The scrolling effect looks like the below:

ESP32 MicroPython LED Matrix - Custom Character

To display special characters or symbols such as a heart or an angry bird on an LED Matrix display, you need to use the character generator.

The character generator makes a character (64 pixels). You just need to follow these steps:

Click on each pixel to select/deselect

Copy below custom character code

Replace the custom_char in the ESP32 MicroPython code

The ESP32 MicroPython code below displays three custom characters on the 32x8 LED Matrix:

""" This ESP32 MicroPython code was developed by newbiely.com This ESP32 MicroPython code is made available for public use without any restriction For comprehensive instructions and wiring diagrams, please visit: https://newbiely.com/tutorials/esp32-micropython/esp32-micropython-led-matrix """ from machine import Pin, SPI from time import sleep from DIYables_MicroPython_LED_Matrix import Max7219 # Initialize SPI and CS pin spi = SPI(1, baudrate=10000000, polarity=0, phase=0, sck=Pin(18), mosi=Pin(23)) cs = Pin(21, Pin.OUT) # Initialize the Max7219 class display = Max7219(spi, cs, num_matrices=4) display.set_brightness(15) # Adjust brightness from 0 to 15 # Clear the display display.clear() display.show() custom_char_1 = [ 0b00000000, 0b00000000, 0b00000000, 0b11110000, 0b00000000, 0b00000000, 0b00000000, 0b00000000 ] custom_char_2 = [ 0b00000000, 0b01101100, 0b10010010, 0b10000010, 0b10000010, 0b01000100, 0b00101000, 0b00010000 ] custom_char_3 = [ 0b00000000, 0b00100000, 0b00010000, 0b11111000, 0b00010000, 0b00100000, 0b00000000, 0b00000000 ] # Clear the display display.clear() display.print_custom_char(custom_char_1, col = 0) display.print_custom_char(custom_char_2, col = 4) display.print_custom_char(custom_char_3, col = 11) display.show()

Detailed Instructions

Copy the provided ESP32 MicroPython code and paste it into Thonny's editor.
Save the MicroPython code to your ESP32 board.
Click the green Run button (or press F5) to execute the code.
Check out the LED matrix. It looks like the below:

ESP32 MicroPython LED matrix custom characters

Learn More

※ OUR MESSAGES

As freelancers, We are AVAILABLE for HIRE. See how to outsource your project to us
Please feel free to share the link of this tutorial. However, Please do not use our content on any other websites. We invested a lot of effort and time to create the content, please respect our work!