@alteriom/painlessmesh 1.9.9 → 1.9.10

package/CHANGELOG.md

@@ -19,6 +19,39 @@ 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

package/README.md

@@ -4,7 +4,7 @@
 
 <div align="center">
 
-**Version 1.9.9** - Latest release with AsyncClient cleanup fixes for improved stability
+**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/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_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.9",
+  "version": "1.9.10",
   "frameworks": [
     "arduino"
   ],

package/library.properties

@@ -1,5 +1,5 @@
 name=Alteriom PainlessMesh
-version=1.9.9
+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.9",
+  "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.9"
+#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 9
+#define ALTERIOM_PAINLESS_MESH_VERSION_PATCH 10
 
 /**
  * @brief Library description and usage information

package/src/arduino/wifi.hpp

@@ -967,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;
   }
 
@@ -2323,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.9
- * @date 2025-12-14
+ * @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/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;
   }