xterra-overland-dashboard/docs/protocol.md

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