docs: add Codex handoff architecture docs
This commit is contained in:
+72
-236
@@ -1,279 +1,115 @@
|
||||
# HARDWARE.md
|
||||
# Hardware
|
||||
|
||||
# Hardware Overview
|
||||
## Cargo ESP32
|
||||
|
||||
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.
|
||||
The cargo ESP32 is the controller and source of truth.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- Battery monitoring
|
||||
- Temperature monitoring
|
||||
- Relay control
|
||||
- Configuration storage
|
||||
- Local API server
|
||||
- Dashboard communications
|
||||
- BMS BLE
|
||||
- Relays
|
||||
- DS18B20 temps
|
||||
- WebUI
|
||||
- HTTP API
|
||||
- AP mode
|
||||
- Alarms
|
||||
|
||||
Current development target:
|
||||
Relay board outputs are trigger/control outputs only.
|
||||
|
||||
text ESP32 DevKit
|
||||
High-current loads must use properly fused automotive relays or contactors.
|
||||
|
||||
Future hardware can be substituted without major firmware changes.
|
||||
Do not directly route fridge, Starlink, inverter, lights, or other major loads through the ESP32 relay board.
|
||||
|
||||
---
|
||||
## Dashboard
|
||||
|
||||
# Raspberry Pi Pico Dashboard
|
||||
Target:
|
||||
|
||||
The dashboard provides the primary user interface.
|
||||
Waveshare ESP32-S3-Touch-LCD-5
|
||||
|
||||
Current development target:
|
||||
Reasons:
|
||||
|
||||
text Raspberry Pi Pico 2 W
|
||||
- ESP32-S3 is mature enough for LVGL dashboard
|
||||
- 5 inch 800x480 display gives enough UI space
|
||||
- WiFi connects to Cargo ESP32 AP
|
||||
- CAN interface with onboard TJA1051 supports future OBD-II vehicle data
|
||||
- microSD allows future logging
|
||||
- 7-36V VIN supports vehicle power
|
||||
|
||||
Planned display hardware:
|
||||
## Dashboard Power
|
||||
|
||||
text 3.5" Touchscreen
|
||||
Preferred:
|
||||
|
||||
Responsibilities:
|
||||
ACC switched 12V
|
||||
-> fuse
|
||||
-> Waveshare VIN
|
||||
|
||||
- Display system status
|
||||
- Display battery information
|
||||
- Display temperatures
|
||||
- Control relays
|
||||
- Configuration interface
|
||||
- Alarm notifications
|
||||
Do not use OBD-II pin 16 for permanent dashboard power.
|
||||
|
||||
---
|
||||
## CAN / OBD-II
|
||||
|
||||
# Battery Monitoring
|
||||
OBD-II pins:
|
||||
|
||||
Supported BMS:
|
||||
Pin 6 = CAN-H
|
||||
Pin 14 = CAN-L
|
||||
Pin 5 = Signal Ground, optional if needed
|
||||
Pin 16 = Battery 12V, do not use for permanent display power
|
||||
|
||||
text JBD Xiaoxiang
|
||||
Waveshare CAN termination must remain disabled on vehicle CAN.
|
||||
|
||||
Communication:
|
||||
Preferred CAN wiring:
|
||||
|
||||
text Bluetooth Low Energy (BLE)
|
||||
OBD pin 6 -> Waveshare CAN-H
|
||||
OBD pin 14 -> Waveshare CAN-L
|
||||
|
||||
Data collected:
|
||||
Optional:
|
||||
|
||||
- State of charge
|
||||
- Voltage
|
||||
- Current
|
||||
- Capacity
|
||||
- Temperature
|
||||
- Cycle count
|
||||
- Cell voltages
|
||||
- Cell imbalance
|
||||
OBD pin 5 -> board/system ground
|
||||
|
||||
---
|
||||
Use twisted pair. Cat5e/Cat6 twisted pair is acceptable for short vehicle runs.
|
||||
|
||||
# Temperature Sensors
|
||||
Avoid Scotchlok/vampire taps on vehicle CAN. Prefer OBD splitter or proper automotive splice.
|
||||
|
||||
Supported sensor type:
|
||||
## Vehicle Data
|
||||
|
||||
text DS18B20
|
||||
Coolant temp:
|
||||
|
||||
Connection:
|
||||
Standard OBD-II PID 0105
|
||||
|
||||
text 1-Wire Bus
|
||||
RPM:
|
||||
|
||||
Current firmware supports:
|
||||
Standard OBD-II PID 010C
|
||||
|
||||
text Up to 8 sensors
|
||||
Vehicle speed:
|
||||
|
||||
Recommended uses:
|
||||
Standard OBD-II PID 010D
|
||||
|
||||
- Refrigerator compartment
|
||||
- Freezer compartment
|
||||
- Cabin temperature
|
||||
- Exterior temperature
|
||||
- Electronics enclosure
|
||||
- Battery compartment
|
||||
## Transmission Temperature Sender
|
||||
|
||||
---
|
||||
Preferred over Nissan-specific trans-temp CAN reverse engineering.
|
||||
|
||||
# Relay Outputs
|
||||
Candidate:
|
||||
|
||||
Current firmware supports:
|
||||
Autometer 2258 / 2259 style sender
|
||||
|
||||
text 2 relay outputs
|
||||
Resistance table:
|
||||
|
||||
Default GPIO assignments:
|
||||
100F = 1123 ohms
|
||||
120F = 708 ohms
|
||||
140F = 460 ohms
|
||||
150F = 374 ohms
|
||||
170F = 253 ohms
|
||||
190F = 175 ohms
|
||||
210F = 123 ohms
|
||||
230F = 89 ohms
|
||||
250F = 65 ohms
|
||||
280F = 42 ohms
|
||||
300F = 32 ohms
|
||||
320F = 25 ohms
|
||||
340F = 20 ohms
|
||||
|
||||
| Relay | GPIO |
|
||||
|---------|---------|
|
||||
| relay_1 | 16 |
|
||||
| relay_2 | 17 |
|
||||
Implementation:
|
||||
|
||||
These outputs are intended to drive relay coils, not high-current loads directly.
|
||||
- Sender to ADC voltage divider, or
|
||||
- Sender to ADS1115 over I2C if no suitable exposed ADC exists
|
||||
|
||||
---
|
||||
|
||||
# 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
|
||||
Use lookup-table interpolation.
|
||||
|
||||
Reference in New Issue
Block a user