diff --git a/README.md b/README.md new file mode 100644 index 0000000..57ccda3 --- /dev/null +++ b/README.md @@ -0,0 +1,175 @@ +# ESP32 Device Framework + +A reusable ESP32 firmware base with Wi-Fi, web configuration UI, authentication, MQTT / Home Assistant integration, and factory reset. Add device-specific logic on top without re-implementing the boilerplate. + +## Table of contents + +- [Features](#features) +- [Building and flashing](#building-and-flashing) +- [First-time Wi-Fi setup](#first-time-wi-fi-setup) +- [Web UI](#web-ui) +- [MQTT / Home Assistant](#mqtt--home-assistant) +- [HTTP API](#http-api) +- [Configuration reference](#configuration-reference) +- [Extending the framework](#extending-the-framework) + +--- + +## Features + +- **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 +- **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 +- **Config persistence** — all settings stored as JSON in LittleFS (`/config.json`) + +--- + +## Building and flashing + +The project uses [PlatformIO](https://platformio.org/). + +```bash +# Build +pio run + +# Flash +pio run --target upload + +# Open serial monitor (115200 baud) +pio device monitor +``` + +Board target: `esp32-s3-devkitc-1` + +--- + +## First-time Wi-Fi setup + +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`). +3. Click **Save**. The device connects to your network and restarts. + +After connecting, the device is reachable at: + +- `http://.local` (default `http://esp32-device.local`) — mDNS, works on most local networks +- `http://` — shown in the serial monitor on boot + +### 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. + +Serial output shows the progress: + +``` +[BOOT] reset count 1/5 +[BOOT] reset count 2/5 +... +[BOOT] reset count 5/5, triggering factory reset +[BOOT] factory reset triggered! +[BOOT] factory reset complete, restarting... +``` + +--- + +## Web UI + +Browse to the device address to open the configuration page. + +### Info panel + +Shows the current hostname and IP address. + +### Hostname + +Sets the mDNS name (`.local`) and the MQTT client ID. Saved across reboots. + +### Security + +| Field | Description | +|-------|-------------| +| Require password | Enables HTTP Basic Auth on the web UI | +| Password | Password for the `admin` account. Leave blank to keep the existing password | + +### MQTT + +| Field | Description | +|-------|-------------| +| Enable | Toggle MQTT on/off | +| Broker | Hostname or IP of your MQTT broker | +| Port | Default `1883` | +| User / Pass | Broker credentials (leave Pass blank to keep the existing value) | +| Prefix | Topic prefix (default `device`) | + +Click **Save** to persist all settings. + +--- + +## MQTT / Home Assistant + +### Connection behaviour + +On connect the device publishes `online` to `/status` (retained) and sets `offline` as the LWT. If the broker is unreachable, the firmware probes the TCP port before attempting a full MQTT connect and retries every 30 seconds without blocking the web server. + +### Extending with discovery and topics + +Three stubs in `main.cpp` are the intended extension points: + +| Function | Purpose | +|----------|---------| +| `mqttSubscribe()` | Subscribe to command topics after connecting | +| `mqttCallback()` | Handle incoming messages | +| `mqttPublishDiscovery()` | Publish Home Assistant discovery payloads | + +--- + +## HTTP API + +### `GET /` + +Returns the HTML configuration page. + +### `POST /config` + +Saves all configuration submitted by the HTML form. Redirects back to `/`. + +--- + +## Configuration reference + +Config is stored as JSON in LittleFS at `/config.json`. + +```json +{ + "hostname": "esp32-device", + "mqtt": { + "en": true, + "host": "192.168.1.10", + "port": 1883, + "user": "ha", + "pass": "secret", + "prefix": "device" + }, + "auth": { + "en": true, + "pass": "secret" + } +} +``` + +The file is written by the web UI. To erase everything including flash, use `pio run --target erase`. + +--- + +## Extending the framework + +1. Add your hardware setup in `setup()` after the framework initialises. +2. Add your per-loop logic in `loop()` alongside `server.handleClient()` and `mqttLoop()`. +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()`. diff --git a/src/main.cpp b/src/main.cpp new file mode 100644 index 0000000..8f89161 --- /dev/null +++ b/src/main.cpp @@ -0,0 +1,470 @@ +#include +#include +#include +#include +#include +#include +#include +#include + +#define HOSTNAME_DEFAULT "esp32-device" +#define MQTT_MANUFACTURER "Baumann Enkataleiptics" +#define AUTH_USERNAME "admin" +#define MQTT_PROBE_TIMEOUT_MS 400 // keep short: blocks loop()/handleClient() per reconnect attempt +#define MQTT_PAYLOAD_AVAILABLE "online" +#define MQTT_PAYLOAD_NOT_AVAILABLE "offline" + +struct MqttConfig { + bool enabled = false; + char host[64] = ""; + uint16_t port = 1883; + char user[32] = ""; + char pass[32] = ""; + char prefix[32] = "device"; +}; + +struct AuthConfig { + bool enabled = false; + char pass[32] = ""; +}; + +static char hostname[32] = HOSTNAME_DEFAULT; +static MqttConfig mqttCfg; +static AuthConfig authCfg; +static WiFiManagerParameter hostnameParam("hostname", "Device hostname", hostname, 32); +static WebServer server(80); +static WiFiClient wifiClient; +static PubSubClient mqttClient(wifiClient); +static unsigned long mqttReconnectAt = 0; + +// --------------------------------------------------------------------------- +// Config persistence (JSON via LittleFS) +// --------------------------------------------------------------------------- + +static void loadConfig() { + Serial.println("[CFG] loading config"); + if (!LittleFS.exists("/config.json")) { Serial.println("[CFG] no config file"); return; } + File f = LittleFS.open("/config.json", "r"); + if (!f) { Serial.println("[CFG] failed to open"); return; } + + JsonDocument doc; + DeserializationError err = deserializeJson(doc, f); + f.close(); + if (err) { Serial.printf("[CFG] parse error: %s\n", err.c_str()); return; } + + if (doc["hostname"].is()) + strlcpy(hostname, doc["hostname"], sizeof(hostname)); + + JsonObject mq = doc["mqtt"]; + if (!mq.isNull()) { + mqttCfg.enabled = mq["en"] | false; + strlcpy(mqttCfg.host, mq["host"] | "", sizeof(mqttCfg.host)); + mqttCfg.port = mq["port"] | 1883; + strlcpy(mqttCfg.user, mq["user"] | "", sizeof(mqttCfg.user)); + strlcpy(mqttCfg.pass, mq["pass"] | "", sizeof(mqttCfg.pass)); + strlcpy(mqttCfg.prefix, mq["prefix"] | "device", sizeof(mqttCfg.prefix)); + } + + JsonObject auth = doc["auth"]; + if (!auth.isNull()) { + authCfg.enabled = auth["en"] | false; + strlcpy(authCfg.pass, auth["pass"] | "", sizeof(authCfg.pass)); + } + + Serial.printf("[CFG] loaded hostname=%s mqtt_en=%d\n", hostname, mqttCfg.enabled); +} + +static void saveConfig() { + JsonDocument doc; + doc["hostname"] = hostname; + + JsonObject mq = doc["mqtt"].to(); + mq["en"] = mqttCfg.enabled; + mq["host"] = mqttCfg.host; + mq["port"] = mqttCfg.port; + mq["user"] = mqttCfg.user; + mq["pass"] = mqttCfg.pass; + mq["prefix"] = mqttCfg.prefix; + + JsonObject auth = doc["auth"].to(); + auth["en"] = authCfg.enabled; + auth["pass"] = authCfg.pass; + + File f = LittleFS.open("/config.json", "w"); + if (f) { + serializeJson(doc, f); + f.close(); + Serial.printf("[CFG] saved hostname=%s mqtt_en=%d\n", hostname, mqttCfg.enabled); + } else { + Serial.println("[CFG] save failed"); + } +} + +// --------------------------------------------------------------------------- +// MQTT +// --------------------------------------------------------------------------- + +static void mqttCallback(char* topic, byte* payload, unsigned int len) { + String valStr; + for (unsigned i = 0; i < len; i++) valStr += (char)payload[i]; + Serial.printf("[MQTT] rcvd topic=%s payload=%s\n", topic, valStr.c_str()); + // TODO: handle incoming messages +} + +static void mqttPublishDiscovery() { + if (!mqttCfg.enabled || !mqttClient.connected()) return; + // TODO: publish Home Assistant discovery payloads +} + +static void mqttSubscribe() { + if (!mqttCfg.enabled) return; + // TODO: subscribe to device-specific topics +} + +static bool mqttConnect() { + if (!mqttCfg.enabled || strlen(mqttCfg.host) == 0) { + Serial.printf("[MQTT] connect skipped en=%d host=%d\n", + mqttCfg.enabled, strlen(mqttCfg.host) > 0); + return false; + } + + char clientId[32]; + { + uint8_t mac[6]; + WiFi.macAddress(mac); + snprintf(clientId, sizeof(clientId), "esp32-%02x%02x%02x", mac[3], mac[4], mac[5]); + } + + char statusTopic[128]; + snprintf(statusTopic, sizeof(statusTopic), "%s/status", mqttCfg.prefix); + + mqttClient.setServer(mqttCfg.host, mqttCfg.port); + mqttClient.setCallback(mqttCallback); + mqttClient.setBufferSize(1024); + + // Pass NULL for empty credentials so the broker treats it as an anonymous + // connection rather than an empty-string login (which some brokers reject). + const char* user = strlen(mqttCfg.user) > 0 ? mqttCfg.user : nullptr; + const char* pass = strlen(mqttCfg.pass) > 0 ? mqttCfg.pass : nullptr; + + Serial.printf("[MQTT] connecting to %s:%d as %s\n", mqttCfg.host, mqttCfg.port, clientId); + bool ok = mqttClient.connect(clientId, user, pass, + statusTopic, 0, true, MQTT_PAYLOAD_NOT_AVAILABLE); + + if (ok) { + Serial.printf("[MQTT] connected to %s:%d\n", mqttCfg.host, mqttCfg.port); + mqttClient.publish(statusTopic, MQTT_PAYLOAD_AVAILABLE, true); + mqttSubscribe(); + mqttPublishDiscovery(); + } else { + Serial.printf("[MQTT] failed rc=%d\n", mqttClient.state()); + } + return ok; +} + +static void mqttLoop() { + if (!mqttCfg.enabled || strlen(mqttCfg.host) == 0) return; + + if (!mqttClient.connected()) { + unsigned long now = millis(); + if (now > mqttReconnectAt) { + Serial.printf("[MQTT] probing %s:%d\n", mqttCfg.host, mqttCfg.port); + WiFiClient probe; + bool reachable = probe.connect(mqttCfg.host, mqttCfg.port, MQTT_PROBE_TIMEOUT_MS); + probe.stop(); + + if (reachable) { + Serial.println("[MQTT] probe OK, connecting"); + if (mqttConnect()) mqttReconnectAt = 0; + else mqttReconnectAt = now + 30000; + } else { + Serial.println("[MQTT] probe failed, retry in 30s"); + mqttReconnectAt = now + 30000; + } + } + } else { + mqttClient.loop(); + } +} + +// --------------------------------------------------------------------------- +// mDNS +// --------------------------------------------------------------------------- + +static void startMDNS() { + if (MDNS.begin(hostname)) { + Serial.printf("mDNS: %s.local\n", hostname); + MDNS.addService("http", "tcp", 80); + } else { + Serial.println("mDNS start failed"); + } +} + +// --------------------------------------------------------------------------- +// Web helpers +// --------------------------------------------------------------------------- + +static String escHtml(const String& s) { + String out; + for (unsigned i = 0; i < s.length(); i++) { + char c = s.charAt(i); + switch (c) { + case '&': out += "&"; break; + case '<': out += "<"; break; + case '>': out += ">"; break; + case '\'': out += "'"; break; + case '"': out += """; break; + default: out += c; + } + } + return out; +} + +static bool requireAuth() { + if (!authCfg.enabled) return true; + if (server.authenticate(AUTH_USERNAME, authCfg.pass)) return true; + server.requestAuthentication(); + return false; +} + +// --------------------------------------------------------------------------- +// Web handlers +// --------------------------------------------------------------------------- + +static void handleRoot() { + if (!requireAuth()) { Serial.println("[HTTP] GET / -> 401"); return; } + Serial.println("[HTTP] GET /"); + + String authSection; + { + String checked = authCfg.enabled ? " checked" : ""; + const char* passHint = strlen(authCfg.pass) > 0 ? "set — leave blank to keep" : "enter password"; + + authSection += + "
Security" + "
" + "" + "" + "
" + "
" + "
"; + } + + String mqttSection; + { + char portStr[8]; + snprintf(portStr, sizeof(portStr), "%u", mqttCfg.port); + String checked = mqttCfg.enabled ? " checked" : ""; + String hostVal = escHtml(mqttCfg.host); + String userVal = escHtml(mqttCfg.user); + String prefVal = escHtml(mqttCfg.prefix); + const char* passHint = strlen(mqttCfg.pass) > 0 ? "set — leave blank to keep" : "enter password"; + + mqttSection += + "
MQTT" + "
" + "" + "" + "
" + "
" + "
" + "
" + "
" + "
" + "
"; + } + + String html; + html.reserve(3072); + html += ""; + html += "ESP32 Device
"; + html += "

