@alteriom/painlessmesh 1.9.7 → 1.9.8

package/CHANGELOG.md

@@ -19,6 +19,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - TBD
 
+## [1.9.8] - 2025-12-14
+
+### Fixed
+
+- **Heap Corruption on TCP Connection Errors** (#254) - Fixed ESP32 heap corruption crashes during AsyncClient deletion
+  - **Root Cause**: AsyncClient objects were being deleted synchronously from within their own error callback handlers, causing heap corruption and use-after-free crashes
+  - **Symptom**: ESP32 devices crash with "CORRUPT HEAP: Bad head at 0x4083a398. Expected 0xabba1234 got 0xfefefefe" during TCP connection error handling
+  - **Solution**: Deferred AsyncClient deletion using task scheduler to execute after error handler completes
+    - Changed from synchronous `delete client` to deferred deletion via `mesh.addTask([client]() { delete client; }, 0)`
+    - Deletion now occurs microseconds after error handler returns, preventing use-after-free
+    - Added logging for cleanup operations to aid debugging
+  - **Impact**: Eliminates heap corruption crashes on ESP32 during TCP connection retries and error conditions
+  - **Files Modified**: `src/painlessmesh/tcp.hpp` (lines 138, 149)
+
+### Changed
+
+- **README Version Reference** - Updated version banner to 1.9.7 for consistency with release history
+
 ## [1.9.7] - 2025-12-13
 
 ### Fixed

package/README.md

@@ -4,7 +4,7 @@
 
 <div align="center">
 
-**Version 1.9.6** - Latest release with TCP connection improvements and documentation updates
+**Version 1.9.8** - Latest release with ESP32 heap corruption fix and improved TCP error handling
 
 [![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)

package/library.json

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

package/library.properties

@@ -1,5 +1,5 @@
 name=Alteriom PainlessMesh
-version=1.9.7
+version=1.9.8
 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.7",
+  "version": "1.9.8",
   "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",

package/src/painlessmesh/mesh.hpp

@@ -622,10 +622,10 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
    * 
    * Use hasLocalInternet() to check if THIS specific node has direct Internet access.
    * 
-   * When connected to mesh, requires recent bridge status (within timeout).
-   * When disconnected from mesh, returns true if any bridge previously
-   * reported Internet connectivity - allowing operations to be queued for
-   * when mesh connectivity is restored.
+   * This method now ALWAYS requires healthy (recent) bridge status to prevent
+   * false positives when mesh connectivity is lost. Without active mesh connections,
+   * stale bridge data cannot be relied upon, as the bridge may have lost Internet
+   * connectivity or become unreachable.
    * 
    * \code
    * if (mesh.hasInternetConnection()) {
@@ -644,16 +644,10 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
    * @see initAsSharedGateway() to give all nodes direct Internet access (requires router credentials)
    */
   bool hasInternetConnection() {
-    bool hasConnections = hasActiveMeshConnections();
-    
+    // Always require healthy bridge status to prevent false positives
+    // when mesh is disconnected. Stale bridge data is unreliable.
     for (const auto& bridge : knownBridges) {
-      // When connected: require fresh status
-      // When disconnected: use last known state
-      bool isUsable = hasConnections 
-          ? (bridge.isHealthy(bridgeTimeoutMs) && bridge.internetConnected)
-          : bridge.internetConnected;
-      
-      if (isUsable) {
+      if (bridge.isHealthy(bridgeTimeoutMs) && bridge.internetConnected) {
         return true;
       }
     }
@@ -698,14 +692,17 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
    * Get the primary (best) bridge node
    * 
    * Primary bridge is selected based on:
-   * 1. Must be healthy (seen within timeout) - unless node is disconnected
+   * 1. Must be healthy (seen within timeout)
    * 2. Must have Internet connection
    * 3. Best WiFi RSSI to router
    * 
-   * When this node is disconnected from the mesh (no active connections),
-   * returns the last known bridge even if lastSeen is stale. This allows
-   * nodes to attempt routing through the last known bridge once mesh
-   * connectivity is restored.
+   * This method now ALWAYS requires healthy (recent) bridge status to prevent
+   * routing messages to unreachable or outdated bridges when mesh connectivity
+   * is lost. Without active mesh connections and fresh status, we cannot reliably
+   * route messages to any bridge.
+   * 
+   * If you need access to the last known bridge regardless of health status,
+   * use getLastKnownBridge() instead.
    * 
    * @return pointer to BridgeInfo of primary bridge, or nullptr if no suitable bridge
    */
@@ -713,17 +710,9 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     BridgeInfo* primary = nullptr;
     int8_t bestRSSI = -127;  // Worst possible RSSI
     
-    // Check if we have active mesh connections
-    bool hasConnections = hasActiveMeshConnections();
-    
+    // Always require healthy bridge status to prevent routing to stale/unreachable bridges
     for (auto& bridge : knownBridges) {
-      // When connected to mesh: require healthy (recent) bridge status
-      // When disconnected: use any bridge that reported Internet (stale info is better than none)
-      bool isUsable = hasConnections 
-          ? (bridge.isHealthy(bridgeTimeoutMs) && bridge.internetConnected)
-          : bridge.internetConnected;
-      
-      if (isUsable) {
+      if (bridge.isHealthy(bridgeTimeoutMs) && bridge.internetConnected) {
         if (bridge.routerRSSI > bestRSSI) {
           bestRSSI = bridge.routerRSSI;
           primary = &bridge;
@@ -1290,6 +1279,18 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
       Log(COMMUNICATION, "sendToInternet(): Local Internet available, using gateway protocol for consistency\n");
     }
 
+    // Validate mesh connectivity before attempting to send
+    if (!hasActiveMeshConnections()) {
+      Log(ERROR, "sendToInternet(): No active mesh connections\n");
+      if (callback) {
+        // Schedule callback to avoid blocking
+        this->addTask([callback]() {
+          callback(false, 0, "No mesh connections - cannot route to gateway");
+        });
+      }
+      return 0;
+    }
+
     // Find the best gateway to route through
     BridgeInfo* gateway = getPrimaryBridge();
     if (gateway == nullptr) {

package/src/painlessmesh/tcp.hpp

@@ -20,6 +20,10 @@ 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)
+// 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
+static const uint32_t TCP_EXHAUSTION_RECONNECT_DELAY_MS = 10000; // 10 seconds before reconnection
 
 inline uint32_t encodeNodeId(const uint8_t *hwaddr) {
   using namespace painlessmesh::logger;
@@ -129,24 +133,42 @@ void connect(AsyncClient &client, IPAddress ip, uint16_t port, M &mesh,
           connect<T, M>((*pRetryConn), ip, port, mesh, retryCount + 1);
         }, retryDelay);
         
-        // Delete the current failed client to prevent memory leak
-        // The AsyncClient is no longer needed after connection failure
-        delete client;
+        // 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
+        // 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);
         
         mesh.semaphoreGive();
         return;
       }
       
-      // All retries exhausted - clean up the failed client and trigger full reconnection
-      Log(CONNECTION, "tcp_err(): All %d retries exhausted, triggering WiFi reconnection\n",
-          TCP_CONNECT_MAX_RETRIES + 1);
-      delete client;
+      // All retries exhausted - schedule delayed reconnection
+      // Adding a significant delay before reconnection prevents rapid reconnection loops
+      // when the TCP server is persistently unavailable or overloaded
+      Log(CONNECTION, "tcp_err(): All %d retries exhausted, scheduling WiFi reconnection in %u ms\n",
+          TCP_CONNECT_MAX_RETRIES + 1, TCP_EXHAUSTION_RECONNECT_DELAY_MS);
+      
+      // 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
+      // 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);
 #endif
       // Defer callback execution to avoid crashes in error handler context
       // Execute callbacks after semaphore is released and error handler completes
+      // The delay helps prevent endless rapid reconnection loops by giving the TCP server
+      // more time to recover and reducing network congestion from multiple retrying nodes
       mesh.addTask([&mesh]() {
+        Log(CONNECTION, "tcp_err(): Executing delayed WiFi reconnection after retry exhaustion\n");
         mesh.droppedConnectionCallbacks.execute(0, true);
-      });
+      }, TCP_EXHAUSTION_RECONNECT_DELAY_MS);
       mesh.semaphoreGive();
     }
   });