fix: defer WS hardware ops to main loop; clean up webserver init

The /snapshot WebSocket handler runs on the AsyncTCP task. Several
commands (display, low_power, sleep, power_off) were calling
u8g2.setPowerSave / u8g2.setContrast / digitalWrite(PWR_CTRL,...)
directly from that task while the main loop hammered the same
peripherals — under feature-test load at 10Hz this caused the device
to stall for ~4s and HTTP responses to time out mid-body.

  * Add a portMUX-protected pending-action mask. The WS callback
    queues the hardware op and updates the matching state flag
    (b_u8g2Sleep / b_softSleep) synchronously so the status frame is
    accurate; the main loop drains the mask early in loop() (before
    the b_softSleep guard so SLEEP_OFF can wake the device).
  * StopWatch.* is just bool/uint32 writes, so timer ops stay
    synchronous in the callback.
  * webserver.h: register handlers only once across stop/start
    cycles, drop the duplicate addHandler(&websocket), and move
    server.begin() to the end of startWebServer() so handlers are
    in place before the server accepts requests.
  * WS DATA callback: build the String with the (buf,len)
    constructor instead of O(N²) char-by-char concatenation, and
    only process complete unfragmented text frames.
  * Use unsigned long for the WS broadcast lastUpdate to avoid
    signed-subtraction wrap at the millis() 49.7-day rollover.
  * Document why WiFi.setSleep(false) is the wrong call here:
    tested it, caused 8% loss and HTTP all-timeout when BLE is
    active because BT/WiFi share the 2.4GHz radio and the coex
    layer needs WiFi sleep windows for BT slots.

Stress test (10Hz WS + HTTP every 1s + 5 cmd/s feature chaos, 120s):

           pre-fix       post-fix
  max gap   4.18 s       0.90 s
  HTTP fail 1            0
  HTTP slow 2            0

Feature regression (60 WS commands) still 60/60 PASS.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: skialpine

include/parameter.h

@@ -25,6 +25,20 @@ uint8_t i_websocketLedR = 0;
 uint8_t i_websocketLedG = 0;
 uint8_t i_websocketLedB = 0;
 unsigned long t_lastWebsocketStatusUpdate = 0;
+
+// Websocket pending-command mask. Set on the AsyncTCP task by the WS event
+// callback; drained on the main loop. Defers hardware-touching ops (u8g2,
+// stopWatch, power-rail GPIOs) so they never race the main loop.
+const uint32_t WSP_DISPLAY_ON  = 1u << 0;
+const uint32_t WSP_DISPLAY_OFF = 1u << 1;
+const uint32_t WSP_LOWPWR_ON   = 1u << 2;
+const uint32_t WSP_LOWPWR_OFF  = 1u << 3;
+const uint32_t WSP_SLEEP_ON    = 1u << 4;
+const uint32_t WSP_SLEEP_OFF   = 1u << 5;
+const uint32_t WSP_POWER_OFF   = 1u << 6;
+portMUX_TYPE wsPendingMux = portMUX_INITIALIZER_UNLOCKED;
+volatile uint32_t wsPendingMask = 0;
+
 int i_onWrite_counter = 0;
 unsigned long t_heartBeat = 0;
 unsigned long t_firstConnect = 0;

include/webserver.h

