diff --git a/README.md b/README.md index 57ccda3..12ffb7a 100644 --- a/README.md +++ b/README.md @@ -19,11 +19,11 @@ A reusable ESP32 firmware base with Wi-Fi, web configuration UI, authentication, - **Wi-Fi** via WiFiManager — captive-portal setup on first boot, credentials stored in flash - **mDNS** — device reachable as `.local` -- **Web UI** — responsive configuration page served from the device +- **Web UI** — responsive configuration page served from the device, with logo support - **Authentication** — optional HTTP Basic Auth to protect the web UI - **MQTT** — connects to any broker, publishes an availability topic, reconnects automatically without blocking the web server - **Home Assistant discovery** — stub ready for your entities -- **Factory reset** — rapid 5× power-cycle clears all settings and restarts +- **Factory reset** — rapid power-cycling clears settings (5× config, 10× config + Wi-Fi credentials) - **Config persistence** — all settings stored as JSON in LittleFS (`/config.json`) --- @@ -34,16 +34,21 @@ The project uses [PlatformIO](https://platformio.org/). ```bash # Build -pio run +pio run -e esp32dev -# Flash -pio run --target upload +# Flash firmware +pio run -e esp32dev --target upload -# Open serial monitor (115200 baud) +# Upload filesystem image (logo, etc.) — only needed when data/ changes +pio run -e esp32dev --target uploadfs + +# Open serial monitor (115 200 baud) pio device monitor ``` -Board target: `esp32-s3-devkitc-1` +> **Note:** close the serial monitor before uploading — it holds the serial port exclusively. + +Board targets: `esp32dev`, `esp32-s3-devkitc-1` --- @@ -52,7 +57,7 @@ Board target: `esp32-s3-devkitc-1` On first boot (or when stored Wi-Fi credentials are missing), the device starts an access point named **ESP32-Device**. Connect to it with any phone or laptop — a captive portal will appear automatically. 1. Enter your Wi-Fi SSID and password. -2. Optionally change the **Device hostname** (default: `esp32-device`). +2. Optionally change the **Device hostname** (default: `esp32-device`, max 63 characters). 3. Click **Save**. The device connects to your network and restarts. After connecting, the device is reachable at: @@ -62,16 +67,21 @@ After connecting, the device is reachable at: ### Factory reset -If you lose the web UI password or need to clear all settings, **reset the device 5 times in quick succession** (press EN or cycle power 5× within a few seconds, before boot completes). All settings are wiped and the device restarts into the Wi-Fi captive portal. +Power-cycle (or press EN) rapidly before the 3-second boot window expires. The reset counter accumulates across rapid reboots: -Serial output shows the progress: +| Cycles | Effect | +|--------|--------| +| 5 – 9 | Clears hostname, auth, and MQTT config; restarts into normal Wi-Fi | +| 10+ | Clears all of the above **plus** stored Wi-Fi credentials; restarts into captive portal | + +Serial output shows the accumulated count: ``` -[BOOT] reset count 1/5 -[BOOT] reset count 2/5 +[BOOT] reset count 3 +[BOOT] reset count 4 ... -[BOOT] reset count 5/5, triggering factory reset -[BOOT] factory reset triggered! +[BOOT] reset count 5, triggering factory reset +[BOOT] factory reset triggered (clearWifi=0)! [BOOT] factory reset complete, restarting... ``` @@ -81,13 +91,17 @@ Serial output shows the progress: Browse to the device address to open the configuration page. +### Logo + +Place a `logo.png` in the `data/` directory and upload the filesystem image once. The logo appears in the top-left of the configuration page. The `data/logo.png` included in this repo is a 200×200 px transparent PNG. + ### Info panel Shows the current hostname and IP address. ### Hostname -Sets the mDNS name (`.local`) and the MQTT client ID. Saved across reboots. +Sets the mDNS name (`.local`). Changing the hostname automatically restarts the device so mDNS re-registers with the new name. ### Security @@ -106,7 +120,7 @@ Sets the mDNS name (`.local`) and the MQTT client ID. Saved across reb | User / Pass | Broker credentials (leave Pass blank to keep the existing value) | | Prefix | Topic prefix (default `device`) | -Click **Save** to persist all settings. +Click **Save** to persist all settings. Click **Reset Device** to restart the device immediately. --- @@ -130,13 +144,12 @@ Three stubs in `main.cpp` are the intended extension points: ## HTTP API -### `GET /` - -Returns the HTML configuration page. - -### `POST /config` - -Saves all configuration submitted by the HTML form. Redirects back to `/`. +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/` | HTML configuration page | +| `GET` | `/logo.png` | Logo image served from LittleFS | +| `POST` | `/config` | Save configuration; redirects to `/`. Restarts if hostname changed | +| `POST` | `/reset` | Restart the device immediately | --- @@ -173,3 +186,4 @@ The file is written by the web UI. To erase everything including flash, use `pio 3. Fill in the three MQTT stubs to subscribe, receive, and publish discovery payloads. 4. Add extra web routes with `server.on(...)` in `startServer()` if you need device-specific endpoints. 5. Persist extra config fields by adding keys to `loadConfig()` and `saveConfig()`. +6. Place static files (images, etc.) in `data/` and upload the filesystem image with `pio run --target uploadfs`.