# Architecture

Overland Controller is a distributed monitoring and control platform for the Nissan Xterra and future mobile power systems.

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.