Multi-Zone Matrix Clock

A WiFi-enabled LED matrix clock for ESP8266 that displays time from multiple timezones. Features automatic NTP synchronization, DST handling, and a web-based configuration interface.

Features

• 🌍 Multiple Timezone Support: Display time from up to 6 different timezones (UTC, CST, EST, PST, IRST, and more)
• ⏰ Automatic Time Sync: NTP synchronization ensures accurate time
• 🛰️ Configurable NTP Server: Pick from popular pools (pool.ntp.org, Google, Cloudflare, NIST, ir.pool.ntp.org) or use your own
• 🌅 DST Handling: Automatic Daylight Saving Time adjustments for US timezones
• 📱 Web Configuration: Easy-to-use web interface for settings
• 🔐 Password-Protected Admin: HTTP Basic Auth on the web UI (default admin / admin)
• 🔌 WiFi Manager: Automatic WiFi configuration portal on first boot
• 🎨 Customizable Display: Adjustable brightness and 12/24-hour format
• 🔄 180° Rotation: Flip the display for upside-down mounting without rewiring
• 📺 Animated Display: Smooth scrolling animations for timezone names and time
• 💾 Persistent Settings: Settings saved to EEPROM

Hardware Requirements

• ESP8266 (NodeMCU, Wemos D1 Mini, or similar)
• MAX7219 LED Matrix Display (4 modules, FC16 hardware type)
• Jumper wires for connections
• 5V power supply (USB or external adapter)

Pin Connections

ESP8266 Pin	MAX7219 Pin	Description
D5	CLK	Clock
D7	DIN	Data In
D8	CS	Chip Select
5V	VCC	Power
GND	GND	Ground

Note: Pin definitions can be modified in config.h.

---

Software Setup

Choose PlatformIO (recommended for professional workflow) or Arduino IDE (traditional approach).

Option 1: PlatformIO (Recommended) 🚀

Why PlatformIO?

• ✅ Automatic library management (no manual installation)
• ✅ Multiple board configurations in one file
• ✅ Faster incremental builds
• ✅ Better code intelligence and debugging
• ✅ Professional development workflow

Quick Start:

1. Install:

   • Download and install Visual Studio Code
   • Install the PlatformIO IDE extension

2. Open Project:

   • Open this folder in VS Code
   • PlatformIO will auto-detect platformio.ini

3. Build & Upload:

   Using VS Code GUI (easiest):

   • Click ✓ (Build) → → (Upload) → 🔌 (Monitor)

   Using Command Line:

   pio run                    # Build
   pio run -t upload          # Upload to device
   pio device monitor         # Open serial monitor

Supported Boards (pre-configured):

• d1_mini - Wemos D1 Mini (default)
• nodemcu - NodeMCU v2
• esp12e - Generic ESP8266

To upload to a specific board:

pio run -e nodemcu -t upload

Common PlatformIO Commands:

pio run -t clean           # Clean build files
pio device list            # List connected devices
pio pkg update             # Update libraries

Option 2: Arduino IDE

Setup Steps:

1. Install Arduino IDE (version 1.8.x or newer)

2. Add ESP8266 Board Support:

   • Go to File → Preferences
   • Add this URL to "Additional Board Manager URLs":

     http://arduino.esp8266.com/stable/package_esp8266com_index.json
     

   • Go to Tools → Board → Boards Manager
   • Search for "ESP8266" and install

3. Install Required Libraries (via Library Manager):

   • WiFiManager by tzapu
   • MD_Parola by majicDesigns
   • MD_MAX72XX by majicDesigns
   • NTPClient by Fabrice Weinberg
   • ESP8266WiFi (included with board support)
   • EEPROM (included with board support)

4. Configure Arduino IDE:

   • Select board: Tools → Board → ESP8266 Boards → NodeMCU 1.0 (or your board)
   • Set upload speed: Tools → Upload Speed → 115200

