overland-controller/docs/ARCHITECTURE.md

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.