Clean up documentation structure
This commit is contained in:
@@ -1,58 +1,260 @@
|
|||||||
# Xterra Overland Power & Monitoring Dashboard
|
Overland Controller
|
||||||
|
|
||||||
A custom monitoring and control system for a Nissan Xterra using:
|
A modular ESP32 and Raspberry Pi Pico based monitoring and control system for overland vehicles, campers, trailers, van builds, and mobile power systems.
|
||||||
|
|
||||||
- Raspberry Pi Pico 2 W dashboard interface
|
The project uses a distributed architecture consisting of:
|
||||||
- ESP32 cargo-area controller
|
|
||||||
- Touchscreen dashboard
|
|
||||||
- Lithium battery monitoring
|
|
||||||
- Fridge monitoring
|
|
||||||
- Relay control
|
|
||||||
- Future vehicle telemetry integration
|
|
||||||
|
|
||||||
## Project Phases
|
* An ESP32 controller mounted near the battery and electrical system
|
||||||
|
* A Raspberry Pi Pico 2 W dashboard mounted in the vehicle cabin
|
||||||
|
* Local WiFi communication
|
||||||
|
* Offline-first operation
|
||||||
|
* Expandable sensor and relay support
|
||||||
|
* Open JSON APIs for future integrations
|
||||||
|
|
||||||
1. Desktop simulator
|
⸻
|
||||||
2. Pico touchscreen UI
|
|
||||||
3. ESP32 communications
|
|
||||||
4. Temperature sensors
|
|
||||||
5. JBD/Xiaoxiang BMS integration
|
|
||||||
6. Future integrations / optional logging
|
|
||||||
|
|
||||||
## Documentation
|
Project Goals
|
||||||
|
|
||||||
### Project Status
|
The goal of Overland Controller is to provide a self-hosted alternative to commercial vehicle monitoring systems.
|
||||||
|
|
||||||
* `docs/project-state.md`
|
The platform is designed to monitor and control:
|
||||||
* `docs/hardware-status.md`
|
|
||||||
|
|
||||||
### System Design
|
* House battery systems
|
||||||
|
* Temperature sensors
|
||||||
|
* Auxiliary relays
|
||||||
|
* Vehicle telemetry
|
||||||
|
* Overland accessories
|
||||||
|
* Future automation systems
|
||||||
|
|
||||||
* `docs/architecture.md`
|
The system should be:
|
||||||
* `docs/protocol.md`
|
|
||||||
* `docs/pico-architecture.md`
|
|
||||||
|
|
||||||
### Hardware
|
* Local-first
|
||||||
|
* Cloud independent
|
||||||
|
* Vehicle independent
|
||||||
|
* Easy to troubleshoot
|
||||||
|
* Easy to expand
|
||||||
|
|
||||||
* `docs/uart.md`
|
⸻
|
||||||
* `docs/wiring.md`
|
|
||||||
* `hardware/bom.md`
|
|
||||||
* `hardware/esp32-pinout.md`
|
|
||||||
|
|
||||||
### User Interface
|
Current Architecture
|
||||||
|
|
||||||
* `docs/ui-wireframes.md`
|
ESP32 Controller
|
||||||
|
|
||||||
### Development
|
The ESP32 acts as the primary control and monitoring node.
|
||||||
|
|
||||||
These documents should be considered the source of truth for ongoing development.
|
Current responsibilities:
|
||||||
|
|
||||||
Priority order:
|
* JBD/Xiaoxiang BMS monitoring
|
||||||
|
* DS18B20 temperature monitoring
|
||||||
|
* Relay control
|
||||||
|
* Configuration management
|
||||||
|
* Local web API
|
||||||
|
* WiFi Access Point
|
||||||
|
* Dashboard communications
|
||||||
|
* System status reporting
|
||||||
|
|
||||||
1. `docs/project-state.md`
|
⸻
|
||||||
2. `docs/hardware-status.md`
|
|
||||||
3. `docs/protocol.md`
|
|
||||||
4. `docs/pico-architecture.md`
|
|
||||||
5. `docs/ui-wireframes.md`
|
|
||||||
|
|
||||||
Implementation should follow documented architecture unless explicitly updated in the documentation first.
|
Raspberry Pi Pico Dashboard
|
||||||
|
|
||||||
|
The Pico dashboard acts as the user interface.
|
||||||
|
|
||||||
|
Planned responsibilities:
|
||||||
|
|
||||||
|
* Touchscreen dashboard
|
||||||
|
* Relay control
|
||||||
|
* Battery monitoring display
|
||||||
|
* Temperature monitoring display
|
||||||
|
* Vehicle status display
|
||||||
|
* Configuration interface
|
||||||
|
* Alarm notifications
|
||||||
|
|
||||||
|
⸻
|
||||||
|
|
||||||
|
Current Features
|
||||||
|
|
||||||
|
Battery Monitoring
|
||||||
|
|
||||||
|
Supported:
|
||||||
|
|
||||||
|
* JBD / Xiaoxiang Bluetooth BMS
|
||||||
|
|
||||||
|
Available telemetry:
|
||||||
|
|
||||||
|
* State of charge
|
||||||
|
* Voltage
|
||||||
|
* Current
|
||||||
|
* Remaining capacity
|
||||||
|
* Total capacity
|
||||||
|
* Runtime estimates
|
||||||
|
* Temperature
|
||||||
|
* Cycle count
|
||||||
|
* Cell voltages
|
||||||
|
* Cell imbalance
|
||||||
|
* Cell count
|
||||||
|
|
||||||
|
⸻
|
||||||
|
|
||||||
|
Temperature Monitoring
|
||||||
|
|
||||||
|
Supported:
|
||||||
|
|
||||||
|
* DS18B20 OneWire temperature sensors
|
||||||
|
|
||||||
|
Features:
|
||||||
|
|
||||||
|
* Up to 8 sensors
|
||||||
|
* User-configurable names
|
||||||
|
* Online/offline detection
|
||||||
|
* Sensor health reporting
|
||||||
|
* JSON API reporting
|
||||||
|
|
||||||
|
⸻
|
||||||
|
|
||||||
|
Relay Control
|
||||||
|
|
||||||
|
Features:
|
||||||
|
|
||||||
|
* Multiple relay outputs
|
||||||
|
* User-configurable names
|
||||||
|
* API control
|
||||||
|
* Serial console control
|
||||||
|
* Dashboard control (planned)
|
||||||
|
|
||||||
|
Recommended usage:
|
||||||
|
|
||||||
|
* Fridge power relays
|
||||||
|
* Starlink power relays
|
||||||
|
* Lighting relays
|
||||||
|
* Inverter enable relays
|
||||||
|
* Accessory relays
|
||||||
|
|
||||||
|
The ESP32 relay outputs are intended to drive automotive relays rather than directly power large loads.
|
||||||
|
|
||||||
|
⸻
|
||||||
|
|
||||||
|
Configuration System
|
||||||
|
|
||||||
|
Configuration is stored locally and survives reboot.
|
||||||
|
|
||||||
|
Configurable items include:
|
||||||
|
|
||||||
|
Device
|
||||||
|
|
||||||
|
* Device name
|
||||||
|
|
||||||
|
Relays
|
||||||
|
|
||||||
|
* Relay name
|
||||||
|
* GPIO assignment
|
||||||
|
* Enabled state
|
||||||
|
|
||||||
|
Temperature Sensors
|
||||||
|
|
||||||
|
* Sensor name
|
||||||
|
* Sensor address
|
||||||
|
* Enabled state
|
||||||
|
|
||||||
|
BMS
|
||||||
|
|
||||||
|
* BMS name
|
||||||
|
* Bluetooth address
|
||||||
|
* Address type
|
||||||
|
|
||||||
|
⸻
|
||||||
|
|
||||||
|
Communication Interfaces
|
||||||
|
|
||||||
|
Serial Console
|
||||||
|
|
||||||
|
Used for:
|
||||||
|
|
||||||
|
* Initial setup
|
||||||
|
* Troubleshooting
|
||||||
|
* Configuration changes
|
||||||
|
* BLE discovery
|
||||||
|
* Diagnostic logging
|
||||||
|
|
||||||
|
See SERIAL_COMMANDS.md for details.
|
||||||
|
|
||||||
|
⸻
|
||||||
|
|
||||||
|
HTTP API
|
||||||
|
|
||||||
|
Provides:
|
||||||
|
|
||||||
|
* Status reporting
|
||||||
|
* Configuration management
|
||||||
|
* Relay control
|
||||||
|
* Dashboard integration
|
||||||
|
|
||||||
|
See API.md for details.
|
||||||
|
|
||||||
|
⸻
|
||||||
|
|
||||||
|
Current Development Status
|
||||||
|
|
||||||
|
Completed
|
||||||
|
|
||||||
|
* Configuration storage
|
||||||
|
* Relay control
|
||||||
|
* JSON status API
|
||||||
|
* BLE BMS integration
|
||||||
|
* BMS setup workflow
|
||||||
|
* DS18B20 framework
|
||||||
|
* Access Point mode
|
||||||
|
* Web server
|
||||||
|
* Dashboard communications framework
|
||||||
|
* Generic naming architecture
|
||||||
|
|
||||||
|
In Progress
|
||||||
|
|
||||||
|
* Dashboard software
|
||||||
|
* Temperature sensor assignment workflow
|
||||||
|
* Expanded configuration API
|
||||||
|
* Documentation cleanup
|
||||||
|
|
||||||
|
Planned
|
||||||
|
|
||||||
|
* Pico touchscreen dashboard
|
||||||
|
* OBD-II integration
|
||||||
|
* GPS integration
|
||||||
|
* MQTT support
|
||||||
|
* Home Assistant integration
|
||||||
|
* Historical data logging
|
||||||
|
* Graphing
|
||||||
|
* Alerting system
|
||||||
|
* OTA updates
|
||||||
|
* Multi-controller support
|
||||||
|
|
||||||
|
⸻
|
||||||
|
|
||||||
|
Design Philosophy
|
||||||
|
|
||||||
|
The project follows several core principles:
|
||||||
|
|
||||||
|
1. Local-first operation
|
||||||
|
2. No cloud dependency
|
||||||
|
3. Generic hardware naming
|
||||||
|
4. Open interfaces
|
||||||
|
5. Modular architecture
|
||||||
|
6. Expandable hardware support
|
||||||
|
7. Easy field troubleshooting
|
||||||
|
8. Vehicle-independent deployment
|
||||||
|
|
||||||
|
⸻
|
||||||
|
|
||||||
|
Documentation
|
||||||
|
|
||||||
|
* README.md — Project overview
|
||||||
|
* API.md — HTTP API documentation
|
||||||
|
* SERIAL_COMMANDS.md — Serial console commands
|
||||||
|
* HARDWARE.md — Hardware overview
|
||||||
|
* ARCHITECTURE.md — System architecture
|
||||||
|
* CHANGELOG.md — Project history
|
||||||
|
|
||||||
|
⸻
|
||||||
|
|
||||||
|
License
|
||||||
|
|
||||||
|
Private project currently under active development.
|
||||||
|
|||||||
@@ -0,0 +1,279 @@
|
|||||||
|
# HARDWARE.md
|
||||||
|
|
||||||
|
# Hardware Overview
|
||||||
|
|
||||||
|
Overland Controller is designed as a distributed system consisting of a control module and a dashboard module.
|
||||||
|
|
||||||
|
The architecture intentionally separates power management from user interface functions.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# System Architecture
|
||||||
|
|
||||||
|
text House Battery │ │ ▼ +-------------------+ | ESP32 Controller | +-------------------+ │ ├── JBD/Xiaoxiang BMS ├── DS18B20 Sensors ├── Relay Outputs ├── Local Web API └── WiFi Network ⇅ +-------------------+ | Pico 2 W Dashboard| +-------------------+ │ ├── Touchscreen ├── Dashboard UI ├── Vehicle Display └── User Controls
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# ESP32 Controller
|
||||||
|
|
||||||
|
The ESP32 controller is installed near the house battery and electrical system.
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
|
||||||
|
- Battery monitoring
|
||||||
|
- Temperature monitoring
|
||||||
|
- Relay control
|
||||||
|
- Configuration storage
|
||||||
|
- Local API server
|
||||||
|
- Dashboard communications
|
||||||
|
|
||||||
|
Current development target:
|
||||||
|
|
||||||
|
text ESP32 DevKit
|
||||||
|
|
||||||
|
Future hardware can be substituted without major firmware changes.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Raspberry Pi Pico Dashboard
|
||||||
|
|
||||||
|
The dashboard provides the primary user interface.
|
||||||
|
|
||||||
|
Current development target:
|
||||||
|
|
||||||
|
text Raspberry Pi Pico 2 W
|
||||||
|
|
||||||
|
Planned display hardware:
|
||||||
|
|
||||||
|
text 3.5" Touchscreen
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
|
||||||
|
- Display system status
|
||||||
|
- Display battery information
|
||||||
|
- Display temperatures
|
||||||
|
- Control relays
|
||||||
|
- Configuration interface
|
||||||
|
- Alarm notifications
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Battery Monitoring
|
||||||
|
|
||||||
|
Supported BMS:
|
||||||
|
|
||||||
|
text JBD Xiaoxiang
|
||||||
|
|
||||||
|
Communication:
|
||||||
|
|
||||||
|
text Bluetooth Low Energy (BLE)
|
||||||
|
|
||||||
|
Data collected:
|
||||||
|
|
||||||
|
- State of charge
|
||||||
|
- Voltage
|
||||||
|
- Current
|
||||||
|
- Capacity
|
||||||
|
- Temperature
|
||||||
|
- Cycle count
|
||||||
|
- Cell voltages
|
||||||
|
- Cell imbalance
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Temperature Sensors
|
||||||
|
|
||||||
|
Supported sensor type:
|
||||||
|
|
||||||
|
text DS18B20
|
||||||
|
|
||||||
|
Connection:
|
||||||
|
|
||||||
|
text 1-Wire Bus
|
||||||
|
|
||||||
|
Current firmware supports:
|
||||||
|
|
||||||
|
text Up to 8 sensors
|
||||||
|
|
||||||
|
Recommended uses:
|
||||||
|
|
||||||
|
- Refrigerator compartment
|
||||||
|
- Freezer compartment
|
||||||
|
- Cabin temperature
|
||||||
|
- Exterior temperature
|
||||||
|
- Electronics enclosure
|
||||||
|
- Battery compartment
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Relay Outputs
|
||||||
|
|
||||||
|
Current firmware supports:
|
||||||
|
|
||||||
|
text 2 relay outputs
|
||||||
|
|
||||||
|
Default GPIO assignments:
|
||||||
|
|
||||||
|
| Relay | GPIO |
|
||||||
|
|---------|---------|
|
||||||
|
| relay_1 | 16 |
|
||||||
|
| relay_2 | 17 |
|
||||||
|
|
||||||
|
These outputs are intended to drive relay coils, not high-current loads directly.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# High Current Loads
|
||||||
|
|
||||||
|
Recommended design:
|
||||||
|
|
||||||
|
text ESP32 GPIO │ ▼ Relay Module │ ▼ Automotive Relay │ ▼ Load
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
- Refrigerator
|
||||||
|
- Starlink
|
||||||
|
- Inverter enable
|
||||||
|
- Lighting circuits
|
||||||
|
- Water pump
|
||||||
|
- Air compressor
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Automotive Relay Recommendation
|
||||||
|
|
||||||
|
Recommended relay type:
|
||||||
|
|
||||||
|
text Bosch-style 30A or 40A relay
|
||||||
|
|
||||||
|
Each high-current circuit should have:
|
||||||
|
|
||||||
|
- Dedicated fuse
|
||||||
|
- Appropriate wire gauge
|
||||||
|
- Proper grounding
|
||||||
|
- Automotive-rated connectors
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Power System
|
||||||
|
|
||||||
|
Typical installation:
|
||||||
|
|
||||||
|
text House Battery │ ├── Main Fuse │ ├── ESP32 Controller │ ├── Relay Circuits │ └── Accessories
|
||||||
|
|
||||||
|
The ESP32 should remain powered from the house battery so monitoring remains active when the vehicle is parked.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Communications
|
||||||
|
|
||||||
|
Current communications:
|
||||||
|
|
||||||
|
## ESP32 ↔ BMS
|
||||||
|
|
||||||
|
text Bluetooth Low Energy
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ESP32 ↔ Dashboard
|
||||||
|
|
||||||
|
Current:
|
||||||
|
|
||||||
|
text UART
|
||||||
|
|
||||||
|
Future:
|
||||||
|
|
||||||
|
text WiFi HTTP API MQTT
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# WiFi Network
|
||||||
|
|
||||||
|
The ESP32 currently provides:
|
||||||
|
|
||||||
|
text Access Point Mode
|
||||||
|
|
||||||
|
Default address:
|
||||||
|
|
||||||
|
text 192.168.4.1
|
||||||
|
|
||||||
|
The dashboard and user devices connect directly to the controller.
|
||||||
|
|
||||||
|
No internet connection is required.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Future Hardware Support
|
||||||
|
|
||||||
|
Planned additions:
|
||||||
|
|
||||||
|
## Vehicle Telemetry
|
||||||
|
|
||||||
|
Possible interfaces:
|
||||||
|
|
||||||
|
text OBD-II ELM327 CAN Bus
|
||||||
|
|
||||||
|
Potential data:
|
||||||
|
|
||||||
|
- Engine RPM
|
||||||
|
- Coolant temperature
|
||||||
|
- Fuel level
|
||||||
|
- Vehicle speed
|
||||||
|
- Diagnostic trouble codes
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## GPS
|
||||||
|
|
||||||
|
Potential features:
|
||||||
|
|
||||||
|
- Location tracking
|
||||||
|
- Trip logging
|
||||||
|
- Route history
|
||||||
|
- Speed tracking
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Environmental Sensors
|
||||||
|
|
||||||
|
Potential additions:
|
||||||
|
|
||||||
|
- Humidity
|
||||||
|
- Barometric pressure
|
||||||
|
- Air quality
|
||||||
|
- Water tank monitoring
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Current Bill of Materials
|
||||||
|
|
||||||
|
## Installed
|
||||||
|
|
||||||
|
- ESP32 Controller
|
||||||
|
- Raspberry Pi Pico 2 W
|
||||||
|
- ESP32 Relay Module
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Planned
|
||||||
|
|
||||||
|
- 3.5" Touchscreen
|
||||||
|
- DS18B20 Sensors
|
||||||
|
- Automotive Relays
|
||||||
|
- Fuse Block
|
||||||
|
- Wiring Harness
|
||||||
|
- Enclosures
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Design Goals
|
||||||
|
|
||||||
|
The hardware platform is intended to be:
|
||||||
|
|
||||||
|
- Modular
|
||||||
|
- Vehicle independent
|
||||||
|
- Serviceable
|
||||||
|
- Expandable
|
||||||
|
- Offline capable
|
||||||
|
- Easy to troubleshoot
|
||||||
|
- Suitable for long-term overland use
|
||||||
@@ -0,0 +1,29 @@
|
|||||||
|
# Documentation
|
||||||
|
|
||||||
|
This folder contains project documentation for Overland Controller.
|
||||||
|
|
||||||
|
## Primary Documents
|
||||||
|
|
||||||
|
- `API.md` - HTTP API reference
|
||||||
|
- `SERIAL_COMMANDS.md` - Serial console command reference
|
||||||
|
- `HARDWARE.md` - Hardware overview
|
||||||
|
- `ARCHITECTURE.md` - System architecture
|
||||||
|
- `CHANGELOG.md` - Project change history
|
||||||
|
|
||||||
|
## Project Tracking
|
||||||
|
|
||||||
|
- `project-state.md` - Current project state
|
||||||
|
- `roadmap.md` - Roadmap and future plans
|
||||||
|
- `hardware-status.md` - Hardware status and bring-up notes
|
||||||
|
- `decisions.md` - Architecture and implementation decisions
|
||||||
|
|
||||||
|
## Technical References
|
||||||
|
|
||||||
|
- `protocol.md` - Dashboard/controller protocol
|
||||||
|
- `wiring.md` - Wiring notes and plans
|
||||||
|
|
||||||
|
## Archive
|
||||||
|
|
||||||
|
Older or duplicate documents have been moved to `archive/`.
|
||||||
|
|
||||||
|
Archived documents are kept for history, but the primary documents above should be treated as the current source of truth.
|
||||||
Reference in New Issue
Block a user