@alteriom/painlessmesh 1.8.4 → 1.8.6

package/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.8.6] - 2025-11-12
+
+### Fixed
+
+- **Bridge Failover Auto-Election (Issue #117)** - Bridge election now triggers when no initial bridge exists
+  - Added periodic monitoring task (30s interval) that detects absence of healthy bridge
+  - Activates after 60s startup grace period to allow network stabilization
+  - Randomized election delay (1-3s) prevents thundering herd problem
+  - Respects existing safeguards: election state, 60s cooldown, router visibility
+  - **Before**: No initial bridge → no election → mesh stays bridgeless indefinitely
+  - **After**: No initial bridge → 60s startup → monitoring detects absence → election triggered → best RSSI node becomes bridge
+  - Fully backward compatible: pre-designated bridge mode continues to work as before
+  - Core fix in `src/arduino/wifi.hpp`
+  - Resolves @woodlist's "Bridge_failover example does not work" issue
+
+### Changed
+
+- **bridge_failover Example Documentation** - Clarified two deployment modes
+  - Auto-Election Mode: All nodes regular (`INITIAL_BRIDGE=false`), RSSI-based election after 60s
+  - Pre-Designated Mode: Traditional single initial bridge setup
+  - Updated README.md with comprehensive auto-election documentation
+  - Enhanced header comments in bridge_failover.ino
+
+### Housekeeping
+
+- Synchronized package-lock.json version to 1.8.5
+
+## [1.8.5] - 2025-11-12
+
+### Fixed
+
+- **ntpTimeSyncBridge and ntpTimeSyncNode Compilation (Issue #108)** - Arduino IDE compilation errors fixed
+  - Fixed include path in ntpTimeSyncBridge.ino from `"examples/alteriom/alteriom_sensor_package.hpp"` to `"alteriom_sensor_package.hpp"`
+  - Fixed include path in ntpTimeSyncNode.ino from `"examples/alteriom/alteriom_sensor_package.hpp"` to `"alteriom_sensor_package.hpp"`
+  - Arduino IDE compiles sketches with sketch directory as working directory, requiring local header files
+  - Resolves @woodlist's compilation error: "No such file or directory"
+  
+- **Arduino String Method Compatibility** - Fixed incompatible method call in wifi.hpp
+  - Changed `stationSSID.empty()` to `stationSSID.isEmpty()` in src/arduino/wifi.hpp line 171
+  - Arduino's String class uses `isEmpty()` method instead of STL's `empty()`
+  - Fixes CI build failures for ESP32/ESP8266 examples
+  - Related to station credentials feature added in #113
+
+### Documentation
+
+- **Example Sketches** - Updated NTP time synchronization examples
+  - ntpTimeSyncBridge now compiles correctly in Arduino IDE
+  - ntpTimeSyncNode now compiles correctly in Arduino IDE
+  - Examples: `examples/ntpTimeSyncBridge/`, `examples/ntpTimeSyncNode/`
+
 ## [1.8.4] - 2025-11-12
 
 ### Fixed

package/docs/design/.gitkeep

@@ -0,0 +1 @@
+Created

package/docs/design/STATION_CREDENTIALS_DESIGN.md

@@ -0,0 +1,182 @@
+# Station Credentials Design Rationale
+
+## Question
+
+Why does `mesh.init()` require a separate `mesh.stationManual()` call to connect to a router, instead of accepting station credentials directly?
+
+## Answer: Multiple Valid Approaches
+
+The library now supports **three approaches** for connecting a bridge node to a router, each with different use cases:
+
+### 1. Separate stationManual() Call (Original Design)
+
+```cpp
+mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT, WIFI_AP_STA, 6);
+mesh.stationManual(STATION_SSID, STATION_PASSWORD);
+mesh.setRoot(true);
+mesh.setContainsRoot(true);
+```
+
+**When to use:**
+- Maximum flexibility - can change router connection without reinitializing mesh
+- Dynamic router selection at runtime
+- Need to call `setHostname()` or other WiFi configuration between init and connection
+- Following existing examples or legacy code
+
+**Advantages:**
+- Separation of concerns: mesh setup vs router connection
+- Can reconnect to different routers without mesh reinitialization
+- More control over connection timing and error handling
+
+### 2. Optional Parameters in init() (New Convenience Feature)
+
+```cpp
+mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT, 
+          WIFI_AP_STA, 6, 0, MAX_CONN,
+          STATION_SSID, STATION_PASSWORD);  // Optional parameters
+mesh.setRoot(true);
+mesh.setContainsRoot(true);
+```
+
+**When to use:**
+- Simple bridge setup with known credentials
+- Static configuration (credentials won't change)
+- Want slightly more concise code
+- Don't need hostname or other WiFi customization
+
+**Advantages:**
+- One line instead of two for basic bridge setup
+- All connection parameters in one place
+- Still maintains full flexibility of other options
+
+### 3. initAsBridge() Method (Recommended for New Projects)
+
+```cpp
+mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
+                  STATION_SSID, STATION_PASSWORD,
+                  &userScheduler, MESH_PORT);
+```
+
+**When to use:**
+- New bridge implementations (recommended)
+- Want automatic channel detection
+- Need simplest possible setup
+- Following modern best practices
+
+**Advantages:**
+- **Automatic channel detection** - no manual channel configuration needed
+- Automatically sets node as root
+- Maintains router connection through channel switches
+- Broadcasts bridge status (Type 610) automatically
+- Comprehensive initialization in one call
+
+## Design Rationale for Original Separation
+
+The original design separated `init()` and `stationManual()` for good architectural reasons:
+
+### 1. Separation of Concerns
+
+**Mesh Setup (`init()`):**
+- Creates mesh network (AP mode)
+- Sets up mesh routing and protocol
+- Configures mesh-specific parameters
+- Lifetime: typically never changes
+
+**Router Connection (`stationManual()`):**
+- Connects to external WiFi (STA mode)
+- Different lifecycle - may connect/disconnect/change
+- Network-specific credentials and settings
+- Can be reconfigured at runtime
+
+This separation allows clean code organization and different lifecycles for each concern.
+
+### 2. Not All Nodes Need Router Connection
+
+In a typical mesh network:
+- **1 bridge node**: Needs router connection (AP+STA mode)
+- **N regular nodes**: Mesh only (AP mode, or AP+STA for mesh connections)
+
+Regular nodes use:
+```cpp
+mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT, WIFI_AP_STA);
+// No stationManual() call - not a bridge
+```
+
+If `init()` always required station credentials, it would be confusing for regular nodes.
+
+### 3. Dynamic Router Switching
+
+Some advanced use cases require changing router connections at runtime:
+
+```cpp
+// Initial setup
+mesh.init(...);
+mesh.stationManual("Router1", "pass1");
+
+// Later, switch to different router
+mesh.stationManual("Router2", "pass2");
+
+// Or respond to failover
+void onRouterDisconnect() {
+    mesh.stationManual(backupSSID, backupPassword);
+}
+```
+
+With station credentials baked into `init()`, this flexibility would be lost.
+
+### 4. Additional WiFi Configuration
+
+Many users need to configure WiFi settings between initialization and connection:
+
+```cpp
+mesh.init(...);
+mesh.setHostname("MESH_BRIDGE");  // Must be before stationManual()
+mesh.stationManual(...);
+```
+
+The separation provides a natural place for these configurations.
+
+### 5. Error Handling and Retry Logic
+
+Separating the calls allows better error handling:
+
+```cpp
+mesh.init(...);  // This typically doesn't fail
+
+// Retry router connection with backoff
+for (int retry = 0; retry < 3; retry++) {
+    if (tryStationConnect()) break;
+    delay(1000 * (retry + 1));
+}
+```
+
+## Comparison Table
+
+| Approach | Setup Complexity | Flexibility | Channel Detection | Best For |
+|----------|-----------------|-------------|-------------------|----------|
+| **stationManual()** | Medium | Highest | Manual | Dynamic configs, legacy code |
+| **init() params** | Low-Medium | High | Manual | Simple static bridges |
+| **initAsBridge()** | Lowest | Medium | Automatic | New projects, recommended |
+
+## Recommendation
+
+**For new projects:** Use `initAsBridge()` - it's the modern, recommended approach with automatic channel detection.
+
+**For existing projects:** The original `init()` + `stationManual()` pattern remains fully supported and appropriate.
+
+**For simple bridges:** The new optional parameters in `init()` provide a middle ground with good flexibility.
+
+All three approaches are valid and will continue to be supported. Choose based on your specific needs.
+
+## Implementation Note
+
+When station credentials are passed to `init()`, the implementation internally calls `stationManual()` after mesh initialization. This maintains consistency and code reuse while providing convenience.
+
+```cpp
+// Inside init() implementation
+if (!stationSSID.empty() && (connectMode & WIFI_STA)) {
+    this->stationManual(stationSSID, stationPassword);
+}
+```
+
+This design ensures all three approaches use the same underlying connection logic.

package/examples/bridge_failover/README.md

@@ -30,10 +30,20 @@ Regular nodes track these broadcasts and detect failures when:
 
 ### 2. Election Trigger
 
-When the primary bridge fails:
+An election is triggered when:
+
+**Scenario 1: No Bridge Exists (Auto-Election Mode)**
+- After 60-second startup period
+- Periodic monitoring (every 30s) detects no healthy bridge
 - Nodes with router credentials configured start an election
 - Nodes without credentials remain passive
 
+**Scenario 2: Bridge Failure**
+- Primary bridge fails or loses Internet connectivity
+- No status received within 60 seconds (configurable timeout)
+- Bridge reports `internetConnected: false`
+- Nodes detect failure and start election
+
 ### 3. Election Protocol
 
 **Step 1: Candidacy Broadcast (Type 611)**
@@ -97,34 +107,77 @@ To prevent oscillation:
 
 ## Setup Instructions
 
-### 1. Flash Initial Bridge Node
+You can choose between two deployment modes:
+
+### Option A: Auto-Election Mode (Recommended)
+
+**Best for**: Equal peers where any node can become the bridge based on signal strength.
+
+1. Keep `INITIAL_BRIDGE = false` on **ALL nodes**
+2. Configure mesh credentials (MESH_PREFIX, MESH_PASSWORD)
+3. Configure router credentials (ROUTER_SSID, ROUTER_PASSWORD)
+4. Flash the same sketch to all ESP32/ESP8266 devices
+5. Power on all nodes simultaneously
+
+**What happens**:
+- Nodes start as regular mesh nodes
+- After 60-second startup period, automatic monitoring begins
+- If no bridge exists, nodes trigger an election
+- Node with best router RSSI wins and becomes bridge
+- Other nodes remain regular with failover capability
+
+**Advantages**:
+- Simpler setup - no need to designate a specific node
+- True dynamic failover - any node can become bridge
+- Best bridge selected based on signal strength
+
+### Option B: Pre-Designated Bridge Mode
+
+**Best for**: When you want a specific node to start as the bridge.
+
+**1. Flash Initial Bridge Node**
 
 1. Set `INITIAL_BRIDGE` to `true`
 2. Configure router credentials
 3. Flash to one ESP32/ESP8266
 4. This node will connect to router and start as bridge
 
-### 2. Flash Regular Nodes
+**2. Flash Regular Nodes**
 
 1. Set `INITIAL_BRIDGE` to `false`
 2. Configure same mesh and router credentials
 3. Flash to other ESP32/ESP8266 devices
 4. These nodes can become bridges via election
 
-### 3. Test Failover
+**Advantages**:
+- Immediate bridge availability (no 60s wait)
+- Predictable initial bridge selection
+- Good for nodes with fixed locations
+
+### Test Failover Scenarios
+
+**Scenario 1: Auto-Election (No Initial Bridge)**
+1. Flash all nodes with `INITIAL_BRIDGE = false`
+2. Power on all nodes
+3. Wait 60 seconds for startup period
+4. Automatic monitoring detects no bridge
+5. Election starts automatically within 30 seconds
+6. Node with best router signal becomes bridge
+7. Monitor serial output to see election process
 
-**Scenario 1: Bridge Goes Offline**
-1. Power off the initial bridge node
+**Scenario 2: Bridge Goes Offline**
+1. Power off the current bridge node (initial or elected)
 2. After 60 seconds, regular nodes detect failure
 3. Election starts automatically
 4. Node with best router signal becomes new bridge
 5. Monitor serial output to see election process
 
-**Scenario 2: Bridge Loses Internet**
-1. Disconnect router from Internet
+**Scenario 3: Bridge Loses Internet**
+1. Disconnect router from Internet (or block bridge node's Internet)
 2. Bridge reports `internetConnected: false`
-3. Election may start (nodes decide if failover needed)
-4. New bridge elected if necessary
+3. Nodes detect loss of Internet via status broadcasts
+4. Election starts to find a node with working Internet
+5. New bridge elected if another node has Internet access
 
 ## Serial Output
 

package/examples/bridge_failover/bridge_failover.ino

@@ -9,14 +9,26 @@
 // - ESP32 or ESP8266
 // - WiFi router with Internet connection
 //
-// Setup:
+// Setup Options:
+//
+// OPTION A - Auto-Election Mode (Recommended):
+// 1. Configure your mesh credentials (MESH_PREFIX, MESH_PASSWORD)
+// 2. Configure your router credentials (ROUTER_SSID, ROUTER_PASSWORD)
+// 3. Keep INITIAL_BRIDGE = false on ALL nodes
+// 4. Flash multiple nodes with this sketch
+// 5. After startup (~60 seconds), nodes will automatically elect a bridge
+//    based on best router signal strength (RSSI)
+//
+// OPTION B - Pre-Designated Bridge Mode:
 // 1. Configure your mesh credentials (MESH_PREFIX, MESH_PASSWORD)
 // 2. Configure your router credentials (ROUTER_SSID, ROUTER_PASSWORD)
-// 3. Flash multiple nodes with this sketch
-// 4. Designate one as the initial bridge by calling mesh.initAsBridge()
-// 5. Other nodes will automatically participate in elections if bridge fails
+// 3. Set INITIAL_BRIDGE = true on ONE node (your designated bridge)
+// 4. Keep INITIAL_BRIDGE = false on all other nodes
+// 5. Flash the nodes - designated bridge starts immediately
+// 6. If designated bridge fails, others will hold election
 //
 // Features Demonstrated:
+// - Automatic bridge election when no bridge exists
 // - Automatic bridge failure detection via heartbeats
 // - RSSI-based election protocol
 // - Deterministic winner selection with tiebreakers

package/examples/ntpTimeSyncBridge/ntpTimeSyncBridge.ino

@@ -12,7 +12,7 @@
  */
 
 #include "painlessMesh.h"
-#include "examples/alteriom/alteriom_sensor_package.hpp"
+#include "alteriom_sensor_package.hpp"
 
 // Mesh configuration
 #define MESH_PREFIX     "AlteriomMesh"

package/examples/ntpTimeSyncNode/ntpTimeSyncNode.ino

@@ -12,7 +12,7 @@
  */
 
 #include "painlessMesh.h"
-#include "examples/alteriom/alteriom_sensor_package.hpp"
+#include "alteriom_sensor_package.hpp"
 
 // Mesh configuration
 #define MESH_PREFIX     "AlteriomMesh"

package/library.json

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

package/library.properties

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

@@ -44,7 +44,8 @@ class Mesh : public painlessmesh::Mesh<Connection> {
    */
   void init(TSTRING ssid, TSTRING password, uint16_t port = 5555,
             WiFiMode_t connectMode = WIFI_AP_STA, uint8_t channel = 1,
-            uint8_t hidden = 0, uint8_t maxconn = MAX_CONN) {
+            uint8_t hidden = 0, uint8_t maxconn = MAX_CONN,
+            TSTRING stationSSID = "", TSTRING stationPassword = "") {
     using namespace logger;
     // Init random generator seed to generate delay variance
     randomSeed(millis());
@@ -154,6 +155,44 @@ class Mesh : public painlessmesh::Mesh<Connection> {
       }
     });
 
+    // Add periodic monitoring task to detect when no bridge exists
+    // This handles the case where no node was initially configured as a bridge
+    this->addTask(30000, TASK_FOREVER, [this]() {
+      // Only check if failover is enabled and we have credentials
+      if (!bridgeFailoverEnabled || !routerCredentialsConfigured) {
+        return;
+      }
+      
+      // Don't check if we're already a bridge
+      if (this->isBridge()) {
+        return;
+      }
+      
+      // Skip check during startup period (60 seconds) to allow initial bridge discovery
+      if (millis() < 60000) {
+        return;
+      }
+      
+      // Check if there are any healthy bridges
+      bool hasHealthyBridge = false;
+      for (const auto& bridge : this->getBridges()) {
+        if (bridge.isHealthy(bridgeTimeoutMs) && bridge.internetConnected) {
+          hasHealthyBridge = true;
+          break;
+        }
+      }
+      
+      // If no healthy bridge exists, trigger an election
+      if (!hasHealthyBridge) {
+        Log(CONNECTION, "Bridge monitor: No healthy bridge detected, triggering election\n");
+        // Small delay to randomize election start across nodes
+        uint32_t randomDelay = random(1000, 3000);
+        this->addTask(randomDelay, TASK_ONCE, [this]() {
+          this->startBridgeElection();
+        });
+      }
+    });
+
     tcpServerInit();
     eventHandleInit();
 
@@ -165,6 +204,12 @@ class Mesh : public painlessmesh::Mesh<Connection> {
     if (connectMode & WIFI_STA) {
       this->initStation();
     }
+    
+    // If station credentials provided, connect to router
+    if (!stationSSID.isEmpty() && (connectMode & WIFI_STA)) {
+      Log(STARTUP, "init(): Connecting to station %s\n", stationSSID.c_str());
+      this->stationManual(stationSSID, stationPassword);
+    }
   }
 
   /** Initialize the mesh network
@@ -187,9 +232,11 @@ class Mesh : public painlessmesh::Mesh<Connection> {
   void init(TSTRING ssid, TSTRING password, Scheduler *baseScheduler,
             uint16_t port = 5555, WiFiMode_t connectMode = WIFI_AP_STA,
             uint8_t channel = 1, uint8_t hidden = 0,
-            uint8_t maxconn = MAX_CONN) {
+            uint8_t maxconn = MAX_CONN,
+            TSTRING stationSSID = "", TSTRING stationPassword = "") {
     this->setScheduler(baseScheduler);
-    init(ssid, password, port, connectMode, channel, hidden, maxconn);
+    init(ssid, password, port, connectMode, channel, hidden, maxconn, 
+         stationSSID, stationPassword);
   }
 
   /**