ESP32 Device

Configuration
"; + html += "
Hostname" + String(hostname) + "
"; + html += "
IP" + WiFi.localIP().toString() + "
"; + html += "
"; + html += ""; + html += authSection; + html += mqttSection; + html += "
"; + html += "
" + WiFi.macAddress() + "
"; + html += ""; + server.send(200, "text/html", html); + Serial.printf("[HTTP] GET / -> 200 (%u bytes)\n", html.length()); +} + +static void handleConfig() { + if (!requireAuth()) { Serial.println("[HTTP] POST /config -> 401"); return; } + Serial.println("[HTTP] POST /config"); + + if (server.hasArg("hostname")) { + String val = server.arg("hostname"); + val.trim(); + if (val.length() > 0) + val.toCharArray(hostname, sizeof(hostname)); + } + + // Persist connection fields regardless of enable checkbox so edits made while + // disabling MQTT aren't discarded. + if (server.hasArg("mqtt_host")) + strlcpy(mqttCfg.host, server.arg("mqtt_host").c_str(), sizeof(mqttCfg.host)); + if (server.hasArg("mqtt_port")) + mqttCfg.port = server.arg("mqtt_port").toInt(); + if (server.hasArg("mqtt_user")) + strlcpy(mqttCfg.user, server.arg("mqtt_user").c_str(), sizeof(mqttCfg.user)); + if (server.hasArg("mqtt_pass") && server.arg("mqtt_pass").length() > 0) + strlcpy(mqttCfg.pass, server.arg("mqtt_pass").c_str(), sizeof(mqttCfg.pass)); + if (server.hasArg("mqtt_prefix")) + strlcpy(mqttCfg.prefix, server.arg("mqtt_prefix").c_str(), sizeof(mqttCfg.prefix)); + + mqttCfg.enabled = server.hasArg("mqtt_en"); + Serial.printf("[HTTP] mqtt enabled=%d host=%s port=%u user=%s prefix=%s\n", + mqttCfg.enabled, mqttCfg.host, mqttCfg.port, mqttCfg.user, mqttCfg.prefix); + + if (server.hasArg("auth_en")) { + if (server.hasArg("auth_pass") && server.arg("auth_pass").length() > 0) + strlcpy(authCfg.pass, server.arg("auth_pass").c_str(), sizeof(authCfg.pass)); + authCfg.enabled = strlen(authCfg.pass) > 0; + Serial.printf("[HTTP] auth enabled=%d\n", authCfg.enabled); + } else { + authCfg.enabled = false; + Serial.println("[HTTP] auth disabled"); + } + + saveConfig(); + + // let mqttLoop handle reconnection to avoid blocking the HTTP handler + if (mqttClient.connected()) mqttClient.disconnect(); + mqttReconnectAt = 0; + + server.sendHeader("Location", "/", true); + server.send(303); +} + +static void startServer() { + server.on("/", handleRoot); + server.on("/config", HTTP_POST, handleConfig); + server.begin(); + Serial.println("HTTP server started"); +} + +// --------------------------------------------------------------------------- +// Factory reset (rapid reset 5x within a few seconds) +// --------------------------------------------------------------------------- + +static void factoryReset() { + Serial.println("[BOOT] factory reset triggered!"); + + strlcpy(hostname, HOSTNAME_DEFAULT, sizeof(hostname)); + hostnameParam.setValue(hostname, strlen(hostname)); + + authCfg.enabled = false; + authCfg.pass[0] = '\0'; + + mqttCfg.enabled = false; + mqttCfg.host[0] = '\0'; + mqttCfg.port = 1883; + mqttCfg.user[0] = '\0'; + mqttCfg.pass[0] = '\0'; + strlcpy(mqttCfg.prefix, "device", sizeof(mqttCfg.prefix)); + + saveConfig(); + + Serial.println("[BOOT] factory reset complete, restarting..."); + delay(200); + ESP.restart(); +} + +static void checkFactoryReset() { + const int THRESHOLD = 5; + int count = 0; + File f = LittleFS.open("/reset_count", "r"); + if (f) { + count = f.parseInt(); + f.close(); + } + count++; + if (count >= THRESHOLD) { + LittleFS.remove("/reset_count"); + Serial.printf("[BOOT] reset count %d, triggering factory reset\n", count); + factoryReset(); + return; + } + f = LittleFS.open("/reset_count", "w"); + if (f) { + f.print(count); + f.close(); + Serial.printf("[BOOT] reset count %d/%d\n", count, THRESHOLD); + } +} + +// --------------------------------------------------------------------------- +// Setup & loop +// --------------------------------------------------------------------------- + +void setup() { + Serial.begin(115200); + Serial.println("\n\n=== ESP32 Device boot ==="); + LittleFS.begin(true); + + loadConfig(); + hostnameParam.setValue(hostname, strlen(hostname)); + + checkFactoryReset(); + + // Reset-counter settle window: if the device stays powered past this point it + // wasn't a rapid power-cycle, so clear the counter before the (possibly + // indefinitely blocking) WiFi portal. + delay(3000); + LittleFS.remove("/reset_count"); + + Serial.println("[WIFI] starting WiFiManager"); + WiFiManager wm; + wm.setTitle("ESP32 Device"); + + wm.addParameter(&hostnameParam); + wm.setSaveParamsCallback([]() { + strlcpy(hostname, hostnameParam.getValue(), sizeof(hostname)); + saveConfig(); + }); + + if (!wm.autoConnect("ESP32-Device")) { + Serial.println("[WIFI] failed, restarting"); + ESP.restart(); + } + Serial.printf("[WIFI] connected, IP: %s\n", WiFi.localIP().toString().c_str()); + + strlcpy(hostname, hostnameParam.getValue(), sizeof(hostname)); + saveConfig(); + startServer(); + startMDNS(); + mqttReconnectAt = 0; + + Serial.printf("[BOOT] ready at http://%s.local or http://%s\n", + hostname, WiFi.localIP().toString().c_str()); +} + +void loop() { + server.handleClient(); + mqttLoop(); +}