feat: scale telemetry via session_info + debug frames

Rebased onto current main (post decentespresso#58 WS-OOM gate, post decentespresso#60 ADC library
swap) and restructured from the original "embed telemetry in status"
shape to deliver telemetry out-of-band, so apps that don't care about
diagnostics (on-device UI, decentespresso app, third-party scale apps)
aren't paying ~21% extra bytes on every status broadcast tick.

The collection bits — SoC die-temperature sampler, weight-stall watchdog,
ADC recovery counter widened to volatile uint32_t, reset-reason capture
at boot, StopWatch-tear-fix timer snapshot — are unchanged from review-
round-2.

Wire-protocol delivery is reorganized into three frames:

  session_info  one-shot, server→client on WS_EVT_CONNECT. Carries the
                fields immutable for the connection (protocol_version,
                firmware_version, reset_reason). Clients no longer have
                to ask for these.

  debug events  broadcast on diagnostic-relevant change. Emitted by:
                  - sendWebsocketDebugStall(true)  on stall onset
                  - sendWebsocketDebugStall(false) on stall resume
                  - sendWebsocketDebugAdcRecovery() on ADC power-cycle
                  - sendWebsocketDebugTempPeak()    on new SoC max temp
                Subscribers see the event the moment it happens; non-
                subscribers ignore the unknown type. No periodic
                broadcast — temp_peak fires at most once per warm-up
                curve, stall_*/adc_recovery only on real events.

  debug reply   on-request snapshot per-client. Send {"command":"debug"}
                (also accepted: "diag") and the server replies with the
                full diagnostic set (current/peak temp, stall state +
                count + last, recovery count). Per-client, not a
                broadcast — no heap cost for other clients.

All event broadcasts go through the existing wsBroadcastHeapOk() gate
(PR decentespresso#58). Per-client sends don't need it (one allocation, not one-per-
client).

Net effect:

  - Status frame stays at its current 16 fields (≈310 B payload). Apps
    that don't care about diagnostics get back ~21% per status broadcast
    — meaningful under multi-client load where allocations stack.
  - Diagnostic consumers (soak tools, debug dashboards, this PR's own
    thermal_load_test.sh) get *immediate* notification of stall /
    recovery events instead of waiting up to 5 s for the next status.
  - session_info means clients no longer have to roundtrip a status
    request just to learn reset_reason after reconnect.

Also includes:

  - Updated ADS1232 debug callback for the new library's field set
    (rebased from old API; the old dataMin/Max/Avg/StdDev /
    tareInProgress/tareTimes are gone in the upstream lib). Callback
    stays dormant by default (registered but setDebugEnabled(false) is
    the default in the lib).
  - StopWatch read-tear fix: sendWebsocketStatus and StatusAll now read
    g_timerRunning/g_timerElapsed (snapshotted once per main-loop pass)
    instead of touching stopWatch directly from the AsyncTCP task.
  - CLAUDE.md: "Fixing bugs you find along the way" guidance from
    review round 2.
  - README.md: full documentation of session_info + debug frames.
  - tools/thermal_load_test.sh: 1-hour multi-protocol soak runner.

Build verified clean on esp32s3 (RAM 17.2%, Flash 45.5%).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: skialpine

CLAUDE.md

