From ca36431eed1c13650126a02f48deeda4f998d7ab Mon Sep 17 00:00:00 2001
From: root <root@development.info>
Date: Wed, 3 Jun 2026 01:33:51 -0600
Subject: [PATCH] Add UART communication plan

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

diff --git a/docs/uart.md b/docs/uart.md
new file mode 100644
index 0000000..acf695f
--- /dev/null
+++ b/docs/uart.md
@@ -0,0 +1,85 @@
+# UART Communication Plan
+
+## Overview
+
+The first hardware version will use plain UART over CAT5 between the Pico dashboard and the ESP32 cargo controller.
+
+UART is simpler than RS-485 and should be reliable enough for the short cable run inside the Xterra.
+
+RS-485 remains a fallback if UART proves unreliable.
+
+## Architecture
+
+Pico Dashboard
+↓
+UART over CAT5
+↓
+ESP32 Controller
+
+Backup:
+WiFi HTTP API
+
+Fallback:
+RS-485 over CAT5
+
+## UART Wiring
+
+Pico TX -> ESP32 RX
+Pico RX <- ESP32 TX
+Ground  <-> Ground
+
+## Planned Baud Rate
+
+Initial:
+115200 baud
+
+Future testing:
+- 57600 baud if noise becomes an issue
+- 230400 baud if higher update rates are needed
+
+## Message Format
+
+Messages will use newline-delimited JSON.
+
+Example request:
+
+{"type":"status_request"}
+
+Example response:
+
+{"type":"status_response","data":{"battery":{"soc":82}}}
+
+Each message ends with a newline character.
+
+## Failure Handling
+
+If no valid response is received within the timeout:
+
+- Dashboard shows communication warning
+- Last known values remain visible
+- Relay commands fail safely
+- WiFi backup may be attempted if enabled
+
+## Why UART First
+
+Advantages:
+
+- Fewer parts
+- Easier wiring
+- Easier debugging
+- No direction-control pin
+- No transceiver modules required
+- Works well over short distances
+
+## Why RS-485 Is Still Available
+
+RS-485 may be used later if UART has issues caused by:
+
+- Alternator noise
+- Relay switching noise
+- Fridge compressor noise
+- Inverter noise
+- Long cable run
+- Ground noise
+
+The software should keep a transport abstraction so UART and RS-485 can be swapped without changing the application protocol.