docs: add Codex handoff architecture docs
This commit is contained in:
+95
-256
@@ -1,93 +1,105 @@
|
||||
# Architecture
|
||||
|
||||
Overland Controller is a distributed monitoring and control platform for vehicles, trailers, campers, and mobile power systems.
|
||||
Overland Controller is a distributed monitoring and control platform for the Nissan Xterra and future mobile power systems.
|
||||
|
||||
The system separates electrical control from user interface logic.
|
||||
Core principle:
|
||||
|
||||
## Main Components
|
||||
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
|
||||
|
||||
### ESP32 Controller
|
||||
The system must work locally without internet.
|
||||
|
||||
The ESP32 is the system authority.
|
||||
## Cargo ESP32 Controller
|
||||
|
||||
The Cargo ESP32 owns critical control state and configuration.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- Read battery/BMS data
|
||||
- Read temperature sensors
|
||||
- Control relay outputs
|
||||
- Read JBD/Xiaoxiang BMS data over BLE
|
||||
- Read DS18B20 temperature sensors
|
||||
- Control relay trigger outputs
|
||||
- Store configuration
|
||||
- Serve the HTTP API
|
||||
- Communicate with the Pico dashboard over UART
|
||||
- Maintain system status
|
||||
- Handle alarms
|
||||
- Serve HTTP API
|
||||
- Serve local WebUI
|
||||
- Run WiFi AP mode
|
||||
- Maintain status, alarms, and fault state
|
||||
|
||||
### Pico Dashboard
|
||||
The Cargo ESP32 should not depend on the dashboard, phone, home server, or internet for core operation.
|
||||
|
||||
The Pico is the primary user interface.
|
||||
## 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:
|
||||
|
||||
- Request status from ESP32
|
||||
- Display battery data
|
||||
- Display temperature data
|
||||
- Display relay states
|
||||
- Send relay commands
|
||||
- Send configuration commands
|
||||
- Provide setup workflows
|
||||
- Operate without internet
|
||||
- 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 Pico should not own critical control state. The ESP32 remains the source of truth.
|
||||
The dashboard is a client only. It must not own relay state, BMS config, alarms, or persistent configuration.
|
||||
|
||||
## Communication Paths
|
||||
## WebUI
|
||||
|
||||
### UART
|
||||
The WebUI remains hosted by the Cargo ESP32.
|
||||
|
||||
Primary dashboard/control path.
|
||||
Use WebUI for:
|
||||
|
||||
Used for:
|
||||
|
||||
- Status requests
|
||||
- Relay control
|
||||
- Configuration updates
|
||||
- Setup/configuration
|
||||
- Relay names
|
||||
- Temperature sensor names
|
||||
- BMS setup
|
||||
- BLE scan requests
|
||||
- BMS selection
|
||||
|
||||
UART should eventually support every core management action needed by the Pico.
|
||||
|
||||
### HTTP
|
||||
|
||||
Secondary setup/debug path.
|
||||
|
||||
Used for:
|
||||
|
||||
- Browser testing
|
||||
- Phone/laptop setup
|
||||
- Future web UI
|
||||
- API debugging
|
||||
|
||||
HTTP should mirror the same data model as UART where practical.
|
||||
|
||||
### USB Serial
|
||||
|
||||
Service/debug path.
|
||||
|
||||
Used for:
|
||||
|
||||
- Development
|
||||
- Recovery
|
||||
- Troubleshooting
|
||||
- Emergency configuration
|
||||
- API testing
|
||||
|
||||
## Data Model
|
||||
Avoid complex configuration on the touchscreen dashboard.
|
||||
|
||||
The same generic data model should be used across:
|
||||
## Network
|
||||
|
||||
- HTTP API
|
||||
- UART protocol
|
||||
- Pico dashboard
|
||||
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 MQTT/Home Assistant integrations
|
||||
- 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
|
||||
|
||||
@@ -109,9 +121,9 @@ Temperature sensors:
|
||||
temp_7
|
||||
temp_8
|
||||
|
||||
Installation-specific names belong only in saved configuration.
|
||||
Install-specific names belong in saved configuration only.
|
||||
|
||||
Examples of configuration names:
|
||||
Examples:
|
||||
|
||||
Fridge
|
||||
Starlink
|
||||
@@ -119,33 +131,11 @@ Examples of configuration names:
|
||||
Outside
|
||||
House Battery
|
||||
|
||||
These names should not be hardcoded into firmware behavior.
|
||||
## Status Model
|
||||
|
||||
## Configuration Ownership
|
||||
Dashboard should be able to render from status/config responses without duplicating business logic.
|
||||
|
||||
Configuration is stored on the ESP32.
|
||||
|
||||
Stored configuration includes:
|
||||
|
||||
- Device name
|
||||
- Relay names
|
||||
- Relay enable states
|
||||
- Temperature sensor names
|
||||
- Temperature sensor addresses
|
||||
- Temperature sensor enable states
|
||||
- BMS name
|
||||
- BMS BLE address
|
||||
- BMS address type
|
||||
|
||||
The Pico may edit configuration through UART, but the ESP32 stores and owns it.
|
||||
|
||||
## Status Flow
|
||||
|
||||
Pico sends:
|
||||
|
||||
status_request
|
||||
|
||||
ESP32 responds with the same shape as HTTP /status:
|
||||
Expected status groups:
|
||||
|
||||
battery
|
||||
temps
|
||||
@@ -156,176 +146,25 @@ ESP32 responds with the same shape as HTTP /status:
|
||||
system
|
||||
config
|
||||
|
||||
## Relay Control Flow
|
||||
## Vehicle Data
|
||||
|
||||
Pico sends a generic relay command:
|
||||
Use standard OBD-II over CAN first.
|
||||
|
||||
relay_1 on
|
||||
relay_1 off
|
||||
relay_2 on
|
||||
relay_2 off
|
||||
Planned standard PIDs:
|
||||
|
||||
ESP32 updates the relay output and reports the new state.
|
||||
0105 coolant temperature
|
||||
010C RPM
|
||||
010D vehicle speed
|
||||
|
||||
## BMS Setup Flow
|
||||
Transmission temperature is planned through a dedicated sender rather than Nissan CAN reverse engineering.
|
||||
|
||||
BMS setup can be started from the Pico.
|
||||
## Future Home Server
|
||||
|
||||
Expected flow:
|
||||
Future optional architecture:
|
||||
|
||||
enter_bms_setup
|
||||
scan_ble
|
||||
scan_ble
|
||||
select_bms
|
||||
save_config
|
||||
Phone/PWA
|
||||
-> Home server HTTPS
|
||||
-> MQTT/WebSocket/HTTPS bridge
|
||||
-> Cargo ESP32 outbound connection
|
||||
|
||||
The ESP32 handles BLE scanning and BMS selection.
|
||||
|
||||
The Pico only displays options and sends the selected index or address.
|
||||
|
||||
## HTTP / UART Parity
|
||||
|
||||
Long-term goal:
|
||||
|
||||
- HTTP /status equals UART status_request
|
||||
- HTTP /config equals UART config_request
|
||||
- HTTP /config/device equals UART config_device
|
||||
- HTTP /config/relay equals UART config_relay
|
||||
- HTTP /config/temp equals UART config_temp
|
||||
- HTTP /config/bms equals UART config_bms
|
||||
- HTTP relay control equals UART set_relay
|
||||
- HTTP factory reset equals UART factory_reset
|
||||
|
||||
## Current Priority
|
||||
|
||||
The next implementation priority is UART parity.
|
||||
|
||||
The Pico should be able to do the important setup and control operations without relying on WiFi.
|
||||
|
||||
Minimum UART v1 scope:
|
||||
|
||||
- status_request
|
||||
- set_relay
|
||||
- config_request
|
||||
- config_device
|
||||
- config_relay
|
||||
- config_temp
|
||||
- config_bms
|
||||
- save_config
|
||||
- factory_reset
|
||||
- enter_bms_setup
|
||||
- scan_ble
|
||||
- select_bms
|
||||
- exit_bms_setup
|
||||
|
||||
## Future Integrations
|
||||
|
||||
Possible future integrations:
|
||||
|
||||
- MQTT
|
||||
- Home Assistant
|
||||
- Grafana
|
||||
- InfluxDB
|
||||
- OBD-II
|
||||
- CAN bus
|
||||
- GPS
|
||||
- Data logging
|
||||
- OTA updates
|
||||
|
||||
All future integrations should consume the same generic status/config model.
|
||||
|
||||
---
|
||||
|
||||
## Networking Architecture
|
||||
|
||||
### Current Network Mode
|
||||
|
||||
The ESP32 currently runs in Access Point mode.
|
||||
|
||||
Default access:
|
||||
|
||||
http://192.168.4.1
|
||||
|
||||
The AP is the recovery/setup network.
|
||||
|
||||
### Planned Network Mode
|
||||
|
||||
The planned long-term network mode is AP + STA.
|
||||
|
||||
AP mode:
|
||||
|
||||
Always available
|
||||
Used for recovery and direct setup
|
||||
|
||||
STA mode:
|
||||
|
||||
Connects to a configured WiFi network
|
||||
Used for camp/home access from phone or laptop
|
||||
|
||||
Example networks:
|
||||
|
||||
Starlink
|
||||
Home WiFi
|
||||
Shop WiFi
|
||||
|
||||
### Multiple WiFi Profiles
|
||||
|
||||
The ESP32 should eventually store multiple WiFi profiles and try them in priority order.
|
||||
|
||||
Example:
|
||||
|
||||
1. Starlink
|
||||
2. Home WiFi
|
||||
3. Shop WiFi
|
||||
|
||||
Expected behavior:
|
||||
|
||||
Start AP first
|
||||
Try configured STA networks
|
||||
Connect to the first available network
|
||||
Keep AP available even after STA connects
|
||||
|
||||
Reason:
|
||||
|
||||
- Starlink may be off
|
||||
- Home WiFi may only be available in the driveway
|
||||
- AP must remain available for recovery
|
||||
- User should not lose access because of a bad WiFi password
|
||||
|
||||
### Phone Dashboard Access
|
||||
|
||||
When connected to the ESP32 AP:
|
||||
|
||||
http://192.168.4.1
|
||||
|
||||
When connected through Starlink/home WiFi:
|
||||
|
||||
http://controller-ip
|
||||
|
||||
Future mDNS target:
|
||||
|
||||
http://overland-controller.local
|
||||
|
||||
### Dashboard Roles
|
||||
|
||||
ESP32:
|
||||
|
||||
Source of truth
|
||||
Lightweight phone dashboard
|
||||
HTTP API
|
||||
Recovery AP
|
||||
|
||||
Pico 2 W:
|
||||
|
||||
Instant physical dashboard
|
||||
UART client
|
||||
Touchscreen UI
|
||||
|
||||
Optional future Pi Zero:
|
||||
|
||||
Advanced web dashboard
|
||||
Logging
|
||||
Charts
|
||||
Integrations
|
||||
|
||||
The Pi Zero should be optional, not required for core operation.
|
||||
Remote features must not break local operation.
|
||||
|
||||
Reference in New Issue
Block a user