# 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.