197 lines
4.4 KiB
Markdown
197 lines
4.4 KiB
Markdown
# Decisions
|
|
|
|
This document records important design and architecture decisions for Overland Controller.
|
|
|
|
The goal is to preserve why choices were made, not just what was implemented.
|
|
|
|
## Decision: ESP32 Owns System State
|
|
|
|
The ESP32 controller is the source of truth.
|
|
|
|
It owns:
|
|
|
|
- Sensor readings
|
|
- Relay states
|
|
- BMS state
|
|
- Configuration
|
|
- Alarm state
|
|
|
|
Reason:
|
|
|
|
The ESP32 is installed near the electrical system and should continue operating even if the dashboard is disconnected.
|
|
|
|
## Decision: Waveshare ESP32-S3 Is the Dashboard Client
|
|
|
|
The Waveshare ESP32-S3 touchscreen dashboard is responsible for local user interaction.
|
|
|
|
It connects to the Cargo ESP32 access point and consumes the HTTP API. It should not own critical control state.
|
|
|
|
Reason:
|
|
|
|
The dashboard may reboot, disconnect, or be removed without disabling the controller.
|
|
|
|
## Decision: HTTP Is the Primary Dashboard Link
|
|
|
|
HTTP over the Cargo ESP32 local WiFi network is the preferred dashboard-to-controller communication path.
|
|
|
|
Reason:
|
|
|
|
- Matches the WebUI and future integration contract
|
|
- Avoids a dedicated dashboard data cable
|
|
- Supports the Waveshare ESP32-S3 dashboard target
|
|
- Keeps the dashboard a simple client
|
|
|
|
The Cargo ESP32 AP remains available for local operation without internet.
|
|
|
|
## Decision: UART Is Optional Diagnostics
|
|
|
|
UART JSON may remain useful for service diagnostics, simulator work, or alternate clients.
|
|
|
|
Reason:
|
|
|
|
USB serial and UART are useful recovery/debug paths, but the dashboard architecture should not depend on a Pico or UART cable.
|
|
|
|
## Decision: HTTP and UART Should Share a Data Model
|
|
|
|
The same status/config model should be used across:
|
|
|
|
- HTTP
|
|
- Simulator
|
|
- Future MQTT/Home Assistant integrations
|
|
- Optional UART diagnostics
|
|
|
|
Reason:
|
|
|
|
Maintaining multiple data models creates unnecessary rework and bugs.
|
|
|
|
## Decision: Use Generic IDs Internally
|
|
|
|
Firmware uses generic identifiers:
|
|
|
|
relay_1
|
|
relay_2
|
|
|
|
temp_1
|
|
temp_2
|
|
temp_3
|
|
temp_4
|
|
temp_5
|
|
temp_6
|
|
temp_7
|
|
temp_8
|
|
|
|
Reason:
|
|
|
|
The project should not be tied to one vehicle or one layout.
|
|
|
|
## Decision: User Names Belong in Configuration
|
|
|
|
Installation-specific names are saved in config, not hardcoded.
|
|
|
|
Examples of allowed config names:
|
|
|
|
Fridge
|
|
Starlink
|
|
Cabin
|
|
Outside
|
|
House Battery
|
|
|
|
Reason:
|
|
|
|
The same firmware should work in different vehicles, trailers, campers, and power systems.
|
|
|
|
## Decision: BMS Address Is Configurable
|
|
|
|
The BMS BLE address is stored in configuration.
|
|
|
|
Reason:
|
|
|
|
Different users will have different BMS devices.
|
|
|
|
The firmware should not require source code changes to connect to a battery.
|
|
|
|
## Decision: BLE Setup Mode Exists
|
|
|
|
BMS discovery runs in setup mode.
|
|
|
|
Reason:
|
|
|
|
BLE scanning can conflict with an active BMS connection.
|
|
|
|
Setup mode pauses normal BMS reconnect behavior and allows repeated scans.
|
|
|
|
## Decision: Keep USB Serial as a Service Interface
|
|
|
|
USB serial remains available for:
|
|
|
|
- Recovery
|
|
- Troubleshooting
|
|
- Factory reset
|
|
- Manual configuration
|
|
- Debug logging
|
|
|
|
Reason:
|
|
|
|
A physical service path is valuable when WiFi, UART, or dashboard software is broken.
|
|
|
|
## Decision: Relays Should Drive Automotive Relays
|
|
|
|
ESP32 relay outputs should not directly power high-current loads.
|
|
|
|
Recommended pattern:
|
|
|
|
ESP32 output
|
|
-> relay module
|
|
-> automotive relay
|
|
-> fused load
|
|
|
|
Reason:
|
|
|
|
Loads like refrigerators, inverters, compressors, and Starlink should use proper fused automotive circuits.
|
|
|
|
## Decision: DS18B20 Sensors Need Pull-Up Resistor
|
|
|
|
The 1-Wire bus requires a pull-up resistor.
|
|
|
|
Recommended value:
|
|
|
|
4.7k ohm
|
|
|
|
Reason:
|
|
|
|
Long DS18B20 leads are unreliable without the required pull-up.
|
|
|
|
## Decision: Local-First Operation
|
|
|
|
The system should not require internet access.
|
|
|
|
Reason:
|
|
|
|
Overland and remote-use scenarios may have no connectivity.
|
|
|
|
## Decision: Keep APIs Human-Debuggable
|
|
|
|
Messages use JSON.
|
|
|
|
Reason:
|
|
|
|
JSON is easy to inspect in serial logs, HTTP responses, simulators, and future tools.
|
|
|
|
## Decision: Avoid Premature Cloud Features
|
|
|
|
Cloud dashboards and remote access are not current priorities.
|
|
|
|
Reason:
|
|
|
|
The core controller/dashboard system should be reliable locally before remote features are considered.
|
|
|
|
## Decision: Future Pi Zero Is Optional
|
|
|
|
A Pi Zero may be added later for long-term logging, charts, dashboards, or local integrations.
|
|
|
|
It must not own relay control, BMS state, alarm authority, or persistent controller configuration.
|
|
|
|
Reason:
|
|
|
|
The Cargo ESP32 must continue operating as the controller and source of truth without any higher-level computer powered on.
|