hardware: retire dashboard uart and assign oled pins

docs/ARCHITECTURE.md

@@ -193,3 +193,20 @@ Recovery target:
 
 - A setup/status button on the Cargo ESP enclosure can show AP credentials on the OLED.
 - A long hold can restore factory AP credentials or enter recovery mode.
+
+
+## Current communications and GPIO decision
+
+Active dashboard communication is WiFi/HTTP using `/api/v1`.
+
+The old Pico/dashboard UART path is retired from active hardware use. USB Serial remains available for development, debug, and manual configuration from a computer.
+
+Current Cargo ESP32 GPIO plan:
+
+- GPIO 16: Relay 1 trigger output
+- GPIO 17: Relay 2 trigger output
+- GPIO 4: DS18B20 OneWire temperature bus
+- GPIO 34: Ignition sense input
+- GPIO 21: SSD1306 OLED I2C SDA
+- GPIO 22: SSD1306 OLED I2C SCL
+- GPIO 25: OLED setup/status button

docs/CHATGPT_HANDOFF.md

@@ -129,3 +129,20 @@ Update this document when any of these change:
 - Hardware assumptions, wiring, power, relay, CAN, or dashboard target.
 - Validation commands, dependencies, or current test status.
 - Important decisions that a future assistant should not rediscover from scratch.
+
+
+## Current communications and GPIO decision
+
+Active dashboard communication is WiFi/HTTP using `/api/v1`.
+
+The old Pico/dashboard UART path is retired from active hardware use. USB Serial remains available for development, debug, and manual configuration from a computer.
+
+Current Cargo ESP32 GPIO plan:
+
+- GPIO 16: Relay 1 trigger output
+- GPIO 17: Relay 2 trigger output
+- GPIO 4: DS18B20 OneWire temperature bus
+- GPIO 34: Ignition sense input
+- GPIO 21: SSD1306 OLED I2C SDA
+- GPIO 22: SSD1306 OLED I2C SCL
+- GPIO 25: OLED setup/status button

docs/HARDWARE.md

@@ -141,3 +141,20 @@ Purpose:
   - 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.
+
+
+## Current communications and GPIO decision
+
+Active dashboard communication is WiFi/HTTP using `/api/v1`.
+
+The old Pico/dashboard UART path is retired from active hardware use. USB Serial remains available for development, debug, and manual configuration from a computer.
+
+Current Cargo ESP32 GPIO plan:
+
+- GPIO 16: Relay 1 trigger output
+- GPIO 17: Relay 2 trigger output
+- GPIO 4: DS18B20 OneWire temperature bus
+- GPIO 34: Ignition sense input
+- GPIO 21: SSD1306 OLED I2C SDA
+- GPIO 22: SSD1306 OLED I2C SCL
+- GPIO 25: OLED setup/status button

docs/UART_PROTOCOL.md

@@ -274,3 +274,20 @@ Alternative:
 `status_response.config.temperature_sensors[]` and `status_response.temps[]` include `weather: false`.
 
 `config_temp` may include `weather: true` to mark one configured sensor as the outside/weather sensor. Clients should treat this as optional and default missing values to `false`.
+
+
+## Current communications and GPIO decision
+
+Active dashboard communication is WiFi/HTTP using `/api/v1`.
+
+The old Pico/dashboard UART path is retired from active hardware use. USB Serial remains available for development, debug, and manual configuration from a computer.
+
+Current Cargo ESP32 GPIO plan:
+
+- GPIO 16: Relay 1 trigger output
+- GPIO 17: Relay 2 trigger output
+- GPIO 4: DS18B20 OneWire temperature bus
+- GPIO 34: Ignition sense input
+- GPIO 21: SSD1306 OLED I2C SDA
+- GPIO 22: SSD1306 OLED I2C SCL
+- GPIO 25: OLED setup/status button

docs/dashboard-esp32s3.md

@@ -154,3 +154,20 @@ Later:
 ## Out of Scope
 
 No Pico dashboard is planned. Existing Pico/UART material is legacy unless explicitly revived for diagnostics or alternate hardware.
