Update architecture decision records

docs/decisions.md

@@ -1,58 +1,179 @@
-# Project Decisions
+# Decisions
 
-## Communications
+This document records important design and architecture decisions for Overland Controller.
 
-Primary:
+The goal is to preserve why choices were made, not just what was implemented.
-- UART over CAT5 initially
 
-Backup/Future:
+## Decision: ESP32 Owns System State
-- RS-485 over CAT5 if UART proves unreliable
-- WiFi HTTP API
 
-## Dashboard
+The ESP32 controller is the source of truth.
 
-- Touchscreen only
+It owns:
-- No physical buttons required
-- Screen sleeps when ignition is off
-- Touch wakes display
 
-## Relay Design
+- Sensor readings
+- Relay states
+- BMS state
+- Configuration
+- Alarm state
 
-- ESP32 relay board does NOT switch loads directly
+Reason:
-- Bosch-style automotive relays switch all major loads
 
-## Power Loads
+The ESP32 is installed near the electrical system and should continue operating even if the dashboard is disconnected.
 
-Current:
+## Decision: Pico Is a Dashboard, Not the Controller
-- Starlink
-- Fridge
 
-Future:
+The Pico dashboard is responsible for user interaction.
-- Inverter
-- Camp Lights
 
-## Sensors
+It should not own critical control state.
 
-Current:
+Reason:
-- Fridge Zone 1
-- Fridge Zone 2
-- Rear Seat Area
-- Outside Air
 
-Future:
+The dashboard may reboot, disconnect, or be removed without disabling the controller.
-- Battery Bay
-- Cabin Air
-- Water Tank
 
-## Configuration
+## Decision: UART Is the Primary Dashboard Link
 
-Configuration is stored on controller side, not browser side.
+UART is the preferred Pico-to-ESP32 communication path.
 
-## Logging
+Reason:
 
-No persistent logging currently planned.
+- Simple wiring
+- Deterministic
+- No WiFi dependency
+- Works offline
+- Easier to debug electrically
 
-Focus:
+HTTP remains useful for setup, debugging, and future web UI.
-- Live monitoring
+
-- Alarms
+## Decision: HTTP and UART Should Share a Data Model
-- Control
+
+The same status/config model should be used across:
+
+- UART
+- HTTP
+- Simulator
+- Future MQTT/Home Assistant integrations
+
+Reason:
+
+Maintaining multiple data models creates unnecessary rework and bugs.
+
+## Decision: Use Generic IDs Internally
+
+Firmware uses generic identifiers:
+
+    relay_1
+    relay_2
+
+    temp_1
+    temp_2
+    temp_3
+    temp_4
+    temp_5
+    temp_6
+    temp_7
+    temp_8
+
+Reason:
+
+The project should not be tied to one vehicle or one layout.
+
+## Decision: User Names Belong in Configuration
+
+Installation-specific names are saved in config, not hardcoded.
+
+Examples of allowed config names:
+
+    Fridge
+    Starlink
+    Cabin
+    Outside
+    House Battery
+
+Reason:
+
+The same firmware should work in different vehicles, trailers, campers, and power systems.
+
+## Decision: BMS Address Is Configurable
+
+The BMS BLE address is stored in configuration.
+
+Reason:
+
+Different users will have different BMS devices.
+
+The firmware should not require source code changes to connect to a battery.
+
+## Decision: BLE Setup Mode Exists
+
+BMS discovery runs in setup mode.
+
+Reason:
+
+BLE scanning can conflict with an active BMS connection.
+
+Setup mode pauses normal BMS reconnect behavior and allows repeated scans.
+
+## Decision: Keep USB Serial as a Service Interface
+
+USB serial remains available for:
+
+- Recovery
+- Troubleshooting
+- Factory reset
+- Manual configuration
+- Debug logging
+
+Reason:
+
+A physical service path is valuable when WiFi, UART, or dashboard software is broken.
+
+## Decision: Relays Should Drive Automotive Relays
+
+ESP32 relay outputs should not directly power high-current loads.
+
+Recommended pattern:
+
+    ESP32 output
+      -> relay module
+      -> automotive relay
+      -> fused load
+
+Reason:
+
+Loads like refrigerators, inverters, compressors, and Starlink should use proper fused automotive circuits.
+
+## Decision: DS18B20 Sensors Need Pull-Up Resistor
+
+The 1-Wire bus requires a pull-up resistor.
+
+Recommended value:
+
+    4.7k ohm
+
+Reason:
+
+Long DS18B20 leads are unreliable without the required pull-up.
+
+## Decision: Local-First Operation
+
+The system should not require internet access.
+
+Reason:
+
+Overland and remote-use scenarios may have no connectivity.
+
+## Decision: Keep APIs Human-Debuggable
+
+Messages use JSON.
+
+Reason:
+
+JSON is easy to inspect in serial logs, HTTP responses, simulators, and future tools.
+
+## Decision: Avoid Premature Cloud Features
+
+Cloud dashboards and remote access are not current priorities.
+
+Reason:
+
+The core controller/dashboard system should be reliable locally before remote features are considered.