From 2dc8d8a8b050124a3855615bb7c0e9792ea4c0a1 Mon Sep 17 00:00:00 2001 From: mfactory-osaka Date: Thu, 5 Jun 2025 22:47:59 +0900 Subject: [PATCH 1/2] Create README.md --- README.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..f972f9b --- /dev/null +++ b/README.md @@ -0,0 +1,110 @@ +![ESPTimeCast](assets/logo.svg) + +**ESPTimeCast** is a WiFi-connected LED matrix clock and weather station using ESP8266 and MAX7219. +It shows the current time and day of the week, syncs via NTP, and fetches weather data every 5 minutes from OpenWeatherMap. + +![clock - weather](assets/demo.gif) +--- + +## ✨ Features + +* LED matrix display (8x32) powered by MAX7219 +* WiFi configuration via web interface +* Real-time clock via NTP, current day of the week +* Current temperature display from OpenWeatherMap +* Fallback AP mode for first-time setup + +--- + +## πŸͺ› Wiring Diagram + +Connect the Wemos D1 Mini (ESP8266) to MAX7219 as follows: + +| Wemos D1 Mini | MAX7219 | +| ------------- | ------- | +| GND | GND | +| D6 | CLK | +| D7 | CS | +| D8 | DIN | +| 3V3 | VCC | + +--- + +## 🌐 Web Interface + +The device hosts a built-in web interface for configuration. + +1. On first boot, connect to the fallback AP: + * **SSID**: `ESPTimeCast` + * **Password**: `12345678` + * Open `http://192.168.4.1` in your browser +2. Enter your home Wifi and Password settings +3. Weather settings: Enter your OpenWeatherMap API, City and Country Code +4. Clock settings: Select your UTC Offset from the dropdown menu (default is `+09:00` for Japan) +5. Configure Clock and Weather display duration (in seconds) +6. Save your settings (device will reboot) + +### UI Preview: + +Web Interface + +--- + +## βš™οΈ Configuration Notes + +* **OpenWeatherMap API Key**: Get one at [openweathermap.org](https://openweathermap.org/api) +* **City Name**: Use city names like `Tokyo`, `London`, etc. +* **Country Code**: Enter the 2-letter country code (e.g., JP for Japan, GB for United Kingdom). +* **UTC Offset**: Select an offset from the dropdown menu. + +--- + +## πŸ”§ Installation + +1. Clone this repo +2. Flash the code using **Arduino IDE** or **PlatformIO** +3. Upload the `/data` folder using **LittleFS uploader** + +### πŸ”§ Board Setup + +Install the ESP8266 board package in Arduino IDE: +**Additional Board Manager URL**: +http://arduino.esp8266.com/stable/package_esp8266com_index.json + + +### πŸ“¦ Dependencies + +Make sure the following libraries are installed via the Arduino Library Manager or PlatformIO: + +* `NTPClient` by Fabrice Weinberg +* `ArduinoJson` by Benoit Blanchon +* `MD_Parola` / `MD_MAX72xx` all dependencies by majicDesigns +* `ESPAsyncTCP` by ESP32Async +* `ESPAsyncWebServer` by ESP32Async + + +### πŸ“ LittleFS Upload + +Use the **LittleFS Uploader Plugin** (install manually): +πŸ‘‰ [Installation Guide](https://randomnerdtutorials.com/arduino-ide-2-install-esp8266-littlefs/) + +To upload the `/data` folder: + +1. Open the Command Palette: + * Windows: `Ctrl + Shift + P` + * macOS: `Cmd + Shift + P` +2. Run: `Upload LittleFS to Pico/ESP8266/ESP32` + +**Important:** Make sure the Serial Monitor is **closed** before uploading. + +--- + +## 🀝 Contributing + +Pull requests are welcome! For major changes or bugs, please open an issue first to discuss what you'd like to improve or add. + +--- + +## β˜• Support This Project + +If you like this project, feel free to support me via [PayPal](https://paypal.me/officialuphoto). From 9e77ccf14b9738cbf76941b5562a12f90c43c400 Mon Sep 17 00:00:00 2001 From: M-Factory Date: Tue, 10 Jun 2025 17:28:55 +0900 Subject: [PATCH 2/2] Update README.md --- README.md | 147 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 94 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index f972f9b..cc93b26 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,34 @@ ![ESPTimeCast](assets/logo.svg) -**ESPTimeCast** is a WiFi-connected LED matrix clock and weather station using ESP8266 and MAX7219. -It shows the current time and day of the week, syncs via NTP, and fetches weather data every 5 minutes from OpenWeatherMap. +**ESPTimeCast** is a WiFi-connected LED matrix clock and weather station based on ESP8266 and MAX7219. +It displays the current time, day of the week (with custom symbols), and local weather fetched from OpenWeatherMap. +Setup and configuration are fully managed via a built-in web interface. ![clock - weather](assets/demo.gif) + --- ## ✨ Features -* LED matrix display (8x32) powered by MAX7219 -* WiFi configuration via web interface -* Real-time clock via NTP, current day of the week -* Current temperature display from OpenWeatherMap -* Fallback AP mode for first-time setup +- **LED Matrix Display (8x32)** powered by MAX7219, with custom font support +- **Simple Web Interface** for all configuration (WiFi, weather, time zone, display durations, and more) +- **Automatic NTP Sync** with robust status feedback and retries +- **Day of Week Display** with custom icons/symbols +- **Weather Fetching** from OpenWeatherMap (every 5 minutes, with error handling) +- **Temperature Unit Selector** (`C`, `F`, or `K`) +- **Fallback AP Mode** for easy first-time setup or WiFi recovery, with `/ap_status` endpoint +- **Timezone Selection** from IANA names (DST integrated on backend) +- **Persistent Config** stored in LittleFS, with backup/restore system +- **Status Animations** for WiFi conection, AP mode, time syncing. --- -## πŸͺ› Wiring Diagram +## πŸͺ› Wiring -Connect the Wemos D1 Mini (ESP8266) to MAX7219 as follows: +**Wemos D1 Mini (ESP8266) β†’ MAX7219** | Wemos D1 Mini | MAX7219 | -| ------------- | ------- | +|:-------------:|:-------:| | GND | GND | | D6 | CLK | | D7 | CS | @@ -30,81 +37,115 @@ Connect the Wemos D1 Mini (ESP8266) to MAX7219 as follows: --- -## 🌐 Web Interface +## 🌐 Web UI & Configuration -The device hosts a built-in web interface for configuration. +The built-in web interface provides full configuration for: -1. On first boot, connect to the fallback AP: - * **SSID**: `ESPTimeCast` - * **Password**: `12345678` - * Open `http://192.168.4.1` in your browser -2. Enter your home Wifi and Password settings -3. Weather settings: Enter your OpenWeatherMap API, City and Country Code -4. Clock settings: Select your UTC Offset from the dropdown menu (default is `+09:00` for Japan) -5. Configure Clock and Weather display duration (in seconds) -6. Save your settings (device will reboot) +- **WiFi settings** (SSID & Password) +- **Weather settings** (OpenWeatherMap API key, City, Country, Units) +- **Time zone** (will auto-populate if TZ is found) +- **Display durations** for clock and weather (milliseconds) +- **Backup & Restore** config options -### UI Preview: +### First-time Setup / AP Mode -Web Interface +1. Power on the device. If WiFi fails, it auto-starts in AP mode: + - **SSID:** `ESPTimeCast` + - **Password:** `12345678` + - Open `http://192.168.4.1` in your browser. +2. Set your WiFi and all other options. +3. Click **Save Setting** – the device saves config, reboots, and connects. + +### UI Example: +Web Interface --- ## βš™οΈ Configuration Notes -* **OpenWeatherMap API Key**: Get one at [openweathermap.org](https://openweathermap.org/api) -* **City Name**: Use city names like `Tokyo`, `London`, etc. -* **Country Code**: Enter the 2-letter country code (e.g., JP for Japan, GB for United Kingdom). -* **UTC Offset**: Select an offset from the dropdown menu. +- **OpenWeatherMap API Key:** [Get yours here](https://openweathermap.org/api) +- **City Name:** e.g. `Tokyo`, `London`, etc. +- **Country Code:** 2-letter code (e.g., `JP`, `GB`) +- **Time Zone:** Select from IANA zones (e.g., `America/New_York`, handles DST automatically) +- **Units:** `metric` (Β°C), `imperial` (Β°F), or `standard` (K) --- ## πŸ”§ Installation -1. Clone this repo -2. Flash the code using **Arduino IDE** or **PlatformIO** -3. Upload the `/data` folder using **LittleFS uploader** +1. **Clone this repo** +2. **Flash the ESP8266** using Arduino IDE or PlatformIO +3. **Upload `/data` folder** with LittleFS uploader (see below) -### πŸ”§ Board Setup +### Board Setup -Install the ESP8266 board package in Arduino IDE: -**Additional Board Manager URL**: -http://arduino.esp8266.com/stable/package_esp8266com_index.json +- Install ESP8266 board package: + `http://arduino.esp8266.com/stable/package_esp8266com_index.json` +- Select **Wemos D1 Mini** (or your ESP8266 variant) in Tools β†’ Board +### Dependencies -### πŸ“¦ Dependencies +Install these libraries (Library Manager / PlatformIO): -Make sure the following libraries are installed via the Arduino Library Manager or PlatformIO: +- `ArduinoJson` by Benoit Blanchon +- `MD_Parola / MD_MAX72xx` all dependencies by majicDesigns +- `ESPAsyncTCP` by ESP32Async +- `ESPAsyncWebServer` by ESP32Async -* `NTPClient` by Fabrice Weinberg -* `ArduinoJson` by Benoit Blanchon -* `MD_Parola` / `MD_MAX72xx` all dependencies by majicDesigns -* `ESPAsyncTCP` by ESP32Async -* `ESPAsyncWebServer` by ESP32Async +### LittleFS Upload +Install the [LittleFS Uploader](https://randomnerdtutorials.com/arduino-ide-2-install-esp8266-littlefs/). -### πŸ“ LittleFS Upload +**To upload `/data`:** -Use the **LittleFS Uploader Plugin** (install manually): -πŸ‘‰ [Installation Guide](https://randomnerdtutorials.com/arduino-ide-2-install-esp8266-littlefs/) +1. Open Command Palette: + - Windows: `Ctrl+Shift+P` + - macOS: `Cmd+Shift+P` +2. Run: `Upload LittleFS to ESP8266` -To upload the `/data` folder: +**Important:** Serial Monitor **must be closed** before uploading! -1. Open the Command Palette: - * Windows: `Ctrl + Shift + P` - * macOS: `Cmd + Shift + P` -2. Run: `Upload LittleFS to Pico/ESP8266/ESP32` +--- + +## πŸ“Ί Display Behavior + +**ESPTimeCast** automatically switches between two display modes: Clock and Weather. +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 | β€” | `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 | `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). +- 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 `no 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 `no temp`. +- All status/error messages (`no ntp`, `no temp`) are shown exactly as written. + +**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 -**Important:** Make sure the Serial Monitor is **closed** before uploading. --- ## 🀝 Contributing -Pull requests are welcome! For major changes or bugs, please open an issue first to discuss what you'd like to improve or add. +Pull requests are welcome! For major changes, please open an issue first to discuss. --- -## β˜• Support This Project +## β˜• Support this project + +If you like this project, you can [buy me a coffee](https://paypal.me/officialuphoto)! -If you like this project, feel free to support me via [PayPal](https://paypal.me/officialuphoto).