Document full UART control protocol

2026-06-04 04:14:01 -06:00
parent 50410b1d0c
commit 0b3961516d
1 changed files with 162 additions and 0 deletions
@@ -0,0 +1,162 @@
+# UART Protocol
+
+The Pico dashboard communicates with the ESP32 controller over UART.
+
+UART is the primary dashboard/control link. HTTP should mirror the same concepts, but the Pico should be able to operate the controller without WiFi.
+
+## Serial Settings
+
+- Baud: 115200
+- Format: 8N1
+- Encoding: UTF-8 JSON
+- Framing: one JSON object per line
+- Line ending: newline
+
+## Design Goals
+
+UART should support:
+
+- Status requests
+- Relay control
+- Device configuration
+- Relay configuration
+- Temperature sensor configuration
+- BMS configuration
+- BMS setup mode
+- BLE scanning
+- BMS selection
+- Factory reset
+- Error reporting
+
+## Generic IDs
+
+Relays:
+
+    relay_1
+    relay_2
+
+Temperature sensors:
+
+    temp_1 through temp_8
+
+## Status Request
+
+Pico sends:
+
+    {"type":"status_request"}
+
+ESP32 responds with the same shape as HTTP /status.
+
+## Relay Control
+
+Pico sends:
+
+    {"type":"set_relay","relay":"relay_1","enabled":true}
+
+ESP32 responds:
+
+    {"type":"relay_response","relay":"relay_1","enabled":true,"ok":true}
+
+## Config Request
+
+Pico sends:
+
+    {"type":"config_request"}
+
+ESP32 responds:
+
+    {"type":"config_response","config":{}}
+
+## Device Name Update
+
+Pico sends:
+
+    {"type":"config_device","device_name":"Overland Controller"}
+
+## Relay Config Update
+
+Pico sends:
+
+    {"type":"config_relay","id":"relay_1","name":"Aux Power","enabled":true}
+
+## Temperature Sensor Config Update
+
+Pico sends:
+
+    {"type":"config_temp","id":"temp_1","name":"Cabin","address":"","enabled":true}
+
+## BMS Config Update
+
+Pico sends:
+
+    {"type":"config_bms","enabled":true,"name":"House Battery","address":"aa:bb:cc:dd:ee:ff","address_type":"public"}
+
+## Save Config
+
+Pico sends:
+
+    {"type":"save_config"}
+
+## Factory Reset
+
+Pico sends:
+
+    {"type":"factory_reset"}
+
+## BMS Setup Mode
+
+Enter setup:
+
+    {"type":"enter_bms_setup"}
+
+Scan BLE:
+
+    {"type":"scan_ble"}
+
+Expected scan response:
+
+    {"type":"ble_scan_response","devices":[{"index":1,"name":"House Battery","address":"aa:bb:cc:dd:ee:ff","rssi":-65}]}
+
+Select BMS:
+
+    {"type":"select_bms","index":1}
+
+Exit setup:
+
+    {"type":"exit_bms_setup"}
+
+## Error Response
+
+ESP32 returns errors as:
+
+    {"type":"error","message":"unknown_message_type"}
+
+Common errors:
+
+- invalid_json
+- unknown_message_type
+- unknown_relay
+- unknown_temp_sensor
+- invalid_bms_selection
+- config_save_failed
+- message_too_long
+
+## UART / HTTP Parity Goal
+
+The UART protocol should eventually support the same management capabilities as HTTP:
+
+- /status equals status_request
+- /config equals config_request
+- /config/device equals config_device
+- /config/relay equals config_relay
+- /config/temp equals config_temp
+- /config/bms equals config_bms
+- /relay/relay_1/on equals set_relay
+- /config/factory-reset equals factory_reset
+
+## Notes
+
+- UART is the preferred dashboard/control path.
+- HTTP is useful for setup, debugging, and future web UI.
+- USB serial remains the emergency service/debug interface.
+- The Pico should not depend on WiFi for normal control.