Structured ADC status signaling over BLE/USB/WebSocket

Parent

PR #47 (Show ADC recovery instead of stuck zero) adds OLED-based ADC recovery indication and suppresses weight publishes during recovery. This issue adds structured status signaling to all wire protocols so connected apps can show recovery state instead of freezing on last-known weight.

What to build

Add a new BLE/USB packet type 0xEF ("ADC status") that replaces suppressed weight packets during ADC recovery. Send it on the same cadence as weight notifications. Also update WebSocket JSON and USB text output to carry the same status. Fire an explicit OK packet (status=0x00) on recovery exit.

State machine:

• OK → RECOVERING: when scale.getSignalTimeoutFlag() fires in pureScale()
• RECOVERING → ERROR: when i_adc_recovery_count >= ADC_ERROR_RECOVERY_COUNT
• RECOVERING/ERROR → OK: when resetAdcRecoveryState() fires (successful scale.update(), ADC init, wake)

BLE/USB binary packet (7 bytes)

[0] modelByte
[1] 0xEF          (ADC status packet type)
[2] status        (0x00=OK, 0x01=RECOVERING, 0x02=ERROR)
[3] recovery_count (0-255, resets to 0 on OK)
[4] reason        (0x01=sample_loss, 0x02=zero_mismatch, 0x03=quick_zero_timeout)
[5] 0x00          (reserved)
[6] XOR checksum

Define enums in include/parameter.h:

static const uint8_t ADC_STATUS_PACKET_TYPE = 0xEF;
static const uint8_t ADC_STATUS_OK = 0x00;
static const uint8_t ADC_STATUS_RECOVERING = 0x01;
static const uint8_t ADC_STATUS_ERROR = 0x02;
static const uint8_t ADC_STATUS_REASON_SAMPLE_LOSS = 0x01;
static const uint8_t ADC_STATUS_REASON_ZERO_MISMATCH = 0x02;
static const uint8_t ADC_STATUS_REASON_QUICK_ZERO_TIMEOUT = 0x03;

WebSocket JSON (500ms interval, during recovery)

{"grams": 0.00, "ms": 12345, "status": "recovering", "recovery_count": 1, "reason": "sample_loss"}

USB text (replaces weight line during recovery)

<millis> ADC RECOVERING (1/2): sample_loss
<millis> ADC ERROR (2/2): sample_loss
<millis> ADC OK

Send timing

State	BLE/USB binary	WebSocket	USB text	Weight packets (0xCE)
OK	fire 0xEF once on transition, then resume 0xCE	resume weight JSON	resume weight text	normal
RECOVERING	0xEF at weightBleNotifyInterval	status JSON at 500ms	status text	suppressed
ERROR	same as RECOVERING	same	same	suppressed

Transition triggers

Set reason variable at each trigger site:

• pureScale() ADC timeout branch → reason = SAMPLE_LOSS
• pureScale() zero-display mismatch → reason = ZERO_MISMATCH
• pureScale() quick-zero timeout → reason = QUICK_ZERO_TIMEOUT

Files to touch

File	Change
include/parameter.h	Add packet type and status/reason enums, reason variable
include/ble.h	buildAdcStatusPacket(), sendBleAdcStatus()
include/usbcomm.h	sendUsbAdcStatus() (binary), sendUsbTextAdcStatus()
src/hds.ino	Call status send in loop() instead of suppressing, fire OK on transition, set reason at trigger sites, update WS message format

Acceptance criteria

• 0xEF packet sent over BLE and USB binary at weight notify interval when b_adc_recovery_active is true
• Status transitions: OK→RECOVERING→ERROR→OK, with explicit OK packet sent on recovery exit
• reason field correctly set at each trigger site (sample_loss, zero_mismatch, quick_zero_timeout)
• recovery_count increments on each ADC timeout, resets to 0 on OK
• WebSocket JSON includes status, recovery_count, reason during recovery, with grams: 0.00
• USB text shows human-readable status line (e.g. ADC RECOVERING (1/2): sample_loss)
• Weight packets (0xCE) suppressed during recovery (already in PR #47)
• Old DE1 app (binary.tcl parse_decent_scale_recv) ignores 0xEF silently — no crash
• Builds and passes existing CI

Blocked by

None — PR #47 merged. Can start immediately.

Start with include/parameter.h, include/ble.h, include/usbcomm.h, and the loop and ADC trigger sites in src/hds.ino; trace the existing recovery suppression and notification timing before implementing the status paths. Done means the listed BLE/USB packets, WebSocket JSON, USB text, transitions, reasons, and recovery counts meet the acceptance criteria and existing CI passes.