Update architecture decision records
This commit is contained in:
+161
-40
@@ -1,58 +1,179 @@
|
||||
# Project Decisions
|
||||
# Decisions
|
||||
|
||||
## Communications
|
||||
This document records important design and architecture decisions for Overland Controller.
|
||||
|
||||
Primary:
|
||||
- UART over CAT5 initially
|
||||
The goal is to preserve why choices were made, not just what was implemented.
|
||||
|
||||
Backup/Future:
|
||||
- RS-485 over CAT5 if UART proves unreliable
|
||||
- WiFi HTTP API
|
||||
## Decision: ESP32 Owns System State
|
||||
|
||||
## Dashboard
|
||||
The ESP32 controller is the source of truth.
|
||||
|
||||
- Touchscreen only
|
||||
- No physical buttons required
|
||||
- Screen sleeps when ignition is off
|
||||
- Touch wakes display
|
||||
It owns:
|
||||
|
||||
## Relay Design
|
||||
- Sensor readings
|
||||
- Relay states
|
||||
- BMS state
|
||||
- Configuration
|
||||
- Alarm state
|
||||
|
||||
- ESP32 relay board does NOT switch loads directly
|
||||
- Bosch-style automotive relays switch all major loads
|
||||
Reason:
|
||||
|
||||
## Power Loads
|
||||
The ESP32 is installed near the electrical system and should continue operating even if the dashboard is disconnected.
|
||||
|
||||
Current:
|
||||
- Starlink
|
||||
- Fridge
|
||||
## Decision: Pico Is a Dashboard, Not the Controller
|
||||
|
||||
Future:
|
||||
- Inverter
|
||||
- Camp Lights
|
||||
The Pico dashboard is responsible for user interaction.
|
||||
|
||||
## Sensors
|
||||
It should not own critical control state.
|
||||
|
||||
Current:
|
||||
- Fridge Zone 1
|
||||
- Fridge Zone 2
|
||||
- Rear Seat Area
|
||||
- Outside Air
|
||||
Reason:
|
||||
|
||||
Future:
|
||||
- Battery Bay
|
||||
- Cabin Air
|
||||
- Water Tank
|
||||
The dashboard may reboot, disconnect, or be removed without disabling the controller.
|
||||
|
||||
## Configuration
|
||||
## Decision: UART Is the Primary Dashboard Link
|
||||
|
||||
Configuration is stored on controller side, not browser side.
|
||||
UART is the preferred Pico-to-ESP32 communication path.
|
||||
|
||||
## Logging
|
||||
Reason:
|
||||
|
||||
No persistent logging currently planned.
|
||||
- Simple wiring
|
||||
- Deterministic
|
||||
- No WiFi dependency
|
||||
- Works offline
|
||||
- Easier to debug electrically
|
||||
|
||||
Focus:
|
||||
- Live monitoring
|
||||
- Alarms
|
||||
- Control
|
||||
HTTP remains useful for setup, debugging, and future web UI.
|
||||
|
||||
## Decision: HTTP and UART Should Share a Data Model
|
||||
|
||||
The same status/config model should be used across:
|
||||
|
||||
- UART
|
||||
- HTTP
|
||||
- Simulator
|
||||
- Future MQTT/Home Assistant integrations
|
||||
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user