# Configuration

Overland Controller stores configuration on the ESP32 so the system can be customized without changing firmware.

Configuration survives reboot.

## Configuration Goals

- Keep firmware generic
- Store installation-specific names in config
- Support multiple vehicle/camper layouts
- Allow setup from HTTP/WebUI and service interfaces
- Avoid hardcoded device names, relay names, sensor names, or BMS names

## Stored Configuration

The controller stores:

- Device name
- Relay configuration
- Temperature sensor configuration
- BMS configuration

## Device Configuration

Device config contains:

    device_name

Example:

    Overland Controller

Serial command:

    devicename Overland Controller
    save

HTTP endpoint:

    POST /api/v1/config/device

## Relay Configuration

Relays use generic firmware IDs:

    relay_1
    relay_2

Each relay has:

- id
- name
- pin
- enabled

Example:

    relay_1 = Aux Power
    relay_2 = Fridge

Serial commands:

    relayname 1 Aux Power
    relayname 2 Fridge
    save

HTTP endpoint:

    POST /api/v1/config/relay

## Temperature Sensor Configuration

Temperature sensors use generic firmware IDs:

    temp_1
    temp_2
    temp_3
    temp_4
    temp_5
    temp_6
    temp_7
    temp_8

Each sensor has:

- id
- name
- address
- enabled

Example:

    temp_1 = Cabin
    temp_2 = Outside Air

Serial commands:

    tempname 1 Cabin
    tempname 2 Outside Air
    save

HTTP endpoint:

    POST /api/v1/config/temp

## BMS Configuration

BMS config contains:

- enabled
- name
- address
- address_type

Example:

    name = House Battery
    address = aa:bb:cc:dd:ee:ff
    address_type = public

Serial commands:

    bmsname House Battery
    bmsaddr aa:bb:cc:dd:ee:ff
    save

HTTP endpoint:

    POST /api/v1/config/bms

## BMS Setup Mode

BMS setup mode allows BLE discovery and BMS selection.

Serial flow:

    enter setup
    scan ble
    scan ble
    select bms 1
    save

Notes:

- Some BMS modules advertise intermittently.
- Multiple scans may be required.
- Once configured, the controller reconnects directly by stored address.

## Factory Reset

Factory reset clears saved configuration and restores firmware defaults.

Serial command:

    factory reset

HTTP endpoint:

    POST /api/v1/config/factory-reset

After factory reset:

- Device name returns to generic default
- Relay names return to generic defaults
- Temperature names return to generic defaults
- BMS is unconfigured until selected or manually entered

## Backup And Restore

Configuration backup includes controller config and saved STA WiFi networks.

HTTP endpoints:

    GET  /api/v1/config/export
    POST /api/v1/config/import

`config/export` includes saved WiFi passwords so the backup can be restored. Treat exported JSON as sensitive.

`config/import` persists the restored config. If WiFi networks are imported, run `POST /api/v1/wifi/connect` afterward to attempt STA connection.

## Configuration Persistence

Configuration is stored using ESP32 non-volatile storage.

Configuration is loaded during boot.

If no saved configuration exists, firmware defaults are loaded and saved.

## Important Rule

Installation-specific names belong only in saved configuration.

Allowed in configuration:

    Starlink
    Fridge
    House Battery
    Outside Air

Not allowed as firmware assumptions:

    hardcoded relay names
    hardcoded sensor names
    hardcoded BMS names
    hardcoded vehicle-specific names