Fix I2C/OLED heap wedge: lazy Wi-Fi bring-up, drop coex preinit/park

wifi_coex_preinit() inited the full Wi-Fi driver at boot and kept it
parked, draining the classic-ESP32 heap so I2C_INIT's Wire-buffer alloc
plus the IDF i2c_driver_install wedged rx_task — the board hangs until a
power cycle (the "everything broke after v0.3.0" OLED-over-BLE failure).

Adopt the Esp-WiFi-BLE-Now model: don't pre-init, bring radios up lazily,
leave IDF defaults alone.

- Remove wifi_coex_preinit / wifi_ensure_started / wifi_parked /
  coex_pinned and the BRIDGE_WIFI_COEX flag. Wi-Fi comes up lazily via
  WiFi.mode(WIFI_STA) on the first Wi-Fi/ESP-NOW command, so a BLE-only
  board keeps full heap and I2C/OLED gets the full 2 KB Wire buffer.
- Simplify mod_i2c init to a short heap-guarded buffer fallback; drop the
  esp_heap_caps math and the rx_task wedge watchdog (band-aids for the
  self-inflicted heap shortage).
- Update firmware README + PROTOCOL coexistence notes; trim stale comments.

Net -152/+41 lines. Host tests: 202 passed.

Author: HamzaYslmn

docs/PROTOCOL.md

@@ -289,11 +289,11 @@ Hosts must treat the tail as optional for compatibility with older firmware.
   `SYS_LOG` warning event.
 - **SYS_RESET** replies OK first, then restarts; the host must expect a new
   `SYS_READY`.
-- **Radio coexistence** (classic ESP32): the Wi-Fi stack must initialize
-  before Bluedroid, so the firmware brings the Wi-Fi driver up at boot when
-  the BLE link is enabled (`BRIDGE_WIFI_COEX` in firmware.ino, default on;
-  costs ~50 KB heap). Power save stays at the IDF default `WIFI_PS_MIN_MODEM`
-  — never `WIFI_PS_NONE` while BT is active.
+- **Radio coexistence** (classic ESP32): the BLE link runs from boot; the
+  Wi-Fi driver comes up lazily on the first Wi-Fi/ESP-NOW command, so a
+  BLE-only board never pays its heap. The SW coex arbiter shares the radio
+  with BLE; power save stays at the IDF default `WIFI_PS_MIN_MODEM` — never
+  `WIFI_PS_NONE` while BT is active.
 - **Wi-Fi scan vs ESP-NOW**: a scan hops channels, so ESP-NOW packets are
   dropped while one is running.
 - **IDF logs become `SYS_LOG` events**: the Wi-Fi/BT stacks log through

firmware/README.md

@@ -19,13 +19,14 @@ USB serial **or Bluetooth**.
 #define BRIDGE_ENABLE_CAM 0          // opt-in: camera (esp32/s2/s3 + PSRAM)
 #define BRIDGE_PASSWORD "espbridge"  // Bluetooth password ("" = open access)
 #define BRIDGE_BLE_LINK 1            // 0 = USB only
