Timekeeper

TickTock — ESP32 LED Clock Platform

A custom ESP32-based clock platform for WS2812B-driven LED clocks. The firmware and PCB are designed to be display-agnostic: any clock that accepts a stream of addressable LEDs (WS2812B/NeoPixel) can be driven with minor adjustments to the display layer. This repository's reference implementation drives a 4-digit Lixie tube display.

Time is sourced from a 3-tier fallback chain: GPS → NTP → RTC, ensuring accurate time even without network or satellite coverage. The display integrates with Home Assistant via MQTT.

Features

• GPS time sync via u-blox NEO-6M over I2C (DDC)
• NTP fallback over WiFi
• DS3231M RTC as offline fallback (battery-backed)
• Home Assistant integration: on/off, RGB color, brightness, display effects

Adapting to a Different Display

The display logic is isolated in MqttDisplay.h/cpp and main.cpp. To drive a different WS2812B-based clock (e.g. a 7-segment LED display, a nixie-style digit ring, or a custom matrix):

1. Replace or modify the Lixie calls in MqttDisplay.cpp and main.cpp with your own FastLED or display-library code.
2. Adjust LIXIE_PIN and LIXIE_DIGIT_COUNT in config.defaults.h to match your LED count and data pin.
3. The TimeManager class, configuration system, and MQTT integration require no changes.

Repository Structure

Protject_Tick_Tock/
├── software/
│   ├── TickTock2/          # Active PlatformIO firmware (start here)
├── hardware/
│   └── timekeeper/         # KiCad V3 mainboard schematic & PCB layout

Hardware

The PCB provides power, programming, and I2C routing for the core timekeeping components. The display connector exposes a single WS2812B data line and can be wired to any compatible LED clock display.

The custom PCB design (V3) is in hardware/timekeeper/. Open timekeeper.kicad_pro in KiCad 7+.

Firmware

The active firmware lives in software/TickTock2/ and is built with PlatformIO.

Dependencies

Managed automatically by PlatformIO:

• mikalhart/TinyGPSPlus — GPS NMEA parsing
• makuna/RTC — DS3231M driver
• knolleary/PubSubClient — MQTT
• bblanchon/ArduinoJson — MQTT payload encoding

Bundled in lib/:

• FastLED — WS2812B LED driver
• Lixie — Lixie display abstraction (reference implementation; replace for other displays)

Configuration

All settings have defaults in src/config.defaults.h. To override with your own credentials and settings, create src/config.local.h (gitignored):

// src/config.local.h
#pragma once

#undef  WIFI_SSID
#define WIFI_SSID "your_network"

#undef  WIFI_PASS
#define WIFI_PASS "your_password"

// Optional: MQTT credentials
#undef  MQTT_HOST
#define MQTT_HOST "homeassistant.local"
#undef  MQTT_USER
#define MQTT_USER "mqtt_user"
#undef  MQTT_PASS
#define MQTT_PASS "mqtt_password"

// Timezone — POSIX TZ string
// Full list: https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv
#undef  TIMEZONE_POSIX
#define TIMEZONE_POSIX "CET-1CEST,M3.5.0,M10.5.0/3"

An annotated example with all available options is in src/config.local.h.example.

Build & Flash

cd software/TickTock2

# Build
pio run

# Upload via USB
pio run --target upload

# Open serial monitor (115200 baud)
pio device monitor

Time Source Fallback

The TimeManager class selects the best available time source at runtime:

Priority:  GPS  >  NTP  >  RTC  >  None

1. GPS — polled every 5 s over I2C. Used when a valid fix is available.
2. NTP — synced on startup via WiFi. Used when GPS is unavailable.
3. RTC — loaded at boot, written back every hour from GPS or NTP. Used when offline.

Time is stored and transmitted in UTC everywhere; the timezone is applied only at display time.

Home Assistant Integration

The display registers itself as an MQTT light via Home Assistant discovery.

Supported commands:

Serial Output

While running, the firmware prints the current time and active source once per second:

[TimeManager] 2025-03-15 14:32:01 UTC  source=GPS

Enable verbose GPS polling output by setting #define GPS_DEBUG 1 in config.local.h.