Add Pico dashboard architecture document

docs/pico-architecture.md

@@ -0,0 +1,325 @@
+# Pico Dashboard Architecture
+
+## Purpose
+
+The Raspberry Pi Pico 2 W dashboard is the primary user interface for the Xterra Overland Power & Monitoring Dashboard.
+
+Its responsibilities are:
+
+* Display live system status
+* Display alarms and warnings
+* Allow relay control
+* Provide touchscreen navigation
+* Communicate with the ESP32 cargo controller
+* Provide audible alerts through a dashboard buzzer
+
+The Pico is intentionally a display and control device.
+
+The ESP32 remains responsible for hardware control and sensor collection.
+
+---
+
+# Hardware
+
+## Dashboard Controller
+
+* Raspberry Pi Pico 2 W
+
+## Display
+
+* ST7796S
+* 320x480 resolution
+* SPI interface
+
+## Touch Controller
+
+* FT6336U
+* Capacitive touch
+* I2C interface
+
+## Audio
+
+* Active buzzer
+
+## Communications
+
+Primary:
+
+* UART over CAT5
+
+Backup:
+
+* WiFi HTTP API
+
+Fallback only:
+
+* RS-485 (not currently planned)
+
+---
+
+# Software Architecture
+
+```text
+main.py
+│
+├── app_state.py
+│
+├── comms/
+│   ├── uart_client.py
+│   ├── http_client.py
+│   └── protocol.py
+│
+├── hardware/
+│   ├── display.py
+│   ├── touch.py
+│   └── buzzer.py
+│
+├── alarms/
+│   ├── alarm_manager.py
+│   └── alarm_definitions.py
+│
+└── ui/
+    ├── screen_manager.py
+    ├── dashboard_screen.py
+    ├── battery_screen.py
+    ├── temps_screen.py
+    ├── power_screen.py
+    ├── system_screen.py
+    └── alarm_overlay.py
+```
+
+---
+
+# Application State
+
+A single application state object should hold all current controller data.
+
+Example:
+
+```python
+state.battery_soc
+state.battery_voltage
+
+state.fridge_zone_1_temp
+state.fridge_zone_2_temp
+
+state.starlink_enabled
+state.fridge_enabled
+
+state.ignition_on
+
+state.uart_connected
+state.wifi_connected
+```
+
+All screens should render from the application state rather than communicating directly with the ESP32.
+
+---
+
+# Communication Layer
+
+## Responsibilities
+
+* Send status requests
+* Receive status responses
+* Send relay commands
+* Handle communication failures
+* Switch to HTTP fallback if UART fails
+
+The communication layer should be the only component that knows how to talk to the ESP32.
+
+---
+
+# Screen Manager
+
+The screen manager owns navigation.
+
+Initial screens:
+
+1. Dashboard
+2. Battery
+3. Temperatures
+4. Power
+5. System
+
+Only one screen should be active at a time.
+
+---
+
+# Dashboard Screen
+
+The dashboard screen is the default landing page.
+
+Display:
+
+* Battery SOC
+* Battery voltage
+* Battery current
+* Remaining runtime
+* Fridge temperatures
+* Relay status
+* Communication status
+* Active alarms
+
+Goal:
+
+Quick vehicle-at-a-glance information.
+
+---
+
+# Battery Screen
+
+Display:
+
+* SOC
+* Voltage
+* Current
+* Remaining amp-hours
+* Runtime estimate
+* Battery temperature
+
+Future:
+
+* BMS cell voltages
+* Charge/discharge limits
+
+---
+
+# Temperature Screen
+
+Display:
+
+* Fridge Zone 1
+* Fridge Zone 2
+* Rear Seat Area
+* Outside Air
+
+Display sensor fault indicators when sensors are missing.
+
+---
+
+# Power Screen
+
+Display:
+
+* Starlink relay status
+* Fridge relay status
+
+Allow relay control.
+
+Future:
+
+* Inverter
+* Lighting
+* Additional accessory relays
+
+---
+
+# System Screen
+
+Display:
+
+* ESP32 status
+* Communication status
+* Firmware versions
+* WiFi status
+* Sensor health
+
+Future:
+
+* Configuration options
+
+---
+
+# Alarm Manager
+
+The alarm manager continuously evaluates system state.
+
+Initial alarms:
+
+## Battery Low
+
+Triggered when SOC falls below configured threshold.
+
+## Battery Voltage Low
+
+Triggered when voltage falls below configured threshold.
+
+## Fridge Temperature High
+
+Triggered when fridge temperature exceeds configured threshold.
+
+## Sensor Failure
+
+Triggered when a sensor becomes unavailable.
+
+## Communication Failure
+
+Triggered when ESP32 communication is lost.
+
+---
+
+# Alarm Overlay
+
+The alarm overlay is visible from any screen.
+
+Severity levels:
+
+* Info
+* Warning
+* Critical
+
+Critical alarms should trigger the buzzer.
+
+---
+
+# Buzzer Manager
+
+Initial buzzer events:
+
+* Critical battery alarm
+* High fridge temperature
+* Communication loss
+* Sensor failure
+
+The buzzer should be non-blocking and event-driven.
+
+---
+
+# UI Design Goals
+
+* Touchscreen-only operation
+* Large buttons
+* Readable in sunlight
+* Minimal navigation depth
+* Fast status visibility
+* Safe operation while driving
+
+---
+
+# Initial Bring-Up Order
+
+1. Display test
+2. Touch test
+3. Buzzer test
+4. Static UI rendering
+5. UART communications
+6. Live status display
+7. Relay control
+8. Alarm overlay
+9. WiFi fallback
+
+---
+
+# Out of Scope
+
+Not currently planned:
+
+* Persistent logging
+* Historical graphs
+* Cloud connectivity
+* Internet access requirements
+* User accounts
+* Remote access
+
+The system is intended to operate fully offline.