+
+
+## Current communications and GPIO decision
+
+Active dashboard communication is WiFi/HTTP using `/api/v1`.
+
+The old Pico/dashboard UART path is retired from active hardware use. USB Serial remains available for development, debug, and manual configuration from a computer.
+
+Current Cargo ESP32 GPIO plan:
+
+- GPIO 16: Relay 1 trigger output
+- GPIO 17: Relay 2 trigger output
+- GPIO 4: DS18B20 OneWire temperature bus
+- GPIO 34: Ignition sense input
+- GPIO 21: SSD1306 OLED I2C SDA
+- GPIO 22: SSD1306 OLED I2C SCL
+- GPIO 25: OLED setup/status button

docs/project-state.md

@@ -185,3 +185,20 @@ Dashboard Client:
 There is no planned Pico dashboard path. Existing Pico/UART files are legacy artifacts unless explicitly revived later.
 
 UART JSON remains optional for diagnostics or alternate clients. New dashboard work should target the Waveshare ESP32-S3 display and the HTTP API.
+
+
+## Current communications and GPIO decision
+
+Active dashboard communication is WiFi/HTTP using `/api/v1`.
+
+The old Pico/dashboard UART path is retired from active hardware use. USB Serial remains available for development, debug, and manual configuration from a computer.
+
+Current Cargo ESP32 GPIO plan:
+
+- GPIO 16: Relay 1 trigger output
+- GPIO 17: Relay 2 trigger output
+- GPIO 4: DS18B20 OneWire temperature bus
+- GPIO 34: Ignition sense input
+- GPIO 21: SSD1306 OLED I2C SDA
+- GPIO 22: SSD1306 OLED I2C SCL
+- GPIO 25: OLED setup/status button

docs/roadmap.md

@@ -128,3 +128,20 @@ Future OLED goals:
 - Long press shows AP credentials.
 - Extended hold enters recovery/reset mode.
 - Add first-boot setup screen once AP password generation is finalized.
+
+
+## Current communications and GPIO decision
+
+Active dashboard communication is WiFi/HTTP using `/api/v1`.
+
+The old Pico/dashboard UART path is retired from active hardware use. USB Serial remains available for development, debug, and manual configuration from a computer.
+
+Current Cargo ESP32 GPIO plan:
+
+- GPIO 16: Relay 1 trigger output
+- GPIO 17: Relay 2 trigger output
+- GPIO 4: DS18B20 OneWire temperature bus
+- GPIO 34: Ignition sense input
+- GPIO 21: SSD1306 OLED I2C SDA
+- GPIO 22: SSD1306 OLED I2C SCL
+- GPIO 25: OLED setup/status button

firmware/esp32/overland-controller/config.h

@@ -12,9 +12,14 @@
 // Ignition Sense
 #define IGNITION_PIN 34
 
-// UART over CAT5 to Pico dashboard
+// Cargo OLED service/setup display
-#define DASHBOARD_UART_TX_PIN 21
+#define OLED_I2C_SDA_PIN 21
-#define DASHBOARD_UART_RX_PIN 22
+#define OLED_I2C_SCL_PIN 22
+#define OLED_SETUP_BUTTON_PIN 25
+
+// Dashboard communication is WiFi/HTTP.
+// Legacy UART dashboard support is retired from active hardware use.
+#define DASHBOARD_UART_ENABLED 0
 #define DASHBOARD_UART_BAUD   115200
 
 // RS-485/MAX3485 is fallback only and not currently planned.

firmware/esp32/overland-controller/overland-controller.ino

@@ -946,9 +946,10 @@ setInterval(load,3000);
 WebServer server(80);
 
 #define API_V1(path) "/api/v1" path
+#if DASHBOARD_UART_ENABLED
 HardwareSerial DashboardSerial(2);
-
 String uartLineBuffer;
+#endif
 
 Preferences wifiPrefs;
 Preferences apPrefs;
