Home Matrix Display

A retro-inspired 32×8 MAX7219 LED matrix display powered by an ESP32 and ESPHome, with display-ready information supplied by Home Assistant.

The display cycles through:

• Time
• Outside temperature
• Inside temperature
• Front-door lock status
• A custom Home Assistant message

Brightness is adjustable from Home Assistant, unavailable pages are skipped, and long messages receive enough display time to complete a full scroll.

Project links

• 3D-printable enclosure on MakerWorld

Hardware

• ESP32 development board
• Four-module MAX7219 8×8 LED matrix display
• Jumper wires
• Suitable USB power supply and cable
• 3D-printed enclosure

Wiring

MAX7219	ESP32
DIN	GPIO12
CLK	GPIO13
CS	GPIO15
GND	GND
VCC	Appropriate module supply

See docs/wiring.md before powering the project.

Repository layout

esphome/
├── matrix-display.yaml
├── secrets.example.yaml
├── fonts/
└── icons/

homeassistant/
└── packages/
    ├── home_matrix.yaml
    └── home_matrix_sources.yaml.example

The public files contain the real display logic. Passwords, encryption keys, and installation-specific Home Assistant entity IDs live in ignored local files and are never committed.

ESPHome setup

1. Copy esphome/secrets.example.yaml to esphome/secrets.yaml.
2. Replace every placeholder with your own value.
3. Follow esphome/fonts/README.md to install the required fonts locally.
4. Review the GPIO assignments for your board and matrix.
5. Validate and install esphome/matrix-display.yaml through ESPHome.

secrets.yaml is ignored by Git. Do not force-add it.

Home Assistant setup

Enable packages in configuration.yaml if they are not already enabled:

homeassistant:
  packages: !include_dir_named packages

Then:

1. Copy homeassistant/packages/home_matrix.yaml into your Home Assistant packages directory.
2. Copy home_matrix_sources.yaml.example to home_matrix_sources.local.yaml.
3. Replace the example weather, climate, and lock entity IDs with your own.
4. Check the Home Assistant configuration and restart Home Assistant.

The .local.yaml filename is ignored by this repository but still ends in .yaml, so Home Assistant can load it normally.

Home Assistant entities created

• sensor.home_matrix_time
• sensor.home_matrix_outside
• sensor.home_matrix_inside
• sensor.home_matrix_lock
• input_text.house_message
• input_number.house_display_brightness

Customization

Common settings are near the top of esphome/matrix-display.yaml:

• Normal page duration
• Scroll speed
• Scroll delay and dwell
• Matrix GPIO assignments
• Font selection

Home Assistant controls message text and brightness through the two helper entities listed above.

Security and privacy

• Never commit secrets.yaml, .env files, Home Assistant runtime data, or local source mappings.
• Generate a unique ESPHome API encryption key for this device.
• Use a fallback access-point password that is different from the home Wi-Fi password.
• Review git status before every commit.

Fonts and third-party assets

Third-party fonts are not covered by the eventual source-code license. See esphome/fonts/README.md for the required local files and their source.

License

The original source code and project documentation are available under the MIT License.

Third-party fonts and other third-party assets retain their own terms and are not relicensed by this project.