4.4 KiB
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