@alteriom/painlessmesh 1.8.14 → 1.9.0

package/examples/bridge_failover/README.md

@@ -105,6 +105,29 @@ To prevent oscillation:
 #define INITIAL_BRIDGE  false
 ```
 
+### Channel Detection (Automatic)
+
+**Critical for Bridge Discovery:**
+
+Regular nodes **must** use channel auto-detection (channel=0) to discover bridges. This is because:
+
+1. Bridge nodes operate on the **router's WiFi channel** (e.g., channel 6)
+2. Regular nodes scanning on a fixed channel (e.g., channel 1) cannot see bridges on different channels
+3. Channel auto-detection scans all channels to find the mesh
+
+The example code automatically uses channel=0:
+```cpp
+// Regular node initialization with auto-detection
+mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT, WIFI_AP_STA, 0);
+//                                                                            ^ channel=0
+```
+
+**What happens:**
+- Node scans all WiFi channels (1-13) to find the mesh SSID
+- Detects the channel where the bridge/mesh is operating
+- Joins the mesh on that channel
+- Ensures proper bridge discovery and mesh connectivity
+
 ## Setup Instructions
 
 You can choose between two deployment modes:
@@ -237,6 +260,14 @@ mesh.setElectionTimeout(5000);
 // Prevents nodes with poor signal from becoming bridges when isolated
 mesh.setMinimumBridgeRSSI(-80);
 
+// Set startup delay before first election check (default: 60000 ms = 60 seconds)
+// Longer delays allow more time for mesh formation, reducing split-brain risk
+mesh.setElectionStartupDelay(90000);  // 90 seconds
+
+// Set random delay range for elections (default: 1000-3000 ms)
+// Longer delays reduce simultaneous election risk when multiple nodes start together
+mesh.setElectionRandomDelay(10000, 30000);  // 10-30 seconds
+
 // Set bridge status broadcast interval
 mesh.setBridgeStatusInterval(30000);
 
@@ -337,12 +368,62 @@ bool amBridge = mesh.isBridge();
 
 **Symptoms**: Regular nodes show "No primary bridge available!" and "Known bridges: 0"
 
+**Root Cause**: Regular nodes must use channel auto-detection (channel=0) to discover bridges on the router's channel.
+
 **Solutions**:
+- **CRITICAL**: Initialize regular nodes with `channel=0` for auto-detection:
+  ```cpp
+  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT, WIFI_AP_STA, 0);
+  ```
 - Verify bridge node successfully connected to router (check serial output)
 - Ensure mesh network name and password match on all nodes
 - Check that nodes are on the same WiFi channel as the router/bridge
 - Wait a few seconds after startup for initial discovery
 - Bridge now broadcasts immediately on startup and when nodes connect (fixed in v1.8.4+)
+- **Note**: The example code has been updated to use channel=0 by default
+
+### Split-Brain Scenario (Multiple Bridges)
+
+**Symptoms**: When nodes start simultaneously, both become bridges and don't see each other
+
+**Root Cause**: Race condition - both nodes detect "no bridge" after startup period, run isolated elections, each wins their own election and becomes a bridge.
+
+**Why This Happens**:
+1. Both nodes initialize as regular nodes with `INITIAL_BRIDGE = false`
+2. After 60s startup period, both detect "no bridge exists"
+3. Both trigger elections with short 1-3s random delay
+4. If mesh connection hasn't formed yet, each runs an isolated election
+5. Each node wins its own election and becomes a bridge
+6. Once both are bridges, they stop scanning for mesh nodes
+
+**Solutions**:
+
+**Option 1: Increase Startup Delay (Recommended)**
+```cpp
+// Allow more time for mesh formation before elections start
+mesh.setElectionStartupDelay(90000);  // 90 seconds instead of default 60 seconds
+```
+
+**Option 2: Increase Random Election Delay**
+```cpp
+// Provide more mesh discovery time when elections trigger
+mesh.setElectionRandomDelay(10000, 30000);  // 10-30 seconds instead of 1-3 seconds
+```
+
+**Option 3: Combine Both**
+```cpp
+mesh.setElectionStartupDelay(90000);      // 90 second startup delay
+mesh.setElectionRandomDelay(10000, 30000); // 10-30 second random delay
+```
+
+**Option 4: Stagger Node Startup**
+- Power on nodes 10-20 seconds apart
+- First node establishes mesh, second node discovers it
+
+**Option 5: Use Pre-Designated Bridge**
+- Set `INITIAL_BRIDGE = true` on one node only
+- Guarantees single bridge from startup
+- Good for fixed deployments
 
 ### Bridge Reports No Internet When Router Has Internet
 

package/examples/bridge_failover/bridge_failover.ino

@@ -34,6 +34,12 @@
 // - Deterministic winner selection with tiebreakers
 // - Seamless promotion to bridge role
 // - Bridge takeover announcements
+// - Automatic mesh channel detection for bridge discovery
+//
+// Important Note:
+// Regular nodes MUST use channel auto-detection (channel=0) to discover
+// bridges that are operating on the router's WiFi channel. The example
+// automatically uses channel=0 for this purpose.
 //
 //************************************************************
 
@@ -122,15 +128,31 @@ void setup() {
     Serial.println("This node will start as the primary bridge\n");
     
     // Initialize as bridge with automatic channel detection
-    mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
-                     ROUTER_SSID, ROUTER_PASSWORD,
-                     &userScheduler, MESH_PORT);
+    bool bridgeSuccess = mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
+                                           ROUTER_SSID, ROUTER_PASSWORD,
+                                           &userScheduler, MESH_PORT);
+    
+    if (!bridgeSuccess) {
+      Serial.println("✗ Failed to initialize as bridge!");
+      Serial.println("Router unreachable - falling back to regular node with failover");
+      
+      // Fallback: Initialize as regular node with bridge failover enabled
+      // This allows automatic promotion to bridge when router becomes available
+      // channel=0 enables automatic mesh channel detection
+      mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT, WIFI_AP_STA, 0);
+      mesh.setRouterCredentials(ROUTER_SSID, ROUTER_PASSWORD);
+      mesh.enableBridgeFailover(true);
+      mesh.setElectionTimeout(5000);
+      
+      Serial.println("✓ Running as regular node - will auto-promote when router available");
+    }
   } else {
     Serial.println("Mode: REGULAR NODE (Failover Enabled)");
     Serial.println("This node can become bridge via election\n");
     
-    // Initialize as regular node
-    mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+    // Initialize as regular node with auto-channel detection
+    // channel=0 enables automatic mesh channel detection
+    mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT, WIFI_AP_STA, 0);
     
     // Configure for automatic bridge failover
     mesh.setRouterCredentials(ROUTER_SSID, ROUTER_PASSWORD);
@@ -140,6 +162,14 @@ void setup() {
     // Optional: Set minimum RSSI for isolated bridge elections (default: -80 dBm)
     // This prevents nodes with poor signal from becoming bridges when isolated
     // mesh.setMinimumBridgeRSSI(-80);  // Uncomment to customize threshold
+    
+    // Optional: Configure election timing to prevent split-brain when nodes start simultaneously
+    // Longer startup delay allows more time for mesh formation before elections begin
+    // mesh.setElectionStartupDelay(90000);  // 90 seconds (default: 60 seconds)
+    
+    // Optional: Increase random delay to reduce simultaneous election risk
+    // Longer delays provide more mesh discovery time when multiple nodes detect missing bridge
+    // mesh.setElectionRandomDelay(10000, 30000);  // 10-30 seconds (default: 1-3 seconds)
   }
 
   // Register callbacks
@@ -172,6 +202,7 @@ void loop() {
     Serial.println("\n--- Bridge Status ---");
     Serial.printf("I am bridge: %s\n", mesh.isBridge() ? "YES" : "NO");
     Serial.printf("Internet available: %s\n", mesh.hasInternetConnection() ? "YES" : "NO");
+    Serial.printf("Mesh connections active: %s\n", mesh.hasActiveMeshConnections() ? "YES" : "NO");
     
     auto bridges = mesh.getBridges();
     Serial.printf("Known bridges: %d\n", bridges.size());
@@ -189,7 +220,21 @@ void loop() {
       Serial.printf("Primary bridge: %u (RSSI: %d dBm)\n", 
                     primary->nodeId, primary->routerRSSI);
     } else {
-      Serial.println("No primary bridge available!");
+      // Provide more context about why no primary bridge
+      if (!mesh.hasActiveMeshConnections()) {
+        Serial.println("No primary bridge: This node is disconnected from mesh");
+        // Show last known bridge info if available
+        auto lastKnown = mesh.getLastKnownBridge();
+        if (lastKnown) {
+          Serial.printf("  Last known bridge: %u (RSSI: %d dBm, last seen %u ms ago)\n",
+                        lastKnown->nodeId, lastKnown->routerRSSI,
+                        millis() - lastKnown->lastSeen);
+        }
+      } else if (bridges.empty()) {
+        Serial.println("No primary bridge: No bridges discovered yet");
+      } else {
+        Serial.println("No primary bridge: Known bridges timed out or lost Internet");
+      }
     }
     Serial.println("--------------------\n");
   }

package/examples/sharedGateway/README.md

@@ -0,0 +1,235 @@
+# Shared Gateway Example
+
+This example demonstrates the **Shared Gateway Mode** feature of painlessMesh. Unlike Bridge Mode where only one node connects to the router, Shared Gateway Mode allows **ALL nodes** to connect to the same WiFi router while maintaining mesh connectivity.
+
+## What is Shared Gateway Mode?
+
+In a traditional painlessMesh network:
+- Regular nodes only communicate over the mesh
+- Bridge nodes connect to a router AND the mesh
+- Only the bridge can access the Internet
+
+With Shared Gateway Mode:
+- **All nodes** connect to the same WiFi router
+- **All nodes** maintain mesh connectivity
+- **Any node** can access the Internet directly
+- Provides redundant Internet paths
+
+## Architecture
+
+```
+                    Internet
+                       │
+                    Router
+         ┌─────────────┼─────────────┐
+         │             │             │
+     Node A        Node B        Node C
+     (AP+STA)      (AP+STA)      (AP+STA)
+         │             │             │
+         └─────────────┼─────────────┘
+                 Mesh Network
+```
+
+## Hardware Requirements
+
+- **ESP32** or **ESP8266** microcontroller
+- WiFi router within range of all nodes
+- USB cable for programming and serial monitoring
+
+## Configuration
+
+Edit the following defines in `sharedGateway.ino`:
+
+```cpp
+// Mesh network settings (must match across all nodes)
+#define MESH_PREFIX     "SharedGatewayMesh"  // Your mesh network name
+#define MESH_PASSWORD   "meshPassword123"    // Your mesh network password
+#define MESH_PORT       5555                 // TCP port (default: 5555)
+
+// Router settings (your WiFi router)
+#define ROUTER_SSID     "YourRouterSSID"     // Your WiFi router name
+#define ROUTER_PASSWORD "YourRouterPassword" // Your WiFi router password
+```
+
+## Building and Uploading
+
+### Using PlatformIO (Recommended)
+
+```bash
+# For ESP32
+pio run -e esp32 -t upload
+
+# For ESP8266
+pio run -e esp8266 -t upload
+```
+
+### Using Arduino IDE
+
+1. Open `sharedGateway.ino` in Arduino IDE
+2. Install the required libraries:
+   - ArduinoJson
+   - TaskScheduler
+   - painlessMesh
+   - AsyncTCP (ESP32) or ESPAsyncTCP (ESP8266)
+3. Select your board (ESP32 or ESP8266)
+4. Click Upload
+
+## Expected Serial Output
+
+After uploading, open Serial Monitor at 115200 baud. You should see:
+
+```
+================================================
+   painlessMesh - Shared Gateway Example
+================================================
+
+Initializing Shared Gateway Mode...
+
+  Mesh SSID: SharedGatewayMesh
+  Mesh Port: 5555
+  Router SSID: YourRouterSSID
+
+=== Shared Gateway Mode Initialization ===
+Step 1: Scanning for router YourRouterSSID to detect channel...
+✓ Router connected on channel 6
+✓ Router IP: 192.168.1.105
+Step 2: Initializing mesh on channel 6...
+Step 3: Establishing router connection in shared gateway mode...
+=== Shared Gateway Mode Active ===
+  Mesh Prefix: SharedGatewayMesh
+  Mesh Channel: 6 (synced with router)
+  Router: YourRouterSSID
+  Port: 5555
+  Mode: AP+STA (all nodes can connect to router)
+
+✓ Shared Gateway Mode initialized successfully!
+
+================================================
+Node ID: 2748965421
+Shared Gateway Mode: Active
+Router IP: 192.168.1.105
+Router Channel: 6
+================================================
+
+Status broadcasts will be sent every 10 seconds.
+```
+
+### Status Broadcast Output
+
+Every 10 seconds, you'll see:
+
+```
+========== STATUS BROADCAST ==========
+Node ID: 2748965421
+Router: Connected
+  IP: 192.168.1.105
+  RSSI: -45 dBm
+  Channel: 6
+Mesh Nodes: 2
+Shared Gateway Mode: Yes
+Free Heap: 45320 bytes
+Uptime: 120 seconds
+=======================================
+```
+
+## Use Cases
+
+### Industrial Sensor Networks
+All sensor nodes can independently send data to cloud services, providing redundancy if any individual node loses connection.
+
+### Fish Farm Monitoring
+Critical O2 alarms can reach the cloud through any available path, ensuring no alerts are missed.
+
+### Smart Building Systems
+HVAC and security data maintains connectivity through redundant paths for maximum reliability.
+
+### Remote Monitoring
+Environmental monitoring stations with shared WiFi infrastructure can relay through nearby nodes if needed.
+
+## Troubleshooting
+
+### Router Connection Fails
+
+**Symptoms:** `✗ Failed to initialize Shared Gateway Mode!`
+
+**Solutions:**
+1. Verify router SSID and password are correct
+2. Ensure the router is powered on and within range
+3. Check that the router is operating on 2.4GHz (5GHz not supported)
+4. Try moving the node closer to the router
+
+### Mesh Not Forming
+
+**Symptoms:** `Mesh Nodes: 0` even with multiple nodes
+
+**Solutions:**
+1. Ensure all nodes use the same `MESH_PREFIX` and `MESH_PASSWORD`
+2. Verify all nodes are using the same router (same channel)
+3. Check that nodes are within WiFi range of each other
+4. Restart all nodes simultaneously
+
+### Frequent Router Disconnections
+
+**Symptoms:** Router status alternates between Connected/Disconnected
+
+**Solutions:**
+1. Check router signal strength (RSSI should be > -70 dBm)
+2. Move nodes closer to the router
+3. Reduce number of devices on the router
+4. Check for WiFi interference
+
+### Low Memory Warnings
+
+**Symptoms:** `Free Heap` decreasing or node crashes
+
+**Solutions:**
+1. Reduce JSON document sizes in your code
+2. Limit the number of mesh nodes
+3. Use ESP32 instead of ESP8266 for larger networks
+
+## API Reference
+
+### Key Method
+
+```cpp
+bool initAsSharedGateway(
+  String meshPrefix,      // Mesh network name
+  String meshPassword,    // Mesh network password
+  String routerSSID,      // Router SSID to connect to
+  String routerPassword,  // Router password
+  Scheduler* scheduler,   // Task scheduler
+  uint16_t port = 5555    // TCP port (optional)
+);
+```
+
+**Returns:** `true` if initialization succeeded, `false` if router connection failed.
+
+### Status Methods
+
+```cpp
+// Check if shared gateway mode is active
+bool isSharedGatewayMode();
+
+// Get router connection status
+WiFi.status() == WL_CONNECTED
+
+// Get router IP address
+WiFi.localIP()
+
+// Get router signal strength
+WiFi.RSSI()
+
+// Get current WiFi channel
+WiFi.channel()
+```
+
+## Related Documentation
+
+- [Shared Gateway Design Document](../../docs/design/SHARED_GATEWAY_DESIGN.md)
+- [Bridge Mode Example](../bridge/README.md)
+- [Bridge Failover Example](../bridge_failover/README.md)
+- [painlessMesh Documentation](https://gitlab.com/painlessMesh/painlessMesh/-/wikis/home)
+
+## License
+
+This example is part of painlessMesh and is released under the same license.

package/examples/{meshCommandNode → sharedGateway}/platformio.ini

@@ -7,6 +7,7 @@ lib_deps =
     arkhipenko/TaskScheduler
 
 lib_ldf_mode = deep+
+
 [env:esp8266]
 platform = espressif8266
 board = nodemcuv2
@@ -14,7 +15,7 @@ framework = arduino
 lib_extra_dirs = ../../
 lib_deps =
     ${env.lib_deps}
-    me-no-dev/ESPAsyncTCP
+    esp32async/ESPAsyncTCP@^2.0.0
 
 [env:esp32]
 platform = espressif32
@@ -23,4 +24,4 @@ framework = arduino
 lib_extra_dirs = ../../
 lib_deps =
     ${env.lib_deps}
-    mathieucarbou/AsyncTCP
+    esp32async/AsyncTCP