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.