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
@@ -233,3 +233,308 @@ text 0.3.x
 Future firmware versions may add fields while maintaining backward compatibility.

 Consumers should ignore unknown fields.
+
+---
+
+## Embedded Dashboard
+
+The ESP32 is planned to serve a lightweight mobile dashboard at:
+
+    GET /
+
+When connected directly to the ESP32 AP:
+
+    http://192.168.4.1/
+
+The page should:
+
+- Poll /status
+- Display battery state
+- Display temperature sensors
+- Display relay states
+- Show alarms
+- Allow basic relay control
+
+Design limits:
+
+- Small inline HTML/CSS/JS
+- No external libraries
+- No large assets
+- No heavy JavaScript framework
+
+The embedded dashboard is intended as a convenient phone view, not a replacement for the physical Pico dashboard.
+
+---
+
+## Future WiFi API
+
+Future configuration may include WiFi management endpoints.
+
+Possible future endpoints:
+
+    GET  /config/wifi
+    POST /config/wifi
+    POST /config/wifi/add
+    POST /config/wifi/remove
+    POST /config/wifi/reorder
+
+Potential config model:
+
+    ap_enabled
+    sta_enabled
+    hostname
+    saved_networks
+
+Saved networks should support priority order.
+
+Example:
+
+    Starlink
+    Home WiFi
+    Shop WiFi
+
+The AP should remain enabled even when connected to STA WiFi.
+
+---
+
+# HTTP / UART Parity Endpoints
+
+These endpoints mirror UART setup/control messages.
+
+## Save Config
+
+    POST /config/save
+
+Equivalent UART message:
+
+    {"type":"save_config"}
+
+## BMS Setup Mode
+
+Enter BMS setup mode:
+
+    POST /bms/setup/enter
+
+Equivalent UART message:
+
+    {"type":"enter_bms_setup"}
+
+Exit BMS setup mode:
+
+    POST /bms/setup/exit
+
+Equivalent UART message:
+
+    {"type":"exit_bms_setup"}
+
+## BLE Scan
+
+Scan for BLE devices:
+
+    POST /bms/scan
+
+Equivalent UART message:
+
+    {"type":"scan_ble"}
+
+Response:
+
+    {
+      "type": "ble_scan_response",
+      "devices": [
+        {
+          "index": 1,
+          "name": "House Battery",
+          "address": "aa:bb:cc:dd:ee:ff",
+          "rssi": -65
+        }
+      ]
+    }
+
+## Select BMS
+
+Select a BMS from the most recent scan:
+
+    POST /bms/select
+
+Request body:
+
+    {
+      "index": 1
+    }
+
+Equivalent UART message:
+
+    {"type":"select_bms","index":1}
+
+---
+
+# Preferred Relay Command Endpoint
+
+The preferred relay control endpoint is:
+
+    POST /relay/set
+
+Request body:
+
+    {
+      "id": "relay_1",
+      "state": true
+    }
+
+Example:
+
+    curl -X POST http://192.168.88.108/relay/set \
+      -H "Content-Type: application/json" \
+      -d '{"id":"relay_1","state":true}'
+
+Equivalent UART message:
+
+    {"type":"set_relay","relay":"relay_1","enabled":true}
+
+Legacy GET 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
+
+---
+
+# WiFi Configuration API
+
+## Get WiFi Config
+
+    GET /config/wifi
+
+## Set WiFi Config
+
+    POST /config/wifi
+
+Request body:
+
+    {
+      "ssid": "Starlink",
+      "password": "password_here"
+    }
+
+## Connect STA WiFi
+
+    POST /wifi/connect
+
+## Clear WiFi Config
+
+    POST /wifi/clear
+
+The ESP32 AP remains available even when STA WiFi is configured.
+
+Equivalent UART messages:
+
+    {"type":"wifi_request"}
+
+    {"type":"config_wifi","ssid":"Starlink","password":"password_here"}
+
+    {"type":"wifi_connect"}
+
+    {"type":"wifi_clear"}
+
+---
+
+# WiFi Priority and Runtime Failover
+
+Saved WiFi networks support priority.
+
+Lower priority numbers are attempted first.
+
+Example:
+
+    {
+      "networks": [
+        {
+          "ssid": "Starlink",
+          "password": "starlink_password",
+          "priority": 1
+        },
+        {
+          "ssid": "Home WiFi",
+          "password": "home_password",
+          "priority": 2
+        }
+      ]
+    }
+
+The ESP32 behavior is:
+
+    AP always stays enabled
+    STA tries saved networks by priority
+    If disconnected at runtime, STA retries saved networks every 30 seconds
+    If all STA networks fail, AP remains available at 192.168.4.1
+
+
+---
+
+# API Parity Notes
+
+The HTTP API is intended to mirror the UART JSON protocol where practical.
+
+## Preferred Relay Control
+
+Preferred endpoint:
+
+    POST /relay/set
+
+Request:
+
+    {
+      "id": "relay_1",
+      "state": true
+    }
+
+Response:
+
+    {
+      "type": "relay_response",
+      "ok": true,
+      "id": "relay_1",
+      "state": true
+    }
+
+Legacy relay routes may remain available for compatibility:
+
+    GET /relay/relay_1/on
+    GET /relay/relay_1/off
+    GET /relay/relay_2/on
+    GET /relay/relay_2/off
+
+## WiFi Parity
+
+WiFi configuration supports multiple saved STA networks.
+
+Request:
+
+    POST /config/wifi
+
+Body:
+
+    {
+      "networks": [
+        {
+          "ssid": "Starlink",
+          "password": "starlink_password",
+          "priority": 1
+        },
+        {
+          "ssid": "Home WiFi",
+          "password": "home_password",
+          "priority": 2
+        }
+      ]
+    }
+
+Lower priority numbers are attempted first.
+
+Runtime behavior:
+
+    AP always remains enabled.
+    STA tries saved networks by priority.
+    If STA disconnects, saved networks are retried every 30 seconds.