overland-controller/docs/ARCHITECTURE.md

# Architecture

Overland Controller is a distributed monitoring and control platform for mobile power systems and overland vehicles.

Core principle:

    Cargo ESP32 = controller / source of truth
    Waveshare ESP32-S3 dashboard = local touchscreen client
    Phone/laptop WebUI = configuration interface
    Home server = future optional remote access layer

The system must work locally without internet.

## Cargo ESP32 Controller

The Cargo ESP32 owns critical control state and configuration.

Responsibilities:

- Read JBD/Xiaoxiang BMS data over BLE
- Read DS18B20 temperature sensors
- Control relay trigger outputs
- Store configuration
- Serve HTTP API
- Serve local WebUI
- Run WiFi AP mode
- Maintain status, alarms, and fault state

The Cargo ESP32 should not depend on the dashboard, phone, home server, or internet for core operation.

## Waveshare ESP32-S3 Dashboard

Target hardware:

- Waveshare ESP32-S3-Touch-LCD-5
- 5 inch 800x480 capacitive touchscreen
- ESP32-S3
- 16MB flash
- 8MB PSRAM
- WiFi + BLE
- CAN with onboard TJA1051 transceiver
- microSD
- 7-36V VIN support

Responsibilities:

- Native LVGL dashboard
- Connect to Cargo ESP32 AP as WiFi client
- Poll Cargo ESP32 HTTP API
- Send simple control commands through HTTP API
- Display battery, relay, temp, vehicle, and alert data
- Future CAN vehicle data
- Future transmission temperature sender display

The dashboard is a client only. It must not own relay state, BMS config, alarms, or persistent configuration.

## WebUI

The WebUI remains hosted by the Cargo ESP32.

Use WebUI for:

- Setup/configuration
- Relay names
- Temperature sensor names
- BMS setup
- Recovery
- API testing

Avoid complex configuration on the touchscreen dashboard.

## Network

Cargo ESP32 runs WPA2 AP mode continuously.

Expected local URL:

    http://192.168.4.1

Dashboard connects to that AP and talks HTTP.

No UART cable is planned between dashboard and Cargo ESP32.

## HTTP API

HTTP is the primary integration contract for:

- WebUI
- Dashboard
- Simulator
- Future home server
- Future MQTT/Home Assistant/Grafana integrations

Preferred direction:

    GET  /api/v1/health
    GET  /api/v1/capabilities
    GET  /api/v1/status
    GET  /api/v1/config
    GET  /api/v1/config/export
    POST /api/v1/config/import
    POST /api/v1/relay/set

Pre-versioned root routes remain registered as compatibility aliases for existing local clients.

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

Install-specific names belong in saved configuration only.

Examples:

    Fridge
    Starlink
    Cabin
    Outside
    House Battery

## Status Model

Dashboard should be able to render from status/config responses without duplicating business logic.

Expected status groups:

    battery
    temps
    relays
    vehicle
    network
    alarms
    system
    config

## Vehicle Data

Use standard OBD-II over CAN first.

Planned standard PIDs:

    0105 coolant temperature
    010C RPM
    010D vehicle speed

Transmission temperature is planned through a dedicated sender rather than Nissan CAN reverse engineering.

## Future Home Server

Future optional architecture:

    Phone/PWA
      -> Home server HTTPS
      -> MQTT/WebSocket/HTTPS bridge
      -> Cargo ESP32 outbound connection

Remote features must not break local operation.


## Cargo-led AP Pairing and Credential Migration

The Cargo ESP32 owns the local overland network. It is the AP owner, source of truth, and configuration authority.

Target behavior:

1. Cargo ESP32 starts a WPA2-protected AP.
2. Cargo OLED shows setup credentials and critical recovery/status information.
3. Phone connects to the Cargo AP and uses the WebUI for setup/admin.
4. Dashboard ESP32-S3 joins the Cargo AP as a client.
5. If the user changes the Cargo AP SSID/password, the Cargo ESP stages the new credentials and coordinates dashboard migration.
6. Dashboard stores the new credentials before the Cargo AP restarts.
7. Cargo AP applies the new credentials.
8. Dashboard reconnects automatically.

The dashboard should not own network authority. A temporary dashboard setup AP may exist only as a recovery/fallback mechanism, not the normal pairing path.

Recovery target:

- A setup/status button on the Cargo ESP enclosure can show AP credentials on the OLED.
- A long hold can restore factory AP credentials or enter recovery mode.


## Current communications and GPIO decision

Active dashboard communication is WiFi/HTTP using `/api/v1`.

