Under-TV Clock

Replacement for the clock lost when the cable box was removed. ESP32 Feather V2 driving a 1.2" red 7-segment display, with DS3231/NTP timekeeping, VEML7700 auto-dimming, captive-portal WiFi setup, and Home Assistant integration over MQTT.

See docs/CHARTER.md for the full project charter (BOM, firmware decisions, HA entity plan, open items).

Status

v1.x — complete and deployed. Enclosure built (OLED left, display center, recessed open-aperture lux sensor right, button + power out the rear), firmware feature-complete and field-verified:

• 7-seg local time from DS3231 (UTC + POSIX TZ), NTP resync with a sanity window guarding the RTC, VEML7700 auto-dim with night-blank
• Captive-portal WiFi setup (AP SimpleClk, portal at 192.168.4.1) with MQTT/NTP/format settings; button long-press = WiFi reset
• OLED diagnostics page (button short-press): WiFi/IP/MQTT/NTP/lux/uptime
• Home Assistant via MQTT discovery (17 entities) — controls: brightness override, auto/manual, display on/off (movie night), 24-h format, sync-now, min-brightness, night-blank lux, lux scale, brightness boost; sensors: lux, brightness, RSSI, uptime, last NTP sync, RTC drift, timezone, RTC battery
• Settings page at simpleclock.local with full HA parity; live status header; auth'd /status JSON for health checks
• OTA at /update (basic auth); scripts/ota.sh builds + flashes over the air at simpleclock.local

Bench serial commands (115200): T<epoch> f b<0-15> a s p n.

Security note

The setup-AP password doubles as basic auth for the settings page and OTA endpoint, and it's compiled in (AP_PASS in src/config.h — and yes, it's in this public repo). That's a deliberate trade-off for a LAN-only family clock: an attacker needs to be on your WiFi first. If your threat model differs, change AP_PASS before building.

License

MIT — see LICENSE.