@alteriom/painlessmesh 1.8.0 → 1.8.2

package/examples/multi_bridge/README.md

@@ -0,0 +1,346 @@
+# Multi-Bridge Example
+
+This example demonstrates advanced multi-bridge coordination for high-availability mesh networks with multiple simultaneous Internet gateways.
+
+## Overview
+
+In a multi-bridge deployment, multiple nodes act as bridges to the Internet simultaneously. This provides:
+
+- **High Availability**: Zero downtime during failover
+- **Load Balancing**: Distribute traffic across multiple uplinks
+- **Geographic Distribution**: Bridges in different locations
+- **Redundancy**: Multiple paths to Internet
+
+## Architecture
+
+```
+Internet Connection A → Primary Bridge (Priority 10)
+                              ↓
+                        Mesh Network
+                              ↓
+Internet Connection B → Secondary Bridge (Priority 5)
+                              ↓
+                        Regular Nodes
+```
+
+## Files
+
+- **primary_bridge.ino** - Primary bridge with highest priority (10)
+- **secondary_bridge.ino** - Secondary bridge for redundancy (priority 5)
+- **regular_node.ino** - Regular mesh node that uses bridges
+
+## How It Works
+
+### Bridge Priority
+
+Bridges are assigned priorities (1-10):
+- **10 = Primary**: Handles all traffic when available
+- **5 = Secondary**: Hot standby, takes over if primary fails
+- **1 = Standby**: Only used if all higher priority bridges fail
+
+### Bridge Selection Strategies
+
+1. **PRIORITY_BASED** (default): Always use highest priority available bridge
+2. **ROUND_ROBIN**: Distribute load evenly across all bridges
+3. **BEST_SIGNAL**: Use bridge with best WiFi signal strength
+
+### Coordination Protocol
+
+Bridges exchange coordination messages (Type 613) containing:
+- Priority level
+- Current role (primary/secondary/standby)
+- Load percentage
+- List of known peer bridges
+
+Regular nodes track all bridges and automatically select the best one based on the configured strategy.
+
+## Setup Instructions
+
+### Hardware Required
+
+- 3+ ESP32 or ESP8266 devices
+- 1-2 WiFi routers with Internet connection
+- USB cables for programming
+
+### Configuration
+
+#### Primary Bridge
+1. Flash `primary_bridge.ino` to first ESP32
+2. Configure router credentials:
+   ```cpp
+   #define ROUTER_SSID     "YourPrimaryRouter"
+   #define ROUTER_PASSWORD "routerpass"
+   ```
+3. Priority is set to 10 (highest)
+
+#### Secondary Bridge
+1. Flash `secondary_bridge.ino` to second ESP32
+2. Configure router credentials (can be same or different router):
+   ```cpp
+   #define ROUTER_SSID     "YourSecondaryRouter"
+   #define ROUTER_PASSWORD "routerpass2"
+   ```
+3. Priority is set to 5 (secondary)
+
+#### Regular Nodes
+1. Flash `regular_node.ino` to remaining ESP32 devices
+2. No router credentials needed
+3. They automatically discover and use bridges
+
+### Testing
+
+#### Normal Operation
+1. Power on primary bridge - should connect to router
+2. Power on secondary bridge - should connect to router
+3. Power on regular nodes - should join mesh
+4. Regular nodes should prefer primary bridge (priority 10)
+
+#### Failover Test
+1. Disconnect primary bridge from power
+2. Regular nodes should detect loss within 60 seconds
+3. Regular nodes should automatically switch to secondary bridge
+4. No data loss or interruption
+
+#### Load Balancing Test (Round-Robin)
+1. On regular nodes, change strategy:
+   ```cpp
+   mesh.setBridgeSelectionStrategy(painlessMesh::ROUND_ROBIN);
+   ```
+2. Messages should alternate between bridges
+
+## Bridge Selection Strategies
+
+### Priority-Based (Default)
+
+Best for most deployments. Uses highest priority bridge available.
+
+```cpp
+mesh.setBridgeSelectionStrategy(painlessMesh::PRIORITY_BASED);
+```
+
+**When to use:**
+- Production systems needing predictable routing
+- When you have primary and backup Internet connections
+- Clear preference for one connection over another
+
+### Round-Robin Load Balancing
+
+Distributes traffic evenly across all bridges.
+
+```cpp
+mesh.setBridgeSelectionStrategy(painlessMesh::ROUND_ROBIN);
+```
+
+**When to use:**
+- High traffic scenarios
+- Multiple equal-quality Internet connections
+- Load distribution is important
+
+### Best Signal
+
+Always uses bridge with strongest WiFi signal.
+
+```cpp
+mesh.setBridgeSelectionStrategy(painlessMesh::BEST_SIGNAL);
+```
+
+**When to use:**
+- Large mesh networks
+- Nodes move around
+- Signal strength affects performance significantly
+
+## API Reference
+
+### Multi-Bridge Configuration
+
+```cpp
+// Enable multi-bridge mode
+mesh.enableMultiBridge(true);
+
+// Set selection strategy
+mesh.setBridgeSelectionStrategy(painlessMesh::PRIORITY_BASED);
+mesh.setBridgeSelectionStrategy(painlessMesh::ROUND_ROBIN);
+mesh.setBridgeSelectionStrategy(painlessMesh::BEST_SIGNAL);
+
+// Set max concurrent bridges (default: 2, max: 5)
+mesh.setMaxBridges(3);
+```
+
+### Bridge Initialization
+
+```cpp
+// Initialize as bridge with priority
+mesh.initAsBridge(meshSSID, meshPassword,
+                  routerSSID, routerPassword,
+                  &scheduler, port, priority);
+```
+
+### Bridge Discovery
+
+```cpp
+// Get list of active bridge node IDs
+std::vector<uint32_t> bridges = mesh.getActiveBridges();
+
+// Get recommended bridge for next message
+uint32_t bridgeId = mesh.getRecommendedBridge();
+
+// Manually select bridge for next transmission
+mesh.selectBridge(bridgeId);
+
+// Check if multi-bridge is enabled
+bool enabled = mesh.isMultiBridgeEnabled();
+```
+
+## Expected Output
+
+### Primary Bridge
+```
+=== Multi-Bridge: PRIMARY BRIDGE ===
+
+=== Bridge Mode Initialization (Priority: 10, Role: primary) ===
+✓ Router connected on channel 6
+✓ Router IP: 192.168.1.100
+Bridge coordination enabled (priority: 10, role: primary)
+
+=== Primary Bridge Status ===
+Node ID: 123456
+Connected Nodes: 3
+Active Bridges: 2
+  - Bridge: 123456 (ME)
+  - Bridge: 789012
+Recommended Bridge: 123456
+```
+
+### Secondary Bridge
+```
+=== Multi-Bridge: SECONDARY BRIDGE ===
+
+=== Bridge Mode Initialization (Priority: 5, Role: secondary) ===
+✓ Router connected on channel 6
+✓ Router IP: 192.168.1.101
+Bridge coordination enabled (priority: 5, role: secondary)
+
+=== Secondary Bridge Status ===
+Node ID: 789012
+Connected Nodes: 3
+Active Bridges: 2
+  - Bridge: 123456
+  - Bridge: 789012 (ME)
+Recommended Bridge: 123456
+✓ Standby mode - primary bridge is active
+```
+
+### Regular Node
+```
+=== Multi-Bridge: REGULAR NODE ===
+
+=== Network Status ===
+Node ID: 456789
+Connected Nodes: 4
+Active Bridges: 2
+  - Bridge: 123456
+  - Bridge: 789012
+Internet Available: YES
+
+--- Sending Sensor Data ---
+Recommended Bridge: 123456
+Message: Temperature: 22.3°C, Humidity: 45.2%
+✓ Sent to bridge
+```
+
+## Troubleshooting
+
+### No Bridges Found
+
+**Symptoms**: `Active Bridges: 0`
+
+**Solutions**:
+- Verify bridge nodes are powered on
+- Check router credentials are correct
+- Ensure bridges successfully connected to router
+- Check all devices use same MESH_PREFIX and MESH_PASSWORD
+
+### Bridges Not Coordinating
+
+**Symptoms**: Bridges don't see each other
+
+**Solutions**:
+- Verify `enableMultiBridge(true)` is called on all bridges
+- Check mesh connectivity between bridges
+- Look for "Bridge coordination" messages in logs
+- Ensure bridges are on same mesh network
+
+### Failover Not Working
+
+**Symptoms**: No automatic switch to secondary
+
+**Solutions**:
+- Check `mesh.onBridgeStatusChanged()` callback is registered
+- Verify secondary bridge has Internet connection
+- Ensure bridge status broadcasts are enabled
+- Check 60-second timeout hasn't been exceeded
+
+### Wrong Bridge Selected
+
+**Symptoms**: Secondary used instead of primary
+
+**Solutions**:
+- Verify priorities are correct (primary=10, secondary=5)
+- Check strategy is PRIORITY_BASED
+- Ensure primary bridge has Internet connection
+- Look for priority values in coordination messages
+
+## Advanced Configuration
+
+### Three or More Bridges
+
+```cpp
+// Bridge 1: Primary (priority 10)
+mesh.initAsBridge(ssid, pass, router1, pass1, &sched, port, 10);
+
+// Bridge 2: Secondary (priority 7)
+mesh.initAsBridge(ssid, pass, router2, pass2, &sched, port, 7);
+
+// Bridge 3: Tertiary (priority 3)
+mesh.initAsBridge(ssid, pass, router3, pass3, &sched, port, 3);
+```
+
+### Geographic Distribution
+
+Use when mesh spans multiple buildings:
+
+```
+Building A: Bridge1 (priority 10) → Internet A
+Building B: Bridge2 (priority 10) → Internet B
+```
+
+Both bridges have same priority, nodes use closest one (BEST_SIGNAL strategy).
+
+### Traffic Shaping (Future)
+
+Route different message types to different bridges:
+
+```cpp
+// Coming in future release
+mesh.setBridgeSelectionStrategy(mesh.TRAFFIC_TYPE);
+mesh.routeTrafficType(ALARM_MESSAGE, bridge1);
+mesh.routeTrafficType(SENSOR_DATA, bridge2);
+```
+
+## Dependencies
+
+- Issue #63: Bridge Status Broadcast ✅ (IMPLEMENTED)
+- Issue #64: Bridge Failover ✅ (IMPLEMENTED)
+- Issue #65: Multi-Bridge Coordination ✅ (THIS FEATURE)
+
+## Related Examples
+
+- `examples/bridge/` - Basic single bridge setup
+- `examples/bridge_failover/` - Single bridge with automatic failover
+- `examples/bridgeAwareSensorNode/` - Node that checks bridge status
+
+## Further Reading
+
+- [Bridge Architecture Documentation](../../BRIDGE_TO_INTERNET.md)
+- [Bridge Health Monitoring](../../BRIDGE_HEALTH_MONITORING_IMPLEMENTATION.md)
+- [painlessMesh Wiki](https://gitlab.com/painlessMesh/painlessMesh/-/wikis/home)

package/examples/multi_bridge/primary_bridge.ino

@@ -0,0 +1,96 @@
+//************************************************************
+// Multi-Bridge Example: Primary Bridge Node
+//
+// This example demonstrates a primary bridge (priority 10) in a
+// multi-bridge deployment. Use with secondary_bridge.ino for
+// redundancy and load balancing.
+//
+// Features demonstrated:
+// - Primary bridge with highest priority
+// - Multi-bridge coordination
+// - Load reporting and bridge discovery
+// - Automatic role management
+//************************************************************
+
+#include "painlessMesh.h"
+
+#define MESH_PREFIX     "MultiBridgeMesh"
+#define MESH_PASSWORD   "meshpassword"
+#define MESH_PORT       5555
+
+// Primary router connection (high-speed Internet)
+#define ROUTER_SSID     "PrimaryRouter"
+#define ROUTER_PASSWORD "routerpass"
+
+Scheduler userScheduler;
+painlessMesh mesh;
+
+// Task to display bridge coordination status
+Task taskBridgeStatus(10000, TASK_FOREVER, [](){
+  Serial.println("\n=== Primary Bridge Status ===");
+  Serial.printf("Node ID: %u\n", mesh.getNodeId());
+  Serial.printf("Connected Nodes: %d\n", mesh.getNodeList().size());
+  
+  // Show all active bridges in the mesh
+  auto activeBridges = mesh.getActiveBridges();
+  Serial.printf("Active Bridges: %d\n", activeBridges.size());
+  for (auto bridgeId : activeBridges) {
+    Serial.printf("  - Bridge: %u%s\n", bridgeId, 
+                  (bridgeId == mesh.getNodeId()) ? " (ME)" : "");
+  }
+  
+  // Show recommended bridge for next message
+  uint32_t recommended = mesh.getRecommendedBridge();
+  Serial.printf("Recommended Bridge: %u\n", recommended);
+  Serial.println("=============================\n");
+});
+
+void receivedCallback(uint32_t from, String& msg) {
+  Serial.printf("Received from %u: %s\n", from, msg.c_str());
+}
+
+void newConnectionCallback(uint32_t nodeId) {
+  Serial.printf("New Connection, nodeId = %u\n", nodeId);
+}
+
+void changedConnectionCallback() {
+  Serial.printf("Changed connections. Node count: %d\n", mesh.getNodeList().size());
+}
+
+void setup() {
+  Serial.begin(115200);
+  delay(2000);
+  
+  Serial.println("\n\n=== Multi-Bridge: PRIMARY BRIDGE ===\n");
+  
+  // Initialize mesh as primary bridge with priority 10 (highest)
+  mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+  
+  // Enable multi-bridge coordination mode
+  mesh.enableMultiBridge(true);
+  
+  // Set bridge selection strategy (PRIORITY_BASED is default)
+  mesh.setBridgeSelectionStrategy(painlessMesh::PRIORITY_BASED);
+  
+  // Initialize as bridge with priority 10 (primary)
+  mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
+                    ROUTER_SSID, ROUTER_PASSWORD,
+                    &userScheduler, MESH_PORT, 10);  // Priority 10 = Primary
+  
+  mesh.onReceive(&receivedCallback);
+  mesh.onNewConnection(&newConnectionCallback);
+  mesh.onChangedConnections(&changedConnectionCallback);
+  
+  // Add status reporting task
+  userScheduler.addTask(taskBridgeStatus);
+  taskBridgeStatus.enable();
+  
+  Serial.println("\n=== Primary Bridge Ready ===");
+  Serial.println("This node is the PRIMARY bridge (Priority 10)");
+  Serial.println("It will be preferred for all mesh traffic");
+  Serial.println("If it fails, the secondary bridge will take over automatically\n");
+}
+
+void loop() {
+  mesh.update();
+}

