# Decisions

This document records important design and architecture decisions for Overland Controller.

The goal is to preserve why choices were made, not just what was implemented.

## Decision: ESP32 Owns System State

The ESP32 controller is the source of truth.

It owns:

- Sensor readings
- Relay states
- BMS state
- Configuration
- Alarm state

Reason:

The ESP32 is installed near the electrical system and should continue operating even if the dashboard is disconnected.

## Decision: Waveshare ESP32-S3 Is the Dashboard Client

The Waveshare ESP32-S3 touchscreen dashboard is responsible for local user interaction.

It connects to the Cargo ESP32 access point and consumes the HTTP API. It should not own critical control state.

Reason:

The dashboard may reboot, disconnect, or be removed without disabling the controller.

## Decision: HTTP Is the Primary Dashboard Link

HTTP over the Cargo ESP32 local WiFi network is the preferred dashboard-to-controller communication path.

Reason:

- Matches the WebUI and future integration contract
- Avoids a dedicated dashboard data cable
- Supports the Waveshare ESP32-S3 dashboard target
- Keeps the dashboard a simple client

The Cargo ESP32 AP remains available for local operation without internet.

## Decision: UART Is Optional Diagnostics

UART JSON may remain useful for service diagnostics, simulator work, or alternate clients.

Reason:

USB serial and UART are useful recovery/debug paths, but the dashboard architecture should not depend on a Pico or UART cable.

## Decision: HTTP and UART Should Share a Data Model

The same status/config model should be used across:

- HTTP
- Simulator
- Future MQTT/Home Assistant integrations
- Optional UART diagnostics

Reason:

Maintaining multiple data models creates unnecessary rework and bugs.

## Decision: Use Generic IDs Internally

Firmware uses generic identifiers:

    relay_1
    relay_2

    temp_1
    temp_2
    temp_3
    temp_4
    temp_5
    temp_6
    temp_7
    temp_8

Reason:

The project should not be tied to one vehicle or one layout.

## Decision: User Names Belong in Configuration

Installation-specific names are saved in config, not hardcoded.

Examples of allowed config names:

    Fridge
    Starlink
    Cabin
    Outside
    House Battery

Reason:

The same firmware should work in different vehicles, trailers, campers, and power systems.

## Decision: BMS Address Is Configurable

The BMS BLE address is stored in configuration.

Reason:

Different users will have different BMS devices.

The firmware should not require source code changes to connect to a battery.

## Decision: BLE Setup Mode Exists

BMS discovery runs in setup mode.

Reason:

BLE scanning can conflict with an active BMS connection.

Setup mode pauses normal BMS reconnect behavior and allows repeated scans.

## Decision: Keep USB Serial as a Service Interface

USB serial remains available for:

- Recovery
- Troubleshooting
- Factory reset
- Manual configuration
- Debug logging

Reason:

A physical service path is valuable when WiFi, UART, or dashboard software is broken.

## Decision: Relays Should Drive Automotive Relays

ESP32 relay outputs should not directly power high-current loads.

Recommended pattern:

    ESP32 output
      -> relay module
      -> automotive relay
      -> fused load

Reason:

Loads like refrigerators, inverters, compressors, and Starlink should use proper fused automotive circuits.

## Decision: DS18B20 Sensors Need Pull-Up Resistor

The 1-Wire bus requires a pull-up resistor.

Recommended value:

    4.7k ohm

Reason:

Long DS18B20 leads are unreliable without the required pull-up.

## Decision: Local-First Operation

The system should not require internet access.

Reason:

Overland and remote-use scenarios may have no connectivity.

## Decision: Keep APIs Human-Debuggable

Messages use JSON.

Reason:

JSON is easy to inspect in serial logs, HTTP responses, simulators, and future tools.

## Decision: Avoid Premature Cloud Features

Cloud dashboards and remote access are not current priorities.

Reason:

The core controller/dashboard system should be reliable locally before remote features are considered.

## Decision: Future Pi Zero Is Optional

A Pi Zero may be added later for long-term logging, charts, dashboards, or local integrations.

It must not own relay control, BMS state, alarm authority, or persistent controller configuration.

Reason:

The Cargo ESP32 must continue operating as the controller and source of truth without any higher-level computer powered on.