overland-controller/docs/api-and-serial-commands.md

ESP32 API and Serial Commands

HTTP API

Base URL while connected to the ESP32 access point:

http://192.168.4.1

---

Status

GET /status

Returns full controller status.

Includes:

• Battery/BMS telemetry
• Cell voltages
• Temperature readings
• Sensor health
• Relay states
• Vehicle state
• Network state
• Alarm state
• System info
• Current configuration

Relay states use generic relay IDs:

relay_1
relay_2

Temperature sensors use generic sensor IDs:

temp_1
temp_2
temp_3
temp_4
temp_5
temp_6
temp_7
temp_8

---

Relay Control API

GET /relay/relay_1/on

Turns relay 1 on.

GET /relay/relay_1/off

Turns relay 1 off.

GET /relay/relay_2/on

Turns relay 2 on.

GET /relay/relay_2/off

Turns relay 2 off.

Relay display names are configurable. The firmware should not assume what a relay controls.

---

Deprecated Relay Aliases

These legacy routes may still exist for compatibility during development, but should not be used by new clients:

/relay/starlink/on
/relay/starlink/off
/relay/fridge/on
/relay/fridge/off

Future work should remove these aliases after the Pico/dashboard clients use generic relay IDs.

---

Configuration API

GET /config

Returns saved configuration.

---

POST /config/relay

Updates relay config.

Example body:

{
  "id": "relay_1",
  "name": "Aux Power",
  "enabled": true
}

Valid IDs:

• relay_1
• relay_2

---

POST /config/bms

Updates BMS config.

Example body:

{
  "enabled": true,
  "name": "House Battery",
  "address": "aa:bb:cc:dd:ee:ff",
  "address_type": "public"
}

---

POST /config/temp

Updates temperature sensor config.

Example body:

{
  "id": "temp_1",
  "name": "Cabin",
  "address": "",
  "enabled": true
}

Valid IDs:

• temp_1
• temp_2
• temp_3
• temp_4
• temp_5
• temp_6
• temp_7
• temp_8

---

POST /config/factory-reset

Clears saved config and restores generic defaults.

---

Serial Monitor

Baud:

115200

Line ending:

Newline

---

Status and Config Commands

status

Prints full JSON status to Serial.

config

Prints current configuration to Serial.

save

Saves current in-memory configuration to NVS.

factory reset

Clears saved config and restores defaults.

---

Log Level Commands

log quiet

Minimizes serial output.

log info

Normal serial output.

log debug

Enables recurring debug output.

---

Relay Control Commands

Legacy relay control commands may still exist during development:

relay starlink on
relay starlink off
relay fridge on
relay fridge off

Future work should replace these with generic serial relay commands.

---

Relay Configuration Commands

relayname 1 Aux Power

Sets relay 1 display name.

relayname 2 Accessory Power

Sets relay 2 display name.

Run save after changing names.

---

Temperature Sensor Configuration Commands

tempname 1 Cabin

Sets temp sensor 1 display name.

tempname 2 Outside Air

Sets temp sensor 2 display name.

Run save after changing names.

---

BMS Configuration Commands

bmsname House Battery

Sets BMS display name.

bmsaddr aa:bb:cc:dd:ee:ff

Sets BMS BLE address.

Run save after changing BMS config manually.

---

BMS Setup Mode Commands

enter setup

Enters BMS setup mode.

Effects:

• Disconnects BMS client
• Pauses BMS reconnect
• Allows repeated BLE scans

scan ble

Scans for BLE devices.

Notes:

• Some BMS modules advertise intermittently.
• Multiple scans may be required.

select bms 1

Selects BLE scan result 1 as the configured BMS.

This saves:

• BMS name
• BMS address
• BMS enabled state

exit setup

Leaves BMS setup mode and allows BMS reconnect.

---

Typical First-Time Setup Flow

log info
enter setup
scan ble
scan ble
select bms 1
relayname 1 Aux Power
relayname 2 Accessory Power
tempname 1 Cabin
tempname 2 Outside Air
save
config

---

Known Notes

• BMS telemetry is reliable once a BMS address is configured.
• BLE discovery depends on how often the BMS advertises.
• DS18B20 sensors require a 4.7kΩ pull-up resistor on the 1-Wire data bus.
• Some legacy relay names still exist internally and should be removed in a future cleanup.