ESPTimeCast

**1,500+ 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.com > After flashing, connect to the ESPTimeCast WiFi access point to complete setup. ### ✅ Officially Tested Boards - ESP8266 Wemos D1 Mini / ESP12-F - ESP32 Dev Module - ESP32-C3 SuperMini - ESP32-S2 (Wemos S2 Mini) - ESP32-S2 (Adafruit ESP32-S2 Feather) - ESP32-S3 WROOM-1 (Camera/SD board) - ESP32-S3 SuperMini - ESP32-S3-Zero ### Compatible Chip Families ESPTimeCast supports the following chip families: - ESP8266 - ESP32 - ESP32-S2 - ESP32-S3 - ESP32-C3 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, Firefox or Brave).   **Wiring guide:** See the [hardware connection table](https://github.com/mfactory-osaka/ESPTimeCast#-advanced-setup--technical-details)   ## 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   > 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](https://www.reddit.com/r/ESPTimeCast/comments/1p2vt16/show_your_esptimecast_build_post_your_photos_setup/) - 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. - [Hackaday](https://hackaday.com/2025/10/02/building-a-desk-display-for-time-and-weather-data) - [XDA Developers](https://www.xda-developers.com/super-sleek-esp32-weather-station) - [Hackster.io](https://www.hackster.io/news/the-perfect-minimalist-led-clock-49a4e4440518)   ## Advanced Setup & Technical Details Most users should start here: https://esptimecast.com Looking for manual setup, wiring details, or advanced configuration? Advanced and developer-focused information is available below.   ✨ Features & Capabilities   - **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 - **Buzzer Support** – add a passive piezo buzzer for audible alerts. - **Alarm Clock** – set a recurring or daily alarm with day-of-week scheduling, snooze, dedicated wake brightness. - **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 re-flashing 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** with mg/dL and mmol/L support (alternates with weather) - **Config export/import** via `/export` and `/upload` endpoints   Wiring & Connections   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 | | ESP8266 | ESP12-F / ESP8266MOD | 14 | 13 | 12 | 5V | GND | | ESP32 | ESP32 Dev Module / D1 Mini ESP32 (not ESP8266) | 18 | 23 | 5 | 5V | GND | | ESP32-S2 | S2 Mini | 7 | 11 | 12 | 5V | GND | | ESP32-S2 | Adafruit ESP32-S2 Feather | 36 | 10 | 35 | 5V | GND | | ESP32-C3 | SuperMini (Updated GPIO Mapping as of v1.3.2) | 4 | 10 | 6 | 5V | GND | | ESP32-S3 | WROOM-1 (Camera / SD board) | 18 | 16 | 17 | 5V | GND | | ESP32-S3 | SuperMini | 4 | 5 | 6 | 5V | GND | | ESP32-S3 | Zero | 12 | 11 | 10 | 5V | GND | > The table lists **raw GPIO numbers**. > MAX7219 modules are typically powered at **5V** but accept **3.3V logic** on DIN / CLK / CS. > All ESP32 boards listed above have been **tested successfully** with this wiring. > ESP8266 D1 Mini boards are often labeled using **D-pins** (D5 = GPIO14, D7 = GPIO13, D8 = GPIO15). > Other boards using the same chip families may work, but SPI pins may differ depending on the manufacturer layout. > ESP32-C3 SuperMini mapping changed to avoid strapping pin conflicts and boot issues present on some boards.   ### Wiring Diagram > **Tip:** Double-check the pin order on your MAX7219 module — labeling and orientation can vary between manufacturers.   ### Upgrading from an older build? If your device was wired before **Oct 17, 2025**, please verify the following: - **CLK** is connected to **D5** - **VCC** is connected to **5V** (not 3.3V) - Flashing via the web installer automatically applies the correct defaults   First-Time Setup (Wi-Fi & AP Mode)   1. Power on the device. If WiFi fails, it auto-starts in AP mode: - **SSID:** `ESPTimeCast` - **Password:** `12345678` - Captive portal should open automatically, if it doesn't open `http://192.168.4.1` or `http://setup.esp` in your browser. 2. Set your WiFi and all other options. 3. Click **Save Settings** – the device saves config, reboots, and connects. 4. The device shows its local IP address after boot so you can login again for setting changes > External links and the "Get My Location" button require internet access. They won't work while the device is in AP Mode - connect to WiFi first.   Web Interface & Device Control   ESPTimeCast includes a built-in **Web UI** that lets you fully configure and control the device from any browser, no apps required. The **Web UI** and **Companion Browser Extension** provide a human-friendly interface for features like timers, icons, stopwatch, and custom messages, using **Message Tokens** (commands such as `[TIMER 5M]` or `[STOPWATCH]`) behind the scenes so you don't have to interact with the API directly. For automation and integrations, ESPTimeCast also provides the `/action` API that allows Home Assistant, scripts, browser extensions, and other applications to control the device directly using simple HTTP requests.. #### You can open the Web UI using either: - http://esptimecast.local mDNS / Bonjour - Works on macOS, iOS, Windows with Bonjour, and most modern browsers. - The device’s **local IP address** → On every reboot, ESPTimeCast shows its IP on the LED display so you can easily connect. #### The Web UI gives you control over: - **WiFi settings** (SSID & Password) - **Weather settings** (OpenWeatherMap API key, City, Country, Coordinates) - **Time zone** (will auto-populate if TZ is found) - **Day of the Week and Weather Description** languages - **Display durations** for clock and weather (milliseconds) - **Custom Scroll Text** - set a persistent scrolling message on the display directly from the Web UI - **Advanced Settings** (see below)   ## UI Example:   ⚙️ Advanced Settings & Tweaks   Click the **cog icon** next to “Advanced Settings” in the Web UI to reveal extra configuration options. **Available advanced settings:** - **Primary NTP Server**: Override the default NTP server (e.g. `pool.ntp.org`) - **Secondary NTP Server**: Fallback NTP server (e.g. `time.nist.gov`) - **Day of the Week**: Display Day of the Week in the desired language - **Blinking Colon** toggle (default is on) - **Show Date** (default is