I thought I needed a graphics tool—turns out building a LED Matrix Icon Library on ESP32 was just bytes, bitmaps, and a little hacker zen.
When I first tinkered with an 8×8 LED matrix on my ESP32, I expected a quick win—just light it up with some icons and call it a day. But once I tried to load custom icons? That’s when things got interesting. Most tutorials either pointed to bloated libraries or assumed you were designing in Photoshop. As a FOSS-minded maker, I wanted more control, fewer dependencies, and something I could teach to students without a GUI. So I did what any stubborn dev would do—I built a minimal, byte-based LED Matrix Icon Library from scratch.
If you’re looking to render pixel icons on your ESP32 without sacrificing freedom or simplicity, this guide will walk you through a no-fluff approach that actually scales. Let’s get started.
Resources:
Why Use an LED Matrix with ESP32?
LED matrices are an excellent medium for displaying information or adding a visual flair to projects. Paired with the ESP32, they unlock numerous possibilities. The ESP32’s robust processing capabilities and built-in Wi-Fi enable real-time updates and remote control of the display. Whether you’re building a clock, a game, or a notification panel, an LED matrix driven by an ESP32 can handle it all with style.
Moreover, the ESP32’s ability to handle multiple devices simultaneously makes it an ideal choice for cascaded LED matrices, expanding the scope for large and complex displays.
· · ─ ·𖥸· ─ · ·
Introducing the ESP32 LED Matrix Icon Library
The ESP32 LED Matrix Icon Library simplifies the process of rendering icons on an LED matrix. Designed with user-friendliness in mind, this library allows developers to quickly load, display, and manage icons.
Key features include:
- Predefined icon sets for common applications.
- Easy creation of custom icons.
- Support for animations and transitions.
- Adjustable brightness settings.
This library is a must-have for anyone looking to add professional-quality visuals to their LED matrix projects.
How to Set Up the Library
- Install MicroPython: Flash your ESP32 with MicroPython firmware. Tools like Thonny make this process straightforward.
- Download Dependencies: Clone or download the MicroPython MAX7219 driver.
- Install the Library: Copy the ESP32 LED Matrix Icon Library files to your ESP32.
- Connect Your Hardware: Wire the ESP32 to your LED matrix. Ensure correct connections for power (3.3V or 5V), ground (GND), and data pins (e.g., DIN, CLK, CS).
- Test the Setup: Run a sample script from the library to verify the installation.
For a detailed guide, check our step-by-step tutorial on LED Matrix setups.
Creating and Using Icons
With the library installed, creating and displaying icons is straightforward. Define your icons as 8×8 or larger bitmaps, then load them using the library functions. Here’s an example:
from matrix_icons import IconLibrary
from max7219 import Matrix
def display_pattern(display, pattern):
"""Custom function to display a binary pattern on the LED matrix."""
for y, row in enumerate(pattern):
for x, pixel in enumerate(row):
display.pixel(x, y, pixel)
display.show()
# Initialize the library
matrix = Matrix()
icons = IconLibrary(matrix)
# Load and display an icon
icons.display_icon("heart")
# Using a custom pattern
pattern = [
"0,1,1,1,1,1,1,0",
"1,0,0,0,0,0,0,1",
"1,0,1,1,1,1,0,1",
"1,0,1,0,0,1,0,1",
"1,0,1,1,1,1,0,1",
"1,0,0,0,0,0,0,1",
"0,1,1,1,1,1,1,0",
"0,0,0,0,0,0,0,0",
]
# Display the custom pattern
display_pattern(matrix, pattern)Icons can also be animated or combined for transitions. This opens up possibilities for games, interactive displays, or notifications.
IconsLibrary
20 common icons for the 8×8 LED Matrix. This will grow over time.
HEART = [
"01100110",
"11111111",
"11111111",
"11111111",
"01111110",
"00111100",
"00011000",
"00000000",
]
HEART_HOLLOW = [
"01100110",
"10011001",
"10000001",
"10000001",
"01000010",
"00100100",
"00011000",
"00000000",
]
HEART_MD_HOLLOW = [
"00000000",
"01100110",
"01011010",
"01000010",
"00100100",
"00011000",
"00000000",
"00000000",
]
HEART_SM_HOLLOW = [
"00000000",
"00000000",
"00111100",
"00111100",
"00011000",
"00000000",
"00000000",
"00000000",
]
STAR = [
"00010000",
"01010100",
"00111000",
"11111110",
"00111000",
"01010100",
"00010000",
"00000000",
]
STAR_MD = [
"00000000",
"01010100",
"00111000",
"11111110",
"00111000",
"01010100",
"00000000",
"00000000",
]
STAR_SM = [
"00000000",
"00000000",
"00010000",
"00111000",
"00010000",
"00000000",
"00000000",
"00000000",
]
CIRCLE = [
"00111100",
"01111110",
"11111111",
"11111111",
"11111111",
"11111111",
"01111110",
"00111100",
]
CIRCLE_HOLLOW = [
"00111100",
"01000010",
"10000001",
"10000001",
"10000001",
"10000001",
"01000010",
"00111100",
]
TRIANGLE = [
"00000000",
"00011000",
"00011000",
"00111100",
"01111110",
"01111110",
"01111110",
"00000000",
]
TRIANGLE_HOLLOW = [
"00000000",
"00011000",
"00011000",
"00100100",
"01000010",
"01111110",
"01111110",
"00000000",
]
ARROW_UP = [
"00011000",
"00111100",
"01111110",
"11111111",
"00011000",
"00011000",
"00011000",
"00011000",
]
ARROW_UP_HOLLOW = [
"00011000",
"00100100",
"01000010",
"11111111",
"00011000",
"00011000",
"00011000",
"00011000",
]
ARROW_DOWN = [
"00011000",
"00011000",
"00011000",
"00011000",
"11111111",
"01111110",
"00111100",
"00011000",
]
ARROW_DOWN_HOLLOW = [
"00011000",
"00011000",
"00011000",
"00011000",
"11111111",
"01000010",
"00100100",
"00011000",
]
ARROW_LEFT = [
"00010000",
"00110000",
"01110000",
"11111111",
"11111111",
"01110000",
"00110000",
"00010000",
]
ARROW_LEFT_HOLLOW = [
"00010000",
"00110000",
"01010000",
"10011111",
"10011111",
"01010000",
"00110000",
"00010000",
]
ARROW_RIGHT = [
"00001000",
"00001100",
"00001110",
"11111111",
"11111111",
"00001110",
"00001100",
"00001000",
]
ARROW_RIGHT_HOLLOW = [
"00001000",
"00001100",
"00001010",
"11111001",
"11111001",
"00001010",
"00001100",
"00001000",
]
· · ─ ·𖥸· ─ · ·
Advanced Features
For those looking to go beyond static icons, the ESP32 LED Matrix Icon Library offers advanced features:
- Animations: Create scrolling or blinking effects for dynamic displays.
- Customizable Transitions: Smoothly switch between icons with fade-ins or slide effects.
- Brightness Control: Adjust display brightness programmatically to suit different environments.
These features make the library versatile, catering to both novice makers and seasoned developers.
· · ─ ·𖥸· ─ · ·
Conclusion: Small Pixels, Big Power
Build Icon Libraries That Keep You in Control
We often take pixel icons for granted—until we try to build them ourselves. As you’ve seen, crafting a lightweight LED Matrix Icon Library for ESP32 isn’t just doable, it’s empowering. Whether you’re working on a custom display, a wearable, or a classroom demo, doing it byte-by-byte gives you complete control and zero bloat. No proprietary drivers, no graphic editors—just clean code and pixel-perfect icons.
If you’re building tools, not toys, and believe in making things the open way, I share more like this every week.
👉 Subscribe here for ESP32 projects, minimalist tools, and byte-sized breakthroughs:
https://www.samgalope.dev/newsletter/
Like what you’re reading?
Help keep DevDigest
free and caffeine-powered
—buy me a coffee on Ko-fi.
Leave a Reply