overland-controller/docs/ARCHITECTURE.md

# Architecture

Overland Controller is a distributed monitoring and control platform for vehicles, trailers, campers, and mobile power systems.

The system separates electrical control from user interface logic.

## Main Components

### ESP32 Controller

The ESP32 is the system authority.

Responsibilities:

- Read battery/BMS data
- Read temperature sensors
- Control relay outputs
- Store configuration
- Serve the HTTP API
- Communicate with the Pico dashboard over UART
- Maintain system status
- Handle alarms

### Pico Dashboard

The Pico is the primary user interface.

Responsibilities:

- Request status from ESP32
- Display battery data
- Display temperature data
- Display relay states
- Send relay commands
- Send configuration commands
- Provide setup workflows
- Operate without internet

The Pico should not own critical control state. The ESP32 remains the source of truth.

## Communication Paths

### UART

Primary dashboard/control path.

Used for:

- Status requests
- Relay control
- Configuration updates
- BMS setup
- BLE scan requests
- BMS selection

UART should eventually support every core management action needed by the Pico.

### HTTP

Secondary setup/debug path.

Used for:

- Browser testing
- Phone/laptop setup
- Future web UI
- API debugging

HTTP should mirror the same data model as UART where practical.

### USB Serial

Service/debug path.

Used for:

- Development
- Recovery
- Troubleshooting
- Emergency configuration

## Data Model

The same generic data model should be used across:

- HTTP API
- UART protocol
- Pico dashboard
- Simulator
- Future MQTT/Home Assistant integrations

## Generic IDs

Firmware uses generic IDs.

Relays:

    relay_1
    relay_2

Temperature sensors:

    temp_1
    temp_2
    temp_3
    temp_4
    temp_5
    temp_6
    temp_7
    temp_8

Installation-specific names belong only in saved configuration.

Examples of configuration names:

    Fridge
    Starlink
    Cabin
    Outside
    House Battery

These names should not be hardcoded into firmware behavior.

## Configuration Ownership

Configuration is stored on the ESP32.

Stored configuration includes:

- Device name
- Relay names
- Relay enable states
- Temperature sensor names
- Temperature sensor addresses
- Temperature sensor enable states
- BMS name
- BMS BLE address
- BMS address type

The Pico may edit configuration through UART, but the ESP32 stores and owns it.

## Status Flow

Pico sends:

    status_request

ESP32 responds with the same shape as HTTP /status:

    battery
    temps
    relays
    vehicle
    network
    alarms
    system
    config

## Relay Control Flow

Pico sends a generic relay command:

    relay_1 on
    relay_1 off
    relay_2 on
    relay_2 off

ESP32 updates the relay output and reports the new state.

## BMS Setup Flow

BMS setup can be started from the Pico.

Expected flow:

    enter_bms_setup
    scan_ble
    scan_ble
    select_bms
    save_config

The ESP32 handles BLE scanning and BMS selection.

The Pico only displays options and sends the selected index or address.

## HTTP / UART Parity

Long-term goal:

- HTTP /status equals UART status_request
- HTTP /config equals UART config_request
- HTTP /config/device equals UART config_device
- HTTP /config/relay equals UART config_relay
- HTTP /config/temp equals UART config_temp
- HTTP /config/bms equals UART config_bms
- HTTP relay control equals UART set_relay
- HTTP factory reset equals UART factory_reset

## Current Priority

The next implementation priority is UART parity.

The Pico should be able to do the important setup and control operations without relying on WiFi.

Minimum UART v1 scope:

- status_request
- set_relay
- config_request
- config_device
- config_relay
- config_temp
- config_bms
- save_config
- factory_reset
- enter_bms_setup
- scan_ble
- select_bms
- exit_bms_setup

## Future Integrations

Possible future integrations:

- MQTT
- Home Assistant
- Grafana
- InfluxDB
- OBD-II
- CAN bus
- GPS
- Data logging
- OTA updates

All future integrations should consume the same generic status/config model.

---

## Networking Architecture

### Current Network Mode

The ESP32 currently runs in Access Point mode.

Default access:

    http://192.168.4.1

The AP is the recovery/setup network.

### Planned Network Mode

The planned long-term network mode is AP + STA.

AP mode:

    Always available
    Used for recovery and direct setup

STA mode:

    Connects to a configured WiFi network
    Used for camp/home access from phone or laptop

Example networks:

    Starlink
    Home WiFi
    Shop WiFi

### Multiple WiFi Profiles

The ESP32 should eventually store multiple WiFi profiles and try them in priority order.

Example:

    1. Starlink
    2. Home WiFi
    3. Shop WiFi

Expected behavior:

    Start AP first
    Try configured STA networks
    Connect to the first available network
    Keep AP available even after STA connects

Reason:

- Starlink may be off
- Home WiFi may only be available in the driveway
- AP must remain available for recovery
- User should not lose access because of a bad WiFi password

### Phone Dashboard Access

When connected to the ESP32 AP:

    http://192.168.4.1

When connected through Starlink/home WiFi:

    http://controller-ip

Future mDNS target:

    http://overland-controller.local

### Dashboard Roles

ESP32:

    Source of truth
    Lightweight phone dashboard
    HTTP API
    Recovery AP

Pico 2 W:

    Instant physical dashboard
    UART client
    Touchscreen UI

Optional future Pi Zero:

    Advanced web dashboard
    Logging
    Charts
    Integrations

The Pi Zero should be optional, not required for core operation.