Checkpoint current docs, BLE setup workflow, and generic config refactor

docs/SERIAL_COMMANDS.md

@@ -0,0 +1,366 @@
+# 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