# Overland Controller

Overland Controller is a local-first vehicle power and monitoring system designed for overland, camping, and off-grid vehicle use.

Current target vehicle:

    Nissan Xterra

The firmware itself is intended to stay vehicle-agnostic.

## Current Version

    0.4.0

## What It Does

The ESP32 controller currently provides:

- Local WebUI
- HTTP API
- UART JSON protocol
- USB serial maintenance commands
- Relay control
- JBD/Xiaoxiang BLE BMS telemetry
- DS18B20 temperature sensor support
- Persistent configuration
- WiFi AP mode
- WiFi STA mode
- Multiple saved WiFi networks with priority

## Current Hardware

Current controller:

- ESP32 2-relay board

Primary dashboard target:

- Waveshare ESP32-S3-Touch-LCD-5
- WiFi client to the Cargo ESP32 access point
- HTTP API integration

Optional future expansion:

- Pi Zero for long-term logging, charts, and local integrations

## WebUI

The embedded WebUI is served directly from the ESP32.

Access through AP mode:

    http://192.168.4.1

Access through STA mode:

    http://<controller-ip>

The WebUI includes:

- Overview tab
- Battery tab
- Config tab

The Config tab is the preferred initial setup workflow.

## Core Concepts

The ESP32 is the source of truth.

The Waveshare ESP32-S3 dashboard is a client-only local display and control surface.

The WebUI is used for setup, configuration, and phone access from camp.

A future Pi Zero may be added for long-term logging or richer local integrations, but it must not become required for core control.

## Documentation

Important docs:

- `docs/project-state.md`
- `docs/API.md`
- `docs/ARCHITECTURE.md`
- `docs/HARDWARE.md`
- `docs/dashboard-esp32s3.md`
- `docs/CONFIGURATION.md`
- `docs/UART_PROTOCOL.md`
- `docs/SERIAL_COMMANDS.md`
- `docs/PARITY_MATRIX.md`
- `docs/TEMP_SETUP.md`
- `docs/ROADMAP.md`
- `docs/CHANGELOG.md`

## Safety

This project controls vehicle electrical loads.

Use:

- Proper fusing
- Proper wire gauge
- Proper terminals/ferrules
- Common ground
- Strain relief
- Testing before connecting expensive loads

Do not connect vehicle 12V directly to ESP32 GPIO pins or dashboard GPIO pins.