Build a WiFi-connected LED matrix clock and MQTT smart display using ESP8266

I wanted to build a simple LED matrix display that could do more than just show a clock.

The idea was to have a display that could:

1. Show the current time
2. Synchronize time automatically using NTP
3. Show the day and date
4. Receive messages through MQTT
5. Display notifications from a smart-home system
6. Publish its own status through MQTT
7. Be configured completely from a web browser
8. Allow the display hardware configuration to be changed without recompiling the firmware

That became SentraMatrix.

SentraMatrix is an open-source ESP8266-based LED matrix clock and smart display controller using MAX7219 LED matrix modules.

The entire configuration is handled through a browser-based interface, so after flashing the firmware you don't need to modify the source code just to change things like the display type, number of modules, brightness, Wi-Fi, timezone, or MQTT settings.

The project is completely local-network based and does not require a cloud service.

What We Are Building

The finished project uses an ESP8266 NodeMCU connected to one or more MAX7219 LED matrix modules.

For my setup, I am using four MAX7219 modules connected in series.

The ESP8266 handles:

1. Wi-Fi connectivity
2. NTP time synchronization
3. Display control
4. MQTT communication
5. Web configuration
6. Persistent configuration storage

The display can operate as a standalone clock, or you can use MQTT to send custom messages to it.

For example, a smart-home system could send:

or:

or:

and the message will scroll across the display.

Features

SentraMatrix currently supports:

1. NTP time synchronization
2. 12-hour and 24-hour clock
3. Scrolling day display
4. Scrolling date display
5. Multiple date formats
6. Digit swipe-up animation
7. Custom clock font
8. Wi-Fi auto connection
9. Wi-Fi configuration portal
10. MQTT incoming message display
11. MQTT periodic device status
12. Boot status display
13. Browser-based configuration UI
14. MAX7219 hardware configuration
15. Configurable GPIO pins
16. Configurable module count
17. Adjustable brightness
18. Timezone configuration
19. Persistent settings using EEPROM
20. GitHub Actions build and release workflow

Parts Required

Hardware

You will need:

1. ESP8266 NodeMCU

I am using an ESP8266 NodeMCU v2.

Any compatible ESP8266 board with SPI support should work, although the pin labels may be different depending on the board.

2. MAX7219 LED Matrix Module

You can use one or multiple MAX7219-based LED matrix modules.

My tested setup uses:

Each module is an 8×8 matrix, giving a combined display of:

when four modules are connected together.

3. 5V Power Supply

For four modules, I recommend using a suitable 5V power supply capable of supplying at least 2A.

4. USB Cable

A USB cable is required for flashing the ESP8266.

Software Required

There are two ways to use SentraMatrix.

Option 1 — Flash the pre-built firmware

This is the easiest method.

You can download the .bin firmware from the GitHub Releases section and flash it directly to the ESP8266.

You don't need PlatformIO or the source code for this method.

Option 2 — Build the firmware yourself

If you want to modify the firmware or contribute to the project, you can clone the repository and build it using PlatformIO.

The project is built using:

1. ESP8266
2. Arduino framework
3. PlatformIO

For the default configuration, connect the MAX7219 module to the NodeMCU as follows.

MAX7219NodeMCUGPIO

DIN -> D7 -> GPIO13

CLK -> D5 -> GPIO14

CS -> D4 -> GPIO2

VCC -> 5V —

GND -> GND —

The important part is the three SPI/control connections:

If you are using multiple MAX7219 modules, connect them in series using the module's output connection to the next module's input.

The nice thing about SentraMatrix is that these pins are not permanently locked.

You can change the display pin configuration later from the Hardware page of the web interface.

The complete source code and firmware are available in the public GitHub repository.

Search GitHub for:

The repository contains the complete source code, PlatformIO configuration, firmware build workflow, and documentation.

The project also includes GitHub Actions for automatically building the firmware.

If you don't want to build the firmware yourself, download the latest .bin file from the Releases section.

At the time of writing this tutorial, the release being used is:

