diff --git a/README.md b/README.md index 14f2292..dcdc407 100644 --- a/README.md +++ b/README.md @@ -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 -- ESP32 cargo-area controller -- Touchscreen dashboard -- Lithium battery monitoring -- Fridge monitoring -- Relay control -- Future vehicle telemetry integration +The project uses a distributed architecture consisting of: -## 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` -* `docs/hardware-status.md` +The platform is designed to monitor and control: -### System Design +* House battery systems +* Temperature sensors +* Auxiliary relays +* Vehicle telemetry +* Overland accessories +* Future automation systems -* `docs/architecture.md` -* `docs/protocol.md` -* `docs/pico-architecture.md` +The system should be: -### 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. diff --git a/docs/api.md b/docs/API.md similarity index 100% rename from docs/api.md rename to docs/API.md diff --git a/docs/architecture.md b/docs/ARCHITECTURE.md similarity index 100% rename from docs/architecture.md rename to docs/ARCHITECTURE.md diff --git a/docs/HARDWARE.md b/docs/HARDWARE.md new file mode 100644 index 0000000..4a232d4 --- /dev/null +++ b/docs/HARDWARE.md @@ -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 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..d6b1cc4 --- /dev/null +++ b/docs/README.md @@ -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. diff --git a/docs/api-and-serial-commands.md b/docs/archive/api-and-serial-commands.md similarity index 100% rename from docs/api-and-serial-commands.md rename to docs/archive/api-and-serial-commands.md diff --git a/docs/codex-handoff.md b/docs/archive/codex-handoff.md similarity index 100% rename from docs/codex-handoff.md rename to docs/archive/codex-handoff.md diff --git a/docs/communications.md b/docs/archive/communications.md similarity index 100% rename from docs/communications.md rename to docs/archive/communications.md diff --git a/docs/dashboard-ui.md b/docs/archive/dashboard-ui.md similarity index 100% rename from docs/dashboard-ui.md rename to docs/archive/dashboard-ui.md diff --git a/docs/hardware-bringup-checklist.md b/docs/archive/hardware-bringup-checklist.md similarity index 100% rename from docs/hardware-bringup-checklist.md rename to docs/archive/hardware-bringup-checklist.md diff --git a/docs/implementation-roadmap.md b/docs/archive/implementation-roadmap.md similarity index 100% rename from docs/implementation-roadmap.md rename to docs/archive/implementation-roadmap.md diff --git a/docs/pico-architecture.md b/docs/archive/pico-architecture.md similarity index 100% rename from docs/pico-architecture.md rename to docs/archive/pico-architecture.md diff --git a/docs/sensors.md b/docs/archive/sensors.md similarity index 100% rename from docs/sensors.md rename to docs/archive/sensors.md diff --git a/docs/uart.md b/docs/archive/uart.md similarity index 100% rename from docs/uart.md rename to docs/archive/uart.md diff --git a/docs/ui-wireframes.md b/docs/archive/ui-wireframes.md similarity index 100% rename from docs/ui-wireframes.md rename to docs/archive/ui-wireframes.md