package/examples/multi_bridge/regular_node.ino

@@ -0,0 +1,141 @@
+//************************************************************
+// Multi-Bridge Example: Regular Node
+//
+// This example demonstrates a regular mesh node in a multi-bridge
+// network. The node automatically discovers and uses available bridges
+// for Internet connectivity.
+//
+// Features demonstrated:
+// - Automatic bridge discovery
+// - Bridge selection awareness
+// - Message routing to best available bridge
+// - Failover handling
+//************************************************************
+
+#include "painlessMesh.h"
+
+#define MESH_PREFIX     "MultiBridgeMesh"
+#define MESH_PASSWORD   "meshpassword"
+#define MESH_PORT       5555
+
+Scheduler userScheduler;
+painlessMesh mesh;
+
+// Simulated sensor data
+float temperature = 22.5;
+float humidity = 45.0;
+
+// Task to send sensor data
+Task taskSendMessage(5000, TASK_FOREVER, [](){
+  // Simulate sensor readings
+  temperature += (random(-10, 10) / 10.0);
+  humidity += (random(-50, 50) / 10.0);
+  
+  String msg = "Temperature: " + String(temperature, 1) + "°C, Humidity: " + String(humidity, 1) + "%";
+  
+  Serial.println("\n--- Sending Sensor Data ---");
+  
+  // Get recommended bridge
+  uint32_t recommendedBridge = mesh.getRecommendedBridge();
+  
+  if (recommendedBridge != 0) {
+    Serial.printf("Recommended Bridge: %u\n", recommendedBridge);
+    Serial.printf("Message: %s\n", msg.c_str());
+    
+    // Send to specific bridge
+    mesh.sendSingle(recommendedBridge, msg);
+    Serial.println("✓ Sent to bridge");
+  } else {
+    Serial.println("⚠️ No bridge available!");
+    Serial.println("Message queued for later delivery");
+    // In production, you would queue this message
+  }
+  Serial.println("---------------------------\n");
+});
+
+// Task to display network status
+Task taskNetworkStatus(15000, TASK_FOREVER, [](){
+  Serial.println("\n=== Network Status ===");
+  Serial.printf("Node ID: %u\n", mesh.getNodeId());
+  Serial.printf("Connected Nodes: %d\n", mesh.getNodeList().size());
+  
+  // Show all active bridges
+  auto activeBridges = mesh.getActiveBridges();
+  Serial.printf("Active Bridges: %d\n", activeBridges.size());
+  
+  if (activeBridges.empty()) {
+    Serial.println("  ⚠️ NO BRIDGES AVAILABLE");
+  } else {
+    for (auto bridgeId : activeBridges) {
+      Serial.printf("  - Bridge: %u\n", bridgeId);
+    }
+  }
+  
+  // Check Internet connectivity
+  bool hasInternet = mesh.hasInternetConnection();
+  Serial.printf("Internet Available: %s\n", hasInternet ? "YES" : "NO");
+  
+  Serial.println("======================\n");
+});
+
+void receivedCallback(uint32_t from, String& msg) {
+  Serial.printf("📨 Received from %u: %s\n", from, msg.c_str());
+}
+
+void newConnectionCallback(uint32_t nodeId) {
+  Serial.printf("🔗 New Connection: %u\n", nodeId);
+}
+
+void changedConnectionCallback() {
+  Serial.printf("🔄 Connections changed. Total nodes: %d\n", mesh.getNodeList().size());
+}
+
+void bridgeStatusCallback(uint32_t bridgeNodeId, bool hasInternet) {
+  Serial.printf("\n🌉 Bridge Status Update: Bridge %u - Internet %s\n", 
+                bridgeNodeId, hasInternet ? "CONNECTED" : "OFFLINE");
+  
+  if (hasInternet) {
+    Serial.println("✓ Internet connection available");
+  } else {
+    Serial.println("⚠️ Bridge lost Internet - checking for alternatives...");
+    
+    auto activeBridges = mesh.getActiveBridges();
+    if (activeBridges.empty()) {
+      Serial.println("⚠️ No alternative bridges available!");
+    } else {
+      Serial.printf("✓ %d alternative bridge(s) available\n", activeBridges.size());
+    }
+  }
+}
+
+void setup() {
+  Serial.begin(115200);
+  delay(2000);
+  
+  Serial.println("\n\n=== Multi-Bridge: REGULAR NODE ===\n");
+  
+  // Initialize as regular mesh node
+  mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+  
+  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+  
+  mesh.onReceive(&receivedCallback);
+  mesh.onNewConnection(&newConnectionCallback);
+  mesh.onChangedConnections(&changedConnectionCallback);
+  mesh.onBridgeStatusChanged(&bridgeStatusCallback);
+  
+  // Add tasks
+  userScheduler.addTask(taskSendMessage);
+  userScheduler.addTask(taskNetworkStatus);
+  taskSendMessage.enable();
+  taskNetworkStatus.enable();
+  
+  Serial.println("\n=== Regular Node Ready ===");
+  Serial.println("This node will automatically discover and use available bridges");
+  Serial.println("In multi-bridge mode, it will use the highest priority bridge");
+  Serial.println("If primary fails, it automatically switches to secondary\n");
+}
+
+void loop() {
+  mesh.update();
+}