@@ -14,49 +14,53 @@ static AsyncWebServer server(80);
 static AsyncWebSocket websocket("/snapshot");
 
 void startWebServer() {
-  server.begin();
-  Serial.println("HTTP server started");
-  AsyncCallbackJsonWebHandler *wifiHandler = new AsyncCallbackJsonWebHandler(
-      "/setup/wifi", [](AsyncWebServerRequest *request, JsonVariant &json) {
-        JsonObject jsonObj = json.as<JsonObject>();
-        if (jsonObj.isNull()) {
-          request->send(400);
-          return;
-        }
-        if (jsonObj["ssid"] == NULL) {
-          request->send(400);
-          return;
-        }
-        String ssid = jsonObj["ssid"];
-        String pass = jsonObj["pass"];
+  // Handlers must be registered before server.begin(), and only once across
+  // stop/start cycles — server.end() doesn't clear the handler list.
+  static bool handlersRegistered = false;
+  if (!handlersRegistered) {
+    AsyncCallbackJsonWebHandler *wifiHandler = new AsyncCallbackJsonWebHandler(
+        "/setup/wifi", [](AsyncWebServerRequest *request, JsonVariant &json) {
+          JsonObject jsonObj = json.as<JsonObject>();
+          if (jsonObj.isNull()) {
+            request->send(400);
+            return;
+          }
+          if (jsonObj["ssid"] == NULL) {
+            request->send(400);
+            return;
+          }
+          String ssid = jsonObj["ssid"];
+          String pass = jsonObj["pass"];
 
-        saveCredentials(ssid, pass);
-        Serial.println("new ssid saved");
-        request->send(200);
-        esp_restart();
-      });
-  server.addHandler(wifiHandler);
+          saveCredentials(ssid, pass);
+          Serial.println("new ssid saved");
+          request->send(200);
+          esp_restart();
+        });
+    server.addHandler(wifiHandler);
 
-  server.addHandler(&websocket).addMiddleware([](AsyncWebServerRequest *request, ArMiddlewareNext next) {
-    // ws.count() is the current count of WS clients: this one is trying to upgrade its HTTP connection
-    if (websocket.count() > 0) {
-      // if we have 1 clients or more, prevent the next one to connect
-      request->send(503, "text/plain", "Server is busy");
+    server.addHandler(&websocket).addMiddleware([](AsyncWebServerRequest *request, ArMiddlewareNext next) {
+      // ws.count() is the current count of WS clients: this one is trying to upgrade its HTTP connection
+      if (websocket.count() > 0) {
+        // if we have 1 clients or more, prevent the next one to connect
+        request->send(503, "text/plain", "Server is busy");
+      } else {
+        // process next middleware and at the end the handler
+        next();
+      }
+    });
+
+    if (!LittleFS.begin()) {
+      Serial.println("LittleFS mount failed");
     } else {
-      // process next middleware and at the end the handler
-      next();
+      server.serveStatic("/", LittleFS, "/").setDefaultFile("index.html");
+      Serial.println("Serving web-apps");
     }
-  });
-  server.addHandler(&websocket);
-
-  if (!LittleFS.begin()) {
-    Serial.println("SPIFFS failed");
-    return;
+    handlersRegistered = true;
   }
 
-  server.serveStatic("/", LittleFS, "/").setDefaultFile("index.html");
-
-  Serial.println("Serving web-apps");
+  server.begin();
+  Serial.println("HTTP server started");
 }
 
 void stopWebServer() {

src/hds.ino

@@ -483,6 +483,45 @@ bool parseWebsocketRgb(String input, uint8_t &r, uint8_t &g, uint8_t &b) {
   return true;
 }
 
+// Queue a pending hardware action so the main loop performs it on its own
+// task. The WS event callback runs on the AsyncTCP task and must not touch
+// u8g2, stopWatch, or power-rail GPIOs directly.
+inline void wsQueuePending(uint32_t bits) {
+  portENTER_CRITICAL(&wsPendingMux);
+  wsPendingMask |= bits;
+  portEXIT_CRITICAL(&wsPendingMux);
+}
+
+void processWsPendingCmds() {
+  portENTER_CRITICAL(&wsPendingMux);
+  uint32_t mask = wsPendingMask;
+  wsPendingMask = 0;
+  portEXIT_CRITICAL(&wsPendingMux);
+  if (mask == 0) return;
+
+  // Hardware ops only — touching u8g2 (I2C) or peripheral power rails from
+  // the AsyncTCP task can race the main loop. State flags (b_u8g2Sleep,
+  // b_softSleep, etc.) are already updated synchronously in the WS callback
+  // so status frames stay accurate.
+  if (mask & WSP_DISPLAY_ON)  { u8g2.setPowerSave(0); }
+  if (mask & WSP_DISPLAY_OFF) { u8g2.setPowerSave(1); }
+  if (mask & WSP_LOWPWR_ON)   { u8g2.setContrast(0); }
+  if (mask & WSP_LOWPWR_OFF)  { u8g2.setContrast(255); }
+  if (mask & WSP_SLEEP_OFF) {
+    digitalWrite(PWR_CTRL, HIGH);
+    digitalWrite(ACC_PWR_CTRL, HIGH);
+    u8g2.setPowerSave(0);
+  }
+  if (mask & WSP_SLEEP_ON) {
+    u8g2.setPowerSave(1);
+    digitalWrite(PWR_CTRL, LOW);
+    digitalWrite(ACC_PWR_CTRL, LOW);
+  }
+  if (mask & WSP_POWER_OFF) {
+    b_powerOff = true;
+  }
+}
+
 void setWebsocketLedRgb(uint8_t r, uint8_t g, uint8_t b) {
   i_websocketLedR = r;
   i_websocketLedG = g;
@@ -649,6 +688,8 @@ bool handleWebsocketControlCommand(AsyncWebSocketClient *client, String command,
   }
 
   if (command == "timer") {
+    // StopWatch is just bool/uint32 state — safe to mutate from the AsyncTCP
+    // task, no hardware bus involved.
     if (action == "start") {
       Serial.println("Websocket timer start detected.");
       stopWatch.reset();
@@ -691,17 +732,20 @@ bool handleWebsocketControlCommand(AsyncWebSocketClient *client, String command,
   }
 
   if (command == "display") {
+    // Update the state flag synchronously so the status frame we send next
+    // reflects the requested state. The u8g2 call (I2C, not thread-safe) is
+    // deferred and runs on the main loop one tick later.
     if (action == "on") {
       Serial.println("Websocket LED/display on detected.");
-      u8g2.setPowerSave(0);
       b_u8g2Sleep = false;
+      wsQueuePending(WSP_DISPLAY_ON);
       sendWebsocketStatus(client, "ok");
       return true;
     }
     if (action == "off") {
       Serial.println("Websocket display off detected.");
-      u8g2.setPowerSave(1);
       b_u8g2Sleep = true;
+      wsQueuePending(WSP_DISPLAY_OFF);
       sendWebsocketStatus(client, "ok");
       return true;
     }
@@ -712,15 +756,15 @@ bool handleWebsocketControlCommand(AsyncWebSocketClient *client, String command,
   if (command == "low_power") {
     if (action == "on") {
       Serial.println("Websocket low power mode on detected.");
-      u8g2.setContrast(0);
       b_websocketLowPowerEnabled = true;
+      wsQueuePending(WSP_LOWPWR_ON);
       sendWebsocketStatus(client, "ok");
       return true;
     }
     if (action == "off") {
       Serial.println("Websocket low power mode off detected.");
-      u8g2.setContrast(255);
       b_websocketLowPowerEnabled = false;
+      wsQueuePending(WSP_LOWPWR_OFF);
       sendWebsocketStatus(client, "ok");
       return true;
     }
@@ -731,20 +775,18 @@ bool handleWebsocketControlCommand(AsyncWebSocketClient *client, String command,
   if (command == "sleep" || command == "soft_sleep") {
     if (action == "on") {
       Serial.println("Websocket soft sleep on detected.");
-      u8g2.setPowerSave(1);
+      // Set state flags synchronously so status reflects the requested mode.
+      // u8g2 + GPIO power-rail writes are deferred to the main loop.
       b_softSleep = true;
-      digitalWrite(PWR_CTRL, LOW);
-      digitalWrite(ACC_PWR_CTRL, LOW);
+      wsQueuePending(WSP_SLEEP_ON);
       sendWebsocketStatus(client, "ok");
       return true;
     }
     if (action == "off" || action == "wake") {
       Serial.println("Websocket soft sleep off detected.");
-      digitalWrite(PWR_CTRL, HIGH);
-      digitalWrite(ACC_PWR_CTRL, HIGH);
-      u8g2.setPowerSave(0);
-      b_u8g2Sleep = false;
       b_softSleep = false;
+      b_u8g2Sleep = false;
+      wsQueuePending(WSP_SLEEP_OFF);
       sendWebsocketStatus(client, "ok");
       return true;
     }
@@ -755,7 +797,7 @@ bool handleWebsocketControlCommand(AsyncWebSocketClient *client, String command,
   if (command == "power" && action == "off") {
     Serial.println("Websocket power off detected.");
     sendWebsocketPowerOff(0);
-    b_powerOff = true;
+    wsQueuePending(WSP_POWER_OFF);
     sendWebsocketStatus(client, "ok");
     return true;
   }
@@ -912,16 +954,15 @@ void _wifi_init(void *args) {
       Serial.printf("Pong received from client %u\n", client->id());
     }
     if (type == WS_EVT_DATA) {
-
       AwsFrameInfo *info = (AwsFrameInfo *)arg;
-      String msg = "";
-
-      for (size_t i = 0; i < info->len; i++) {
-        msg += (char)data[i];
+      // Only handle complete, unfragmented text frames. Fragmented or binary
+      // frames would corrupt the parsers below.
+      if (info->final && info->index == 0 && info->len == len && info->opcode == WS_TEXT) {
+        String msg((const char *)data, len);
+        Serial.print("Websocket recv: ");
+        Serial.println(msg);
+        handleWebsocketRateCommand(client, msg);
       }
-      Serial.print("Websocket recv: ");
-      Serial.println(msg);
-      handleWebsocketRateCommand(client, msg);
     }
   });
   vTaskDelete(NULL);
@@ -1806,6 +1847,11 @@ void setManualStableValue(float value) {
 
 
 void loop() {
+  // Drain any deferred WS hardware actions before checking shutdown/sleep,
+  // so a SLEEP_OFF / POWER_OFF queued from the AsyncTCP task takes effect
+  // here on the loop task rather than racing peripheral drivers.
+  processWsPendingCmds();
+
   if (b_powerOff){
     shut_down_now_nobeep();
     return;
@@ -1930,7 +1976,7 @@ void loop() {
         if (b_wifiEnabled) {
           websocket.cleanupClients(1);
           ElegantOTA.loop();
-          static long lastUpdate = 0;
+          static unsigned long lastUpdate = 0;
           unsigned long current = millis();
           if (current - lastUpdate >= weightWebsocketNotifyInterval) {
             if (websocket.availableForWriteAll() > 0) {

src/wifi_setup.cpp

@@ -51,6 +51,10 @@ void connectToWifi() {
 
   WiFi.begin(params.getSSID(), params.getPass());
   WiFi.setTxPower(WIFI_POWER_18_5dBm);
+  // Leaving WiFi modem-sleep at the Arduino default (WIFI_PS_MIN_MODEM):
+  // forcing setSleep(false) caused severe packet loss and HTTP stalls when
+  // BLE was active, because BT/WiFi share one 2.4GHz radio and the coex
+  // layer needs WiFi's sleep windows for BT slots.
   int wifiCounter = 0;
   while (WiFi.status() != WL_CONNECTED) {
     if (WiFi.status() == WL_CONNECT_FAILED) {