MatrixClock Firmware

ESP8266 LED clock firmware based on the jnetzhou/MatrixClock project (itself derived from the original hack-apollo/hack_clock) by HACK实验室 (HACK Labs), rebuilt from the example_2 source with PlatformIO and modified for AliExpress hardware compatibility.

Hardware Compatibility

This firmware has been tested on AliExpress ESP8266 LED clock modules like this one (many visually identical variants exist).

⚠️ Pinout Difference from Original Source

The original example_2 source code assumes SDA on GPIO5, but the AliExpress clock boards wire SDA to GPIO2 instead. This firmware has been corrected to use GPIO2 for SDA. If you port this code back to the original repo, remember to change the SDA pin definition.

Hardware

MCU: ESP8266 (Generic module)
Flash: GD25Q32C (4MB, QIO mode)
Display: 4× MAX7219-driven 8×8 LED matrix modules (SPI)
RTC: DS3231M (I2C)
Optional: Mercury tilt switch on GPIO16

Pinout (AliExpress Board)

Pin	Function
GPIO2	I2C SDA (RTC) — not GPIO5 as in original source
GPIO4	I2C SCL (RTC)
GPIO15	SPI CS (MAX7219)
GPIO13	SPI MOSI (MAX7219)
GPIO14	SPI SCK (MAX7219)
GPIO16	Mercury tilt switch (INPUT)

Building

pio run

Flashing

pio run --target upload

Flashing the Filesystem

The clock uses SPIFFS for config storage (/config.json). Upload an empty filesystem:

pio run --target uploadfs

Or create a custom data/config.json first:

{
  "ssid": "",
  "pass": "",
  "bri": 5,
  "t_format": 1,
  "zero": 0,
  "ntp": "pool.ntp.org",
  "std_offset": 60,
  "dst_enable": 1,
  "std_week": 1,
  "std_day": 0,
  "std_month": 10,
  "std_hour": 1,
  "dst_week": 1,
  "dst_day": 0,
  "dst_month": 3,
  "dst_hour": 2
}

Then upload:

pio run --target uploadfs

Configuration

On first boot (or if WiFi credentials are missing), the clock creates a WiFi AP:

SSID: MatrixClock_XXXXXX (last 3 bytes of MAC address)
IP: 10.10.10.1
Timeout: 5 minutes

Connect to the AP and open http://10.10.10.1 in a browser to configure WiFi and clock settings.

OTA Updates

After initial setup, firmware can be updated via OTA at http://<clock-ip>/update.

Username: nick
Password: nick

Source Files

File	Purpose
`MatrixClock.ino`	Main file: setup(), loop(), WiFi, display logic
`config_portal.ino`	WiFi AP config portal, HTML web UI, OTA server
`NDP_fns.ino`	NTP packet handling, time sync
`NDP_setup.ino`	Timezone/DST configuration
`RTC.ino`	DS3231 RTC driver
`MAX7219.ino`	LED matrix driver, font rendering
`fns.ino`	Utility functions (MAC helpers, config I/O)
`zk.h`	Font data (two 5×8 character sets), month/day arrays

Timezone Configuration

Edit the default timezone rules in src/MatrixClock.ino:

TimeChangeRule EDT = {"EDT", Last, Sun, Mar, 1, 120};  // DST: UTC+2h
TimeChangeRule EST = {"EST", Last, Sun, Oct, 1, 60};   // Standard: UTC+1h

Or set via the web config portal after first boot.

EchterAgo/MatrixClock

README