@@ -1180,11 +1181,11 @@ const int OLED_RESET_PIN = -1;
 const uint8_t OLED_I2C_ADDR = 0x3C;
 
 // Default ESP32 I2C pins. Change these if the cargo controller wiring uses a different I2C bus.
-const int OLED_I2C_SDA = 21;
+const int OLED_I2C_SDA = OLED_I2C_SDA_PIN;
-const int OLED_I2C_SCL = 22;
+const int OLED_I2C_SCL = OLED_I2C_SCL_PIN;
 
 // Optional future setup/status button. Leave disabled until hardware is wired.
-const int OLED_BUTTON_PIN = -1;
+const int OLED_BUTTON_PIN = OLED_SETUP_BUTTON_PIN;
 
 Adafruit_SSD1306 oled(OLED_SCREEN_WIDTH, OLED_SCREEN_HEIGHT, &Wire, OLED_RESET_PIN);
 
@@ -2013,6 +2014,7 @@ void sendBleScanResponse(Stream& output) {
     output.println();
 }
 
+#if DASHBOARD_UART_ENABLED
 int findRelayConfigIndexForUart(const String& id) {
     for (int i = 0; i < MAX_RELAYS; i++) {
         if (appConfig.relays[i].id == id) {
@@ -2421,6 +2423,8 @@ void pollDashboardUart() {
     }
 }
 
+#endif
+
 void handleDebugSerial() {
     if (!Serial.available()) return;
 
@@ -3361,12 +3365,15 @@ void handleStatus() {
 void setup() {
     Serial.begin(115200);
 
+#if DASHBOARD_UART_ENABLED
     DashboardSerial.begin(
         DASHBOARD_UART_BAUD,
         SERIAL_8N1,
-        DASHBOARD_UART_RX_PIN,
+        0,
-        DASHBOARD_UART_TX_PIN
+        0
     );
+    Serial.println("Legacy dashboard UART enabled");
+#endif
 
     Serial.println();
     Serial.println("==================================");
@@ -3462,7 +3469,6 @@ void setup() {
     server.begin();
 
     Serial.println("Web Server Started");
-    Serial.println("Dashboard UART Started");
 }
 
 void loop() {
@@ -3471,7 +3477,9 @@ void loop() {
     handleDebugSerial();
     updateBms();
     updateAlarms();
+#if DASHBOARD_UART_ENABLED
     pollDashboardUart();
+#endif
     oledLoop();
 
     static unsigned long lastSensorUpdate = 0;

tests/test_http_api_contract.py

@@ -425,3 +425,26 @@ def test_cargo_oled_shows_setup_and_service_pages():
     assert 'oledClear("Alarms")' in source
     assert "oledShowSetupPage();" in source
     assert "oledLoop();" in source
+
+
+def test_gpio_pin_plan_assigns_oled_to_21_22():
+    config = (ROOT / "firmware" / "esp32" / "overland-controller" / "config.h").read_text()
+    source = firmware_source()
+
+    assert "#define OLED_I2C_SDA_PIN 21" in config
+    assert "#define OLED_I2C_SCL_PIN 22" in config
+    assert "#define OLED_SETUP_BUTTON_PIN 25" in config
+    assert "const int OLED_I2C_SDA = OLED_I2C_SDA_PIN;" in source
+    assert "const int OLED_I2C_SCL = OLED_I2C_SCL_PIN;" in source
+    assert "const int OLED_BUTTON_PIN = OLED_SETUP_BUTTON_PIN;" in source
+
+
+def test_legacy_dashboard_uart_is_disabled_by_default():
+    config = (ROOT / "firmware" / "esp32" / "overland-controller" / "config.h").read_text()
+    source = firmware_source()
+
+    assert "#define DASHBOARD_UART_ENABLED 0" in config
+    assert "DASHBOARD_UART_TX_PIN 21" not in config
+    assert "DASHBOARD_UART_RX_PIN 22" not in config
+    assert "#if DASHBOARD_UART_ENABLED" in source
+    assert "pollDashboardUart();" in source