Is MAX7219 8x8 LED Matrix Display Compatible with Home Assistant (ESPHome)?
Electrical Specifications
Always confirm pin assignments against the manufacturer datasheet before wiring.
Compatibility Overview
Cascadable 8x8 red LED dot matrix display module for scrolling text clocks stock tickers and status banners.
Wiring MAX7219 8x8 LED Matrix Display to ESP32
| Module pin | ESP32 | Note |
|---|---|---|
| VCC | 5V | From the supply, not the ESP32's regulator: a 4-in-1 stick at full intensity draws over an amp. |
| GND | GND | |
| DIN | GPIO23 | MOSI. There is no data back from the display, so MISO stays free. |
| CS | GPIO5 | |
| CLK | GPIO18 |
Host pins are the ones the configuration on this page uses. Move a pin here and change it in the YAML — they are documented together so they cannot disagree.
Technical Specification Matrix
| Feature / Attribute | Specification / Status |
|---|---|
| Hardware Protocol | SPI Bus / 3.3V to 5V |
| Bridge Required | NO |
| Border Router Needed | None |
| Hardware Capabilities & Peripherals | 8x8 LED Dot Matrix Scrolling Text Banner Brightness Note: these entities come from the ESPHome configuration you flash — each one needs its matching component in that YAML before it appears. |
| Pairing Complexity | Plug-and-Play |
| Factory Reset Instruction | Hold BOOT button for 3s. |
Wire, Flash, Adopt, Check
Wire it up
Follow the wiring table above. The ESP32 pins there are the ones the configuration uses, so if you move one, change it in both places.
Flash the configuration
Create a new device in the ESPHome dashboard (the Home Assistant add-on) and paste the configuration below into it, or save it as emb_esp32_max7219_esphome.yaml and run esphome run emb_esp32_max7219_esphome.yaml. The first flash goes over USB. If it is not detected, hold BOOT button for 3s to put it in download mode. Every update after that is over the air.
Adopt it in Home Assistant
Settings → Devices & Services. A node on the same network shows up as a discovered ESPHome device within a minute of joining Wi-Fi; choose Configure and enter the API encryption key from your secrets.yaml. If discovery does not find it, add the ESPHome integration by hand with the node's IP address.
Check it works
HELLO appears on the matrix within a second of boot. Text that is rotated or mirrored is the FC-16 orientation; text on the first module only means num_chips is too low; random dots across the last module are the 3.3V logic margin.
ESPHome Configuration
Starting configuration for MAX7219 8x8 LED Matrix Display on ESP32. Untested on hardware — verify wiring and pins against your own board.
# ESPHome configuration for MAX7219 8x8 LED Matrix Display
# Host: ESP32. Pin numbers below are host-side defaults — any free
# GPIO will do, and you should change them to match your own wiring.
esphome:
name: emb_esp32_max7219_esphome
friendly_name: "MAX7219 8x8 LED Matrix Display"
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
api:
encryption:
key: !secret api_encryption_key
ota:
- platform: esphome
password: !secret ota_password
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
spi:
clk_pin: GPIO18
mosi_pin: GPIO23
miso_pin: GPIO19
# max7219digit is the dot-matrix platform; the plain max7219 platform is
# for 7-segment modules and will not drive this display.
# num_chips counts cascaded 8x8 blocks — the common blue 4-in-1 stick is 4.
font:
- file: "gfonts://Roboto"
id: matrix_font
size: 6
display:
- platform: max7219digit
cs_pin: GPIO5
num_chips: 4
intensity: 8
lambda: |-
it.print(0, 0, id(matrix_font), "HELLO");
Before you flash:
the !secret values come from your
secrets.yaml, and the GPIO numbers are host-side
defaults rather than properties of this part — change them to match how you actually wired it.
What Appears in Home Assistant
Displays have no entity in Home Assistant. To show HA state on it, pull the state into the node with text_sensor: platform: homeassistant and print it in the lambda.
Known Problems and Fixes
max7219digit, not max7219
Two platforms share the chip name. max7219 drives seven-segment modules; max7219digit drives dot matrices. The wrong one compiles and shows garbage.
3.3V logic on a 5V chip
At 5V the MAX7219 wants a high level of 3.5V, and the ESP32 gives 3.3V. It usually works and sometimes shows corruption on the last module. A 74HCT125 fixes it properly; a silicon diode in the display's 5V feed, dropping it to about 4.3V, brings 3.3V logic into spec and is the cheap fix.
FC-16 sticks come out rotated
The common blue 4-in-1 module wires its matrices rotated relative to the generic boards. If text is on its side or mirrored, try rotate_chip: 90 and reverse_enable: true before touching anything else.
Eight pixels of font
The matrix is eight rows tall. Fonts larger than about 8px clip; the config uses Roboto at 6px, and a pixel font at 8px fills the height better. scroll_mode: CONTINUOUS with scroll_speed handles text longer than the panel.
Brightness is current
intensity runs 0–15. At 15 a single 8x8 block can pull 300mA with every LED lit; four blocks exceed what a USB port supplies. Start at 8 and power it separately.
Report a Pinout Error or Submit Tested Code Snippets
Found a pin mapping quirk or built a custom ESPHome YAML driver for MAX7219 8x8 LED Matrix Display? Submit a pull request or report corrections to our index.