Connect the NodeMCU to your computer using USB.

You can use an ESP8266-compatible web flasher such as an online ESP flashing tool.

Select the appropriate serial device.

Use:

When adding the firmware, use:

Then select the downloaded SentraMatrix .bin file and start the programming process.

Wait until the flashing process is complete.

After the firmware has been successfully uploaded, restart the NodeMCU.

When SentraMatrix starts for the first time, it will try to connect to the configured Wi-Fi network.

If no Wi-Fi credentials are available, it will create its own Wi-Fi access point.

The default network is:

Connect your phone or computer to this network.

The configuration portal should open automatically.

If it doesn't, open the captive portal manually.

From here, select your normal 2.4 GHz Wi-Fi network and enter the password.

Save the configuration.

SentraMatrix will restart and connect to your network.

Once the ESP8266 successfully connects to Wi-Fi, the IP address will be shown on the LED matrix during startup.

For example:

The actual address will depend on your network.

You can also connect the NodeMCU to the serial console at:

The serial console provides useful information during startup, including Wi-Fi connection status, IP address, NTP synchronization, and MQTT connection status.

The boot sequence is designed to make troubleshooting easier.

Open a browser on a device connected to the same network.

Enter the IP address shown on the display.

For example:

You should now see the SentraMatrix web interface.

The web UI is divided into several sections:

Let's go through each one.

The Home page is the main status dashboard.

It provides an overview of the device.

Depending on the configuration, you can see information such as:

1. Device status
2. Wi-Fi status
3. Display configuration
4. Time status
5. MQTT status

This is the first page I normally check when troubleshooting the device.

The Hardware page is where SentraMatrix becomes much more flexible than a typical fixed MAX7219 project.

Here you can configure the physical display setup.

Display pins

You can configure:

This means you don't necessarily need to modify and recompile the firmware if your hardware wiring is different.

MAX7219 module type

You can select the appropriate MAX7219 hardware type.

The tested configuration for my setup is:

Number of modules

You can also configure the number of chained modules.

For my setup:

Brightness

Brightness can be configured from:

This can be changed directly from the web interface.

For example, you can lower the brightness at night without changing the firmware.

The WiFi page allows you to configure the network connection.

You can scan for available networks and configure the device's Wi-Fi settings.

This is useful if you move the display to another network.

You don't need to recompile or re-flash the firmware.

Simply update the Wi-Fi configuration from the web UI.

The Time page handles the clock configuration.

SentraMatrix uses NTP to synchronize the time automatically.

You can configure:

1. NTP server
2. Timezone / UTC offset
3. 12-hour format
4. 24-hour format
5. Date format

For example, the timezone needs to be configured according to your location.

For India, the UTC offset is:

The date can also be configured using different formats such as:

You can also disable the time functionality if you want to use SentraMatrix primarily as an MQTT message display.

This is one of the main features of SentraMatrix.

MQTT allows other devices and applications on your network to send messages to the display.

For example, a Home Assistant installation can send notifications to SentraMatrix.

Open the MQTT page.

Enable MQTT and configure:

SentraMatrix subscribes to the configured message topic.

When a message arrives, it is displayed on the LED matrix.

The default message topic in the project is:

You can send a message using Mosquitto:

The message will be received by SentraMatrix and displayed on the matrix.

For example:

will scroll across the display.

This makes the display useful for much more than just showing the time.

SentraMatrix can also publish its own status periodically.

The default status topic is:

A status payload can contain information such as:

This can be useful if you want to monitor the display from another system.

For example, you could use Home Assistant, Node-RED, or another MQTT client to monitor the device.

Because SentraMatrix uses MQTT, it can easily be used with Home Assistant.

For example, you could send a notification when a door opens.

A Home Assistant MQTT action can publish:

The display will receive the message and show it immediately.

You can use the same approach for:

1. Doorbell notifications
2. Motion alerts
3. Temperature
4. Security alerts
5. Appliance status
6. Server notifications
7. Custom smart-home messages