The old Pico/dashboard UART path is retired from active hardware use. USB Serial remains available for development, debug, and manual configuration from a computer.

Current Cargo ESP32 GPIO plan:

- GPIO 16: Relay 1 trigger output
- GPIO 17: Relay 2 trigger output
- GPIO 4: DS18B20 OneWire temperature bus
- GPIO 34: Ignition sense input
- GPIO 21: SSD1306 OLED I2C SDA
- GPIO 22: SSD1306 OLED I2C SCL
- GPIO 25: OLED setup/status button

## Role Boundary Summary

See `docs/controller-roles.md` for the authoritative role split.

Committed v1 architecture:

    Dashboard ESP32-S3
            <-> WiFi / HTTP REST
    Cargo ESP32 AP
            <-> control outputs
    Automotive load-switching layer
            <-> fused loads
    Fridge / Starlink / lights / spare outputs

The Cargo ESP32 owns power-system control.

The Dashboard ESP32-S3 renders the touchscreen UI and future vehicle visualization.

For v1, controller-to-dashboard communication is WiFi/HTTP only. ESP-NOW, MQTT, UART, and CAN-between-controllers are not part of the v1 dashboard link.

The load-switching hardware is not finalized. Bosch relays, WUPP-style modules, smart high-side switching, or a future custom PCB remain implementation options until explicitly selected.

## Dashboard Hardware Target

The current dashboard hardware target is the Waveshare ESP32-S3 Touch LCD 5B.

Selected dashboard hardware:

- Waveshare ESP32-S3 Touch LCD 5B
- 5-inch touchscreen
- 1024x600 display resolution
- Capacitive touch
- Native WiFi
- LVGL-capable ESP32-S3 platform
- Integrated CAN transceiver available for future vehicle integration

This replaces the earlier Pico dashboard concept as the active dashboard architecture.

The Dashboard ESP32-S3 communicates with the Cargo ESP32 over WiFi/HTTP REST for v1. CAN/OBD-II support remains a future dashboard-side vehicle-visualization feature and is not part of the Cargo ESP32 role.

## Existing DS18B20 Temperature Support

DS18B20 temperature sensor support is already part of the Cargo ESP architecture.

Current responsibility split:

- Cargo ESP32 owns DS18B20 sensor reading.
- Cargo ESP32 exposes temperature state through the WebUI/API path.
- Dashboard ESP32-S3 should consume temperature data from the Cargo ESP API.
- Dashboard ESP32-S3 should not wire directly to cargo-area DS18B20 sensors for v1.

This means future dashboard work should display existing Cargo ESP temperature telemetry rather than reimplementing temperature sensing on the dashboard.

## Cargo ESP API Contract

The Cargo ESP API contract is documented in `docs/cargo-api-contract.md`.

The Cargo ESP32 is the source of truth for:

- Relay/output state
- DS18B20 temperature readings
- BMS telemetry
- Alarm/fault state
- Local configuration

The ESP32-S3 dashboard should consume Cargo ESP API data over WiFi/HTTP REST instead of directly owning cargo sensors or relay state.

## Cargo ESP Hardware Transition Plan

Current active development and testing remains on the existing 2-channel relay board.

A LILYGO T-Relay-S3 6-way board has been ordered as a future Cargo ESP candidate.

Transition strategy:

- Keep current 2-channel board working.
- Make the Cargo ESP API output-count agnostic.
- Represent outputs as a list of output objects.
- Let clients render whatever output list the Cargo ESP exposes.
- Add a hardware profile/config layer before migrating firmware to LilyGO.
- Bench test LilyGO relay boot behavior before connecting it to the WUPP block.

The API should not require redesign when moving from 2 outputs to 6 outputs.

## Planned WebSocket Push Layer

The project may add a WebSocket push layer in addition to the current `/api/v1` REST API. This is intended as an additive transport, not a replacement for the REST API.

Recommended model:

```text
Dashboard ESP  <-- WebSocket /ws live status --  Cargo ESP
Dashboard ESP  -- REST /api/v1 relay commands -> Cargo ESP
Dashboard ESP  -- REST /api/v1/status fallback -> Cargo ESP
```

The REST API remains the canonical, human-debuggable contract for snapshots, testing, and compatibility. WebSockets should be used for live status pushes so dashboard UI elements can update immediately after sensor changes, relay state changes, and future vehicle telemetry updates.

Initial implementation should preserve existing polling as a fallback path. If the WebSocket connection is unavailable or stale, the dashboard should continue to use `/api/v1/status`.