package/examples/multi_bridge/secondary_bridge.ino

@@ -0,0 +1,111 @@
+//************************************************************
+// Multi-Bridge Example: Secondary Bridge Node
+//
+// This example demonstrates a secondary bridge (priority 5) in a
+// multi-bridge deployment. This provides hot standby redundancy
+// and can handle load if the primary bridge is busy.
+//
+// Features demonstrated:
+// - Secondary bridge with medium priority
+// - Hot standby mode (always ready)
+// - Automatic failover if primary fails
+// - Load balancing support
+//************************************************************
+
+#include "painlessMesh.h"
+
+#define MESH_PREFIX     "MultiBridgeMesh"
+#define MESH_PASSWORD   "meshpassword"
+#define MESH_PORT       5555
+
+// Secondary router connection (backup Internet or different ISP)
+#define ROUTER_SSID     "SecondaryRouter"
+#define ROUTER_PASSWORD "routerpass2"
+
+Scheduler userScheduler;
+painlessMesh mesh;
+
+// Task to display bridge coordination status
+Task taskBridgeStatus(10000, TASK_FOREVER, [](){
+  Serial.println("\n=== Secondary Bridge Status ===");
+  Serial.printf("Node ID: %u\n", mesh.getNodeId());
+  Serial.printf("Connected Nodes: %d\n", mesh.getNodeList().size());
+  
+  // Show all active bridges in the mesh
+  auto activeBridges = mesh.getActiveBridges();
+  Serial.printf("Active Bridges: %d\n", activeBridges.size());
+  for (auto bridgeId : activeBridges) {
+    Serial.printf("  - Bridge: %u%s\n", bridgeId, 
+                  (bridgeId == mesh.getNodeId()) ? " (ME)" : "");
+  }
+  
+  // Show recommended bridge for next message
+  uint32_t recommended = mesh.getRecommendedBridge();
+  Serial.printf("Recommended Bridge: %u\n", recommended);
+  
+  if (recommended == mesh.getNodeId()) {
+    Serial.println("⚠️  I AM THE ACTIVE BRIDGE (primary likely failed!)");
+  } else {
+    Serial.println("✓ Standby mode - primary bridge is active");
+  }
+  Serial.println("=============================\n");
+});
+
+void receivedCallback(uint32_t from, String& msg) {
+  Serial.printf("Received from %u: %s\n", from, msg.c_str());
+}
+
+void newConnectionCallback(uint32_t nodeId) {
+  Serial.printf("New Connection, nodeId = %u\n", nodeId);
+}
+
+void changedConnectionCallback() {
+  Serial.printf("Changed connections. Node count: %d\n", mesh.getNodeList().size());
+}
+
+void bridgeStatusCallback(uint32_t bridgeNodeId, bool hasInternet) {
+  if (hasInternet) {
+    Serial.printf("✓ Bridge %u: Internet connected\n", bridgeNodeId);
+  } else {
+    Serial.printf("⚠️ Bridge %u: Internet OFFLINE\n", bridgeNodeId);
+  }
+}
+
+void setup() {
+  Serial.begin(115200);
+  delay(2000);
+  
+  Serial.println("\n\n=== Multi-Bridge: SECONDARY BRIDGE ===\n");
+  
+  // Initialize mesh as secondary bridge with priority 5
+  mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+  
+  // Enable multi-bridge coordination mode
+  mesh.enableMultiBridge(true);
+  
+  // Set bridge selection strategy (PRIORITY_BASED is default)
+  mesh.setBridgeSelectionStrategy(painlessMesh::PRIORITY_BASED);
+  
+  // Initialize as bridge with priority 5 (secondary)
+  mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
+                    ROUTER_SSID, ROUTER_PASSWORD,
+                    &userScheduler, MESH_PORT, 5);  // Priority 5 = Secondary
+  
+  mesh.onReceive(&receivedCallback);
+  mesh.onNewConnection(&newConnectionCallback);
+  mesh.onChangedConnections(&changedConnectionCallback);
+  mesh.onBridgeStatusChanged(&bridgeStatusCallback);
+  
+  // Add status reporting task
+  userScheduler.addTask(taskBridgeStatus);
+  taskBridgeStatus.enable();
+  
+  Serial.println("\n=== Secondary Bridge Ready ===");
+  Serial.println("This node is the SECONDARY bridge (Priority 5)");
+  Serial.println("It operates in hot standby mode");
+  Serial.println("Will take over if primary bridge fails\n");
+}
+
+void loop() {
+  mesh.update();
+}