Standardize API UART parity and update docs

2026-06-04 14:10:13 -06:00
parent 6884bc7b32
commit f46e72fc7f
7 changed files with 576 additions and 6 deletions
@@ -0,0 +1,81 @@
+# Command Parity Matrix
+
+This document tracks feature parity across the three control surfaces.
+
+Control surfaces:
+
+- USB serial console
+- UART JSON protocol
+- HTTP API
+
+## Current Parity
+
+| Feature | USB Serial | UART JSON | HTTP API | Notes |
+|---|---:|---:|---:|---|
+| Status | Yes | Yes | Yes | `/status` equals `status_request` |
+| Config view | Yes | Yes | Yes | `/config` equals `config_request` |
+| Relay control | Yes | Yes | Yes | Preferred HTTP endpoint is `POST /relay/set` |
+| Device name config | Yes | Yes | Yes | `devicename`, `config_device`, `/config/device` |
+| Relay config | Yes | Yes | Yes | `relayname`, `config_relay`, `/config/relay` |
+| Temperature config | Yes | Yes | Yes | `tempname`, `config_temp`, `/config/temp` |
+| BMS config | Yes | Yes | Yes | `bmsname`/`bmsaddr`, `config_bms`, `/config/bms` |
+| Save config | Yes | Yes | Yes | `save`, `save_config`, `/config/save` |
+| Factory reset | Yes | Yes | Yes | AP remains recovery path |
+| BMS setup enter | Yes | Yes | Yes | Setup pauses normal BMS reconnect behavior |
+| BMS setup exit | Yes | Yes | Yes | Returns to normal mode |
+| BLE scan | Yes | Yes | Yes | Some BMS devices require repeated scans |
+| Select BMS | Yes | Yes | Yes | Uses most recent scan result index |
+| WiFi config | Yes | Yes | Yes | Supports multiple saved STA networks |
+| WiFi priority | Yes | Yes | Yes | Lower priority number is tried first |
+| WiFi connect | Yes | Yes | Yes | AP remains available |
+| WiFi clear | Yes | Yes | Yes | Clears saved STA networks |
+
+## Preferred Command Model
+
+Use generic IDs everywhere.
+
+Relays:
+
+    relay_1
+    relay_2
+
+Temperature sensors:
+
+    temp_1 through temp_8
+
+Preferred relay command shape:
+
+    {
+      "type": "set_relay",
+      "id": "relay_1",
+      "state": true
+    }
+
+Legacy UART relay fields may still be accepted:
+
+    relay
+    enabled
+
+Preferred HTTP relay endpoint:
+
+    POST /relay/set
+
+Legacy HTTP relay routes may remain for compatibility:
+
+    GET /relay/relay_1/on
+    GET /relay/relay_1/off
+    GET /relay/relay_2/on
+    GET /relay/relay_2/off
+
+## Response Shape Standard
+
+Success responses should include:
+
+    ok: true
+
+Error responses should include:
+
+    ok: false
+    error: "error_code"
+
+Status/config responses should preserve the generic data model used by `/status`.