Clean up documentation structure

2026-06-04 04:07:28 -06:00
parent ff39a06ff4
commit 50410b1d0c
15 changed files with 550 additions and 40 deletions
@@ -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