firmware: scaffold optional cargo OLED display

docs/HARDWARE.md

@@ -113,3 +113,31 @@ Implementation:
 - Sender to ADS1115 over I2C if no suitable exposed ADC exists
 
 Use lookup-table interpolation.
+
+
+## Cargo OLED service display
+
+Planned optional hardware:
+
+- 0.96 inch SSD1306 OLED
+- 128x64 resolution
+- I2C interface
+- Typical address: 0x3C
+- Suggested initial pins:
+  - SDA: GPIO 21
+  - SCL: GPIO 22
+  - VCC: 3.3V
+  - GND: common ground
+
+Purpose:
+
+- Show first-boot AP setup credentials without requiring Serial Monitor.
+- Show AP SSID, password, and IP address during setup/recovery.
+- Show quick service status:
+  - battery SOC
+  - voltage/current
+  - relay states
+  - WiFi/IP
+  - active alarms
+
+Firmware support is optional and disabled by default with OLED_ENABLED set to 0. Enable only after the OLED libraries are installed and the display is wired.

docs/roadmap.md

@@ -103,3 +103,28 @@ UI direction:
 - Add QR code display for joining Cargo AP.
 - Add dashboard settings UI.
 - Add LVGL on-screen keyboard only after core dashboard functionality is stable.
+
+
+## Cargo OLED firmware foundation
+
+Status: planned / scaffolded
+
+Initial OLED firmware goals:
+
+- Add optional SSD1306 128x64 support behind a compile-time flag.
+- Keep OLED support disabled by default so the controller firmware builds without extra libraries.
+- Display boot/setup status.
+- Display AP SSID/password/IP for phone-first setup.
+- Display rotating service pages:
+  - battery
+  - relays
+  - network
+  - alarms
+
+Future OLED goals:
+
+- Add setup/status button.
+- Short press cycles pages.
+- Long press shows AP credentials.
+- Extended hold enters recovery/reset mode.
+- Add first-boot setup screen once AP password generation is finalized.