Document configuration model

docs/CONFIGURATION.md

@@ -0,0 +1,193 @@
+# Configuration
+
+Overland Controller stores configuration on the ESP32 so the system can be customized without changing firmware.
+
+Configuration survives reboot.
+
+## Configuration Goals
+
+- Keep firmware generic
+- Store installation-specific names in config
+- Support multiple vehicle/camper layouts
+- Allow setup from serial, HTTP, and eventually Pico UART
+- Avoid hardcoded device names, relay names, sensor names, or BMS names
+
+## Stored Configuration
+
+The controller stores:
+
+- Device name
+- Relay configuration
+- Temperature sensor configuration
+- BMS configuration
+
+## Device Configuration
+
+Device config contains:
+
+    device_name
+
+Example:
+
+    Overland Controller
+
+Serial command:
+
+    devicename Overland Controller
+    save
+
+HTTP endpoint:
+
+    POST /config/device
+
+## Relay Configuration
+
+Relays use generic firmware IDs:
+
+    relay_1
+    relay_2
+
+Each relay has:
+
+- id
+- name
+- pin
+- enabled
+
+Example:
+
+    relay_1 = Aux Power
+    relay_2 = Fridge
+
+Serial commands:
+
+    relayname 1 Aux Power
+    relayname 2 Fridge
+    save
+
+HTTP endpoint:
+
+    POST /config/relay
+
+## Temperature Sensor Configuration
+
+Temperature sensors use generic firmware IDs:
+
+    temp_1
+    temp_2
+    temp_3
+    temp_4
+    temp_5
+    temp_6
+    temp_7
+    temp_8
+
+Each sensor has:
+
+- id
+- name
+- address
+- enabled
+
+Example:
+
+    temp_1 = Cabin
+    temp_2 = Outside Air
+
+Serial commands:
+
+    tempname 1 Cabin
+    tempname 2 Outside Air
+    save
+
+HTTP endpoint:
+
+    POST /config/temp
+
+## BMS Configuration
+
+BMS config contains:
+
+- enabled
+- name
+- address
+- address_type
+
+Example:
+
+    name = House Battery
+    address = aa:bb:cc:dd:ee:ff
+    address_type = public
+
+Serial commands:
+
+    bmsname House Battery
+    bmsaddr aa:bb:cc:dd:ee:ff
+    save
+
+HTTP endpoint:
+
+    POST /config/bms
+
+## BMS Setup Mode
+
+BMS setup mode allows BLE discovery and BMS selection.
+
+Serial flow:
+
+    enter setup
+    scan ble
+    scan ble
+    select bms 1
+    save
+
+Notes:
+
+- Some BMS modules advertise intermittently.
+- Multiple scans may be required.
+- Once configured, the controller reconnects directly by stored address.
+
+## Factory Reset
+
+Factory reset clears saved configuration and restores firmware defaults.
+
+Serial command:
+
+    factory reset
+
+HTTP endpoint:
+
+    POST /config/factory-reset
+
+After factory reset:
+
+- Device name returns to generic default
+- Relay names return to generic defaults
+- Temperature names return to generic defaults
+- BMS is unconfigured until selected or manually entered
+
+## Configuration Persistence
+
+Configuration is stored using ESP32 non-volatile storage.
+
+Configuration is loaded during boot.
+
+If no saved configuration exists, firmware defaults are loaded and saved.
+
+## Important Rule
+
+Installation-specific names belong only in saved configuration.
+
+Allowed in configuration:
+
+    Starlink
+    Fridge
+    House Battery
+    Outside Air
+
+Not allowed as firmware assumptions:
+
+    hardcoded relay names
+    hardcoded sensor names
+    hardcoded BMS names
+    hardcoded vehicle-specific names