Last Commit

🎉 1,000+ GitHub stars - thank you to the community!

ESPTimeCast™ is a sleek, WiFi-connected LED matrix clock and weather display built on ESP8266/ESP32 and MAX7219. It combines real-time NTP time sync, live OpenWeatherMap updates, and a modern web-based configuration interface — all in one compact design.

🚀 Install in Under a Minute (Recommended)

Flash ESPTimeCast directly from your browser — no Arduino IDE, no drivers setup, no manual configuration.

👉 Web Installer:
https://esptimecast.github.io

After flashing, connect to the ESPTimeCast WiFi access point to complete setup.

✅ Officially Tested Boards

Wemos D1 Mini (ESP8266)
ESP32 Dev Module
ESP32-C3 SuperMini
Wemos S2 Mini (ESP32-S2)
ESP32-S3 WROOM-1 (Camera/SD board)

Compatible Chip Families

ESPTimeCast supports the following chip families:

ESP8266
ESP32
ESP32-S2
ESP32-C3
ESP32-S3

Other development boards using these chips may work,
but pin mapping and USB behavior can vary.

🔄 Updating ESPTimeCast

ESPTimeCast supports two ways to update your device:

🌐 OTA Updates (Wi-Fi)

Update your device wirelessly directly from the Web UI — no cable required.

Fully supported for devices installed using the Web Installer.
Manual installations (e.g. via Arduino IDE) may have limited OTA support.

🔌 Web Installer Updates (USB)

Update your device through the Web Installer using a USB connection.

Option to preserve your settings (no erase)
Works on all supported devices
Recommended if OTA is unavailable

Requires a Web Serial compatible browser (Chrome, Edge, or Brave).

📌 Wiring guide:
See the hardware connection table

🌐 Now Playing — ESPTimeCast Companion Extension

The ESPTimeCast Companion Extension automatically detects what you're watching or listening to and displays it on your device in real time.

Send messages, start timers, and control your display — all directly from your browser, no Web UI required.

🎵 Auto-detects music & video titles (YouTube, Spotify, Twitch, and more)
⚡ Instantly sends messages and timers from the popup
🎛️ Control brightness, modes, and rotation remotely
📡 Cast to multiple ESPTimeCast devices at once
🔒 Runs locally on your network — fast and private
<img src="assets/extension.png" alt="ESPTimeCast Companion Extension" width="400" />

Works with YouTube, Spotify, Prime Video, Vimeo, Dailymotion, Twitch, and SoundCloud.
Note: Firmware v1.5.0+ required

📦 3D Printable Case

To help support the project’s development, the official ESPTimeCast™ case design is available as a paid STL download (see links below).

If you prefer a free option, there are many compatible MAX7219 LED matrix enclosures shared by the community - you can find plenty by searching for “MAX7219 case” on Printables, Cults3D, or similar sites.

🖼️ Community Builds Gallery

A small selection of ESPTimeCast™ builds from the community ❤️

Huge thanks to all the makers on Printables who shared their ESPTimeCast™ builds featured here:

Achduka, ChrisBalo_2103728, LazyManJoe_199553, LeoB_746630, Manni0605_464156, Purduesi_774301, rhe_3695705, sardaukar_1942598, Stefan_37395, TO3IAS, thirddimensionlabs

You all made this community showcase possible - thank you! 🙏

Want your build featured here?
Share your photos on r/ESPTimeCast - I’d love to showcase more builds! 📸

📰 Press Mentions

ESPTimeCast™ has been featured on major maker and tech platforms highlighting its design, usability, and open-source community.

🛠 Advanced Setup & Technical Details

Most users should start here: 👉 https://esptimecast.github.io

Looking for manual setup, wiring details, or advanced configuration? Advanced and developer-focused information is available below.

<details> <summary>✨ Features & Capabilities</summary>

8x32 LED Matrix Display powered by MAX7219 with custom font support
Web-Based Configuration – no apps required, configure everything from your browser
Accurate Time Sync (NTP) with automatic retries and status feedback
Live Weather Updates from OpenWeatherMap (temperature, humidity, conditions)
Custom Scroll Messages with persistent display control
Countdowns & Timers – create event countdowns with custom messages or run quick timers (e.g. 15 min)
OTA Firmware Updates – update your device directly from the browser, no reflashing required
Open API & Home Assistant Integration for automation, remote control, and custom messages
Automatic Setup Mode (AP) for first-time configuration or recovery
Timezone Support using IANA database (DST handled automatically)
Location Detection via “Get My Location” (Lat/Long auto-fill)
Multi-language Support for weekday and weather descriptions
Persistent Storage (LittleFS) with backup and restore support
Visual Status Animations for Wi-Fi, AP mode, and syncing
Advanced Controls & Customization:
- Custom NTP servers (primary & fallback)
- 12/24h clock and date display options
- Toggle weekday, humidity, and weather descriptions
- Metric / Imperial units (°C / °F)
- Display rotation (180° flip)
- Adjustable brightness
- Auto dimming (sunrise/sunset) or custom schedule
Optional Integrations:
- Nightscout glucose display (alternates with weather)
- Config export/import via /export and /upload endpoints

</details> <details> <summary>🔌 Wiring & Connections</summary>

ESPTimeCast uses board-specific recommended SPI pin mappings to ensure consistent behavior, stable power delivery, and reliable brightness.

📌 Current Pin Assignment

The following pin mappings correspond to the official Web Installer builds. If you are compiling manually, ensure your pin definitions match this table.

| Chip | Board / Module | CLK | CS | DIN | VCC | GND | |------------|------------------------------------|:---:|:--:|:---:|:---:|:---:| | ESP8266 | D1 Mini (USB-C / Micro-USB) | 14 | 13 | 15 | 5V | GND | | ESP32 | ESP32 Dev Module / D1 Mi

ESPTimeCast

Install / Use

README