@alteriom/painlessmesh 1.9.0 → 1.9.1

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.1] - 2025-12-01
+
+### Added
+
+- **Isolated Bridge Retry Mechanism** - Nodes that fail initial bridge setup can now retry automatically
+  - New `attemptIsolatedBridgePromotion()` method for direct bridge promotion when isolated
+  - Periodic retry task runs every 60 seconds when node is isolated (no mesh connections)
+  - Requires 6 consecutive empty mesh scans before attempting retry
+  - Limited to 5 actual retry attempts before 5-minute cooldown
+  - Counter resets on success, mesh reconnection, or after cooldown
+  - **Impact**: Fixes issue where nodes with `INITIAL_BRIDGE=true` that fail router connection
+    would never retry becoming a bridge (endless "Bridge monitor: Skipping - no active mesh connections")
+
+- **Comprehensive Test Coverage** - Added tests for all woodlist use cases
+  - Use Case 1: INITIAL_BRIDGE=true with router temporarily unavailable
+  - Use Case 2: Regular node with no mesh found - isolated retry
+  - Use Case 3: Router association refused error handling
+  - Use Case 4: Node loses mesh connection to bridge
+  - Use Case 5: Multiple retry attempts with cooldown
+  - Use Case 6: Correct serial output for bridge failure
+
+### Fixed
+
+- **Bridge Retry for Isolated Nodes** (#212) - Fixed nodes not retrying bridge connection
+  - **Root Cause**: Bridge monitor task skips isolated nodes to prevent split-brain scenarios,
+    but this prevented retry when initial bridge setup fails
+  - **Symptom**: Endless "Bridge monitor: Skipping - no active mesh connections" log messages
+  - **Solution**: Added separate isolated bridge retry mechanism that activates when:
+    - Node has router credentials configured
+    - Node is isolated (no mesh connections)
+    - Multiple empty scans have occurred (mesh not found)
+  - **Behavior**: Node scans for router, checks RSSI, and attempts direct bridge promotion
+  - Addresses feedback from @woodlist regarding failed initial bridge setup scenarios
+
+### Changed
+
+- **Updated bridge_failover Example** - Added documentation about automatic retry behavior
+  - Example now notes that isolated nodes will retry bridge connection periodically
+  - Clearer messaging about fallback and retry mechanisms
+
 ## [1.9.0] - 2025-11-30
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@
 
 <div align="center">
 
-**Version 1.9.0** - Major update with improved bridge detection, consolidated examples, and cleaned documentation
+**Version 1.9.1** - Isolated bridge retry mechanism for failed initial bridge setup
 
 [![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/examples/bridge_failover/README.md

@@ -483,6 +483,38 @@ evaluateElection(): 1 candidates
 - Ensure bridge timeout passed (60 seconds)
 - Verify nodes can see router (RSSI scan)
 
+### Isolated Node Never Retries Bridge Connection (Fixed in v1.9.1)
+
+**Symptoms**: Node with `INITIAL_BRIDGE=true` fails to connect to router at startup, then endlessly logs "Bridge monitor: Skipping - no active mesh connections" without ever retrying to become a bridge.
+
+**Root Cause (Before v1.9.1)**: 
+When a node configured as `INITIAL_BRIDGE=true` failed to connect to the router during setup(), it correctly fell back to regular node mode with failover enabled. However, the bridge monitor task skipped isolated nodes (those with no mesh connections) to prevent split-brain scenarios. This prevented the node from ever retrying to become a bridge.
+
+**Solution (Automatic in v1.9.1+)**:
+A new isolated bridge retry mechanism now handles this case:
+1. Periodic task runs every 60 seconds when the node is isolated
+2. After 6 consecutive empty mesh scans, retry is triggered
+3. Node scans for router signal and checks minimum RSSI threshold (-80 dBm)
+4. If router is visible with adequate signal, attempts direct bridge promotion
+5. Limited to 5 retry attempts before 5-minute cooldown
+6. Counter resets on success, mesh reconnection, or after cooldown
+
+**Expected Behavior** (v1.9.1+):
+```
+Isolated bridge retry: Node isolated with 6 empty scans, attempting bridge promotion
+=== Isolated Bridge Promotion Attempt ===
+Attempt 1 of 5
+attemptIsolatedBridgePromotion(): Router visible with RSSI -45 dBm
+Attempting direct bridge promotion (bypassing election)
+✓ Isolated bridge promotion complete on channel 6
+```
+
+**Manual Solutions**:
+- Update to painlessMesh v1.9.1 or later
+- Ensure router credentials are configured: `mesh.setRouterCredentials()`
+- Ensure failover is enabled: `mesh.enableBridgeFailover(true)`
+- Check router is visible and signal strength is adequate (>= -80 dBm)
+
 ### Multiple Nodes Claim Bridge Role
 
 **Symptoms**: Split-brain scenario with multiple bridges

package/examples/bridge_failover/bridge_failover.ino

@@ -35,6 +35,8 @@
 // - Seamless promotion to bridge role
 // - Bridge takeover announcements
 // - Automatic mesh channel detection for bridge discovery
+// - Isolated node retry: Nodes that fail initial bridge setup will
+//   periodically retry connecting to the router when no mesh is found
 //
 // Important Note:
 // Regular nodes MUST use channel auto-detection (channel=0) to discover
@@ -145,6 +147,7 @@ void setup() {
       mesh.setElectionTimeout(5000);
       
       Serial.println("✓ Running as regular node - will auto-promote when router available");
+      Serial.println("Note: If isolated (no mesh found), will retry bridge connection periodically");
     }
   } else {
     Serial.println("Mode: REGULAR NODE (Failover Enabled)");

package/library.json

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

package/library.properties

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

@@ -205,6 +205,71 @@ class Mesh : public painlessmesh::Mesh<Connection> {
       }
     });
 
+    // Add separate periodic task for isolated bridge retry
+    // This handles the case where a node:
+    // - Has router credentials configured
+    // - Is isolated (no mesh connections)
+    // - Should attempt to become a bridge directly
+    // This is different from the election mechanism which requires mesh connectivity
+    this->addTask(isolatedBridgeRetryIntervalMs, TASK_FOREVER, [this]() {
+      // Only retry if failover is enabled and we have credentials
+      if (!bridgeFailoverEnabled || !routerCredentialsConfigured) {
+        return;
+      }
+      
+      // Don't retry if we're already a bridge
+      if (this->isBridge()) {
+        return;
+      }
+      
+      // Skip during startup period
+      if (millis() < electionStartupDelayMs) {
+        return;
+      }
+      
+      // Only retry when isolated (no mesh connections found)
+      if (this->hasActiveMeshConnections()) {
+        // Reset retry counter when mesh is active
+        _isolatedBridgeRetryAttempts = 0;
+        return;
+      }
+      
+      // Limit retry attempts with reset after timeout
+      if (_isolatedBridgeRetryAttempts >= MAX_ISOLATED_BRIDGE_RETRY_ATTEMPTS) {
+        // Check if enough time has passed to reset the counter
+        if (millis() > _isolatedBridgeRetryResetTime) {
+          Log(CONNECTION, "Isolated bridge retry: Reset timeout reached, resetting attempt counter\n");
+          _isolatedBridgeRetryAttempts = 0;
+        } else {
+          Log(CONNECTION, "Isolated bridge retry: Max attempts (%d) reached, reset in %u seconds\n",
+              MAX_ISOLATED_BRIDGE_RETRY_ATTEMPTS, (_isolatedBridgeRetryResetTime - millis()) / 1000);
+          return;
+        }
+      }
+      
+      // 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
+      uint16_t emptyScans = stationScan.getConsecutiveEmptyScans();
+      if (emptyScans < ISOLATED_BRIDGE_RETRY_SCAN_THRESHOLD) {
+        Log(CONNECTION, "Isolated bridge retry: Only %d empty scans, waiting for more scans\n",
+            emptyScans);
+        return;
+      }
+      
+      Log(CONNECTION, "Isolated bridge retry: Node isolated with %d empty scans, attempting bridge promotion\n",
+          emptyScans);
+      
+      // Attempt to become bridge directly (bypassing election since we're isolated)
+      // Only increment retry counter if we actually attempted promotion
+      if (this->attemptIsolatedBridgePromotion()) {
+        _isolatedBridgeRetryAttempts++;
+        // Set reset time when reaching max attempts
+        if (_isolatedBridgeRetryAttempts >= MAX_ISOLATED_BRIDGE_RETRY_ATTEMPTS) {
+          _isolatedBridgeRetryResetTime = millis() + isolatedBridgeRetryResetIntervalMs;
+        }
+      }
+    });
+
     tcpServerInit();
     eventHandleInit();
 
@@ -1529,6 +1594,95 @@ class Mesh : public painlessmesh::Mesh<Connection> {
     });
   }
 