If you want to modify SentraMatrix, clone the GitHub repository:

Open the project using PlatformIO.

Then build it with:

To upload the firmware directly:

You can also use the Upload button from the PlatformIO interface.

The project is organized into separate modules so that different parts of the firmware are easier to maintain.

The main modules are separated by responsibility:

Display handles the MAX7219 and LED matrix.

Clock manager handles NTP, time, day and date.

WiFi manager handles Wi-Fi and the configuration AP.

Web server provides the browser-based configuration interface.

MQTT manager handles MQTT communication.

Settings handles persistent configuration.

This makes it easier to extend the project later.

SentraMatrix uses several open-source libraries:

LibraryPurpose

MD_Parola

LED matrix text effects

MD_MAX72XX

MAX7219/MAX7221 driver

WiFiManager

Wi-Fi configuration

PubSubClient

MQTT communication

One important detail is the WiFiManager version.

For the current build, use:

Do not upgrade past this version for this particular build, because newer versions may cause ESP8266 compatibility issues.

There are many ESP8266 and MAX7219 clock projects available.

The main reason I built SentraMatrix was to make the display configurable without repeatedly modifying the firmware.

Instead of changing something like:

and rebuilding the firmware, the hardware configuration can be changed through the browser.

The same idea applies to:

1. Brightness
2. Module count
3. Wi-Fi
4. Timezone
5. Time format
6. Date format
7. MQTT
8. MQTT credentials
9. Topics

The goal is to make the firmware reusable across different MAX7219 display builds.

And that's it.

We now have a Wi-Fi-connected ESP8266 LED matrix display that can work as a clock, date display, and MQTT notification display.

The complete workflow is:

Once everything is configured, the display can run completely independently on your local network.

And because it uses MQTT, it can be connected to almost any home automation or IoT system that supports MQTT.

I have also recorded a complete setup and demonstration video showing:

1. Downloading the firmware
2. Flashing the NodeMCU
3. First boot
4. Wi-Fi configuration
5. Web UI
6. Hardware configuration
7. Brightness control
8. Time configuration
9. MQTT configuration
10. Sending an MQTT message
11. Displaying the message on the matrix

You can watch the complete demonstration in the video accompanying this project.

The complete SentraMatrix source code and firmware are available on GitHub.

Repository:

The project is open source and released under the MIT License.

Display is not showing anything

Check:

1. 5V power supply
2. GND connection
3. DIN connection
4. CLK connection
5. CS connection
6. MAX7219 module type
7. Number of modules configured

Also verify that the selected hardware configuration matches your actual module.

ESP8266 cannot connect to Wi-Fi

Make sure the network is a 2.4 GHz Wi-Fi network.

If no saved Wi-Fi credentials are available, connect to:

using:

and configure the network again.

MQTT is not connecting

Check:

1. MQTT broker IP/hostname
2. MQTT port
3. Username
4. Password
5. Network connectivity
6. MQTT topic configuration

You can also check the serial console at:

to see the MQTT connection status.

Wrong characters or display orientation

Check the selected MAX7219 hardware type.

Different MAX7219 modules can have different physical arrangements, so selecting the correct module type is important.

There are several features I would like to add in future versions:

1. OTA firmware updates
2. Factory reset from the web UI
3. Configuration backup and restore
4. REST API
5. Multiple display zones
6. Scheduled messages
7. Temperature and humidity sensors
8. Home Assistant MQTT Discovery
9. Mobile-optimized web interface
10. Custom message scroll speed

SentraMatrix started as a simple ESP8266 + MAX7219 LED matrix project, but evolved into a much more flexible smart display platform.

The idea is simple:

Build the hardware once, then configure everything from the browser.

Whether you want a network clock, an MQTT notification display, a Home Assistant status screen, or simply a programmable LED matrix, SentraMatrix gives you a starting point that can be extended for your own project.

If you build your own version, I'd love to see what you do with it.

Built for makers. Built to be configurable. Built to be extended.

⭐ If you find the project useful, consider starring the GitHub repository and sharing your build.