5. Upload:

   • Open MultiZoneMatrixClock.ino
   • Select your COM port
   • Click Upload button

---

First Time Setup

1. Power on the ESP8266
2. The device creates a WiFi access point: "MultiZoneClock"
3. Connect to this network with your phone/computer
4. A configuration portal opens automatically (or navigate to 192.168.4.1)
5. Enter your WiFi credentials and connect
6. Find the device IP: Check Serial Monitor (115200 baud) or your router's device list
7. Access web interface: Open the IP address in your browser

---

Configuration

Web Interface

Navigate to your device's IP address in a web browser to access settings. The page is protected by HTTP Basic Auth — the browser will prompt for credentials on first load (default admin / admin).

• Timezones: Enable/disable which timezones to display
• Display Intensity: Adjust brightness (0-15)
• Time Display Duration: How long to show each timezone (seconds)
• Rotate display 180°: Flip the matrix so the clock reads correctly when the unit is mounted upside-down (no rewiring needed)
• Time Format: Toggle between 12-hour (AM/PM) or 24-hour format
• NTP Server: Choose a preset (pool.ntp.org, time.google.com, time.cloudflare.com, time.nist.gov, ir.pool.ntp.org) or select Custom… to type your own hostname
• Admin Password: Change the password used for the web UI. Leave the field blank to keep the current password.
• WiFi Configuration: Reconfigure WiFi connection

🔐 Change the default password. The first thing you should do after setup is open the Security section and set a new admin password.

Default Settings

• Enabled Timezones: EST, IRST
• Display Intensity: 5
• Time Format: 24-hour
• Time Display Duration: 10 seconds per timezone
• Display Rotation: 0° (not flipped)
• NTP Server: pool.ntp.org
• Admin Username / Password: admin / admin

Manual Configuration in Code

• Timezones: Edit timezone.cpp
• Hardware pins: Edit config.h
• Display settings: Edit config.h

---

Usage

Display Modes

Single Timezone Mode (when only 1 timezone is enabled):

• Time displays statically with blinking colon
• Updates every second

Multiple Timezone Mode (when 2+ timezones are enabled):

1. Timezone name scrolls up
2. Brief pause
3. Time scrolls in from left
4. Time displays for configured duration
5. Time scrolls out to right
6. Repeats for next timezone

Time Synchronization

• Automatic NTP sync with the configured server (default pool.ntp.org; selectable from preset pools or a custom hostname)
• Periodic updates to maintain accuracy
• Automatic DST calculation for US timezones

🇮🇷 Iran users: select ir.pool.ntp.org from the NTP Server dropdown. It resolves to Iran-zone servers in the global NTP Pool project, which gives you a faster, in-country sync than the generic pool.

---

3D Printing Enclosure

3D printable enclosure files are included in the stl/ directory, optimized for Bambu Lab A1 Mini.

Available Files

File	Description	Quantity
FRONT.3mf	Front panel/enclosure	1
FRONT Wemos D1 Mini.3mf	Front with Wemos D1 Mini mount	1
BACK.3mf	Back panel/enclosure	1
FRAME FRONT.3mf	Front frame	1
FRAME BACK.3mf	Back frame	1
2 x MATRIX HOLDER.3mf	Matrix display holder	2

Print Settings

• Layer height: 0.2mm (standard) or 0.16mm (fine)
• Infill: 15-20%
• Material: PLA or PETG
• Supports: As needed

---

Troubleshooting

Arduino IDE Issues

Error: "display.h: No such file or directory"

• Solution: Make sure all .cpp and .h files are in the same directory as the .ino file
• Don't manually create src/ or include/ directories for Arduino IDE

WiFi Issues

• Can't connect to AP: Reset device and try again
• Portal doesn't open: Manually navigate to 192.168.4.1
• Can't find device IP: Check Serial Monitor (115200 baud) or router

Display Issues