+  /**
+   * Attempt to promote an isolated node to bridge
+   * 
+   * This method handles the case where a node is isolated (no mesh connections)
+   * but has router credentials. Unlike the election-based promotion, this
+   * directly attempts to connect to the router without requiring mesh connectivity.
+   * 
+   * This is useful for:
+   * - Nodes that failed initial bridge setup and need to retry
+   * - Nodes that are the first to start and no mesh exists yet
+   * - Recovery scenarios where mesh network is unavailable
+   *
+   * @return true if promotion was attempted (regardless of success), false if skipped
+   */
+  bool attemptIsolatedBridgePromotion() {
+    using namespace logger;
+    
+    Log(CONNECTION, "=== Isolated Bridge Promotion Attempt ===\n");
+    Log(CONNECTION, "Attempt %d of %d\n", _isolatedBridgeRetryAttempts + 1, MAX_ISOLATED_BRIDGE_RETRY_ATTEMPTS);
+    
+    // First, scan for router to check if it's visible
+    int8_t routerRSSI = scanRouterSignalStrength(routerSSID);
+    
+    if (routerRSSI == 0) {
+      Log(CONNECTION, "attemptIsolatedBridgePromotion(): Router %s not visible\n", routerSSID.c_str());
+      return false;  // Don't count as an attempt - router not visible
+    }
+    
+    // Check minimum RSSI threshold for isolated promotion
+    if (routerRSSI < minimumBridgeRSSI) {
+      Log(CONNECTION, "attemptIsolatedBridgePromotion(): Router RSSI %d dBm below threshold %d dBm\n",
+          routerRSSI, minimumBridgeRSSI);
+      return false;  // Don't count as an attempt - signal too weak
+    }
+    
+    Log(CONNECTION, "attemptIsolatedBridgePromotion(): Router visible with RSSI %d dBm\n", routerRSSI);
+    Log(CONNECTION, "Attempting direct bridge promotion (bypassing election)\n");
+    
+    // Save current mesh configuration
+    uint8_t savedChannel = _meshChannel;
+    
+    // Stop current mesh operations
+    this->stop();
+    delay(1000);
+    
+    // Attempt to initialize as bridge
+    bool bridgeInitSuccess = this->initAsBridge(_meshSSID, _meshPassword, routerSSID, routerPassword,
+                                                 mScheduler, _meshPort);
+    
+    if (!bridgeInitSuccess) {
+      Log(ERROR, "✗ Isolated bridge promotion failed - router unreachable\n");
+      Log(ERROR, "Reverting to regular node on channel %d\n", savedChannel);
+      
+      // Re-initialize as regular node on the original channel
+      this->init(_meshSSID, _meshPassword, mScheduler, _meshPort, WIFI_AP_STA,
+                 savedChannel, _meshHidden, MAX_CONN);
+      
+      // Re-configure router credentials for future retry attempts
+      this->setRouterCredentials(routerSSID, routerPassword);
+      this->enableBridgeFailover(true);
+      
+      // Notify via callback
+      if (bridgeRoleChangedCallback) {
+        bridgeRoleChangedCallback(false, "Isolated bridge promotion failed - router unreachable");
+      }
+      
+      return true;  // Count as an attempt - we tried but failed
+    }
+    
+    // Success! Reset retry counter
+    _isolatedBridgeRetryAttempts = 0;
+    lastRoleChangeTime = millis();
+    
+    Log(STARTUP, "✓ Isolated bridge promotion complete on channel %d\n", _meshChannel);
+    
+    // Notify via callback
+    if (bridgeRoleChangedCallback) {
+      bridgeRoleChangedCallback(true, "Isolated node promoted to bridge");
+    }
+    
+    // Send bridge status announcement to attract other nodes
+    this->addTask(3000, TASK_ONCE, [this]() {
+      Log(STARTUP, "Sending bridge status announcement on channel %d\n", _meshChannel);
+      this->sendBridgeStatus();
+    });
+    
+    return true;  // Count as an attempt - we succeeded
+  }
+
   /**
    * Handle received bridge election package
    * Called by package handler when election message arrives
@@ -1760,6 +1914,14 @@ class Mesh : public painlessmesh::Mesh<Connection> {
   std::vector<BridgeCandidate> electionCandidates;
   std::function<void(bool isBridge, TSTRING reason)> bridgeRoleChangedCallback;
 
+  // Isolated bridge retry state and configuration
+  uint8_t _isolatedBridgeRetryAttempts = 0;
+  uint32_t _isolatedBridgeRetryResetTime = 0;  // Time when retry counter can be reset
+  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
+  static const uint16_t ISOLATED_BRIDGE_RETRY_SCAN_THRESHOLD = 6;  // Require 6 empty scans before retrying
+
   // Multi-bridge coordination state and configuration
  protected:
   bool multiBridgeEnabled = false;