overland-controller/docs/UART_PROTOCOL.md

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.

WiFi Config Request

Pico sends:

{"type":"wifi_request"}

ESP32 responds:

{"type":"wifi_config_response","ok":true,"wifi":{}}

WiFi Config Update

Pico sends:

{"type":"config_wifi","ssid":"Starlink","password":"password_here"}

WiFi Connect

Pico sends:

{"type":"wifi_connect"}

WiFi Clear

Pico sends:

{"type":"wifi_clear"}

AP mode remains enabled as the recovery path.