mirror of
https://github.com/mfactory-osaka/ESPTimeCast.git
synced 2026-04-03 03:00:24 -04:00
Update README.md
This commit is contained in:
M-Factory
147
README.md
147
README.md
@@ -1,27 +1,34 @@
|
||||
|
||||
|
||||
**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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## ✨ 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
|
||||
|
||||
<img src="assets/webui.png" alt="Web Interface" width="50%" />
|
||||
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:
|
||||
<img src="assets/webui2.png" alt="Web Interface" width="30%" />
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 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).
|
||||
|
||||
Reference in New Issue
Block a user