From ef3a639a19706a54fceff920fd91f27cc62df939 Mon Sep 17 00:00:00 2001
From: root <root@development.info>
Date: Wed, 3 Jun 2026 01:35:00 -0600
Subject: [PATCH] Document UART as primary communication method

---
 docs/communications.md       |  4 +--
 docs/uart.md                 | 65 ++++++++++++++----------------------
 docs/wiring.md               |  2 +-
 hardware/cat5-pinout.md      | 25 +++++++++-----
 hardware/uart-cat5-pinout.md | 28 ++++++++++++++++
 5 files changed, 72 insertions(+), 52 deletions(-)
 create mode 100644 hardware/uart-cat5-pinout.md

diff --git a/docs/communications.md b/docs/communications.md
index d19b8ab..fd5d408 100644
--- a/docs/communications.md
+++ b/docs/communications.md
@@ -4,7 +4,7 @@
 
 Pico Dashboard
 ↓
-RS-485
+UART over CAT5
 ↓
 ESP32 Controller
 
@@ -28,7 +28,7 @@ Message Types:
 
 ## Failure Handling
 
-If RS-485 is lost:
+If UART over CAT5 is lost:
 - Dashboard displays warning
 - Last known values remain visible
 - Relay commands fail safely
diff --git a/docs/uart.md b/docs/uart.md
index acf695f..dccb810 100644
--- a/docs/uart.md
+++ b/docs/uart.md
@@ -2,18 +2,18 @@
 
 ## Overview
 
-The first hardware version will use plain UART over CAT5 between the Pico dashboard and the ESP32 cargo controller.
+The first hardware version will use UART over CAT5 between the Pico dashboard and the ESP32 controller.
 
-UART is simpler than RS-485 and should be reliable enough for the short cable run inside the Xterra.
+UART is simpler than RS-485 and should be reliable for the short cable run inside the Xterra.
 
-RS-485 remains a fallback if UART proves unreliable.
+RS-485 remains a future fallback if testing reveals communication issues.
 
 ## Architecture
 
 Pico Dashboard
-↓
-UART over CAT5
-↓
+|
+| UART over CAT5
+|
 ESP32 Controller
 
 Backup:
@@ -26,60 +26,45 @@ RS-485 over CAT5
 
 Pico TX -> ESP32 RX
 Pico RX <- ESP32 TX
-Ground  <-> Ground
+Ground <-> Ground
 
 ## Planned Baud Rate
 
 Initial:
-115200 baud
+115200
 
-Future testing:
-- 57600 baud if noise becomes an issue
-- 230400 baud if higher update rates are needed
+Future Options:
+- 57600
+- 230400
 
 ## Message Format
 
-Messages will use newline-delimited JSON.
-
-Example request:
+Newline-delimited JSON
 
+Request:
 {"type":"status_request"}
 
-Example response:
-
-{"type":"status_response","data":{"battery":{"soc":82}}}
-
-Each message ends with a newline character.
+Response:
+{"type":"status_response"}
 
 ## Failure Handling
 
-If no valid response is received within the timeout:
+If communication is lost:
 
-- Dashboard shows communication warning
+- Dashboard shows warning
 - Last known values remain visible
 - Relay commands fail safely
-- WiFi backup may be attempted if enabled
+- WiFi backup may be attempted
 
-## Why UART First
-
-Advantages:
+## Advantages
 
 - Fewer parts
-- Easier wiring
 - Easier debugging
-- No direction-control pin
-- No transceiver modules required
-- Works well over short distances
+- Easier wiring
+- No transceivers
+- No direction control
+- Works well for short runs
 
-## Why RS-485 Is Still Available
+## Future RS-485 Option
 
-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.
+If vehicle electrical noise causes issues, the transport layer can be switched to RS-485 without changing application logic.
diff --git a/docs/wiring.md b/docs/wiring.md
index cea93bb..6d2535c 100644
--- a/docs/wiring.md
+++ b/docs/wiring.md
@@ -28,7 +28,7 @@ Pico Dashboard
 
 Pico
 ↓
-RS-485
+UART over CAT5
 ↓
 ESP32
 
diff --git a/hardware/cat5-pinout.md b/hardware/cat5-pinout.md
index ea0c83e..d261f29 100644
--- a/hardware/cat5-pinout.md
+++ b/hardware/cat5-pinout.md
@@ -1,23 +1,30 @@
 # CAT5 Pinout
 
+## Primary Configuration
+
+UART over CAT5
+
 Pair 1
-Blue        +5V
-Blue/White  +5V
+Blue       +5V
+Blue/White +5V
 
 Pair 2
-Orange      Ground
+Orange       Ground
 Orange/White Ground
 
 Pair 3
-Green       RS-485 A
-Green/White RS-485 B
+Green       Pico TX -> ESP32 RX
+Green/White Pico RX <- ESP32 TX
 
 Pair 4
 Brown       Ignition Sense
 Brown/White Spare
 
-Notes:
+## Future RS-485 Conversion
 
-- Use twisted pair for RS-485
-- Double conductors for power
-- Spare conductor reserved for future use
+Pair 3
+
+Green       RS-485 A
+Green/White RS-485 B
+
+All other conductors remain unchanged.
diff --git a/hardware/uart-cat5-pinout.md b/hardware/uart-cat5-pinout.md
new file mode 100644
index 0000000..7a3e2e4
--- /dev/null
+++ b/hardware/uart-cat5-pinout.md
@@ -0,0 +1,28 @@
+# UART CAT5 Pinout
+
+## Pair 1
+
+Blue       +5V
+Blue/White +5V
+
+## Pair 2
+
+Orange       Ground
+Orange/White Ground
+
+## Pair 3
+
+Green       Pico TX -> ESP32 RX
+Green/White Pico RX <- ESP32 TX
+
+## Pair 4
+
+Brown       Ignition Sense
+Brown/White Spare
+
+## Notes
+
+- Double conductors used for power
+- Shared ground required
+- Spare conductor reserved for future use
+- Pair 3 may later be repurposed for RS-485