@alteriom/painlessmesh 1.9.4 → 1.9.6

package/CHANGELOG.md

@@ -5,6 +5,64 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.6] - 2025-12-10
+
+### Fixed
+
+- **TCP Connection Retry Improvements** (#231) - Improved TCP connection reliability with increased retries and exponential backoff
+  - **Root Cause**: Nodes experience endless loop of WiFi connect → TCP error -14 → WiFi disconnect because the TCP retry mechanism wasn't sufficient for real-world mesh conditions
+  - **Symptom**: Mesh connections never fully establish; nodes can discover and get IP from bridge but TCP connection consistently fails
+  - **Solution**: Improved TCP connection retry parameters and added exponential backoff:
+    - Increased `TCP_CONNECT_STABILIZATION_DELAY_MS` from 100ms to 500ms (more time for network stack to stabilize after IP acquisition)
+    - Increased `TCP_CONNECT_RETRY_DELAY_MS` from 500ms to 1000ms (base delay between retries)
+    - Increased `TCP_CONNECT_MAX_RETRIES` from 3 to 5 (more retry attempts before giving up)
+    - Added exponential backoff: retry delays are 1s, 2s, 4s, 8s, 8s (capped) for attempts 1-5
+  - **Impact**: More reliable mesh connection establishment, especially when bridge TCP server is temporarily busy or network is congested
+
+### Documentation
+
+- **README.md Comprehensive Review** - Updated main README for completeness and accuracy
+  - Updated version references from 1.9.2 to 1.9.6
+  - Verified all documentation links and references
+  - Confirmed package type documentation accuracy
+  - Validated installation instructions
+  - Updated "Latest Release" section with current features
+  - Fixed ArduinoJson v7 code examples (DynamicJsonDocument → JsonDocument)
+  - Updated dependency versions in documentation (ArduinoJson 6.x→7.x, TaskScheduler 3.x→4.x)
+  - Corrected API Documentation links (GitLab → GitHub Pages)
+  - Fixed Contributing section references (master→main, GitLab→GitHub)
+
+### Changed
+
+- **Version Consistency** - Synchronized version numbers across all distribution files
+  - Updated library.properties to v1.9.6
+  - Updated library.json to v1.9.6
+  - Updated package.json to v1.9.6
+  - Ensures consistent versioning for NPM, PlatformIO, and Arduino Library Manager
+
+## [1.9.5] - 2025-12-03
+
+### Fixed
+
+- **Bridge Status Send Race Condition** (#224) - Fixed sendToInternet failures caused by race condition
+  - **Root Cause**: Bridge would attempt to send status messages to nodes that had already disconnected during the 500ms delay after `changedConnectionCallbacks`
+  - **Symptom**: Silent failures when the connection times out before the delayed task executes, causing sendToInternet to fail
+  - **Solution**: Added connection validation before sending bridge status:
+    - Check `findRoute()` and `conn->connected()` before attempting to send
+    - Use direct high-priority send via `conn->addMessage(msg, true)` to avoid redundant routing lookup
+    - Added debug logging for cancelled sends to aid troubleshooting
+  - **Impact**: Improved reliability of sendToInternet by ensuring bridge status is only sent to active connections
+
+- **Isolated Bridge Retry Mechanism** (#225) - Fixed isolated bridge retry when mesh network not found
+  - Nodes that fail initial bridge setup can now retry automatically via mesh connection monitoring
+  - **Impact**: More reliable bridge establishment in challenging network conditions
+
+- **Isolated Bridge Retry Delay After Failed Promotion** - Fixed slow retry after failed bridge promotion
+  - **Root Cause**: When bridge promotion fails, `init()` is called which resets `consecutiveEmptyScans` to 0. The isolated retry task would then wait for 6+ new empty scans (90 seconds) before retrying.
+  - **Symptom**: After a failed bridge promotion, retries only happen every ~2 minutes instead of ~60 seconds
+  - **Solution**: Added `_isolatedRetryPending` flag that is set when promotion fails. This flag allows the next retry attempt to skip the empty scan threshold check.
+  - **Impact**: Faster retry after failed promotion - retries happen at the normal 60 second interval instead of waiting for scan accumulation
+
 ## [1.9.4] - 2025-12-03
 
 ### Fixed

package/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-We try to follow the [git flow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) development model. Which means that we have a `develop` branch and `master` branch. All development is done under feature branches, which are (when finished) merged into the development branch. When a new version is released we merge the `develop` branch into the `master` branch.
+We try to follow the [git flow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) development model. Which means that we have a `develop` branch and `main` branch. All development is done under feature branches, which are (when finished) merged into the development branch. When a new version is released we merge the `develop` branch into the `main` branch.
 
 ## Git flow
 
@@ -8,9 +8,9 @@ If you would like to use [git flow tools](http://danielkummer.github.io/git-flow
 
 ## Submit a pull request:
 
-* If your push triggered a 'you just pushed...' message from GitLab then click on the button provided by that pop up to create a pull request.
+* If your push triggered a 'you just pushed...' message from GitHub then click on the button provided by that pop up to create a pull request.
 * If not, then create a pull request and point it to your branch.
-* Make sure that you're attempting to merge into `develop` and not `master`.
+* Make sure that you're attempting to merge into `develop` and not `main`.
 * Get your code reviewed by another contributor. If there are no contributors who possess the same set of skills then get them to review it anyway but explain what the code does beforehand and why. Use it as an opportunity for discussion around the feature set, to transfer knowledge, and to possibly [rubber duck](https://en.wikipedia.org/wiki/Rubber_duck_debugging) your code.
 * Once the code is reviewed then have your reviewer merge your code.
 

package/README.md

@@ -4,7 +4,7 @@
 
 <div align="center">
 
-**Version 1.9.2** - Consolidated release across all distribution channels
+**Version 1.9.6** - Latest release with TCP connection improvements and documentation updates
 
 [![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)
@@ -418,7 +418,7 @@ void loop() {
 }
 
 void receivedCallback(uint32_t from, String& msg) {
-    DynamicJsonDocument doc(1024);
+    JsonDocument doc;  // ArduinoJson v7
     deserializeJson(doc, msg);
     
     if (doc["type"] == 200) { // SensorPackage
@@ -553,15 +553,24 @@ These are the message types used by applications built on painlessMesh:
 - **Event Coordination** - Synchronized displays, distributed processing
 - **Bridge Networks** - Connect mesh to WiFi/Internet/MQTT - [📖 Bridge Guide](BRIDGE_TO_INTERNET.md)
 
-## Latest Release: v1.9.0 (November 30, 2025)
+## Latest Release: v1.9.6 (December 10, 2025)
 
-**Major Update: Improved Bridge Detection, Consolidated Examples & Documentation**
+**TCP Connection Improvements & Documentation Update**
+
+- ⚡ **TCP Connection Retry Improvements** - Enhanced reliability with exponential backoff (#231)
+  - Increased stabilization delay (100ms → 500ms)
+  - Increased retry delay (500ms → 1000ms) with exponential backoff
+  - More retry attempts (3 → 5) for better connection establishment
+- 📚 **Comprehensive Documentation Review** - Updated README.md for completeness and accuracy
+- 🔄 **Version Consistency** - Aligned version numbers across all distribution channels
+
+**Recent Key Features (v1.9.0 - v1.9.5):**
 
 - 🔍 **Mesh Connectivity Detection** - New `hasActiveMeshConnections()` and `getLastKnownBridge()` APIs
 - 🌉 **Improved Bridge Detection** - `getPrimaryBridge()` returns last known bridge when disconnected
-- ⚡ **Election Guard** - Skip election trigger when node is disconnected from mesh
-- 📦 **Consolidated Examples** - Reduced from 32 to 14 essential examples
-- 📚 **Cleaned Documentation** - Removed obsolete docs, kept only essentials
+- ⚡ **Enhanced TCP Reliability** - Exponential backoff and increased retries for mesh connections
+- 🛡️ **Race Condition Fixes** - Improved bridge status and connection validation
+- 📦 **Consolidated Examples** - Streamlined to 14 essential examples
 - ⚙️ **Configurable Election Timing** - Prevent split-brain with `setElectionStartupDelay()` and `setElectionRandomDelay()`
 
 **[📋 Full CHANGELOG](CHANGELOG.md)**
@@ -572,7 +581,7 @@ These are the message types used by applications built on painlessMesh:
 - **[Common Issues](docs/troubleshooting/common-issues.md)** - Troubleshooting guide
 - **[GitHub Issues](https://github.com/Alteriom/painlessMesh/issues)** - Bug reports and feature requests  
 - **[Community Forum](https://groups.google.com/forum/#!forum/painlessmesh-user)** - Community support
-- **[API Documentation](http://painlessmesh.gitlab.io/painlessMesh/index.html)** - Generated API docs
+- **[API Documentation](https://alteriom.github.io/painlessMesh/#/api/doxygen)** - Generated API docs
 
 ## Development
 
@@ -590,7 +599,7 @@ run-parts --regex catch_ bin/  # Run tests
 ### Requirements
 
 - **ESP32/ESP8266**: Arduino Core 2.0.0+
-- **Dependencies**: ArduinoJson 6.x, TaskScheduler 3.x  
+- **Dependencies**: ArduinoJson 7.x, TaskScheduler 4.x  
 - **Development**: CMake, Ninja, Boost (for desktop testing)
 
 ### CI/CD Pipeline
@@ -628,7 +637,7 @@ See [RELEASE_GUIDE.md](RELEASE_GUIDE.md) for complete release documentation.
 
 ## Contributing
 
-We try to follow the [git flow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) development model. Which means that we have a `develop` branch and `master` branch. All development is done under feature branches, which are (when finished) merged into the development branch. When a new version is released we merge the `develop` branch into the `master` branch. For more details see the [CONTRIBUTING](https://gitlab.com/painlessMesh/painlessMesh/blob/master/CONTRIBUTING.md) file.
+We try to follow the [git flow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) development model. Which means that we have a `develop` branch and `main` branch. All development is done under feature branches, which are (when finished) merged into the development branch. When a new version is released we merge the `develop` branch into the `main` branch. For more details see the [CONTRIBUTING.md](CONTRIBUTING.md) file.
 
 ## Funding
 
@@ -726,7 +735,7 @@ Initialize the mesh network. This routine does the following things.
 `ssid` = the name of your mesh.  All nodes share same AP ssid. They are distinguished by BSSID.
 `password` = wifi password to your mesh.
 `port` = the TCP port that you want the mesh server to run on. Defaults to 5555 if not specified.
-[`connectMode`](https://gitlab.com/painlessMesh/painlessMesh/wikis/connect-mode:-WIFI_AP,-WIFI_STA,-WIFI_AP_STA-mode) = switch between WIFI_AP, WIFI_STA and WIFI_AP_STA (default) mode
+`connectMode` = switch between WIFI_AP, WIFI_STA and WIFI_AP_STA (default) mode
 
 #### void painlessMesh::stop()
 
@@ -813,7 +822,7 @@ Return the chipId of the node that we are running on.
 
 Returns the mesh timebase microsecond counter. Rolls over 71 minutes from startup of the first node.
 
-Nodes try to keep a common time base synchronizing to each other using [an SNTP based protocol](https://gitlab.com/painlessMesh/painlessMesh/wikis/mesh-protocol#time-sync)
+Nodes try to keep a common time base synchronizing to each other using an SNTP based protocol
 
 #### bool painlessMesh::startDelayMeas(uint32_t nodeId)
 

package/docs/README.md

@@ -115,7 +115,7 @@ Welcome to the comprehensive documentation for the Alteriom fork of painlessMesh
 ## Quick Links
 
 - **[GitHub Repository](https://github.com/Alteriom/painlessMesh)**
-- **[API Documentation](http://painlessmesh.gitlab.io/painlessMesh/index.html)**
+- **[API Documentation](https://alteriom.github.io/painlessMesh/#/api/doxygen)**
 - **[Community Forum](https://groups.google.com/forum/#!forum/painlessmesh-user)**
 - **[Issue Tracker](https://github.com/Alteriom/painlessMesh/issues)**
 

package/docs/troubleshooting/common-issues.md

@@ -149,6 +149,81 @@ void checkMemory() {
 }
 ```
 
+### TCP Connection Error -14 (ERR_CONN)
+
+**Symptoms:**
+- Serial output shows: `tcp_err(): error trying to connect -14`
+- Nodes get an IP address but fail to establish mesh connection
+- Connection attempts keep failing and retrying
+
+**Cause:**
+
+The error -14 (ERR_CONN in LwIP) indicates a TCP connection failure. This typically occurs when:
+1. The TCP server on the target node is not ready when the connection is attempted
+2. There's a timing issue between WiFi association and TCP readiness
+3. Network stack hasn't fully stabilized after IP acquisition
+4. The target node is overloaded or has resource constraints
+
+**Solutions:**
+
+#### 1. Update AsyncTCP Library (Most Common Fix)
+The error often occurs with older AsyncTCP versions that don't have proper thread safety for ESP32 Arduino Core 3.x:
+
+For PlatformIO:
+```ini
+lib_deps =
+    esp32async/AsyncTCP @ ^3.4.7
+```
+
+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
+
+This helps handle transient timing issues automatically.
+
+#### 3. Check Node Resource Usage
+Monitor memory and ensure nodes aren't overloaded:
+
+```cpp
+void loop() {
+    mesh.update();
+    
+    // Monitor health periodically
+    static unsigned long lastCheck = 0;
+    if (millis() - lastCheck > 10000) {
+        lastCheck = millis();
+        Serial.printf("Free heap: %d, WiFi RSSI: %d\n", 
+                      ESP.getFreeHeap(), WiFi.RSSI());
+    }
+}
+```
+
+#### 4. Ensure Proper Initialization Order
+Make sure the mesh is properly initialized before connections are attempted:
+
+```cpp
+void setup() {
+    Serial.begin(115200);
+    delay(100);  // Let serial initialize
+    
+    mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+    mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+    // Add callbacks after init
+    mesh.onReceive(&receivedCallback);
+    mesh.onNewConnection(&newConnectionCallback);
+}
+```
+
+#### 5. Check WiFi Signal Strength
+Poor signal can cause connection timing issues:
+- Ensure nodes are within good WiFi range
+- Check for interference from other 2.4GHz devices
+- Monitor RSSI values (should be above -80 dBm for reliable connections)
+
 ## Message Delivery Issues
 
 ### Messages Not Being Received

package/examples/bridge_failover/bridge_failover.ino

@@ -15,6 +15,9 @@
 //
 // To send data to the Internet from a regular node:
 //   1. Use mesh.sendToInternet() to route through a gateway
+//      - Call mesh.enableSendToInternet() on the sending node after mesh.init()
+//      - Bridge nodes (this example) do NOT need enableSendToInternet() - they route automatically
+//      - See examples/sendToInternet/sendToInternet.ino for complete usage
 //   2. Use initAsSharedGateway() so all nodes have router access
 //      NOTE: initAsSharedGateway() requires ROUTER credentials:
 //      mesh.initAsSharedGateway(MESH_PREFIX, MESH_PASSWORD,

package/examples/sendToInternet/sendToInternet.ino

@@ -24,9 +24,27 @@
 // - Smart home sensors reporting to home automation servers
 //
 // Prerequisites:
-// - At least one node must be a bridge/gateway with Internet access
-// - OR use initAsSharedGateway() so all nodes have Internet
-// - Enable sendToInternet() after mesh.init(): mesh.enableSendToInternet()
+//
+// 1. GATEWAY SETUP (Choose one approach):
+//
+//    Option A - Dedicated Bridge (Recommended):
+//    - Use initAsBridge() on ONE node (see examples/bridge/bridge.ino)
+//    - The bridge node automatically handles Internet routing
+//
+//    Option B - Shared Gateway (All nodes have router access):
+//    - Use initAsSharedGateway() on ALL nodes (see examples/sharedGateway/sharedGateway.ino)
+//    - Requires ROUTER_SSID and ROUTER_PASSWORD on every node
+//    - All nodes connect directly to the router for Internet access
+//
+//    Option C - Failover Bridge (High Availability):
+//    - Use bridge_failover example unchanged (see examples/bridge_failover/bridge_failover.ino)
+//    - Automatically elects backup bridges if primary fails
+//    - Works as-is without any modifications needed!
+//
+// 2. SENDING NODE SETUP:
+//    - Call mesh.enableSendToInternet() AFTER mesh.init() on nodes that will SEND requests
+//    - Bridge nodes do NOT need to call enableSendToInternet() - they route automatically
+//    - This example shows how to enable it in the setup() function below
 //
 // For Callmebot WhatsApp API:
 // - Get your API key from https://www.callmebot.com/blog/free-api-whatsapp-messages/

package/library.json

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

package/library.properties

@@ -1,5 +1,5 @@
 name=Alteriom PainlessMesh
-version=1.9.4
+version=1.9.6
 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.4",
+  "version": "1.9.6",
   "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/arduino/wifi.hpp

@@ -229,8 +229,9 @@ class Mesh : public painlessmesh::Mesh<Connection> {
       
       // Only retry when isolated (no mesh connections found)
       if (this->hasActiveMeshConnections()) {
-        // Reset retry counter when mesh is active
+        // Reset retry counter and pending flag when mesh is active (no longer isolated)
         _isolatedBridgeRetryAttempts = 0;
+        _isolatedRetryPending = false;
         return;
       }
       
@@ -249,13 +250,17 @@ class Mesh : public painlessmesh::Mesh<Connection> {
       
       // Check if mesh network exists on any channel before trying to become bridge
       // If mesh exists but we can't connect, don't try to become bridge
+      // Skip this check if we already confirmed isolation from a previous failed attempt
       uint16_t emptyScans = stationScan.getConsecutiveEmptyScans();
-      if (emptyScans < ISOLATED_BRIDGE_RETRY_SCAN_THRESHOLD) {
+      if (!_isolatedRetryPending && emptyScans < ISOLATED_BRIDGE_RETRY_SCAN_THRESHOLD) {
         Log(CONNECTION, "Isolated bridge retry: Only %d empty scans, waiting for more scans\n",
             emptyScans);
         return;
       }
       
+      // Clear the pending flag now that we're proceeding
+      _isolatedRetryPending = false;
+      
       Log(CONNECTION, "Isolated bridge retry: Node isolated with %d empty scans, attempting bridge promotion\n",
           emptyScans);
       
@@ -703,6 +708,15 @@ class Mesh : public painlessmesh::Mesh<Connection> {
    * - Needs access to mesh state and callbacks
    * - Moving it would increase complexity without clear benefits
    * - The existing design keeps connection logic cohesive with WiFi management
+   * 
+   * TCP Connection Retry:
+   * The TCP connection now includes automatic retry with exponential backoff.
+   * If the initial connection fails (error -14 ERR_CONN or other errors), 
+   * the system will retry up to TCP_CONNECT_MAX_RETRIES times before 
+   * triggering a full WiFi reconnection cycle. This helps handle:
+   * - Timing issues where TCP server is not ready immediately
+   * - Network stack stabilization after IP acquisition
+   * - Transient network conditions
    */
   void tcpConnect() {
     using namespace logger;
@@ -715,9 +729,26 @@ class Mesh : public painlessmesh::Mesh<Connection> {
       IPAddress targetIP = stationScan.manualIP ? stationScan.manualIP : WiFi.gatewayIP();
       uint16_t targetPort = stationScan.port;
       
-      AsyncClient *pConn = new AsyncClient();
-      painlessmesh::tcp::connect<Connection, painlessmesh::Mesh<Connection>>(
-          (*pConn), targetIP, targetPort, (*this));
+      Log(CONNECTION, "tcpConnect(): Connecting to %s:%d\n", 
+          targetIP.toString().c_str(), targetPort);
+      
+      // Add a small stabilization delay before attempting TCP connection
+      // This helps prevent error -14 (ERR_CONN) by allowing the network stack
+      // and TCP server to be fully ready. The delay is added via task scheduler
+      // to avoid blocking the event loop.
+      this->addTask(painlessmesh::tcp::TCP_CONNECT_STABILIZATION_DELAY_MS, TASK_ONCE, 
+          [this, targetIP, targetPort]() {
+            // Verify WiFi is still connected after the delay
+            if (WiFi.status() != WL_CONNECTED || !WiFi.localIP()) {
+              Log(CONNECTION, "tcpConnect(): WiFi disconnected during stabilization delay\n");
+              return;
+            }
+            
+            Log(CONNECTION, "tcpConnect(): Starting TCP connection after stabilization\n");
+            AsyncClient *pConn = new AsyncClient();
+            painlessmesh::tcp::connect<Connection, painlessmesh::Mesh<Connection>>(
+                (*pConn), targetIP, targetPort, (*this));
+          });
     } else {
       Log(ERROR, "tcpConnect(): err Something unexpected in tcpConnect()\n");
     }
@@ -1129,6 +1160,16 @@ class Mesh : public painlessmesh::Mesh<Connection> {
       // Small delay to ensure connection is fully stable, then send directly to the new node
       // This avoids issues with time sync blocking broadcast messages
       this->addTask(500, TASK_ONCE, [this, nodeId]() {
+        // Check if the connection is still valid - the node may have disconnected
+        // during the 500ms delay (e.g., due to timeout or network issues)
+        // This prevents attempting to send messages to dropped connections
+        // findRoute returns nullptr if node is not in the routing table
+        auto conn = router::findRoute<Connection>((*this), nodeId);
+        if (!conn || !conn->connected()) {
+          Log(CONNECTION, "Bridge status send cancelled: Node %u no longer connected\n", nodeId);
+          return;
+        }
+        
         // Create bridge status message
         JsonDocument doc;
         JsonObject obj = doc.to<JsonObject>();
@@ -1154,10 +1195,11 @@ class Mesh : public painlessmesh::Mesh<Connection> {
         Log(CONNECTION, "Sending bridge status directly to node %u (Internet: %s)\n",
             nodeId, hasInternet ? "YES" : "NO");
         
-        // Send directly to the new node using raw message to preserve type BRIDGE_STATUS
-        // Using sendSingle() would wrap it in type 1 (SINGLE) and hide type BRIDGE_STATUS
-        protocol::Variant variant(msg);
-        router::send<Connection>(variant, (*this));
+        // Send directly to the connection with high priority
+        // This ensures the message is sent immediately rather than queued
+        // The JSON message format is the same as what router::send() produces
+        // (Variant serializes to the same JSON format we built manually)
+        conn->addMessage(msg, true);
       });
     });
     
@@ -1691,6 +1733,10 @@ class Mesh : public painlessmesh::Mesh<Connection> {
       this->setRouterCredentials(routerSSID, routerPassword);
       this->enableBridgeFailover(true);
       
+      // Set flag to skip empty scan check on next retry attempt
+      // since we already confirmed isolation before this failed attempt
+      _isolatedRetryPending = true;
+      
       // Notify via callback
       if (bridgeRoleChangedCallback) {
         bridgeRoleChangedCallback(false, "Isolated bridge promotion failed - router unreachable");
@@ -1953,6 +1999,7 @@ class Mesh : public painlessmesh::Mesh<Connection> {
   // Isolated bridge retry state and configuration
   uint8_t _isolatedBridgeRetryAttempts = 0;
   uint32_t _isolatedBridgeRetryResetTime = 0;  // Time when retry counter can be reset
+  bool _isolatedRetryPending = false;  // Flag to skip empty scan check after failed promotion
   static const uint8_t MAX_ISOLATED_BRIDGE_RETRY_ATTEMPTS = 5;  // Max retry attempts before waiting
   static const uint32_t isolatedBridgeRetryIntervalMs = 60000;  // Retry every 60 seconds
   static const uint32_t isolatedBridgeRetryResetIntervalMs = 300000;  // Reset counter after 5 minutes

package/src/painlessMeshSTA.cpp

@@ -239,13 +239,24 @@ void ICACHE_FLASH_ATTR StationScan::connectToAP() {
           mesh->apInit(mesh->getNodeId());
           Log(CONNECTION, "connectToAP(): AP restarted on channel %d\n", detectedChannel);
         }
+        // Reset counter only when mesh is found on a new channel
+        // This allows isolated bridge retry to continue when mesh is truly absent
+        consecutiveEmptyScans = 0;
       } else if (detectedChannel == 0) {
         Log(CONNECTION,
             "connectToAP(): Mesh not found on any channel during re-scan\n");
+        // Do NOT reset consecutiveEmptyScans here - mesh is still absent
+        // This allows isolated bridge retry mechanism to trigger when
+        // the counter exceeds ISOLATED_BRIDGE_RETRY_SCAN_THRESHOLD
+      } else {
+        // detectedChannel == mesh->_meshChannel
+        // Mesh found on same channel we're already on - no channel change needed
+        // Reset counter since mesh exists, nodes may appear in subsequent scans
+        Log(CONNECTION,
+            "connectToAP(): Mesh found on current channel %d, no channel change needed\n",
+            detectedChannel);
+        consecutiveEmptyScans = 0;
       }
-      
-      // Reset counter after re-scan attempt
-      consecutiveEmptyScans = 0;
     }
     
     if (WiFi.status() == WL_CONNECTED &&

package/src/painlessmesh/mesh.hpp

@@ -3238,7 +3238,7 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
       Mesh &, protocol::NodeTree, std::shared_ptr<T> conn);
   friend void painlessmesh::tcp::initServer<T, Mesh>(AsyncServer &, Mesh &);
   friend void painlessmesh::tcp::connect<T, Mesh>(AsyncClient &, IPAddress,
-                                                  uint16_t, Mesh &);
+                                                  uint16_t, Mesh &, uint8_t);
 };
 
 class Connection : public painlessmesh::layout::Neighbour,

package/src/painlessmesh/tcp.hpp

@@ -10,6 +10,17 @@
 
 namespace painlessmesh {
 namespace tcp {
+
+// TCP connection retry configuration
+// These can be tuned for different network conditions
+// Increased values to better handle real-world mesh network conditions where:
+// - TCP server may need more time to be ready after AP initialization
+// - Network stack stabilization takes longer on some hardware
+// - Multiple nodes connecting simultaneously can cause temporary overload
+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)
+
 inline uint32_t encodeNodeId(const uint8_t *hwaddr) {
   using namespace painlessmesh::logger;
   Log(GENERAL, "encodeNodeId():\n");
@@ -41,12 +52,96 @@ void initServer(AsyncServer &server, M &mesh) {
   server.begin();
 }
 
+/**
+ * Establish TCP connection with retry mechanism and exponential backoff
+ * 
+ * This function attempts to connect to the mesh network via TCP.
+ * If the connection fails (error -14 ERR_CONN or other errors), it will
+ * retry up to TCP_CONNECT_MAX_RETRIES times before triggering a full
+ * WiFi reconnection cycle.
+ * 
+ * The retry mechanism helps handle timing issues where:
+ * - The TCP server may not be immediately ready after AP initialization
+ * - Network stack may need time to stabilize after IP acquisition
+ * - Transient network conditions may cause temporary connection failures
+ * - Multiple nodes connecting simultaneously may cause temporary overload
+ * 
+ * Exponential backoff is used to increase delay between retries, which:
+ * - Gives the TCP server more time to recover from overload
+ * - Reduces network contention when multiple nodes are retrying
+ * - Improves overall connection success rate in congested networks
+ * 
+ * @param client AsyncClient to use for connection
+ * @param ip Target IP address
+ * @param port Target port
+ * @param mesh Reference to mesh instance for callbacks
+ * @param retryCount Current retry attempt (default 0, used internally for recursion)
+ */
 template <class T, class M>
-void connect(AsyncClient &client, IPAddress ip, uint16_t port, M &mesh) {
+void connect(AsyncClient &client, IPAddress ip, uint16_t port, M &mesh, 
+             uint8_t retryCount = 0) {
   using namespace logger;
-  client.onError([&mesh](void *, AsyncClient *client, int8_t err) {
+  
+  Log(CONNECTION, "tcp::connect(): Attempting connection to port %d (attempt %d/%d)\n",
+      port, retryCount + 1, TCP_CONNECT_MAX_RETRIES + 1);
+  
+  // Store retry count and connection parameters for the error handler
+  // We need to capture these by value since they're used in the lambda
+  client.onError([&mesh, ip, port, retryCount](void *, AsyncClient *client, int8_t err) {
     if (mesh.semaphoreTake()) {
-      Log(CONNECTION, "tcp_err(): error trying to connect %d\n", err);
+      Log(CONNECTION, "tcp_err(): error trying to connect %d (attempt %d/%d)\n", 
+          err, retryCount + 1, TCP_CONNECT_MAX_RETRIES + 1);
+      
+      // Check if we have retries left - retry logic only works on real hardware
+      // In test environment (PAINLESSMESH_BOOST), fall through to dropped connection
+      // Note: ip and port are used in retry logic below, suppress unused warnings for test builds
+      (void)ip;
+      (void)port;
+#if !defined(PAINLESSMESH_BOOST) && (defined(ESP32) || defined(ESP8266))
+      if (retryCount < TCP_CONNECT_MAX_RETRIES) {
+        // Calculate delay with exponential backoff: base_delay * 2^retryCount
+        // This gives increasing time between retries as failures accumulate:
+        // - retryCount=0: 1000ms * 1 = 1s
+        // - retryCount=1: 1000ms * 2 = 2s
+        // - retryCount=2: 1000ms * 4 = 4s
+        // - retryCount=3: 1000ms * 8 = 8s (capped at 8)
+        // - retryCount=4: 1000ms * 8 = 8s (capped at 8)
+        // Cap multiplier at 8 to prevent excessive delays
+        uint8_t backoffMultiplier = (retryCount < 3) ? (1U << retryCount) : 8;
+        uint32_t retryDelay = TCP_CONNECT_RETRY_DELAY_MS * backoffMultiplier;
+        
+        Log(CONNECTION, "tcp_err(): Scheduling retry in %u ms (backoff x%d)\n", 
+            retryDelay, backoffMultiplier);
+        
+        // Schedule a retry after a delay using the mesh's task scheduler
+        // Note: &mesh is captured by reference because:
+        // 1. Mesh is a singleton that lives for the program's lifetime
+        // 2. The task scheduler belongs to the mesh, so mesh is always valid when task runs
+        // 3. Copying the mesh object is not possible/allowed
+        // Recursion depth is strictly bounded by TCP_CONNECT_MAX_RETRIES (default: 5)
+        mesh.addTask([&mesh, ip, port, retryCount]() {
+          Log(CONNECTION, "tcp_err(): Retrying TCP connection...\n");
+          
+          // Create a new AsyncClient for the retry
+          // On success, the client is managed by the Connection object
+          // On failure, the onError handler for the new client will handle cleanup
+          AsyncClient *pRetryConn = new AsyncClient();
+          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;
+        
+        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;
+#endif
       mesh.droppedConnectionCallbacks.execute(0, true);
       mesh.semaphoreGive();
     }