@alteriom/painlessmesh 1.7.9 → 1.8.1

package/examples/diagnosticsExample/diagnosticsExample.ino

@@ -0,0 +1,171 @@
+/**
+ * painlessMesh Diagnostics API Example
+ * 
+ * This example demonstrates the enhanced diagnostics API for bridge operations.
+ * It shows how to:
+ * - Enable diagnostics tracking
+ * - Get bridge status information
+ * - Monitor election history
+ * - Test bridge connectivity
+ * - Generate diagnostic reports
+ * - Export topology for visualization
+ * 
+ * Hardware: ESP32 or ESP8266
+ * 
+ * Usage:
+ * 1. Upload to multiple devices
+ * 2. Configure one device as a bridge (see bridgeExample)
+ * 3. Regular nodes will use this diagnostics API to monitor mesh health
+ * 4. Open Serial Monitor to see diagnostic information
+ */
+
+#include "painlessMesh.h"
+
+#define   MESH_PREFIX     "DiagnosticsMesh"
+#define   MESH_PASSWORD   "diagnostic123"
+#define   MESH_PORT       5555
+
+Scheduler userScheduler;
+painlessMesh mesh;
+
+// Task to periodically print diagnostics
+Task taskPrintDiagnostics(30000, TASK_FOREVER, []() {
+  Serial.println("\n" + mesh.getDiagnosticReport());
+});
+
+// Task to test bridge connectivity
+Task taskTestBridge(60000, TASK_FOREVER, []() {
+  Serial.println("\n=== Testing Bridge Connectivity ===");
+  auto result = mesh.testBridgeConnectivity();
+  
+  if (result.success) {
+    Serial.printf("✓ Bridge test PASSED: %s\n", result.message.c_str());
+    Serial.printf("  Latency: %u ms\n", result.latencyMs);
+    Serial.printf("  Internet available: %s\n", result.internetReachable ? "Yes" : "No");
+  } else {
+    Serial.printf("✗ Bridge test FAILED: %s\n", result.message.c_str());
+  }
+});
+
+// Task to monitor bridge status
+Task taskMonitorBridge(15000, TASK_FOREVER, []() {
+  auto status = mesh.getBridgeStatus();
+  
+  Serial.println("\n=== Bridge Status ===");
+  Serial.printf("Node ID: %u\n", mesh.getNodeId());
+  Serial.printf("Role: %s\n", status.role.c_str());
+  Serial.printf("Is Bridge: %s\n", status.isBridge ? "Yes" : "No");
+  Serial.printf("Internet Connected: %s\n", status.internetConnected ? "Yes" : "No");
+  
+  if (status.bridgeNodeId != 0) {
+    Serial.printf("Bridge Node: %u (RSSI: %d dBm)\n", 
+                  status.bridgeNodeId, status.bridgeRSSI);
+    Serial.printf("Time since bridge change: %u seconds\n", 
+                  status.timeSinceBridgeChange / 1000);
+  } else {
+    Serial.println("No bridge available");
+  }
+});
+
+// Task to show election history
+Task taskShowElections(120000, TASK_FOREVER, []() {
+  auto history = mesh.getElectionHistory();
+  
+  if (history.size() > 0) {
+    Serial.println("\n=== Election History ===");
+    for (const auto& election : history) {
+      Serial.printf("Winner: %u (RSSI: %d dBm, %u candidates) - %s\n",
+                    election.winnerNodeId, election.winnerRSSI,
+                    election.candidateCount, election.reason.c_str());
+    }
+  }
+});
+
+// Task to export topology for visualization
+Task taskExportTopology(300000, TASK_FOREVER, []() {
+  Serial.println("\n=== Mesh Topology (GraphViz DOT format) ===");
+  Serial.println(mesh.exportTopologyDOT());
+  Serial.println("Copy above to http://www.webgraphviz.com/ to visualize");
+});
+
+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);
+  
+  // Get last bridge change when new node connects
+  auto event = mesh.getLastBridgeChange();
+  if (event.timestamp > 0) {
+    Serial.printf("Last bridge change: %u -> %u (%s)\n",
+                  event.oldBridgeId, event.newBridgeId, event.reason.c_str());
+  }
+}
+
+void changedConnectionCallback() {
+  Serial.println("Connections changed");
+  Serial.printf("Mesh nodes: %d\n", mesh.getNodeList().size());
+  
+  // Show Internet path for this node
+  auto path = mesh.getInternetPath(mesh.getNodeId());
+  if (path.size() > 0) {
+    Serial.print("Path to Internet: ");
+    for (auto nodeId : path) {
+      Serial.printf("%u -> ", nodeId);
+    }
+    Serial.println("Internet");
+  }
+}
+
+void bridgeStatusChangedCallback(uint32_t bridgeNodeId, bool hasInternet) {
+  Serial.printf("\n!!! Bridge Status Changed !!!\n");
+  Serial.printf("Bridge %u Internet: %s\n", 
+                bridgeNodeId, hasInternet ? "Connected" : "Disconnected");
+  
+  // Run immediate connectivity test
+  auto result = mesh.testBridgeConnectivity();
+  Serial.printf("Connectivity test: %s\n", result.message.c_str());
+}
+
+void setup() {
+  Serial.begin(115200);
+  
+  Serial.println("\n\n=== painlessMesh Diagnostics Example ===");
+  Serial.println("Initializing mesh network...");
+  
+  // Initialize mesh
+  mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+  
+  // Enable diagnostics tracking
+  Serial.println("Enabling diagnostics...");
+  mesh.enableDiagnostics(true);
+  
+  // Setup callbacks
+  mesh.onReceive(&receivedCallback);
+  mesh.onNewConnection(&newConnectionCallback);
+  mesh.onChangedConnections(&changedConnectionCallback);
+  mesh.onBridgeStatusChanged(&bridgeStatusChangedCallback);
+  
+  // Add diagnostic tasks
+  userScheduler.addTask(taskPrintDiagnostics);
+  userScheduler.addTask(taskTestBridge);
+  userScheduler.addTask(taskMonitorBridge);
+  userScheduler.addTask(taskShowElections);
+  userScheduler.addTask(taskExportTopology);
+  
+  // Enable tasks
+  taskPrintDiagnostics.enable();
+  taskTestBridge.enable();
+  taskMonitorBridge.enable();
+  taskShowElections.enable();
+  taskExportTopology.enable();
+  
+  Serial.println("Setup complete!");
+  Serial.printf("Node ID: %u\n", mesh.getNodeId());
+}
+
+void loop() {
+  mesh.update();
+}

package/examples/diagnosticsExample/platformio.ini

@@ -0,0 +1,26 @@
+[platformio]
+src_dir = .
+
+[env]
+lib_deps =
+    bblanchon/ArduinoJson
+    arkhipenko/TaskScheduler
+
+lib_ldf_mode = deep+
+[env:esp8266]
+platform = espressif8266
+board = nodemcuv2
+framework = arduino
+lib_extra_dirs = ../../
+lib_deps =
+    ${env.lib_deps}  ; Inherit common dependencies
+    esp32async/ESPAsyncTCP@^2.0.0  ; Only for ESP8266
+
+[env:esp32]
+platform = espressif32
+board = esp32dev
+framework = arduino
+lib_extra_dirs = ../../
+lib_deps =
+    ${env.lib_deps}  ; Inherit common dependencies
+    esp32async/AsyncTCP

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();
+}