Checkpoint current docs, BLE setup workflow, and generic config refactor
This commit is contained in:
+356
-52
@@ -1,76 +1,380 @@
|
||||
# Xterra Overland Power & Monitoring Dashboard
|
||||
# ARCHITECTURE.md
|
||||
|
||||
## Purpose
|
||||
# System Architecture
|
||||
|
||||
A custom monitoring and control system for a Nissan Xterra using a Raspberry Pi Pico 2 W dashboard interface and an ESP32 cargo-area controller.
|
||||
Overland Controller is built as a distributed monitoring and control platform for overland vehicles, campers, trailers, and mobile power systems.
|
||||
|
||||
The system provides:
|
||||
The architecture intentionally separates user interface functions from monitoring and control functions.
|
||||
|
||||
- House battery monitoring
|
||||
- Fridge monitoring
|
||||
- Temperature monitoring
|
||||
- Power control
|
||||
- Alarm management
|
||||
- Future vehicle telemetry
|
||||
This improves reliability, modularity, and future expandability.
|
||||
|
||||
## Dashboard Module
|
||||
---
|
||||
|
||||
### Hardware
|
||||
# High-Level Overview
|
||||
|
||||
- Raspberry Pi Pico 2 W
|
||||
- 3.5" SPI Capacitive Touchscreen
|
||||
- UART-over-CAT5 communications
|
||||
- WiFi backup communications
|
||||
text User │ ▼ +----------------+ | Dashboard UI | | Pico 2 W | +----------------+ │ │ UART / WiFi ▼ +----------------+ | ESP32 Controller| +----------------+ │ │ │ │ │ │ ▼ ▼ ▼ BMS Sensors Relays
|
||||
|
||||
### Responsibilities
|
||||
The ESP32 is the system authority.
|
||||
|
||||
- Touchscreen user interface
|
||||
- Local web dashboard
|
||||
- Alarm display
|
||||
- Configuration management
|
||||
- Relay control interface
|
||||
- Data visualization
|
||||
The dashboard acts as a user interface only.
|
||||
|
||||
## Cargo Module
|
||||
---
|
||||
|
||||
### Hardware
|
||||
# Core Design Principles
|
||||
|
||||
- ESP32 Relay Controller
|
||||
- UART-over-CAT5 interface
|
||||
- House Battery Interface
|
||||
- DS18B20 Temperature Sensor Bus
|
||||
- Bosch Relay Drivers
|
||||
## Local First
|
||||
|
||||
### Responsibilities
|
||||
The system must function completely offline.
|
||||
|
||||
- Sensor collection
|
||||
- Relay control
|
||||
- Alarm processing
|
||||
- Communications server
|
||||
Requirements:
|
||||
|
||||
- No cloud dependency
|
||||
- No internet requirement
|
||||
- No third-party service requirement
|
||||
- No account requirement
|
||||
|
||||
---
|
||||
|
||||
## Controller First
|
||||
|
||||
The ESP32 is responsible for:
|
||||
|
||||
- Data collection
|
||||
- Device control
|
||||
- Configuration storage
|
||||
- State management
|
||||
|
||||
## Communications
|
||||
The dashboard should never be required for normal operation.
|
||||
|
||||
Primary:
|
||||
- UART over CAT5
|
||||
---
|
||||
|
||||
Backup:
|
||||
- WiFi HTTP API
|
||||
## Generic Hardware Naming
|
||||
|
||||
The firmware should never assume installation-specific names.
|
||||
|
||||
Avoid:
|
||||
|
||||
text Fridge Starlink Greta Outside Rear Seat
|
||||
|
||||
Instead use:
|
||||
|
||||
text relay_1 relay_2 temp_1 temp_2 temp_3 temp_4
|
||||
|
||||
User-specific naming belongs in configuration.
|
||||
|
||||
---
|
||||
|
||||
## API Driven
|
||||
|
||||
All data should be exposed through structured APIs.
|
||||
|
||||
Benefits:
|
||||
|
||||
- Dashboard independence
|
||||
- Future Home Assistant integration
|
||||
- Future MQTT support
|
||||
- Easier testing
|
||||
- Easier automation
|
||||
|
||||
---
|
||||
|
||||
# ESP32 Controller
|
||||
|
||||
The ESP32 is the primary controller.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
## Battery Monitoring
|
||||
|
||||
Source:
|
||||
|
||||
text JBD / Xiaoxiang BLE BMS
|
||||
|
||||
Provides:
|
||||
|
||||
- State of charge
|
||||
- Voltage
|
||||
- Current
|
||||
- Capacity
|
||||
- Temperature
|
||||
- Cell data
|
||||
|
||||
---
|
||||
|
||||
## Temperature Monitoring
|
||||
|
||||
Source:
|
||||
|
||||
text DS18B20 Sensors
|
||||
|
||||
Provides:
|
||||
|
||||
- Temperature readings
|
||||
- Sensor health
|
||||
- Online/offline status
|
||||
|
||||
---
|
||||
|
||||
## Relay Control
|
||||
|
||||
Provides:
|
||||
|
||||
- Output control
|
||||
- State reporting
|
||||
- Future automation logic
|
||||
|
||||
---
|
||||
|
||||
## Configuration Storage
|
||||
|
||||
Stores:
|
||||
|
||||
- Device name
|
||||
- Relay configuration
|
||||
- Temperature sensor configuration
|
||||
- BMS configuration
|
||||
|
||||
Configuration survives reboot.
|
||||
|
||||
---
|
||||
|
||||
## Local Web Server
|
||||
|
||||
Provides:
|
||||
|
||||
- Status endpoint
|
||||
- Configuration endpoint
|
||||
- Relay control endpoint
|
||||
|
||||
Current transport:
|
||||
|
||||
text HTTP JSON
|
||||
|
||||
---
|
||||
|
||||
# Dashboard
|
||||
|
||||
Current target:
|
||||
|
||||
text Raspberry Pi Pico 2 W
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- Display information
|
||||
- User interaction
|
||||
- Relay control
|
||||
- Configuration management
|
||||
|
||||
The dashboard should not contain critical business logic.
|
||||
|
||||
---
|
||||
|
||||
# Data Flow
|
||||
|
||||
## Battery Data
|
||||
|
||||
text BMS │ ▼ ESP32 │ ▼ Status API │ ▼ Dashboard
|
||||
|
||||
---
|
||||
|
||||
## Temperature Data
|
||||
|
||||
text DS18B20 │ ▼ ESP32 │ ▼ Status API │ ▼ Dashboard
|
||||
|
||||
---
|
||||
|
||||
## Relay Control
|
||||
|
||||
text User │ ▼ Dashboard │ ▼ ESP32 API │ ▼ Relay Output
|
||||
|
||||
Future automation may bypass the dashboard entirely.
|
||||
|
||||
---
|
||||
|
||||
# Communications
|
||||
|
||||
## Current
|
||||
|
||||
### BMS → ESP32
|
||||
|
||||
text BLE
|
||||
|
||||
### Dashboard → ESP32
|
||||
|
||||
text UART
|
||||
|
||||
### Browser → ESP32
|
||||
|
||||
text HTTP
|
||||
|
||||
---
|
||||
|
||||
## Future
|
||||
|
||||
Potential future transports:
|
||||
|
||||
text WiFi MQTT WebSockets CAN Bus
|
||||
|
||||
---
|
||||
|
||||
# Configuration Model
|
||||
|
||||
Configuration exists in three layers.
|
||||
|
||||
## Firmware Defaults
|
||||
|
||||
Built into firmware.
|
||||
|
||||
Example:
|
||||
|
||||
text relay_1 relay_2 temp_1 temp_2
|
||||
|
||||
Used when no configuration exists.
|
||||
|
||||
---
|
||||
|
||||
## Stored Configuration
|
||||
|
||||
Saved in non-volatile storage.
|
||||
|
||||
Contains:
|
||||
|
||||
- User names
|
||||
- Addresses
|
||||
- Enable states
|
||||
|
||||
Persists through reboot.
|
||||
|
||||
---
|
||||
|
||||
## Runtime State
|
||||
|
||||
Current operational values.
|
||||
|
||||
Examples:
|
||||
|
||||
text Battery voltage Relay state Temperature readings Alarm status
|
||||
|
||||
Generated dynamically.
|
||||
|
||||
Never stored permanently.
|
||||
|
||||
---
|
||||
|
||||
# Status Model
|
||||
|
||||
The status API contains six major sections.
|
||||
|
||||
## Battery
|
||||
|
||||
Battery telemetry.
|
||||
|
||||
---
|
||||
|
||||
## Temperatures
|
||||
|
||||
Temperature sensor readings.
|
||||
|
||||
---
|
||||
|
||||
## Relays
|
||||
|
||||
Relay states.
|
||||
|
||||
---
|
||||
|
||||
## Vehicle
|
||||
|
||||
Vehicle telemetry.
|
||||
|
||||
Currently minimal.
|
||||
|
||||
Future expansion point.
|
||||
|
||||
---
|
||||
|
||||
## Alarms
|
||||
|
||||
System alarm state.
|
||||
|
||||
Examples:
|
||||
|
||||
text Low battery High temperature BMS disconnected Cell imbalance
|
||||
|
||||
---
|
||||
|
||||
## System
|
||||
|
||||
Controller information.
|
||||
|
||||
Examples:
|
||||
|
||||
text Firmware version Build date Build time Uptime
|
||||
|
||||
---
|
||||
|
||||
# Future Expansion
|
||||
|
||||
## Vehicle Integration
|
||||
|
||||
Potential sources:
|
||||
|
||||
text OBD-II ELM327 CAN Bus
|
||||
|
||||
Potential data:
|
||||
|
||||
- RPM
|
||||
- Fuel level
|
||||
- Coolant temperature
|
||||
- Vehicle speed
|
||||
- Trouble codes
|
||||
|
||||
---
|
||||
|
||||
## GPS
|
||||
|
||||
Potential features:
|
||||
|
||||
- Location
|
||||
- Trip logging
|
||||
- Route history
|
||||
|
||||
---
|
||||
|
||||
## MQTT
|
||||
|
||||
Potential integrations:
|
||||
|
||||
Future:
|
||||
- MQTT
|
||||
- Home Assistant
|
||||
- Node-RED
|
||||
- Grafana
|
||||
- InfluxDB
|
||||
|
||||
## Future Expansion
|
||||
---
|
||||
|
||||
- JBD/Xiaoxiang BLE Battery Monitoring
|
||||
- OBD-II
|
||||
- CAN Bus
|
||||
- GPS
|
||||
- Trip Logging
|
||||
- Fuel Level
|
||||
- Coolant Temperature
|
||||
- RPM
|
||||
- Starlink Diagnostics
|
||||
## Data Logging
|
||||
|
||||
Potential storage:
|
||||
|
||||
text SD Card Internal Flash Network Storage
|
||||
|
||||
Potential data:
|
||||
|
||||
- Battery history
|
||||
- Temperature history
|
||||
- Relay history
|
||||
- Vehicle telemetry
|
||||
|
||||
---
|
||||
|
||||
# Long-Term Vision
|
||||
|
||||
The long-term goal is a modular platform capable of monitoring and controlling nearly every subsystem in an overland vehicle while remaining:
|
||||
|
||||
- Offline capable
|
||||
- Self-hosted
|
||||
- Hardware independent
|
||||
- Expandable
|
||||
- Easy to troubleshoot
|
||||
- Easy to maintain
|
||||
- Free from cloud dependencies
|
||||
|
||||
Reference in New Issue
Block a user