overland-controller/docs/SERIAL_COMMANDS.md

SERIAL_COMMANDS.md

Serial Console Reference

The ESP32 controller exposes a serial console for setup, troubleshooting, diagnostics, and configuration.

Default settings:

text Baud Rate: 115200 Data Bits: 8 Parity: None Stop Bits: 1 Line Ending: Newline

---

General Commands

status

Displays the complete system status as JSON.

Example:

text status

Returns:

text { "type": "status_response", ... }

---

config

Displays the current active configuration.

Example:

text config

---

save

Saves the current configuration to non-volatile storage.

Example:

text save

Response:

text OK configuration saved

---

factory reset

Restores firmware defaults and clears saved configuration.

Example:

text factory reset

Response:

text OK factory reset complete

Controller will reboot after reset.

---

Device Configuration

devicename

Sets the controller display name.

Example:

text devicename Overland Controller save

Response:

text OK device name updated

---

Relay Commands

Relay IDs are firmware identifiers and do not change.

Available relay IDs:

text relay_1 relay_2

---

relay 1 on

Turns relay 1 on.

Example:

text relay 1 on

Response:

text OK relay 1 on

---

relay 1 off

Turns relay 1 off.

Example:

text relay 1 off

Response:

text OK relay 1 off

---

relay 2 on

Turns relay 2 on.

Example:

text relay 2 on

---

relay 2 off

Turns relay 2 off.

Example:

text relay 2 off

---

Relay Naming

relayname <relay_number>

Assigns a user-friendly name to a relay.

Examples:

text relayname 1 Aux Power relayname 2 Compressor save

Response:

text OK relay renamed

---

Temperature Sensor Commands

Temperature sensor IDs:

text temp_1 temp_2 temp_3 temp_4 temp_5 temp_6 temp_7 temp_8

---

tempname <sensor_number>

Assigns a user-friendly name to a temperature sensor.

Examples:

text tempname 1 Cabin tempname 2 Fridge tempname 3 Outside save

Response:

text OK temperature sensor renamed

---

BMS Configuration

bmsname

Sets the BMS display name.

Example:

text bmsname House Battery save

Response:

text OK BMS name updated

---

bmsaddr

Manually sets the Bluetooth address of the BMS.

Example:

text bmsaddr AA:BB:CC:DD:EE:FF save

Response:

text OK BMS address updated

---

BLE Setup Mode

BLE setup mode is used to discover and select a Bluetooth BMS.

This mode temporarily disconnects the active BMS connection so scans can run reliably.

---

enter setup

Enters BMS setup mode.

Example:

text enter setup

Response:

text OK entered BMS setup mode

---

scan ble

Scans for nearby Bluetooth devices.

Example:

text scan ble

Example output:

text 1) House Battery | AA:BB:CC:DD:EE:FF | RSSI -65 2) Sensor Node | 11:22:33:44:55:66 | RSSI -82 Use: select bms

Notes:

• Some BMS devices advertise infrequently.
• Multiple scans may be required before a device appears.
• BLE scans may take up to 20 seconds.

---

select bms

Selects one of the discovered BLE devices.

Example:

text select bms 1

Response:

text OK selected BMS BMS will reconnect on next update cycle

Remember to save configuration afterward:

text save

---

exit setup

Leaves BMS setup mode.

Example:

text exit setup

Response:

text OK exited BMS setup mode

---

Logging

log level info

Sets console logging to informational messages.

Example:

text log level info

---

log level debug

Enables verbose debugging output.

Example:

text log level debug

Useful when troubleshooting:

• BLE scanning
• BMS connections
• Sensor discovery
• API requests
• Relay control

---

Recommended Initial Setup

Example workflow for a new installation:

text factory reset devicename Overland Controller relayname 1 Aux Power relayname 2 Fridge tempname 1 Cabin tempname 2 Refrigerator tempname 3 Exterior enter setup scan ble select bms 1 exit setup save

Verify configuration:

text config status

---

Troubleshooting

BMS Not Found

Try:

text enter setup scan ble scan ble scan ble

Some BMS devices advertise slowly and may require multiple scans.

---

Relay Testing

Test outputs directly:

text relay 1 on relay 1 off relay 2 on relay 2 off

---

Verify Configuration

text config

Displays all currently loaded settings.

---

Verify Live Status

text status

Returns complete runtime status including:

• Battery data
• Temperatures
• Relay states
• Alarms
• Network state
• System information

---

WiFi Serial Commands

wifi status

Print current WiFi status.

wifi list

Print saved WiFi networks, priorities, and whether passwords are set.

wifi clear

Clear saved STA WiFi networks.

wifi ssid

Set primary WiFi SSID.

wifi pass

Set primary WiFi password.

wifi add ||

Add a saved WiFi network.

Example:

wifi add Starlink|starlink_password|1
wifi add WardAP|Ward5213|2
wifi save
wifi connect

Lower priority numbers are tried first.

wifi save

Save WiFi configuration.

wifi connect

Attempt STA WiFi connection using saved networks by priority.

AP remains available at:

192.168.4.1

---

Temperature Probe Setup

scan temps

Scans the DS18B20 1-Wire bus and prints detected sensor addresses.

Example:

scan temps

assign temp

Assigns a detected physical sensor to a configured temp slot.

Example:

assign temp 1 1
assign temp 2 2
save

clear temp

Clears and disables a configured temp slot.

Example:

clear temp 1

Wiring reminder:

DS18B20 red    -> 3.3V
DS18B20 black  -> GND
DS18B20 yellow -> GPIO4

A single 4.7k resistor is required between 3.3V and GPIO4/data.