@@ -158,6 +158,10 @@ This document is meant to evolve with the codebase. During a session, if you (Cl
 
 If you fix a bug whose symptom is documented in the "When something is broken" table, leave the entry in place — it's still the right "first place to look" for the next person.
 
+## Fixing bugs you find along the way
+
+Pre-existing bugs get fixed too — "it was already there" is not a reason to defer. When you turn up a bug while working on something else (a review flags it, you read past it, a test surfaces it), fix it as part of the same change; a pre-existing bug is no less bad than a newly introduced one, and the person touching the code is the right person to fix it. The only exception is when the fix is genuinely a large, independent effort — then call it out explicitly and agree on a separate change, rather than silently leaving it in place.
+
 ## Don't
 
 - Don't call I²C / SPI / blocking IO from the AsyncTCP task.

README.md

@@ -186,6 +186,81 @@ Status frame shape:
 }
 ```
 
+### `session_info` frame (per-connect, server → client)
+
+Sent once to each client immediately after WebSocket handshake. Carries the
+fields that don't change for the life of the connection, so the hot status
+broadcast doesn't have to ship them on every tick.
+
+```json
+{
+  "type": "session_info",
+  "protocol_version": 1,
+  "firmware_version": "FW: 3.0.9",
+  "reset_reason": "poweron",
+  "ms": 12345
+}
+```
+
+### `debug` frames (diagnostic telemetry, opt-in)
+
+Diagnostic telemetry — SoC die temperature, weight-stall watchdog state, ADC
+power-cycle recovery count — is delivered out-of-band from the hot status
+broadcast so apps that don't care about it (the on-device UI, the
+decentespresso app, third-party scale apps) aren't paying ~21% extra bytes per
+status tick.
+
+**On-request snapshot** — send `{"command":"debug"}` (also accepted: `diag`)
+to get the full diagnostic set per-client. Reply:
+
+```json
+{
+  "type": "debug",
+  "status": "ok",
+  "soc_temp_c": 33.3,
+  "soc_temp_max_c": 41.2,
+  "weight_stalled": false,
+  "stall_count": 0,
+  "last_stall_ms": 0,
+  "last_stall_temp_c": 0.0,
+  "adc_recovery_count": 0,
+  "ms": 12345
+}
+```
+
+**Event broadcasts** — emitted when something diagnostic-relevant changes.
+Subscribers keep their own snapshot from `session_info` + the on-request
+debug reply and apply these deltas. Non-subscribers ignore the unknown type.
+
+```json
+{"type":"debug","event":"stall_start","stall_count":1,
+ "last_stall_ms":12345,"last_stall_temp_c":42.1,"ms":12350}
+
+{"type":"debug","event":"stall_end","ms":17890}
+
+{"type":"debug","event":"adc_recovery","adc_recovery_count":3,"ms":34567}
+
+{"type":"debug","event":"temp_peak","soc_temp_max_c":41.5,"ms":56789}
+```
+
+Field meanings:
+
+- `soc_temp_c` / `soc_temp_max_c` — current and peak ESP32-S3 die temperature
+  (°C) since boot. `soc_temp_max_c` is `-100` until the first valid sample.
+- `weight_stalled` — `true` while the load-cell raw value has been frozen/railed
+  for >8 s (readings have stopped), cleared when they resume.
+- `stall_count` — number of stall events since boot; `last_stall_ms` is the
+  `millis()` of the most recent stall onset (`0` = none yet) and
+  `last_stall_temp_c` is the die temp at that moment (valid only when
+  `last_stall_ms != 0`).
+- `adc_recovery_count` — number of ADC power-cycle recoveries since boot. A
+  climbing value is the signal for a perpetual-recovery loop (the case
+  `weight_stalled` is blind to).
+- `reset_reason` (in `session_info`) — why the SoC last reset (`poweron`,
+  `panic`, `brownout`, `task_wdt`, …), so a reboot mid-soak is explained.
+
+These reset on reboot (not persisted to NVS).
+
 For backwards compatibility, WiFi only sends weight snapshots by default. A
 client must send `events on` before periodic status, local scale button presses,
 or power-off notifications are emitted. The event stream resets to off when the

include/parameter.h

@@ -193,9 +193,46 @@ static const unsigned long ZERO_DISPLAY_MISMATCH_TIMEOUT = 1500;
 static const float ZERO_DISPLAY_MISMATCH_THRESHOLD = 0.5;
 static const uint8_t ADC_ERROR_RECOVERY_COUNT = 2;
 static bool b_adc_recovery_active = false;
-static uint8_t i_adc_recovery_count = 0;
+// volatile: written on the main loop -- incremented on each ADC power-cycle
+// recovery, reset to 0 by resetAdcRecoveryState() -- and read in the WS status
+// frame (which can be built on the AsyncTCP task). uint32_t (not uint8_t) so a
+// *perpetual* recovery loop -- the one failure mode the stall watchdog is blind
+// to -- keeps counting truthfully over a long soak instead of saturating at 255.
+static volatile uint32_t i_adc_recovery_count = 0;
 //bool b_tempDisablePowerOff = true;
 
+// Instrumentation for diagnosing the "weight stops being collected" failure
+// under sustained load (suspected thermal). These are all written on the main
+// loop and read by the WS status frame, which is built BOTH on the main loop
+// (periodic) AND on the AsyncTCP task (command responses) -- so the read crosses
+// a task boundary. volatile prevents the AsyncTCP reader caching a stale value
+// (single aligned scalars => the load/store is atomic on Xtensa, no mutex
+// needed). b_weightStalled is set by the pureScale() stall watchdog when the ADC
+// raw value is frozen/railed.
+volatile bool b_weightStalled = false;
+// volatile for the same cross-task reason; written once at boot in setup().
+volatile const char *g_resetReason = "unknown";
+// Peak/last-event stats since boot (no NVS; reset on reboot, which g_resetReason
+// then explains). g_socTempMaxC = highest SoC die temp seen. The *_stall_*
+// fields capture the most recent stall so the failure is visible after the fact
+// -- consumers must treat last_stall_temp_c as valid only when g_lastStallMs != 0
+// (0.0 otherwise means "no stall yet", not a real 0 C reading).
+volatile float g_socTempC = 0.0f;          // latest SoC temperature (C)
+volatile float g_socTempMaxC = -100.0f;    // peak SoC temperature since boot (C); -100 = no valid sample yet
+volatile uint32_t g_stallCount = 0;        // number of weight-stall events since boot
+volatile unsigned long g_lastStallMs = 0;  // millis() of the last stall onset (0 = none)
+volatile float g_lastStallTempC = 0.0f;    // SoC temp when the last stall began (valid only if g_lastStallMs != 0)
+
+// Snapshot of the stopWatch state, refreshed once per main-loop iteration. The
+// WS status frame is built BOTH on the main loop AND on the AsyncTCP task
+// (command responses); stopWatch is a multi-field object (running flag + start
+// ts + accumulator) also mutated from BLE/USB, so reading it directly off the
+// AsyncTCP task can tear (CLAUDE.md). The status frame reads these single
+// aligned volatiles instead. g_timerElapsed carries stopWatch.elapsed() in its
+// configured resolution (SECONDS) -- it is the WS "timer_seconds" field.
+volatile bool g_timerRunning = false;
+volatile unsigned long g_timerElapsed = 0;
+
 bool b_negativeWeight = false;
 
 bool b_weight_quick_zero = false;           //Tare后快速显示为0优化

include/websocket.h

@@ -221,8 +221,8 @@ void sendWebsocketStatus(AsyncWebSocketClient *client, const char *status) {
                  websocketBatteryPercent(),
                  f_batteryVoltage,
                  websocketIsCharging() ? "true" : "false",
-                 stopWatch.isRunning() ? "true" : "false",
-                 (unsigned long)stopWatch.elapsed(),
+                 g_timerRunning ? "true" : "false",
+                 g_timerElapsed,
                  b_u8g2Sleep ? "false" : "true",
                  b_websocketLowPowerEnabled ? "true" : "false",
                  b_softSleep ? "true" : "false",
@@ -250,8 +250,8 @@ void sendWebsocketStatusAll(const char *status) {
                       websocketBatteryPercent(),
                       f_batteryVoltage,
                       websocketIsCharging() ? "true" : "false",
-                      stopWatch.isRunning() ? "true" : "false",
-                      (unsigned long)stopWatch.elapsed(),
+                      g_timerRunning ? "true" : "false",
+                      g_timerElapsed,
                       b_u8g2Sleep ? "false" : "true",
                       b_websocketLowPowerEnabled ? "true" : "false",
                       b_softSleep ? "true" : "false",
@@ -266,6 +266,85 @@ void sendWebsocketWeightAll(float grams, unsigned long ms) {
   websocket.printfAll("{\"grams\":%.2f,\"ms\":%lu}", grams, ms);
 }
 
+// --- Telemetry delivery ------------------------------------------------------
+//
+// Telemetry (SoC temp, weight-stall watchdog, ADC recovery count, reset reason)
+// is delivered out-of-band from the hot status frame so that apps which don't
+// care about it -- the on-device UI, the decentespresso app, third-party scale
+// apps -- aren't paying ~21% extra bytes on every status broadcast. The split:
+//
+//   session_info  one-shot, sent to each client on WS_EVT_CONNECT. Carries the
+//                 fields that don't change for the life of the connection
+//                 (protocol_version, firmware_version, reset_reason).
+//
+//   debug events  broadcast on the *change* that matters: stall_start /
+//                 stall_end, adc_recovery (count incremented), temp_peak (new
+//                 max). Subscribers see the event the moment it happens; non-
+//                 subscribers ignore the unknown type. No periodic broadcast.
+//
+//   debug reply   on-request snapshot. A client sends {"command":"debug"} and
+//                 the server replies with the full diagnostic set (current
+//                 SoC temp, max temp, stall state/count/last, recovery count).
+//                 Per-client, not a broadcast -- no heap cost for other clients.
+//
+// All event broadcasts use the same wsBroadcastHeapOk() gate as the other
+// printfAll helpers above. Per-client sends (session_info, debug reply) don't
+// need the gate since they're one allocation, not one-per-client.
+void sendWebsocketSessionInfo(AsyncWebSocketClient *client) {
+  client->printf("{\"type\":\"session_info\",\"protocol_version\":1,\"firmware_version\":\"%s\",\"reset_reason\":\"%s\",\"ms\":%lu}",
+                 FIRMWARE_VER,
+                 (const char *)g_resetReason,
+                 millis());
+}
+
+void sendWebsocketDebug(AsyncWebSocketClient *client, const char *status) {
+  client->printf("{\"type\":\"debug\",\"status\":\"%s\",\"soc_temp_c\":%.1f,\"soc_temp_max_c\":%.1f,\"weight_stalled\":%s,\"stall_count\":%lu,\"last_stall_ms\":%lu,\"last_stall_temp_c\":%.1f,\"adc_recovery_count\":%lu,\"ms\":%lu}",
+                 status,
+                 g_socTempC,
+                 g_socTempMaxC,
+                 b_weightStalled ? "true" : "false",
+                 (unsigned long)g_stallCount,
+                 g_lastStallMs,
+                 g_lastStallTempC,
+                 (unsigned long)i_adc_recovery_count,
+                 millis());
+}
+
+// Event broadcasts. Only fields relevant to the event are included -- subscribers
+// keep their own running snapshot from session_info + the on-request debug reply,
+// and update it from these deltas. Keeps each event small (~80-140 B).
+void sendWebsocketDebugStall(bool started) {
+  if (!b_wifiEnabled || websocket.count() == 0) return;
+  if (!wsBroadcastHeapOk()) return;
+  if (started) {
+    websocket.printfAll("{\"type\":\"debug\",\"event\":\"stall_start\",\"stall_count\":%lu,\"last_stall_ms\":%lu,\"last_stall_temp_c\":%.1f,\"ms\":%lu}",
+                        (unsigned long)g_stallCount,
+                        g_lastStallMs,
+                        g_lastStallTempC,
+                        millis());
+  } else {
+    websocket.printfAll("{\"type\":\"debug\",\"event\":\"stall_end\",\"ms\":%lu}", millis());
+  }
+}
+
+void sendWebsocketDebugAdcRecovery() {
+  if (!b_wifiEnabled || websocket.count() == 0) return;
+  if (!wsBroadcastHeapOk()) return;
+  websocket.printfAll("{\"type\":\"debug\",\"event\":\"adc_recovery\",\"adc_recovery_count\":%lu,\"ms\":%lu}",
+                      (unsigned long)i_adc_recovery_count,
+                      millis());
+}
+
+// temp_peak is broadcast when g_socTempMaxC ticks up. Rate-limited at the call
+// site (main loop) -- not here -- since the temp sampler already throttles.
+void sendWebsocketDebugTempPeak(float maxC) {
+  if (!b_wifiEnabled || websocket.count() == 0) return;
+  if (!wsBroadcastHeapOk()) return;
+  websocket.printfAll("{\"type\":\"debug\",\"event\":\"temp_peak\",\"soc_temp_max_c\":%.1f,\"ms\":%lu}",
+                      maxC,
+                      millis());
+}
+
 void sendWebsocketError(AsyncWebSocketClient *client, const char *code, const char *message) {
   client->printf("{\"type\":\"error\",\"code\":\"%s\",\"message\":\"%s\",\"ms\":%lu}",
                  code,
@@ -328,6 +407,11 @@ bool handleWebsocketControlCommand(AsyncWebSocketClient *client, String command,
     return true;
   }
 
+  if (command == "debug" || command == "diag") {
+    sendWebsocketDebug(client, "ok");
+    return true;
+  }
+
   if (command == "events") {
     if (action == "on" || action == "enable" || action == "enabled") {
       b_websocketEventsEnabled = true;
@@ -594,6 +678,10 @@ void setupWebsocketEvents() {
       // when the radio frees up instead of dropping. A genuinely dead client is
       // still reaped, just later.
       client->client()->setAckTimeout(30000);
+      // Send the session-immutable fields (protocol version, firmware version,
+      // reset reason) once on connect, so clients don't have to ask -- and so
+      // the hot status broadcast doesn't carry them on every tick.
+      sendWebsocketSessionInfo(client);
     } else if (type == WS_EVT_DISCONNECT) {
       Serial.printf("Client %u disconnected\n", client->id());
       // Only reset shared session state when the LAST client leaves —