adebaumann/Device-Framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README

Browse Source
This commit is contained in:
Adrian A. Baumann
2026-06-29 01:10:47 +02:00
parent 8cff7a4f1c
commit 39182e108f
1 changed files with 37 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+37 -23
View File
@@ -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 `<hostname>.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 (`<hostname>.local`) and the MQTT client ID. Saved across reboots.
Sets the mDNS name (`<hostname>.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 (`<hostname>.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`.