5.8 KiB
UART Protocol
This document describes the optional UART JSON protocol supported by the ESP32 controller.
UART is not the primary dashboard/control link. The current dashboard target is the Waveshare ESP32-S3 display over WiFi/HTTP.
Keep this protocol for diagnostics, simulator work, service tools, or alternate clients. Do not treat it as evidence that a Pico dashboard is planned.
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
Client sends:
{"type":"status_request"}
ESP32 responds with the same shape as HTTP /status.
Relay Control
Client sends:
{"type":"set_relay","relay":"relay_1","enabled":true}
ESP32 responds:
{"type":"relay_response","relay":"relay_1","enabled":true,"ok":true}
Config Request
Client sends:
{"type":"config_request"}
ESP32 responds:
{"type":"config_response","config":{}}
Device Name Update
Client sends:
{"type":"config_device","device_name":"Overland Controller"}
Relay Config Update
Client sends:
{"type":"config_relay","id":"relay_1","name":"Aux Power","enabled":true}
Temperature Sensor Config Update
Client sends:
{"type":"config_temp","id":"temp_1","name":"Cabin","address":"","enabled":true}
BMS Config Update
Client sends:
{"type":"config_bms","enabled":true,"name":"House Battery","address":"aa:bb:cc:dd:ee:ff","address_type":"public"}
Save Config
Client sends:
{"type":"save_config"}
Factory Reset
Client 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
- HTTP is the preferred dashboard/control path.
- UART is useful for diagnostics and alternate clients.
- USB serial remains the emergency service/debug interface.
- No Pico dashboard is currently planned.
WiFi Config Request
Client sends:
{"type":"wifi_request"}
ESP32 responds:
{"type":"wifi_config_response","ok":true,"wifi":{}}
WiFi Config Update
Client sends:
{"type":"config_wifi","ssid":"Starlink","password":"password_here"}
WiFi Connect
Client sends:
{"type":"wifi_connect"}
WiFi Clear
Client sends:
{"type":"wifi_clear"}
AP mode remains enabled as the recovery path.
WiFi Priority
WiFi configuration supports multiple saved networks.
Lower priority numbers are tried first.
Example:
{"type":"config_wifi","networks":[{"ssid":"Starlink","password":"password","priority":1},{"ssid":"Home WiFi","password":"password","priority":2}]}
Runtime behavior:
If STA disconnects, the ESP32 retries saved networks by priority every 30 seconds.
AP mode remains available as a recovery path.
UART Parity Notes
UART should use the same generic command model as HTTP.
Preferred Relay Command
Preferred:
{"type":"set_relay","id":"relay_1","state":true}
Legacy accepted shape:
{"type":"set_relay","relay":"relay_1","enabled":true}
Preferred response:
{"type":"relay_response","ok":true,"id":"relay_1","state":true}
WiFi Priority Config
{"type":"config_wifi","networks":[{"ssid":"Starlink","password":"password","priority":1},{"ssid":"Home WiFi","password":"password","priority":2}]}
Lower priority numbers are tried first.
Temperature Probe Setup
Scan Temperature Sensors
Client sends:
{"type":"scan_temps"}
ESP32 responds:
{"type":"temp_scan_response","ok":true,"devices":[{"index":1,"address":"28:AA:BB:CC:DD:EE:FF:00"}]}
Assign Temperature Sensor
Client sends:
{"type":"assign_temp","id":"temp_1","index":1}
Alternative:
{"type":"assign_temp","slot":1,"index":1}
Clear Temperature Sensor
Client sends:
{"type":"clear_temp","id":"temp_1"}
Alternative:
{"type":"clear_temp","slot":1}
Temperature weather flag
status_response.config.temperature_sensors[] and status_response.temps[] include weather: false.
config_temp may include weather: true to mark one configured sensor as the outside/weather sensor. Clients should treat this as optional and default missing values to false.
Current communications and GPIO decision
Active dashboard communication is WiFi/HTTP using /api/v1.
The old Pico/dashboard UART path is retired from active hardware use. USB Serial remains available for development, debug, and manual configuration from a computer.
Current Cargo ESP32 GPIO plan:
- GPIO 16: Relay 1 trigger output
- GPIO 17: Relay 2 trigger output
- GPIO 4: DS18B20 OneWire temperature bus
- GPIO 34: Ignition sense input
- GPIO 21: SSD1306 OLED I2C SDA
- GPIO 22: SSD1306 OLED I2C SCL
- GPIO 25: OLED setup/status button