overland-controller/docs/CONFIGURATION.md

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

Disabled relays are forced OFF immediately, hidden from normal dashboard controls, and protected from /api/v1/relay/set commands until re-enabled.

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