overland-controller/docs/UART_PROTOCOL.md

# 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