# 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