# 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.