@alteriom/painlessmesh 1.9.8 → 1.9.10

package/BRIDGE_TO_INTERNET.md

@@ -4,7 +4,20 @@ You can bridge your mesh network to the Internet by creating a **gateway node**
 
 ## Quick Start (Recommended: Auto Channel Detection)
 
-The **new bridge-centric approach** automatically detects your router's channel and configures the mesh accordingly. No manual channel configuration required!
+The **bridge-centric approach** automatically detects your router's channel and configures the mesh accordingly. No manual channel configuration required!
+
+### Resilient Initialization (v1.9.7+)
+
+**Power-up order no longer matters!** The bridge will initialize successfully even if:
+- Router is not yet powered on
+- Internet connection is unavailable
+- Router is temporarily offline
+
+The bridge will:
+- Establish the mesh network immediately
+- Accept connections from mesh nodes right away
+- Retry router connection automatically in the background
+- Update status when router/Internet becomes available
 
 ```cpp
 #include "painlessMesh.h"
@@ -25,10 +38,10 @@ void setup() {
   mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
   
   // Single call does everything:
-  // 1. Connects to router and detects its channel
-  // 2. Initializes mesh on detected channel
+  // 1. Attempts to connect to router and detect its channel
+  // 2. Initializes mesh on detected channel (or default if router unavailable)
   // 3. Sets node as root/bridge
-  // 4. Maintains router connection
+  // 4. Maintains/retries router connection automatically
   mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
                     ROUTER_SSID, ROUTER_PASSWORD,
                     &userScheduler, MESH_PORT);
@@ -46,10 +59,10 @@ void receivedCallback(uint32_t from, String& msg) {
 }
 ```
 
-**Expected Output:**
+**Expected Output (Router Available):**
 ```
 === Bridge Mode Initialization ===
-Step 1: Connecting to router YourRouterSSID...
+Step 1: Attempting to connect to router YourRouterSSID...
 ✓ Router connected on channel 6
 ✓ Router IP: 192.168.1.100
 Step 2: Initializing mesh on channel 6...
@@ -58,10 +71,35 @@ Step 3: Establishing bridge connection...
 === Bridge Mode Active ===
   Mesh SSID: MyMeshNetwork
   Mesh Channel: 6 (matches router)
-  Router: YourRouterSSID
+  Router: YourRouterSSID (connected)
+  Port: 5555
+```
+
+**Expected Output (Router Unavailable but Visible):**
+```
+=== Bridge Mode Initialization ===
+Step 1: Attempting to connect to router YourRouterSSID...
+⚠ Router connection unavailable during initialization
+⚠ Scanning for router 'YourRouterSSID' to detect channel...
+✓ Router found on channel 6 (not connected, will retry)
+⚠ Proceeding with bridge setup on channel 6
+⚠ Bridge will retry router connection in background
+Step 2: Initializing mesh on channel 6...
+STARTUP: init(): Mesh channel set to 6
+Step 3: Establishing bridge connection...
+=== Bridge Mode Active ===
+  Mesh SSID: MyMeshNetwork
+  Mesh Channel: 6 (default, router pending)
+  Router: YourRouterSSID (will retry)
   Port: 5555
+
+INFO: Bridge initialized without router connection
+INFO: Mesh network is active and accepting node connections
+INFO: Router connection will be established automatically when available
 ```
 
+**Note:** If the router cannot connect but is visible in a WiFi scan, the bridge detects its channel and uses it for the mesh. This minimizes channel switching when the router becomes connectable. If the router is completely invisible (powered off), channel 1 is used as default.
+
 ### Regular Nodes with Auto-Detection
 
 Regular mesh nodes can also auto-detect the mesh channel:

package/CHANGELOG.md

@@ -19,6 +19,66 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - TBD
 
