From c243c361af39c6d4249aaaa445414a25983f6746 Mon Sep 17 00:00:00 2001
From: root <root@development.info>
Date: Wed, 3 Jun 2026 02:28:36 -0600
Subject: [PATCH] Add UART communication protocol specification

---
 docs/protocol.md | 163 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 163 insertions(+)
 create mode 100644 docs/protocol.md

diff --git a/docs/protocol.md b/docs/protocol.md
new file mode 100644
index 0000000..1e5de6b
--- /dev/null
+++ b/docs/protocol.md
@@ -0,0 +1,163 @@
+# 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