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