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.