-#define BRIDGE_WIFI_COEX 1           // classic ESP32: Wi-Fi up before BLE (coex)
 ```
 
 Change the password here and reflash. USB never asks for a password.
-`BRIDGE_WIFI_COEX` pre-starts the Wi-Fi driver before Bluedroid so Wi-Fi /
-ESP-NOW / BLE can all run together (required init order on classic ESP32);
-set it to 0 to reclaim ~50 KB heap on boards that never use the radio.
+Wi-Fi / ESP-NOW / BLE all coexist: the BLE link is up at boot, and the Wi-Fi
+driver comes up lazily on the host's first Wi-Fi/ESP-NOW command — so a
+BLE-only board never pays the Wi-Fi driver's ~30–50 KB heap (which is what
+used to starve I2C/SPI). The SW coex arbiter shares the radio; IDF defaults
+are left untouched (never `WIFI_PS_NONE` with BT).
 Ethernet and camera stay compile-time opt-ins because they cost real flash;
 board pin maps live on the Python side (`espbridge.eth` / `espbridge.camera`
 presets), so one firmware build serves every board.

firmware/firmware.ino

@@ -32,15 +32,6 @@
 // Set to 0 to turn the Bluetooth link off entirely (USB only).
 #define BRIDGE_BLE_LINK 1
 
-// Classic-ESP32 coexistence: bring the Wi-Fi stack up BEFORE Bluedroid so the
-// coex arbiter sees the radios in the right order (Wi-Fi -> ESP-NOW -> BLE),
-// then park the radio until the host first uses Wi-Fi/ESP-NOW. A parked
-// radio gives Bluetooth uncontested airtime and ~25 KB extra heap, so an
-// idle board's BLE link is as solid as a no-Wi-Fi build. Set 0 if this
-// board never uses Wi-Fi/ESP-NOW (saves the remaining driver heap too).
-// Ignored on chips other than the classic ESP32 (they have no ordering rule).
-#define BRIDGE_WIFI_COEX 1
-
 void setup() {
   // Route IDF Wi-Fi/BT logs into SYS_LOG events; raw log bytes on UART0 would
   // corrupt protocol frames. Must precede any radio bring-up.
@@ -60,12 +51,11 @@ void setup() {
   wifi_init();
   proto_start();   // spawn bridge_tx / bridge_rx / bridge_net tasks
 
-#if BRIDGE_WIFI_COEX && BRIDGE_BLE && defined(CONFIG_IDF_TARGET_ESP32)
-  // Wi-Fi driver up before BLEDevice::init() inside link_ble_init(). Power
-  // save stays at the default WIFI_PS_MIN_MODEM — never WIFI_PS_NONE with BT.
-  wifi_coex_preinit();
-#endif
-
+  // Wi-Fi/ESP-NOW stay off until the host's first radio command, then come up
+  // lazily (WiFi.mode in the wifi/espnow handlers). A BLE-only board never
+  // pays the Wi-Fi driver's heap — which is what kept I2C/SPI from wedging.
+  // The SW coex arbiter shares the radio with BLE; leave its defaults alone
+  // (never WIFI_PS_NONE with BT). See mod_wifi.cpp / mod_espnow.cpp.
 #if BRIDGE_BLE_LINK
   // Bluetooth link: same protocol, no USB cable. Clients authenticate with
   // SYS_AUTH (BRIDGE_PASSWORD above) before any other command is accepted.

firmware/src/espbridge/commands.h

@@ -243,7 +243,7 @@ enum ChipModel : uint8_t {
 #define NET_UDP_EVT     CMD(MOD_NET, 0x83)  // handle u8|ip[4]|port u16|data..
 
 // ESP-NOW (connectionless 2.4 GHz messaging; coexists with Wi-Fi STA/AP + BLE).
-// Init order on classic ESP32: Wi-Fi -> ESP-NOW -> BLE (see BRIDGE_WIFI_COEX).
+// ESPNOW_INIT brings the Wi-Fi driver up lazily (STA) if it's still off.
 // Channel rule: when Wi-Fi STA is connected ESP-NOW inherits its channel and
 // the requested channel is ignored (changing it would drop the AP).
 #define ESPNOW_INIT     CMD(MOD_ESPNOW, 0x01) // channel u8 (0=auto/inherit)|flags u8 (bit0=long range) -> mac[6]

firmware/src/espbridge/modules.h

@@ -30,13 +30,6 @@ void mcpwm_handle(uint8_t op, uint8_t seq, const uint8_t* p, uint16_t len);
 void gpio_init();
 void wifi_init();
 
-// Classic-ESP32 coexistence: bring the Wi-Fi driver up before Bluedroid,
-// then park the radio (called from setup() ahead of link_ble_init when
-// BRIDGE_WIFI_COEX is set). wifi_ensure_started() resumes the parked radio
-// on first Wi-Fi/ESP-NOW use; no-op everywhere else.
-void wifi_coex_preinit();
-void wifi_ensure_started();
-
 // Pollers: gpio/uart run on rx_task, wifi/net on net_task; must not block.
 void gpio_poll();
 void uart_poll();

firmware/src/espbridge/protocol.cpp

@@ -223,36 +223,8 @@ struct RxState {
 static RxState rxstate[2];  // [LINK_USB], [LINK_BLE]
 static uint8_t rxframe[MAX_FRAME];
 
-// Wedge watchdog: some IDF calls can block rx_task forever with no panic
-// and no error (seen: i2c driver install at exhausted heap). tx_task stays
-// alive, so a watcher can still tell the host WHERE the firmware is stuck
-// instead of leaving it guessing at timeouts.
-static volatile uint16_t cur_cmd = 0xFFFF;  // command rx_task is inside, if any
-static volatile uint32_t disp_n = 0;
-
-static void watch_task(void*) {
-  uint32_t last_n = 0;
-  uint8_t stuck = 0;
-  for (;;) {
-    vTaskDelay(pdMS_TO_TICKS(1000));
-    uint16_t c = cur_cmd;
-    if (c != 0xFFFF && disp_n == last_n) {
-      if (++stuck >= 2 && (stuck & 1) == 0) {  // after 2 s, then every 2 s
-        char msg[56];
-        snprintf(msg, sizeof(msg), "rx_task stuck in cmd 0x%04X for %u s", c, stuck);
-        proto_log(2, msg);
-      }
-    } else {
-      stuck = 0;
-    }
-    last_n = disp_n;
-  }
-}
-
 static void dispatch(uint8_t seq, uint16_t cmd, const uint8_t* p, uint16_t len) {
   uint8_t mod = cmd >> 8, op = cmd & 0xFF;
-  cur_cmd = cmd;
-  disp_n++;
   switch (mod) {
     // Fast handlers: run inline on rx_task.
     case MOD_SYS:   sys_handle(op, seq, p, len); break;
@@ -281,7 +253,6 @@ static void dispatch(uint8_t seq, uint16_t cmd, const uint8_t* p, uint16_t len)
     case MOD_CAM:   net_enqueue(cmd, seq, p, len); break;
     default:        proto_reply_err(seq, cmd, ST_UNKNOWN_CMD); break;
   }
-  cur_cmd = 0xFFFF;
 }
 
 // Constant-time-ish password compare (no early exit on mismatch).
@@ -395,6 +366,4 @@ void proto_start() {
   xTaskCreatePinnedToCore(tx_task, "bridge_tx", 4096, nullptr, 12, nullptr, BRIDGE_CORE);
   xTaskCreatePinnedToCore(rx_task, "bridge_rx", 8192, nullptr, 10, nullptr, BRIDGE_CORE);
   xTaskCreatePinnedToCore(net_task, "bridge_net", 8192, nullptr, 9, nullptr, BRIDGE_CORE);
-  // Above rx_task so a wedged handler can't starve it; sleeps 1 s between looks.
-  xTaskCreatePinnedToCore(watch_task, "bridge_watch", 2048, nullptr, 11, nullptr, BRIDGE_CORE);
 }

firmware/src/link_ble.cpp

@@ -21,10 +21,9 @@
 // Classic ESP32 ships a dual-mode (Classic BT + BLE) controller and the
 // Arduino sdkconfig keeps it that way, but this firmware is BLE-only.
 // Hand the Classic-BT memory back to the heap BEFORE any BT init and start
-// the controller in BLE-only mode: with the Wi-Fi driver already up for
-// coexistence (BRIDGE_WIFI_COEX) there otherwise isn't enough heap for
-// Bluedroid, and its failed init crashes on core 0 (BTE_InitStack error
-// path -> OBEX_Deinit dereferences a never-allocated control block).
+// the controller in BLE-only mode — frees heap and avoids a dual-mode
+// Bluedroid init that can crash on core 0 (BTE_InitStack -> OBEX_Deinit
+// dereferences a never-allocated control block).
 // One-way until reboot; nothing in this firmware uses Classic BT.
 void bt_prepare_ble_only() {
 #if defined(CONFIG_IDF_TARGET_ESP32)
@@ -126,8 +125,7 @@ void link_ble_init(const char* password) {
   bt_prepare_ble_only();
   proto_log_heap("ble: controller up");
   if (ESP.getFreeHeap() < BLE_MIN_FREE_HEAP) {
-    proto_log(2, "ble: link disabled, not enough free heap "
-                 "(set BRIDGE_WIFI_COEX 0 if Wi-Fi/ESP-NOW is unused)");
+    proto_log(2, "ble: link disabled, not enough free heap at boot");
     return;
   }
   link_password = password ? password : "";

firmware/src/mod_espnow.cpp

@@ -155,7 +155,6 @@ static void handle_send(uint8_t seq, uint16_t cmd, const uint8_t* p, uint16_t le
 void espnow_handle(uint8_t op, uint8_t seq, const uint8_t* p, uint16_t len) {
   uint16_t cmd = CMD(MOD_ESPNOW, op);
   if (!inited && op != 0x01) { proto_reply_err(seq, cmd, ST_NOT_INIT); return; }
-  wifi_ensure_started();  // coex: the radio is parked until first radio use
   switch (op) {
     case 0x01:  // INIT
       handle_init(seq, cmd, p, len);

firmware/src/mod_i2c.cpp

@@ -2,7 +2,6 @@
 #include "espbridge/protocol.h"
 #include "espbridge/modules.h"
 #include <Wire.h>
-#include <esp_heap_caps.h>
 
 static bool i2c_inited[2];
 
@@ -27,39 +26,16 @@ void i2c_handle(uint8_t op, uint8_t seq, const uint8_t* p, uint16_t len) {
     case 0x01: {  // INIT: bus, sda, scl, freq u32 -> wire_buf u16
       if (len < 7) { proto_reply_err(seq, cmd, ST_BAD_ARGS); return; }
       if (i2c_inited[bus]) w->end();
-      // Wire's default TX buffer is 128 bytes and write() silently drops
-      // anything beyond it; size it to fit any I2C_WRITE payload. begin()
-      // allocates 2x this from the heap — which a classic ESP32 with the
-      // BLE link connected runs within a few KB of — so fall back to
-      // smaller buffers instead of failing, and report the size that stuck
-      // (hosts chunk their writes to it).
-      //
-      // The fallback must be heap-aware, not try-and-see (all measured on
-      // classic ESP32 + BLE link, core 3.3.6):
-      //  - the IDF i2c driver install after the buffer allocation eats
-      //    ~2 KB and WEDGES rx_task silently below ~7 KB free (no panic,
-      //    no error return — the board just stops answering);
-      //  - the radio stacks need ~6.5 KB free *for the rest of the
-      //    session*, or Bluedroid starts dropping replies under load
-      //    (6.7 KB rest = solid; 5.9 KB rest = host-visible timeouts).
-      // So a buffer above the 128-byte floor must leave 2*size + ~9 KB,
-      // plus a contiguous chunk to spare.
-      static const uint16_t sizes[] = {MAX_PAYLOAD, 1024, 512, 256, 128};
+      // Wire's default 128-byte TX buffer silently truncates longer writes, so
+      // grow it; begin() allocates 2x from the heap, so fall back to a smaller
+      // buffer when heap is tight (full Wi-Fi+BLE coexistence) and report the
+      // size that stuck — the host chunks its writes to it.
       uint16_t got = 0;
-      for (uint8_t i = 0; i < 5 && !got; i++) {
-        if (sizes[i] > 128) {
-          if (ESP.getFreeHeap() < 2u * sizes[i] + 9216) continue;
-          if (heap_caps_get_largest_free_block(MALLOC_CAP_8BIT)
-              < (size_t)sizes[i] + 2048) continue;
-        }
-        if (w->setBufferSize(sizes[i]) && w->begin(p[1], p[2], rd32(p + 3)))
-          got = sizes[i];
-      }
-      if (!got) {
-        proto_log_heap("i2c: init failed");  // ST_IO alone is opaque
-        proto_reply_err(seq, cmd, ST_IO);
-        return;
+      for (uint16_t sz : {MAX_PAYLOAD, 512, 128}) {
+        if (sz > 128 && ESP.getFreeHeap() < 2u * sz + 8192) continue;
+        if (w->setBufferSize(sz) && w->begin(p[1], p[2], rd32(p + 3))) { got = sz; break; }
       }
+      if (!got) { proto_reply_err(seq, cmd, ST_NO_MEM); return; }
       i2c_inited[bus] = true;
       uint8_t out[2] = {(uint8_t)(got >> 8), (uint8_t)got};
       proto_reply(seq, cmd, out, 2);

firmware/src/mod_wifi.cpp

@@ -4,49 +4,15 @@
 #include "espbridge/protocol.h"
 #include "espbridge/modules.h"
 #include <WiFi.h>
-#include <esp_wifi.h>
 
 static bool scanning = false;
 static bool ap_active = false;
 static bool sta_started = false;
-static bool coex_pinned = false;  // Wi-Fi pre-inited for BLE coex: never drop to MODE_NULL
-static bool wifi_parked = false;  // driver inited but radio stopped (coex idle)
 
-bool wifi_is_active() {
-  // Parked = driver up, RF off: no ADC2 conflict, no coex airtime claimed.
-  return WiFi.getMode() != WIFI_MODE_NULL && !wifi_parked;
-}
-
-// Classic-ESP32 coexistence: the Wi-Fi driver must come up BEFORE Bluedroid
-// (heap ordering — Bluedroid's init crashes if the Wi-Fi driver grabs its
-// buffers afterwards). Called from setup() ahead of link_ble_init() when
-// BRIDGE_WIFI_COEX is set. Power save stays at the Arduino default
-// WIFI_PS_MIN_MODEM — customizing it (especially WIFI_PS_NONE) destabilizes
-// BLE coexistence per the IDF guide.
-//
-// Lesson from Esp-WiFi-BLE-Now: only bring the radio up when it is actually
-// used. An idle-but-started STA makes the coex arbiter timeslice the
-// 2.4 GHz radio against BLE forever (an unassociated STA never modem-
-// sleeps) and holds ~25 KB of RX buffers — both destabilize the BLE link.
-// So: init the driver in order, then PARK the radio until the host first
-// asks for Wi-Fi/ESP-NOW (wifi_ensure_started below).
-void wifi_coex_preinit() {
-  WiFi.mode(WIFI_STA);
-  esp_wifi_stop();
-  wifi_parked = true;
-  coex_pinned = true;
-  proto_log_heap("coex: wifi inited, radio parked");
-}
-
-// Resume the parked radio before any Wi-Fi/ESP-NOW use. Arduino's layer
-// still believes Wi-Fi is started (we stopped underneath it), so this is
-// the matching low-level start; a no-op everywhere else.
-void wifi_ensure_started() {
-  if (!wifi_parked) return;
-  wifi_parked = false;
-  esp_wifi_start();
-  proto_log_heap("coex: wifi radio resumed");
-}
+// Wi-Fi is off until the first command here brings it up (WiFi.mode below);
+// a BLE-only board never pays the driver's heap. Leave coex/power-save at
+// IDF defaults (never WIFI_PS_NONE with BT) — the SW arbiter handles slotting.
+bool wifi_is_active() { return WiFi.getMode() != WIFI_MODE_NULL; }
 
 static void on_wifi_event(WiFiEvent_t event, WiFiEventInfo_t info) {
   uint8_t buf[5] = {0};
@@ -117,7 +83,6 @@ static bool take_str(const uint8_t*& p, uint16_t& left, char* out, uint8_t cap)
 
 void wifi_handle(uint8_t op, uint8_t seq, const uint8_t* p, uint16_t len) {
   uint16_t cmd = CMD(MOD_WIFI, op);
-  wifi_ensure_started();  // coex: the radio is parked until first Wi-Fi use
   switch (op) {
     case 0x01: {  // SCAN (async)
       // Quirk: a scan hops channels, so ESP-NOW packets are dropped while it
@@ -150,9 +115,8 @@ void wifi_handle(uint8_t op, uint8_t seq, const uint8_t* p, uint16_t len) {
     case 0x03:  // DISCONNECT
       WiFi.disconnect(true /*wifioff if no AP*/, false);
       sta_started = false;
-      // Keep the radio in STA mode while ESP-NOW rides on it or the driver is
-      // coex-pinned (turning it off would break espnow / the BLE coex order).
-      if (!ap_active && !espnow_is_active() && !coex_pinned) WiFi.mode(WIFI_MODE_NULL);
+      // Drop the radio (frees its heap) unless an AP or ESP-NOW still needs it.
+      if (!ap_active && !espnow_is_active()) WiFi.mode(WIFI_MODE_NULL);
       proto_reply_ok(seq, cmd);
       break;
 
@@ -196,7 +160,7 @@ void wifi_handle(uint8_t op, uint8_t seq, const uint8_t* p, uint16_t len) {
     case 0x06:  // AP_STOP
       WiFi.softAPdisconnect(true);
       ap_active = false;
-      if (!sta_started && !espnow_is_active() && !coex_pinned) WiFi.mode(WIFI_MODE_NULL);
+      if (!sta_started && !espnow_is_active()) WiFi.mode(WIFI_MODE_NULL);
       proto_reply_ok(seq, cmd);
       break;