# 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 <name>

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> <name>

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> <name>

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 <name>

Sets the BMS display name.

Example:

text bmsname House Battery save 

Response:

text OK BMS name updated 

---

## bmsaddr <address>

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 <number> 

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 <number>

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