+## [1.9.10] - 2025-12-15
+
+### Fixed
+
+- **TCP Connection Retry Immediate Execution** - Fixed mesh connection failures where TCP retries executed immediately instead of with exponential backoff delays
+  - **Root Cause**: `PackageHandler::addTask()` was calling `task->enable()` instead of `task->enableDelayed()` for one-shot delayed tasks, causing immediate execution
+  - **Symptom**: Nodes unable to establish mesh connection - TCP error -14 (ERR_CONN) with all retry attempts happening immediately rather than with 1s, 2s, 4s, 8s, 8s delays
+  - **Solution**: Modified `PackageHandler::addTask()` to use `enableDelayed()` for `TASK_ONCE` tasks with intervals > 0
+    - Retry tasks now properly wait for their scheduled delays before executing
+    - Exponential backoff mechanism now works as designed (total ~23s before WiFi reconnection)
+    - Reduces network congestion from multiple simultaneously retrying nodes
+  - **Impact**: Enables successful mesh connection establishment with proper retry timing
+  - **Files Modified**: 
+    - `src/painlessmesh/plugin.hpp` (lines 231, 239, 245-251)
+    - `docs/troubleshooting/common-issues.md` (lines 206-212)
+    - `test/catch/catch_delayed_task_execution.cpp` (new test file)
+    - `ISSUE_TCP_RETRY_FIX.md` (new documentation)
+
+- **Hard Reset on Bridge Failover Election Winner** - Fixed ESP32 hard reset (Guru Meditation Error: Load access fault) when node becomes bridge after election
+  - **Root Cause**: The `bridgeRoleChangedCallback` signature used pass-by-value for the String parameter (`TSTRING reason`), causing temporary String object creation from const char* literals. On memory-constrained ESP32/ESP8266, this could trigger heap allocation failures and memory access faults
+  - **Symptom**: Device crashes with "Guru Meditation Error: Core 0 panic'ed (Load access fault)" immediately after logging "🎯 PROMOTED TO BRIDGE: Election winner - best router signal"
+  - **Solution**: Changed callback signature to use const reference (`const TSTRING& reason`) instead of pass-by-value
+    - Eliminates unnecessary String object copying and temporary creation
+    - Reduces memory pressure during callback invocation
+    - String literals are now directly bound to const references without heap allocation
+  - **Impact**: Eliminates hard resets during bridge promotion, allows stable failover operation
+  - **Breaking Change**: Users must update their callback function signatures from `void callback(bool, String)` to `void callback(bool, const String&)`
+  - **Files Modified**: 
+    - `src/arduino/wifi.hpp` (lines 970, 2326)
+    - `examples/bridge_failover/bridge_failover.ino` (line 147)
+    - `README.md` (line 171)
+    - `USER_GUIDE.md` (line 731)
+
+## [1.9.9] - 2025-12-14
+
+### Fixed
+
+- **Hard Reset from Heap Corruption in Connection Destructor** - Fixed ESP32/ESP8266 hard resets caused by heap corruption when connections were closed
+  - **Root Cause**: AsyncClient objects were being deleted immediately in `~BufferedConnection()` destructor when `eraseClosedConnections()` removed closed connections. The AsyncTCP library was still referencing these objects internally, causing heap corruption and hard resets
+  - **Symptom**: Device crashes with "CORRUPT HEAP: Bad head at 0x408388a4. Expected 0xabba1234 got 0xfefefefe" and "assert failed: multi_heap_free multi_heap_poisoning.c:279" when connections are removed from the mesh
+  - **Solution**: Deferred AsyncClient deletion in destructor using task scheduler with 500ms delay
+    - Store scheduler reference in `BufferedConnection` for use in destructor
+    - Schedule AsyncClient deletion with 500ms delay to give AsyncTCP time to complete internal cleanup
+    - Use same deferred deletion pattern as error handler fixes (Issues #254, #269)
+    - Added fallback for test environments where scheduler may not be available
+  - **Impact**: Eliminates hard resets and heap corruption when mesh connections are closed, allows stable mesh network operation
+  - **Files Modified**: `src/painlessmesh/connection.hpp` (lines 42-81, 89-91, 192)
+  - **Documentation**: See `ISSUE_HARD_RESET_FIX.md` for detailed analysis
+
+- **Node Crash During TCP Connection Retries** - Fixed device crashes that occurred after 2-3 TCP connection retry attempts
+  - **Root Cause**: AsyncClient objects were being deleted too quickly (0ms delay) after connection errors. The AsyncTCP library needs 200-400ms to complete internal cleanup operations, and accessing the deleted object caused crashes
+  - **Symptom**: Device crashes or hangs after 2-3 TCP retry attempts, serial log stops abruptly during retry sequence
+  - **Solution**: Increased AsyncClient cleanup delay from 0ms to 500ms
+    - Added new constant `TCP_CLIENT_CLEANUP_DELAY_MS = 500` to give AsyncTCP library time to complete internal cleanup
+    - Updated both cleanup paths (retry and exhaustion) to use this delay
+    - Provides sufficient time for AsyncTCP to finish processing before object deletion
+  - **Impact**: Eliminates crashes during TCP connection retries, allows full retry sequence to complete
+  - **Files Modified**: `src/painlessmesh/tcp.hpp` (lines 26, 149, 170)
+  - **Documentation**: See `ASYNCCLIENT_CLEANUP_FIX.md` for detailed analysis
+
 ## [1.9.8] - 2025-12-14
 
 ### Fixed

package/README.md

@@ -4,7 +4,7 @@
 
 <div align="center">
 
-**Version 1.9.8** - Latest release with ESP32 heap corruption fix and improved TCP error handling
+**Version 1.9.10** - Latest release with critical bug fixes for TCP retry and bridge failover
 
 [![CI/CD Pipeline](https://github.com/Alteriom/painlessMesh/actions/workflows/ci.yml/badge.svg)](https://github.com/Alteriom/painlessMesh/actions/workflows/ci.yml)
 [![Documentation](https://github.com/Alteriom/painlessMesh/actions/workflows/docs.yml/badge.svg)](https://github.com/Alteriom/painlessMesh/actions/workflows/docs.yml)
@@ -168,7 +168,7 @@ mesh.setRouterCredentials(ROUTER_SSID, ROUTER_PASSWORD);
 mesh.enableBridgeFailover(true);
 mesh.onBridgeRoleChanged(&bridgeRoleCallback);
 
-void bridgeRoleCallback(bool isBridge, String reason) {
+void bridgeRoleCallback(bool isBridge, const String& reason) {
   if (isBridge) {
     Serial.printf("🎯 Promoted to bridge: %s\n", reason.c_str());
   }

package/RELEASE_GUIDE.md

@@ -2,9 +2,52 @@
 
 This document provides comprehensive instructions for releasing new versions of the Alteriom painlessMesh library across all distribution channels.
 
+## ⚠️ Important: Agent Requirements for Releases
+
+**Releases MUST be performed by Alteriom AI Agent (`@alteriom-ai-agent`) with full tool access.**
+
+### Why This Matters
+
+A release requires updating 7 files consistently:
+1. library.properties
+2. library.json  
+3. package.json
+4. src/painlessMesh.h
+5. src/AlteriomPainlessMesh.h
+6. README.md
+7. CHANGELOG.md
+
+**✅ Correct Agent:** `@alteriom-ai-agent`
+- Has file editing tools (`replace_string_in_file`, `multi_replace_string_in_file`)
+- Can run terminal commands (`run_in_terminal`)
+- Can execute git operations
+- **Use this for release preparation**
+
+**❌ Wrong Agent:** `@painlessmesh-coordinator` or specialized agents without tools
+- Lack file editing capabilities
+- Can only provide documentation/checklists
+- Cannot actually perform releases
+- Will result in manual work
+
+### Agent-Assisted Release (Recommended)
+
+```bash
+# Ask Alteriom AI Agent to prepare release
+@alteriom-ai-agent Prepare release v1.9.9 with these changes:
+- Fixed ESP8266 WiFiClientSecure scope issue  
+- Fixed TCP retry crash with AsyncClient cleanup
+
+# Agent will:
+# ✅ Update all 7 version files
+# ✅ Restructure CHANGELOG.md
+# ✅ Run validation: ./scripts/release-agent.sh
+# ✅ Commit: "release: v1.9.9 - Description"
+# ✅ Push to trigger automation
+```
+
 ## 🚀 Quick Release Process
 
-### Standard Release (Recommended)
+### Standard Release (Manual)
 
 ```bash
 # 1. Update version using the bump script
@@ -21,7 +64,7 @@ This document provides comprehensive instructions for releasing new versions of
 ./scripts/release-agent.sh
 
 # 5. If all checks pass, commit and trigger release
-git add library.properties library.json package.json CHANGELOG.md src/*.h
+git add library.properties library.json package.json CHANGELOG.md src/*.h README.md
 git commit -m "release: v1.7.9 - Brief description"
 git push origin main
 ```

package/docs/troubleshooting/common-issues.md

@@ -205,11 +205,12 @@ For Arduino IDE, install manually from: https://github.com/ESP32Async/AsyncTCP
 
 #### 2. Built-in Retry Mechanism
 painlessMesh now includes automatic TCP connection retry with the following behavior:
-- Up to 3 retry attempts with 500ms delay between each
-- 100ms stabilization delay after IP acquisition before first connection attempt
-- Full WiFi reconnection only triggered after all retries are exhausted
+- Up to 6 total connection attempts (initial + 5 retries)
+- Exponential backoff delays between retries: 1s, 2s, 4s, 8s, 8s (total ~23s)
+- 500ms stabilization delay after IP acquisition before first connection attempt
+- Full WiFi reconnection with 10s delay only triggered after all retries are exhausted
 
-This helps handle transient timing issues automatically.
+This exponential backoff helps handle transient timing issues automatically while reducing network congestion from multiple retrying nodes.
 
 #### 3. Check Node Resource Usage
 Monitor memory and ensure nodes aren't overloaded:

package/examples/bridge/bridge.ino

@@ -1,20 +1,29 @@
 //************************************************************
-// Bridge Node Example - Automatic Channel Detection
+// Bridge Node Example - Automatic Channel Detection & Resilient Initialization
 //
-// This example demonstrates the new bridge-centric architecture that
+// This example demonstrates the bridge-centric architecture that
 // automatically detects the router's WiFi channel and configures the
 // mesh network accordingly.
 //
 // Features:
-// - Connects to router FIRST and auto-detects its channel
-// - Creates mesh network on the same channel as router
+// - Resilient initialization: Works even if router is unavailable at boot
+// - Automatically detects router channel when available
+// - Creates mesh network immediately (default channel if needed)
 // - No manual channel configuration required
 // - Automatically sets itself as root node
+// - Retries router connection in background if initially unavailable
 // - Broadcasts bridge status to mesh (Type 610 - BRIDGE_STATUS)
 //   - Reports Internet connectivity status
 //   - Updates every 30 seconds by default
 //   - Enables nodes to implement failover and queueing logic
 //
+// POWER-UP ORDER INDEPENDENCE (v1.9.7+):
+// The bridge now initializes successfully regardless of power-up order:
+// - Bridge can boot before router is ready
+// - Mesh nodes can connect immediately to bridge
+// - Router connection is established automatically when available
+// - No need to restart bridge when router becomes ready
+//
 // For more details, see BRIDGE_TO_INTERNET.md
 //
 // EXTERNAL DEVICE CONNECTIONS:
@@ -63,29 +72,27 @@ void setup() {
   // Set debug message types before init() to see startup messages
   mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
 
-  // NEW: Single call to initialize as bridge with auto channel detection
+  // Single call to initialize as bridge with auto channel detection
   // This will:
-  // 1. Connect to router and detect its channel
-  // 2. Initialize mesh on the detected channel
-  // 3. Set this node as root
-  // 4. Maintain router connection
+  // 1. Attempt to connect to router and detect its channel
+  // 2. Initialize mesh on the detected channel (or default if router unavailable)
+  // 3. Set this node as root/bridge
+  // 4. Maintain/retry router connection automatically
   // 5. Start broadcasting bridge status (Type 610) every 30 seconds
-  bool bridgeSuccess = mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
-                                         ROUTER_SSID, ROUTER_PASSWORD,
-                                         &userScheduler, MESH_PORT);
-
-  if (!bridgeSuccess) {
-    Serial.println("✗ Failed to initialize as bridge!");
-    Serial.println("Router unreachable - falling back to regular mesh node");
-    Serial.println("The node will join the mesh without bridge functionality");
-    
-    // Fallback: Initialize as regular mesh node
-    // This allows the device to still participate in the mesh
-    mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
-    
-    Serial.println("✓ Initialized as regular mesh node");
-    Serial.println("Note: To function as a bridge, fix router connectivity and restart");
-  }
+  //
+  // RESILIENT INITIALIZATION (v1.9.7+):
+  // The bridge will successfully initialize even if the router is unavailable
+  // at boot time. It will:
+  // - Establish the mesh network immediately on a default channel
+  // - Accept connections from mesh nodes right away
+  // - Retry router connection automatically in the background
+  // - Update bridge status when router becomes available
+  //
+  // This solves the power-up order issue (Issue #268) where bridge
+  // initialization would fail if the router wasn't ready yet.
+  mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
+                    ROUTER_SSID, ROUTER_PASSWORD,
+                    &userScheduler, MESH_PORT);
 
   // Optional: Configure bridge status broadcasting
   // mesh.setBridgeStatusInterval(60000);  // Change to 60 seconds
@@ -98,6 +105,8 @@ void setup() {
   mesh.onReceive(&receivedCallback);
   
   Serial.println("✓ Bridge node initialized and ready!");
+  Serial.println("Mesh network active - accepting node connections");
+  Serial.println("Router connection will be established automatically when available");
   Serial.println("Broadcasting bridge status to mesh every 30 seconds");
 }
 

package/examples/bridge_failover/bridge_failover.ino

@@ -144,7 +144,7 @@ void bridgeStatusCallback(uint32_t bridgeNodeId, bool hasInternet) {
   }
 }
 
-void bridgeRoleCallback(bool isBridge, String reason) {
+void bridgeRoleCallback(bool isBridge, const String& reason) {
   if (isBridge) {
     Serial.printf("🎯 PROMOTED TO BRIDGE: %s\n", reason.c_str());
     Serial.println("This node is now the primary bridge!");

package/library.json

@@ -6,7 +6,7 @@
     "type": "git",
     "url": "https://github.com/Alteriom/painlessMesh"
   },
-  "version": "1.9.8",
+  "version": "1.9.10",
   "frameworks": [
     "arduino"
   ],

package/library.properties

@@ -1,5 +1,5 @@
 name=Alteriom PainlessMesh
-version=1.9.8
+version=1.9.10
 author=Coopdis,Scotty Franzyshen,Edwin van Leeuwen,Germán Martín,Maximilian Schwarz,Doanh Doanh,Alteriom
 maintainer=Alteriom
 sentence=A painless way to setup a mesh with ESP8266 and ESP32 devices with Alteriom extensions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alteriom/painlessmesh",
-  "version": "1.9.8",
+  "version": "1.9.10",
   "description": "painlessMesh is a user-friendly library for creating mesh networks with ESP8266 and ESP32 devices. This Alteriom fork includes additional packages for sensor data (SensorPackage), device commands (CommandPackage), and status monitoring (StatusPackage). It handles routing and network management automatically, so you can focus on your application. The library uses JSON-based messaging and syncs time across all nodes, making it ideal for coordinated behaviour like synchronized light displays or sensor networks reporting to a central node.",
   "keywords": [
     "arduino",
@@ -40,7 +40,7 @@
   },
   "devDependencies": {
     "@alteriom/mqtt-schema": "^0.8.0",
-    "@eslint/js": "^9.39.1",
+    "@eslint/js": "^9.39.2",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "prettier": "^3.7.4"

package/src/AlteriomPainlessMesh.h

@@ -29,10 +29,10 @@
 /**
  * @brief AlteriomPainlessMesh library version information
  */
-#define ALTERIOM_PAINLESS_MESH_VERSION "1.9.7"
+#define ALTERIOM_PAINLESS_MESH_VERSION "1.9.10"
 #define ALTERIOM_PAINLESS_MESH_VERSION_MAJOR 1
 #define ALTERIOM_PAINLESS_MESH_VERSION_MINOR 9
-#define ALTERIOM_PAINLESS_MESH_VERSION_PATCH 7
+#define ALTERIOM_PAINLESS_MESH_VERSION_PATCH 10
 
 /**
  * @brief Library description and usage information

package/src/arduino/wifi.hpp

@@ -386,9 +386,12 @@ class Mesh : public painlessmesh::Mesh<Connection> {
     using namespace logger;
 
     Log(STARTUP, "=== Bridge Mode Initialization ===\n");
-    Log(STARTUP, "Step 1: Connecting to router %s...\n", routerSSID.c_str());
+    Log(STARTUP, "Step 1: Attempting to connect to router %s...\n", routerSSID.c_str());
 
-    // Step 1: Connect to router first to detect its channel
+    // Store router credentials for future connection attempts
+    setRouterCredentials(routerSSID, routerPassword);
+
+    // Step 1: Attempt to connect to router first to detect its channel
     // Shut Wifi down and start with a blank slate
     if (WiFi.status() != WL_DISCONNECTED) WiFi.disconnect();
 
@@ -413,6 +416,7 @@ class Mesh : public painlessmesh::Mesh<Connection> {
     }
 
     uint8_t detectedChannel = 1;  // Default fallback
+    bool routerConnected = false;
 
     if (WiFi.status() == WL_CONNECTED) {
       detectedChannel = WiFi.channel();
@@ -425,18 +429,50 @@ class Mesh : public painlessmesh::Mesh<Connection> {
       } else {
         Log(STARTUP, "\n✓ Router connected on channel %d\n", detectedChannel);
         Log(STARTUP, "✓ Router IP: %s\n", WiFi.localIP().toString().c_str());
+        routerConnected = true;
       }
     } else {
-      Log(ERROR, "\n✗ Failed to connect to router\n");
-      Log(ERROR, "Cannot become bridge without router connection\n");
-      Log(ERROR, "Bridge initialization aborted - remaining as regular node\n");
-      return false;
+      Log(STARTUP, "\n⚠ Router connection unavailable during initialization\n");
+      
+      // Scan for router to detect its channel even though we can't connect
+      // This minimizes channel mismatch when router becomes available later
+      Log(STARTUP, "⚠ Scanning for router '%s' to detect channel...\n", routerSSID.c_str());
+      
+      // ESP32 and ESP8266 have different scanNetworks signatures
+#ifdef ESP32
+      int16_t numNetworks = WiFi.scanNetworks(false, false, false, 300U, 0);
+#elif defined(ESP8266)
+      int16_t numNetworks = WiFi.scanNetworks(false, false, 0);
+#endif
+      
+      if (numNetworks > 0) {
+        for (int16_t i = 0; i < numNetworks; i++) {
+          if (WiFi.SSID(i) == routerSSID) {
+            uint8_t scannedChannel = WiFi.channel(i);
+            if (scannedChannel >= 1 && scannedChannel <= 13) {
+              detectedChannel = scannedChannel;
+              Log(STARTUP, "✓ Router found on channel %d (not connected, will retry)\n", 
+                  detectedChannel);
+              break;
+            }
+          }
+        }
+        WiFi.scanDelete();
+      }
+      
+      if (detectedChannel == 1) {
+        Log(STARTUP, "⚠ Router not found in scan, using default channel %d\n", detectedChannel);
+      }
+      
+      Log(STARTUP, "⚠ Proceeding with bridge setup on channel %d\n", detectedChannel);
+      Log(STARTUP, "⚠ Bridge will retry router connection in background\n");
     }
 
     Log(STARTUP, "Step 2: Initializing mesh on channel %d...\n",
         detectedChannel);
 
-    // Step 2: Initialize mesh on detected channel
+    // Step 2: Initialize mesh on detected/default channel
+    // This allows the bridge to establish the mesh network even without router
     init(meshSSID, meshPassword, baseScheduler, port, WIFI_AP_STA,
          detectedChannel, 0, MAX_CONN);
 
@@ -446,10 +482,13 @@ class Mesh : public painlessmesh::Mesh<Connection> {
 
     Log(STARTUP, "Step 3: Establishing bridge connection...\n");
 
-    // Step 3: Re-establish router connection using stationManual
+    // Step 3: Establish/re-establish router connection using stationManual
+    // If router wasn't available initially, this will be retried automatically
     stationManual(routerSSID, routerPassword, 0);
 
     // Step 4: Configure as root/bridge node
+    // Bridge role is established regardless of router connectivity
+    // This ensures mesh nodes can connect and the bridge can provide mesh services
     this->setRoot(true);
     this->setContainsRoot(true);
 
@@ -461,9 +500,21 @@ class Mesh : public painlessmesh::Mesh<Connection> {
 
     Log(STARTUP, "=== Bridge Mode Active ===\n");
     Log(STARTUP, "  Mesh SSID: %s\n", meshSSID.c_str());
-    Log(STARTUP, "  Mesh Channel: %d (matches router)\n", detectedChannel);
-    Log(STARTUP, "  Router: %s\n", routerSSID.c_str());
+    Log(STARTUP, "  Mesh Channel: %d%s\n", detectedChannel, 
+        routerConnected ? " (matches router)" : " (default, router pending)");
+    Log(STARTUP, "  Router: %s%s\n", routerSSID.c_str(),
+        routerConnected ? " (connected)" : " (will retry)");
     Log(STARTUP, "  Port: %d\n", port);
+    
+    if (!routerConnected) {
+      Log(STARTUP, "\nINFO: Bridge initialized without router connection\n");
+      Log(STARTUP, "INFO: Mesh network is active and accepting node connections\n");
+      Log(STARTUP, "INFO: Router connection will be established automatically when available\n");
+    }
+    
+    // Return true - bridge mesh functionality is active even without router
+    // The mesh network is operational and nodes can connect
+    // Router connection will be retried automatically via stationManual
     return true;
   }
 
@@ -916,7 +967,7 @@ class Mesh : public painlessmesh::Mesh<Connection> {
    * @param callback Function to call when role changes
    */
   void onBridgeRoleChanged(
-      std::function<void(bool isBridge, TSTRING reason)> callback) {
+      std::function<void(bool isBridge, const TSTRING& reason)> callback) {
     bridgeRoleChangedCallback = callback;
   }
 
@@ -2272,7 +2323,7 @@ class Mesh : public painlessmesh::Mesh<Connection> {
   ElectionState electionState = ELECTION_IDLE;
   uint32_t electionDeadline = 0;
   std::vector<BridgeCandidate> electionCandidates;
-  std::function<void(bool isBridge, TSTRING reason)> bridgeRoleChangedCallback;
+  std::function<void(bool isBridge, const TSTRING& reason)> bridgeRoleChangedCallback;
 
   // Isolated bridge retry state and configuration
   uint8_t _isolatedBridgeRetryAttempts = 0;

package/src/painlessMesh.h

@@ -5,8 +5,8 @@
  * @file painlessMesh.h
  * @brief Main header file for Alteriom painlessMesh library
  * 
- * @version 1.9.7
- * @date 2025-12-13
+ * @version 1.9.10
+ * @date 2025-12-15
  * 
  * painlessMesh is a user-friendly library for creating mesh networks with 
  * ESP8266 and ESP32 devices. This Alteriom fork includes additional packages 

package/src/painlessmesh/connection.hpp

@@ -14,6 +14,11 @@ extern painlessmesh::logger::LogClass Log;
 namespace painlessmesh {
 namespace tcp {
 
+// Delay before cleaning up failed AsyncClient after connection error or close
+// This prevents crashes when AsyncTCP library is still accessing the client internally
+// The AsyncTCP library may take a few hundred milliseconds to complete its internal cleanup
+static const uint32_t TCP_CLIENT_CLEANUP_DELAY_MS = 500; // 500ms delay before deleting AsyncClient
+
 // Shared buffer for reading/writing to the buffer
 static painlessmesh::buffer::temp_buffer_t shared_buffer;
 
@@ -40,16 +45,50 @@ class BufferedConnection
   BufferedConnection(AsyncClient *client) : client(client) {}
 
   ~BufferedConnection() {
+    using namespace logger;
     Log.remote("~BufferedConnection");
     this->close();
     if (!client->freeable()) {
       client->close(true);
     }
     client->abort();
-    delete client;
+    
+    // Defer deletion of the AsyncClient to prevent heap corruption
+    // Deleting immediately can cause use-after-free issues when the AsyncTCP 
+    // library is still referencing the object internally during cleanup
+    // See ISSUE_254_HEAP_CORRUPTION_FIX.md and ASYNCCLIENT_CLEANUP_FIX.md
+    if (mScheduler) {
+      // Capture client pointer by value for safe deferred deletion
+      AsyncClient* clientToDelete = client;
+      
+      // Schedule deletion task with TCP_CLIENT_CLEANUP_DELAY_MS delay
+      // This gives AsyncTCP library time to complete its internal cleanup
+      // Note: Task object is intentionally leaked to keep implementation simple
+      // This is acceptable because:
+      // 1. Connections are long-lived, destructor calls are infrequent
+      // 2. Task object is small (~32-64 bytes) vs preventing critical heap corruption
+      // 3. In typical deployments, memory impact is negligible (few KB over months)
+      // 4. Alternative cleanup patterns would add significant complexity
+      Task* cleanupTask = new Task(TCP_CLIENT_CLEANUP_DELAY_MS * TASK_MILLISECOND, TASK_ONCE, [clientToDelete]() {
+        using namespace logger;
+        Log(CONNECTION, "~BufferedConnection: Deferred cleanup of AsyncClient\n");
+        delete clientToDelete;
+      });
+      
+      mScheduler->addTask(*cleanupTask);
+      cleanupTask->enableDelayed();
+    } else {
+      // Fallback: If scheduler not available, delete immediately
+      // This should only happen in test environments or edge cases
+      Log(CONNECTION, "~BufferedConnection: No scheduler available, deleting AsyncClient immediately (risky)\n");
+      delete client;
+    }
   }
 
   void initialize(Scheduler *scheduler) {
+    // Store scheduler reference for deferred cleanup in destructor
+    mScheduler = scheduler;
+    
     auto self = this->shared_from_this();
     sentBufferTask.set(TASK_SECOND, TASK_FOREVER, [self]() {
       if (!self->sentBuffer.empty() && self->client->canSend()) {
@@ -156,6 +195,7 @@ class BufferedConnection
   bool mConnected = true;
 
   AsyncClient *client;
+  Scheduler *mScheduler = nullptr; // Scheduler for deferred AsyncClient cleanup
 
   std::function<void(TSTRING)> receiveCallback;
   std::function<void()> disconnectCallback;

package/src/painlessmesh/plugin.hpp

@@ -228,7 +228,13 @@ class PackageHandler : public layout::Layout<T> {
     for (auto&& task : taskList) {
       if (task.use_count() == 1 && !task->isEnabled()) {
         task->set(aInterval, aIterations, aCallback, NULL, NULL);
-        task->enable();
+        // Use enableDelayed() for delayed one-shot tasks to prevent immediate execution
+        // This ensures tasks with intervals execute after the delay, not immediately
+        if (aInterval > 0 && aIterations == TASK_ONCE) {
+          task->enableDelayed();
+        } else {
+          task->enable();
+        }
         return task;
       }
     }
@@ -236,7 +242,13 @@ class PackageHandler : public layout::Layout<T> {
     std::shared_ptr<Task> task =
         std::make_shared<Task>(aInterval, aIterations, aCallback);
     scheduler.addTask((*task));
-    task->enable();
+    // Use enableDelayed() for delayed one-shot tasks to prevent immediate execution
+    // This ensures tasks with intervals execute after the delay, not immediately
+    if (aInterval > 0 && aIterations == TASK_ONCE) {
+      task->enableDelayed();
+    } else {
+      task->enable();
+    }
     taskList.push_front(task);
     return task;
   }

package/src/painlessmesh/tcp.hpp

@@ -20,6 +20,7 @@ namespace tcp {
 static const uint8_t TCP_CONNECT_MAX_RETRIES = 5;       // Max retry attempts before giving up
 static const uint32_t TCP_CONNECT_RETRY_DELAY_MS = 1000; // Delay between retry attempts (1 second)
 static const uint32_t TCP_CONNECT_STABILIZATION_DELAY_MS = 500; // Delay after IP acquisition (500ms)
+// TCP_CLIENT_CLEANUP_DELAY_MS is defined in connection.hpp since it's used in the destructor
 // Delay before WiFi reconnection after all TCP retries are exhausted
 // This prevents rapid reconnection loops when TCP server is persistently unavailable
 // Gives the TCP server more time to recover and reduces network congestion
@@ -136,11 +137,13 @@ void connect(AsyncClient &client, IPAddress ip, uint16_t port, M &mesh,
         // Defer deletion of the failed AsyncClient to prevent heap corruption
         // Deleting from within the error callback can cause use-after-free issues
         // as the AsyncTCP library may still be referencing the object
+        // Use TCP_CLIENT_CLEANUP_DELAY_MS to give AsyncTCP library time to complete
+        // its internal cleanup before we delete the object
         // Note: client is captured by value (pointer copy) and we are the sole owner
         mesh.addTask([client]() {
           Log(CONNECTION, "tcp_err(): Cleaning up failed AsyncClient (retry path)\n");
           delete client;
-        }, 0);
+        }, TCP_CLIENT_CLEANUP_DELAY_MS);
         
         mesh.semaphoreGive();
         return;
@@ -155,11 +158,13 @@ void connect(AsyncClient &client, IPAddress ip, uint16_t port, M &mesh,
       // Defer deletion of the failed AsyncClient to prevent heap corruption
       // Deleting from within the error callback can cause use-after-free issues
       // as the AsyncTCP library may still be referencing the object
+      // Use TCP_CLIENT_CLEANUP_DELAY_MS to give AsyncTCP library time to complete
+      // its internal cleanup before we delete the object
       // Note: client is captured by value (pointer copy) and we are the sole owner
       mesh.addTask([client]() {
         Log(CONNECTION, "tcp_err(): Cleaning up failed AsyncClient (exhaustion path)\n");
         delete client;
-      }, 0);
+      }, TCP_CLIENT_CLEANUP_DELAY_MS);
 #endif
       // Defer callback execution to avoid crashes in error handler context
       // Execute callbacks after semaphore is released and error handler completes