• No display: Check wiring, especially power (5V) and ground
• Garbled text: Verify pin connections match config.h
• Too dim/bright: Adjust intensity in web interface (0-15)

Time Issues

• Wrong time: Ensure WiFi is connected and NTP can sync
• DST not working: Check timezone DST settings in timezone.cpp
• Timezone offset wrong: Verify offset in timezone.cpp

PlatformIO Issues

Upload failed:

pio device list              # Check available devices
pio run -t clean             # Clean and rebuild
pio pkg install --force      # Reinstall libraries

Port not found: Make sure CH340/CP2102 drivers are installed

---

Customization

Adding New Timezones

Edit timezone.cpp:

// Add new timezone to timezones array
timezones[5] = {"TZNAME", offset_seconds, uses_dst};

Update TZ_COUNT in config.h if adding more than 6 timezones.

Changing Display Hardware

Modify config.h:

#define HARDWARE_TYPE MD_MAX72XX::FC16_HW  // Change module type
#define MAX_DEVICES 4                       // Number of modules
#define CLK_PIN   D5                        // Clock pin
#define DATA_PIN  D7                        // Data pin
#define CS_PIN    D8                        // Chip select pin

Adjusting Display Timing

Edit config.h:

const unsigned long WAIT_DURATION = 2000;  // Pause between animations (ms)
const unsigned long STATIC_TIME_DURATION_DEFAULT = 10000;  // Time display duration (ms)

---

Project Structure

MultiZoneMatrixClock/
├── MultiZoneMatrixClock.ino    # Main sketch (Arduino IDE)
├── *.h, *.cpp                  # Source files (Arduino IDE)
│   ├── config.h                #   Pins, EEPROM layout, Settings struct
│   ├── display.{h,cpp}         #   Matrix animation + rotation
│   ├── timezone.{h,cpp}        #   Timezone catalogue + DST
│   ├── webserver.{h,cpp}       #   Web UI + HTTP Basic Auth
│   └── html_utils.{h,cpp}      #   Reusable HTML/form helpers
├── src/                        # Source files (PlatformIO — mirror of root .cpp)
│   ├── main.cpp                #   Main entry point
│   ├── display.cpp             #   Display manager
│   ├── timezone.cpp            #   Timezone manager
│   ├── webserver.cpp           #   Web server manager
│   └── html_utils.cpp          #   HTML helpers
├── platformio.ini              # PlatformIO configuration
├── docs/                       # Documentation and images
├── stl/                        # 3D printing files
└── README.md                   # This file

File Usage:

• Arduino IDE: Uses .ino and root *.cpp/*.h files (ignores src/ folder)
• PlatformIO: Uses src/ folder and root *.h files

---

Technical Specifications

• MCU: ESP8266 @ 80MHz, 4MB Flash
• Display: MAX7219 8x8 LED Matrix (4 modules = 32×8)
• Communication: SPI for display, WiFi 802.11 b/g/n
• Storage: EEPROM for persistent settings
• Time Protocol: NTP (Network Time Protocol)
• RAM Usage: ~48.6% (39,808 bytes)
• Flash Usage: ~37.1% (387,995 bytes)

---

Quick Reference Commands

PlatformIO

Task	Command
Build	pio run
Upload	pio run -t upload
Monitor	pio device monitor
Clean	pio run -t clean
List devices	pio device list
Update libs	pio pkg update
Specific board	pio run -e nodemcu -t upload

Serial Monitor Settings

• Baud Rate: 115200
• Shows: WiFi status, IP address, NTP sync, debug info

---

License

This project is open source. Feel free to modify and distribute.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

• Built with Arduino framework for ESP8266
• Uses excellent libraries from the Arduino community
• Inspired by the need for a simple, elegant multi-timezone clock

Support

For issues, questions, or contributions, please open an issue on GitHub.

---

Enjoy your Multi-Zone Matrix Clock! ⏰🌍