#pragma once // Browser-based configuration portal for ESP32 MQTT observer builds. // // Two modes: // - SETUP: open SoftAP + captive portal, raised automatically on first boot // when no WiFi is configured (wifi_ssid empty), or manually via // `start webconfig ap`. Save -> reboot; auto-stops after an idle timeout. // - LAN: bound to the existing STA connection (owned by the MQTT bridge // task), started via `start webconfig`, admin-password login required. // // Concurrency model: AsyncWebServer handlers run on the async_tcp task and // must never touch the CLI, prefs persistence, or the radio. Config writes // are marshaled into a single-slot command batch that tick() - called from // MyMesh::loop() on the Arduino loop task - drains through the existing CLI // `set` handlers. Prefs-struct reads and batch state are guarded by _mux. // The HTTP server/routes live for the firmware lifetime; routes acquire the // currently attached WebConfigServer session only for the synchronous handler // call. This lets a stopped session be reclaimed without deleting an // AsyncWebServer that may still be referenced by a partially received request. // // No persisted state: everything here is RAM-only, so prefs-file layouts // (fleet-critical) are untouched. #if defined(ESP_PLATFORM) && defined(WITH_MQTT_BRIDGE) #define WITH_WEBCONFIG 1 #include #include #include #include class AsyncWebServer; class AsyncWebServerRequest; class DNSServer; struct NodePrefs; struct MQTTPrefs; #ifndef WEBCONFIG_AP_IDLE_TIMEOUT_MS #define WEBCONFIG_AP_IDLE_TIMEOUT_MS (10UL * 60UL * 1000UL) #endif #ifndef WEBCONFIG_SESSION_TTL_MS #define WEBCONFIG_SESSION_TTL_MS (20UL * 60UL * 1000UL) #endif class WebConfigServer { public: enum Mode : uint8_t { MODE_OFF = 0, MODE_SETUP, MODE_LAN }; class Callbacks { public: // Run one CLI command. Called from tick() only (loop task); reply is 160 bytes. virtual void execCommand(char* cmd, char* reply) = 0; virtual void rebootNow() = 0; // Bracket a config batch so bridge restarts triggered by individual // `set` handlers can be coalesced into one. virtual void onConfigBatchStart() {} virtual void onConfigBatchEnd() {} // Fill buf with the stats JSON snapshot. Called from tick() (loop task). virtual void buildStatsJson(char* buf, size_t buf_size) = 0; // Teardown finished (session + DNS freed, WiFi mode restored). virtual void onWebConfigStopped() {} }; WebConfigServer(NodePrefs* prefs, MQTTPrefs* obs, Callbacks* callbacks, const uint8_t* pub_key, const char* fw_ver, const char* role, const char* board_name); ~WebConfigServer(); // For the device display: true while a setup-mode portal is active. // Fills the AP SSID and portal IP; either buffer may be NULL to just poll. // Call from the loop task only (same task that changes the mode). static bool getSetupInfo(char* ssid, size_t ssid_len, char* ip, size_t ip_len); // For the device display: true once a config save completed and the node is // about to reboot — ground truth for the user even if the browser lost its // connection before the confirmation arrived. Loop task only. static bool isRebootPending(); bool startSetupMode(char reply[]); // open SoftAP + DNS captive portal bool startLanMode(char reply[]); // bind to existing STA connection void requestStop(); // stop listening and detach this session void tick(uint32_t now); // call every loop iteration Mode mode() const { return _mode; } bool isRunning() const { return _mode != MODE_OFF; } bool isStopping() const { return _stopping; } private: // Batch/reboot/stop decisions and timings live in the fork-owned pure spec // WebConfigBatch.h (host-tested by test/test_webconfig_batch). These aliases // keep a single source of truth so the spec and this server cannot drift. static const int MAX_BATCH = WebConfigBatch::kMaxBatch; static const size_t MAX_BODY = 4096; // A detached session normally drains immediately because handlers are short. // If one does not, keep the session alive (safe) and emit a diagnostic rather // than freeing memory still referenced by the async task. static const uint32_t STOP_WARN_MS = WebConfigBatch::kStopWarnMs; enum BatchState : uint8_t { BATCH_IDLE = 0, BATCH_PENDING, BATCH_DONE }; // What filled the shared slot. A config save comes from allowlisted form // fields; a CLI sequence is arbitrary commands typed into the terminal. They // share the slot (see WebConfigBatch.h) but differ in how results are read // and in whether `key` means anything, so every reader checks the kind. enum BatchKind : uint8_t { BATCH_CONFIG = 0, BATCH_CLI }; // BatchState and WebConfigBatch::State are deliberately kept as separate // types (the enum is stored in a volatile member and used in prints); this // is the one conversion point. static WebConfigBatch::State toSpecState(BatchState s) { switch (s) { case BATCH_PENDING: return WebConfigBatch::State::Pending; case BATCH_DONE: return WebConfigBatch::State::Done; default: return WebConfigBatch::State::Idle; } } struct BatchEntry { char key[24]; // allowlisted config key (echoed back to the UI); empty for CLI entries char cmd[160]; // full CLI command (may contain secrets - never echoed) char reply[160]; // CLI reply budget, same 160 bytes the serial console gets }; NodePrefs* _prefs; MQTTPrefs* _obs; Callbacks* _cb; const uint8_t* _pub_key; const char* _fw_ver; const char* _role; const char* _board_name; AsyncWebServer* _server = NULL; DNSServer* _dns = NULL; SemaphoreHandle_t _mux; Mode _mode = MODE_OFF; bool _stopping = false; bool _was_setup_ap = false; bool _initial_setup = false; char _ap_ssid[33] = {0}; // Currently attached session, also used by the display's setup-info poll. static WebConfigServer* _active; // Process-lifetime listener and route table. Requests retain a pointer to the // AsyncWebServer internally until disconnect, so this object is deliberately // never deleted during normal firmware operation. static AsyncWebServer* _host; // Command batch: filled by async_tcp under _mux, drained by tick(). volatile BatchState _batch_state = BATCH_IDLE; volatile BatchKind _batch_kind = BATCH_CONFIG; uint8_t _batch_count = 0; uint8_t _batch_next = 0; // drain progress (one command per tick) uint32_t _batch_last_cmd = 0; bool _batch_reboot = false; bool _batch_reboot_armed = false; bool _batch_all_ok = true; // every drained command replied "OK" (gates reboot) // Client-supplied batch identity, echoed in the 202/result/409 responses so a // reused/lost/concurrent result can't be mistaken for this client's own. char _batch_reqid[24] = {0}; BatchEntry _batch[MAX_BATCH]; // LAN-mode session (single slot; new login evicts the old session) char _session_token[33] = {0}; uint32_t _session_last_seen = 0; uint8_t _login_fails = 0; uint32_t _login_lock_until = 0; // Once set (via /api/portal/exit), OS captive probes get native "success" // replies so the phone's sign-in sheet can be dismissed without dropping the // WiFi, letting the user continue in their real browser. async_tcp-task only. volatile bool _captive_release = false; // Save-path diagnostics: 1 Hz serial trace for 60 s after each config POST // (AP station count, heap, batch state) to pinpoint client drops on hardware. volatile uint32_t _diag_until = 0; uint32_t _diag_last = 0; volatile uint32_t _last_activity = 0; uint32_t _reboot_at = 0; // 0 = none scheduled uint32_t _stop_warn_at = 0; bool _stop_warned = false; // Number of synchronous route handlers currently using this session. Access // is serialized by the file-local route spinlock in WebConfigServer.cpp. uint32_t _handler_refs = 0; volatile uint32_t _stats_wanted_until = 0; uint32_t _stats_built_at = 0; char _stats_json[1024] = {0}; void createServer(); void registerRoutes(); typedef void (WebConfigServer::*RequestHandler)(AsyncWebServerRequest*); static void dispatchRequest(AsyncWebServerRequest* req, RequestHandler handler); void attachRoutes(); void detachRoutes(); uint32_t handlerRefCount() const; void drainBatch(uint32_t now); void finalizeTeardown(); bool checkAuth(AsyncWebServerRequest* req); static void collectBody(AsyncWebServerRequest* req, uint8_t* data, size_t len, size_t index, size_t total); void handleRoot(AsyncWebServerRequest* req); void handleStatus(AsyncWebServerRequest* req); void handleLogin(AsyncWebServerRequest* req); void handleLogout(AsyncWebServerRequest* req); void handleConfigGet(AsyncWebServerRequest* req); void handleConfigPost(AsyncWebServerRequest* req); void handleConfigResult(AsyncWebServerRequest* req); void handleCliPost(AsyncWebServerRequest* req); void handleCliResult(AsyncWebServerRequest* req); void handleStats(AsyncWebServerRequest* req); void handleScan(AsyncWebServerRequest* req); void handlePresets(AsyncWebServerRequest* req); void handleReboot(AsyncWebServerRequest* req); void handlePortalExit(AsyncWebServerRequest* req); void handleNotFound(AsyncWebServerRequest* req); }; #endif // ESP_PLATFORM && WITH_MQTT_BRIDGE