171 lines
3.3 KiB
Markdown
171 lines
3.3 KiB
Markdown
# 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/status
|
|
GET /api/config
|
|
POST /api/relays/relay_1/on
|
|
POST /api/relays/relay_1/off
|
|
POST /api/relays/relay_1/toggle
|
|
|
|
Future versioning may move to /api/v1.
|
|
|
|
## 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.
|