> **Tip:** Always double-check that VCC (5V), GND, and DIN/CS/CLK match your MAX7219 module’s pin order — different modules sometimes label them differently.
## 🌐 Web UI & Configuration
The built-in web interface provides full configuration for:
- **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)
- **Advanced Settings** (see below)
## First-time Setup / 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 Setting** – 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 Wi-Fi first.
## UI Example:
## ⚙️ Advanced Settings
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 off, duration is the same as weather duration)
- **24/12h Clock**: Switch between 24-hour and 12-hour time formats (24-hour default)
- **Imperial Units (°F)** toggle (metric °C defaults)
- **Humidity**: Display Humidity besides Temperature
- **Weather description** toggle (display weather description in the selected language* for 3 seconds or scrolls once if description is too long)
- **Flip Display**: Invert the display vertically/horizontally
- **Brightness**: Off - 0 (dim) to 15 (bright)
- **Dimming Feature**: Start time, end time and desired brightness selection
- **Countdown** function, set a countdown to your favorite/next event, 2 modes: Scroll/Dramatic!
>Non-English characters converted to their closest English alphabet.
>For Esperanto, Irish, and Swahili, weather description translations are not available. Japanese translations exist, but since the device cannot display all Japanese characters, English will be used in all these cases.
> **Tip:** Don't forget to press the save button to keep your settings
## 📝 Configuration Notes
- **OpenWeatherMap API Key:**
- [Make an account here](https://home.openweathermap.org/users/sign_up)
- [Check your API key here](https://home.openweathermap.org/api_keys)
- **City Name:** e.g. `Tokyo`, `London`, etc.
- **Country Code:** 2-letter code (e.g., `JP`, `GB`)
- **ZIP Code:** Enter your ZIP code in the city field and US in the country field (US only)
- **Latitude and Longitude** You can enter coordinates in the city field (lat.) and country field (long.)
- **Time Zone:** Select from IANA zones (e.g., `America/New_York`, handles DST automatically)
## 🧩 Hidden & Advanced Features
ESPTimeCast includes a few optional “power-user” features that aren’t visible in the main interface but can be accessed directly from your browser. These are intended for advanced users who want more control or integration.
#### 💾 `/export`
Downloads your current configuration (`config.json`) directly from the device.
This is useful for creating backups or migrating settings between devices.
**Example:**
```
http://your-device-ip/export
```
The file will download automatically with your saved Wi-Fi credentials (safely masked for security) and all other settings.
#### 📂 `/upload`
Lets you manually upload a configuration file (`config.json`) to the device.
Perfect for restoring a backup or quickly switching between setups.
**Usage:**
1. Go to
```
http://your-device-ip/upload
```
2. Select your edited or backup `config.json` file.
3. The device will confirm the upload and automatically reboot with the new configuration.
> *Tip:* You can export → edit the file on your computer → re-upload to test new settings without using the web interface.
#### ⚕️ Nightscout Integration
ESPTimeCast supports displaying glucose data from **Nightscout** servers alongside weather information.
When the secondary NTP/URL field (`ntpServer2`) contains a valid Nightscout API endpoint for example:
```
https://your-cgm-server/api/v1/entries/current.json?token=xxxxxxxxxxxxx
```
the device automatically enables **Glucose Display Mode**.
In this mode:
- The device fetches glucose data every 5 minutes.
- Glucose value and trend direction are displayed alternately with time and weather.
- The display duration for Nightscout data is the same as the weather display duration.
- Weather data continues to display normally.
- Debug logs confirm updates and Nightscout responses in the Serial Monitor.
#### ⚠️ Notes
- These features are optional and hidden from the main interface to avoid clutter.
- `/upload` and `/export` are intentionally unlinked from the UI to prevent accidental access.
- Always verify your Wi-Fi credentials and tokens before uploading edited configurations.
## 🚀 Getting Started
This guide will walk you through setting up your environment and uploading the **ESPTimeCast** project to your **ESP8266** or **ESP32** board. Please follow the instructions carefully for your specific board type.
#### ⚙️ ESP8266 Setup
Follow these steps to prepare your Arduino IDE for ESP8266 development:
1. **Install ESP8266 Board Package:**
* Open `File > Preferences` in Arduino IDE.
* Add `http://arduino.esp8266.com/stable/package_esp8266com_index.json` to "Additional Boards Manager URLs."
* Go to `Tools > Board > Boards Manager...`. Search for `esp8266` by `ESP8266 Community` and click "Install".
2. **Select Your Board:**
* Go to `Tools > Board` and select your specific board, e.g., **Wemos D1 Mini** (or your ESP8266 variant).
3. **Configure Flash Size:**
* Under `Tools`, select `Flash Size "4MB FS:2MB OTA:~1019KB"`. This ensures enough space for the sketch and LittleFS data.
4. **Install Libraries:**
* Go to `Sketch > Include Library > Manage Libraries...` and install the following:
* `ArduinoJson` by Benoit Blanchon
* `MD_Parola` by majicDesigns (this will typically also install its dependency: `MD_MAX72xx`)
* `ESPAsyncTCP` by ESP32Async
* `ESPAsyncWebServer` by ESP32Async
#### ⚙️ ESP32 Setup
Follow these steps to prepare your Arduino IDE for ESP32 development:
1. **Install ESP32 Board Package:**
* Go to `Tools > Board > Boards Manager...`. Search for `esp32` by `Espressif Systems` and click "Install".
2. **Select Your Board:**
* Go to `Tools > Board` and select your specific board, e.g., **LOLIN S2 Mini** (or your ESP32 variant).
3. **Configure Partition Scheme:**
* Under `Tools`, select `Partition Scheme "Default 4MB with spiffs"`. This ensures enough space for the sketch and LittleFS data.
4. **Install Libraries:**
* Go to `Sketch > Include Library > Manage Libraries...` and install the following:
* `ArduinoJson` by Benoit Blanchon
* `MD_Parola` by majicDesigns (this will typically also install its dependency: `MD_MAX72xx`)
* `AsyncTCP` by ESP32Async
* `ESPAsyncWebServer` by ESP32Async
#### ⬆️ Uploading the Code and Data
Once your Arduino IDE is set up for your board (as described above):
1. **Open the Project Folder:**
* For ESP8266: Navigate to and open the `ESPTimceCast_ESP8266` project folder. Inside, you'll find the main sketch file, typically named `ESPTimceCast_ESP8266.ino`. Open this `.ino` file in the Arduino IDE.
* For ESP32: Navigate to and open the `ESPTimceCast_ESP32` project folder. Inside, you'll find the main sketch file, typically named `ESPTimceCast_ESP32.ino`. Open this `.ino` file in the Arduino IDE.
2. **Upload the Sketch:**
* With the main sketch file open, click the "Upload" button (the right arrow icon) in the Arduino IDE toolbar. This will compile the entire project and upload it to your board.
3. **Upload `/data` folder (LittleFS):**
* This project uses LittleFS for storing web interface files and other assets. You'll need the LittleFS Uploader plugin.
* [**Install the LittleFS Uploader Plugin**](https://randomnerdtutorials.com/arduino-ide-2-install-esp8266-littlefs/)
* **Before uploading, ensure the Serial Monitor is closed.**
* Open the Command Palette (`Ctrl+Shift+P` on Windows, `Cmd+Shift+P` on macOS).
* Search for and run: `Upload Little FS to Pico/ESP8266/ESP32` (the exact command name might vary).
* **Important for ESP32:** If the upload fails, you might need to manually put your ESP32 into "Download Mode." While holding down the **Boot button** (often labeled 'BOOT' or 'IO0' or 'IO9'), briefly press and release the **RST button**, then release the Boot button.
## 📺 Display Behavior
**ESPTimeCast** automatically switches between two display modes: Clock and Weather.
If "Show Weather Description" is enabled a third mode (Description) will display with a duration of 3 seconds, if the description is too long to fit on the display the description will scroll from right to left once.
What you see on the LED matrix depends on whether the device has successfully fetched the current time (via NTP) and weather (via OpenWeatherMap).
The following table summarizes what will appear on the display in each scenario:
| Display Mode | 🕒 NTP Time | 🌦️ Weather Data | 📺 Display Output |
|:------------:|:----------:|:--------------:|:--------------------------------------------|
| **Clock** | ✅ Yes | — | 🗓️ Day Icon + ⏰ Time (e.g. `@ 14:53`) |
| **Clock** | ❌ No | — | `! NTP` (NTP sync failed) |
| **Weather** | — | ✅ Yes | 🌡️ Temperature (e.g. `23ºC`) |
| **Weather** | ✅ Yes | ❌ No | 🗓️ Day Icon + ⏰ Time (e.g. `@ 14:53`) |
| **Weather** | ❌ No | ❌ No | `! TEMP` (no weather or time data) |
## How it works:
- The display automatically alternates between **Clock** and **Weather** modes (the duration for each is configurable).
- If "Show Weather Description" is enabled a third mode **Description** will display after the **Weather** display with a duration of 3 seconds.
- In **Clock** mode, if NTP time is available, you’ll see the current time plus a unique day-of-week icon. If NTP is not available, you'll see `! NTP`.
- In **Weather** mode, if weather is available, you’ll see the temperature (like `23ºC`). If weather is not available but time is, it falls back to showing the clock. If neither is available, you’ll see `! TEMP`.
- All status/error messages (`! NTP`, `! TEMP`) are big icons shown on the display.
**Legend:**
- 🗓️ **Day Icon**: Custom symbol for day of week (`@`, `=`, etc.)
- ⏰ **Time**: Current time (HH:MM)
- 🌡️ **Temperature**: Weather from OpenWeatherMap
- ✅ **Yes**: Data available
- ❌ **No**: Data not available
- — : Value does not affect this mode
## Support this project
ESPTimeCast is an open-source passion project designed to blend art, engineering, and information display.
If you enjoy this project, please consider supporting my work:
[](https://www.paypal.me/officialuphoto)
[](https://github.com/sponsors/mfactory-osaka)