# ESP32 ↔ Pico Communication Protocol

## Current Decision

Primary communication is **UART over CAT5**.

Backup communication is the **ESP32 WiFi HTTP API**.

RS-485/MAX3485 is fallback-only and is not currently planned.

## Physical Link

* Transport: UART
* Baud: 115200
* Format: 8N1
* Framing: newline-delimited JSON
* Direction: Pico dashboard ↔ ESP32 cargo controller

## Message Rules

Each message is one JSON object followed by a newline.

Example:

```
{"type":"status_request"}
```

Responses should also be one JSON object followed by a newline.

## Pico → ESP32 Messages

### Status Request

```
{"type":"status_request"}
```

Expected response:

```
{"type":"status_response"}
```

### Set Relay

```
{
  "type": "set_relay",
  "relay": "starlink",
  "enabled": true
}
```

Valid relay names:

* starlink
* fridge

Expected response:

```
{
  "type": "relay_response",
  "relay": "starlink",
  "enabled": true,
  "ok": true
}
```

## ESP32 → Pico Messages

### Status Response

```
{
  "type": "status_response",
  "timestamp": 123456,
  "battery": {
    "soc": 82.0,
    "voltage": 13.2,
    "current": -6.4,
    "remaining_ah": 82.0,
    "runtime_hours": 12.0,
    "temperature_f": 76.0
  },
  "temps": {
    "fridge_zone_1": 34.5,
    "fridge_zone_2": 36.0,
    "rear_seat": 71.2,
    "outside": 89.1
  },
  "sensor_health": {
    "fridge_zone_1": true,
    "fridge_zone_2": true,
    "rear_seat": true,
    "outside": true
  },
  "relays": {
    "starlink": false,
    "fridge": true
  },
  "vehicle": {
    "ignition_on": false
  },
  "network": {
    "wifi_enabled": true,
    "uart_connected": true
  }
}
```

## Error Response

```
{
  "type": "error",
  "message": "unknown_message_type"
}
```

Known error messages:

* invalid_json
* unknown_message_type
* unknown_relay
* message_too_long

## Sensor Null Handling

If a DS18B20 sensor is missing or faulted, its temperature value should be null.

Example:

```
{
  "temps": {
    "fridge_zone_1": null
  },
  "sensor_health": {
    "fridge_zone_1": false
  }
}
```

## Current Scope

The protocol currently supports:

* Live status polling
* Relay control
* Temperature reporting
* Sensor health reporting
* Basic error reporting

The protocol does not currently include:

* Persistent logging
* Historical data sync
* OTA updates
* BMS write/config commands
* Starlink diagnostic integration
* GPS/OBD-II data