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.