root
164 lines
2.3 KiB
Markdown
164 lines
2.3 KiB
Markdown
# 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
|