@alteriom/painlessmesh 1.8.13 → 1.8.15

package/docs/troubleshooting/common-architecture-mistakes.md

@@ -0,0 +1,438 @@
+# Common Architecture Mistakes
+
+This document explains common misunderstandings about painlessMesh architecture and how to fix them.
+
+## Mistake #1: Expecting Regular Nodes to Have Internet Access
+
+### The Problem
+
+**What users expect:**
+```cpp
+// Regular mesh node trying to make HTTP requests
+void sendSensorData() {
+    HTTPClient http;
+    http.begin("http://api.example.com/sensor");
+    http.POST("{\"temp\":25.5}");  // ❌ This fails!
+    http.end();
+}
+```
+
+**Error message:**
+```
+[HTTPS] GET... failed, error: connection refused
+```
+
+### Why This Fails
+
+painlessMesh creates a **mesh network**, not a mesh-routed internet gateway. Only the bridge node connects to your WiFi router.
+
+**Architecture:**
+```text
+Internet
+   |
+Router (WiFi - Channel 6)
+   |
+Bridge Node (WIFI_AP_STA mode)
+   |            ← Only this node has internet!
+   |
+Mesh Network (Channel 6)
+ / | \
+Node1 Node2 Node3  ← These nodes do NOT have internet!
+```
+
+**Technical explanation:**
+
+1. **Bridge node** (`WIFI_AP_STA` mode):
+   - Acts as Access Point (AP) for mesh
+   - Acts as Station (STA) connected to router
+   - Has internet access via router connection
+   - Can make HTTP/HTTPS requests
+
+2. **Regular nodes** (`WIFI_AP` mode):
+   - Only act as Access Points for mesh
+   - No router connection
+   - No internet access
+   - Cannot make HTTP/HTTPS requests directly
+
+ESP8266/ESP32 WiFi hardware can only operate on one channel at a time. Regular nodes use their WiFi radio to create the mesh AP - they cannot simultaneously connect to your router.
+
+### The Solution
+
+**Pattern 1: Forward through bridge (Recommended)**
+
+```cpp
+// ==== BRIDGE NODE ====
+#include "painlessMesh.h"
+#include "HTTPClient.h"
+
+painlessMesh mesh;
+
+void setup() {
+    // Initialize as bridge with internet access
+    mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
+                      ROUTER_SSID, ROUTER_PASSWORD,
+                      &userScheduler, 5555);
+    
+    mesh.onReceive(&receivedCallback);
+}
+
+void receivedCallback(uint32_t from, String& msg) {
+    // Parse message from mesh nodes
+    DynamicJsonDocument doc(1024);
+    deserializeJson(doc, msg);
+    
+    // Forward to internet service
+    if (WiFi.status() == WL_CONNECTED) {
+        HTTPClient http;
+        http.begin("http://api.example.com/sensor");
+        http.addHeader("Content-Type", "application/json");
+        int httpCode = http.POST(msg);
+        
+        if (httpCode > 0) {
+            Serial.printf("Data forwarded to cloud: %d\n", httpCode);
+        } else {
+            Serial.printf("HTTP POST failed: %s\n", http.errorToString(httpCode).c_str());
+        }
+        
+        http.end();
+    } else {
+        Serial.println("No internet connection - data not forwarded");
+    }
+}
+
+// ==== REGULAR SENSOR NODE ====
+#include "painlessMesh.h"
+
+painlessMesh mesh;
+uint32_t bridgeNodeId = 0;
+
+void setup() {
+    // Regular node - no router connection
+    mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, 5555);
+    mesh.onReceive(&receivedCallback);
+    mesh.onNewConnection(&newConnectionCallback);
+}
+
+void loop() {
+    mesh.update();
+    
+    // Read sensor
+    float temperature = readTemperatureSensor();
+    
+    // Send to bridge (NOT directly to internet!)
+    if (bridgeNodeId != 0) {
+        String msg = "{\"sensor\":\"temp\",\"value\":" + String(temperature) + "}";
+        mesh.sendSingle(bridgeNodeId, msg);
+        Serial.println("Data sent to bridge for forwarding");
+    }
+}
+
+void newConnectionCallback(uint32_t nodeId) {
+    // You could implement bridge discovery here
+    // For now, configure bridge ID manually or via broadcast discovery
+}
+```
+
+**Pattern 2: Bridge failover (High availability)**
+
+```cpp
+// All nodes configured with router credentials
+mesh.setRouterCredentials(ROUTER_SSID, ROUTER_PASSWORD);
+mesh.enableBridgeFailover(true);
+
+mesh.onBridgeRoleChanged(&bridgeRoleCallback);
+
+void bridgeRoleCallback(bool isBridge, String reason) {
+    if (isBridge) {
+        Serial.printf("I am now bridge: %s\n", reason.c_str());
+        // This node now has internet access
+        startForwardingToCloud();
+    } else {
+        Serial.println("I am a regular node - no internet access");
+        // This node must forward through bridge
+    }
+}
+```
+
+See [BRIDGE_FAILOVER.md](../BRIDGE_FAILOVER.md) for details.
+
+## Mistake #2: Thinking All Nodes Should Be Bridges
+
+### The Problem
+
+Some users try to make every node a bridge:
+
+```cpp
+// ❌ Bad idea: Making all nodes bridges
+void setup() {
+    // Every node connects to router
+    mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
+                      ROUTER_SSID, ROUTER_PASSWORD,
+                      &userScheduler, 5555);
+}
+```
+
+### Why This Is Problematic
+
+1. **Memory overhead**: Each router connection uses 5-10KB RAM
+2. **Performance**: All nodes compete for router bandwidth
+3. **Complexity**: Loses benefits of mesh architecture
+4. **Channel conflicts**: All nodes must match router channel
+5. **Connection limit**: Router has max client limit
+
+### The Solution
+
+**Use the bridge-forwarding pattern:**
+
+- **1 bridge node**: Connects to router and mesh
+- **N regular nodes**: Connect to mesh only, forward data to bridge
+- **Bridge forwards**: Takes messages and forwards to internet
+
+This is the intended architecture and scales much better.
+
+## Mistake #3: Not Identifying the Bridge Node
+
+### The Problem
+
+Regular nodes send data but don't know which node is the bridge:
+
+```cpp
+// ❌ How do I know which node is the bridge?
+void sendData() {
+    String msg = "{\"data\":\"value\"}";
+    mesh.sendBroadcast(msg);  // Wasteful - sends to everyone!
+}
+```
+
+### The Solution
+
+**Option 1: Bridge discovery via status broadcasts**
+
+```cpp
+// Bridge node broadcasts status
+#include "examples/alteriom/alteriom_sensor_package.hpp"
+using namespace alteriom;
+
+// Bridge node
+Task taskBridgeStatus(30000, TASK_FOREVER, []() {
+    if (mesh.isRoot()) {
+        BridgeStatusPackage status;
+        status.from = mesh.getNodeId();
+        status.internetConnected = (WiFi.status() == WL_CONNECTED);
+        status.routerRSSI = WiFi.RSSI();
+        
+        mesh.sendBroadcast(status.toJsonString());
+    }
+});
+
+// Regular node
+uint32_t bridgeNodeId = 0;
+
+void receivedCallback(uint32_t from, String& msg) {
+    DynamicJsonDocument doc(1024);
+    deserializeJson(doc, msg);
+    
+    if (doc["type"] == 610) {  // BridgeStatusPackage
+        bridgeNodeId = from;
+        Serial.printf("Bridge node discovered: %u\n", bridgeNodeId);
+    }
+}
+
+void sendDataToBridge() {
+    if (bridgeNodeId != 0) {
+        mesh.sendSingle(bridgeNodeId, myData);
+    } else {
+        Serial.println("Bridge not yet discovered");
+    }
+}
+```
+
+**Option 2: Hardcode bridge ID (simple approach)**
+
+```cpp
+// Configure bridge ID on all nodes
+#define BRIDGE_NODE_ID 1234567890
+
+void sendDataToBridge() {
+    mesh.sendSingle(BRIDGE_NODE_ID, myData);
+}
+```
+
+**Option 3: Use root node as bridge**
+
+```cpp
+void setup() {
+    mesh.setRoot(true);  // Bridge should be root
+    mesh.setContainsRoot(true);  // Tell all nodes
+}
+
+void sendDataToBridge() {
+    // Send to root node (which is the bridge)
+    auto nodeList = mesh.getNodeList();
+    for (auto nodeId : nodeList) {
+        // Check if this node is root
+        // (painlessMesh automatically routes toward root)
+    }
+}
+```
+
+## Mistake #4: Using Wrong WiFi Mode
+
+### The Problem
+
+```cpp
+// ❌ Regular node trying to use AP+STA mode
+void setup() {
+    mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, 5555, 
+              WIFI_AP_STA);  // This is for bridges!
+    
+    // Then trying to connect to router
+    WiFi.begin(ROUTER_SSID, ROUTER_PASSWORD);  // Conflicts with mesh!
+}
+```
+
+### The Solution
+
+**Bridge nodes:**
+```cpp
+// Use initAsBridge() which handles AP+STA mode correctly
+mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
+                  ROUTER_SSID, ROUTER_PASSWORD,
+                  &userScheduler, 5555);
+```
+
+**Regular nodes:**
+```cpp
+// Use default WIFI_AP mode (or let init() choose)
+mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, 5555);
+// No router connection needed
+```
+
+## Mistake #5: Blocking Code on Regular Nodes Waiting for Internet
+
+### The Problem
+
+```cpp
+// ❌ Regular node waiting forever for internet that never comes
+void sendToCloud() {
+    HTTPClient http;
+    http.begin("http://api.example.com");
+    http.setTimeout(30000);  // Waits 30 seconds
+    http.POST(data);  // Will always timeout!
+}
+```
+
+### The Solution
+
+**Check your node role:**
+
+```cpp
+bool isBridgeNode = false;
+
+void setup() {
+    if (shouldBeBridge()) {
+        mesh.initAsBridge(...);
+        isBridgeNode = true;
+    } else {
+        mesh.init(...);
+        isBridgeNode = false;
+    }
+}
+
+void sendData() {
+    if (isBridgeNode && WiFi.status() == WL_CONNECTED) {
+        // Bridge can send directly to internet
+        http.POST("http://api.example.com", data);
+    } else {
+        // Regular node forwards to bridge
+        mesh.sendSingle(bridgeNodeId, data);
+    }
+}
+```
+
+## Real-World Example: WhatsApp Notifications
+
+This is a real issue reported by a user trying to use the Callmebot-ESP32 library with painlessMesh.
+
+### Original (Incorrect) Approach
+
+```cpp
+// ❌ Regular mesh node trying to send WhatsApp messages
+#include "Callmebot_ESP32.h"
+
+Callmebot_ESP32 whatsapp;
+
+void sendAlarm() {
+    // This fails on regular nodes: "connection refused"
+    whatsapp.sendMessage("Sensor alarm!");  // ❌ No internet!
+}
+```
+
+### Corrected Approach
+
+```cpp
+// ==== BRIDGE NODE ====
+#include "painlessMesh.h"
+#include "Callmebot_ESP32.h"
+
+Callmebot_ESP32 whatsapp;
+
+void setup() {
+    // Bridge has internet access
+    mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
+                      ROUTER_SSID, ROUTER_PASSWORD,
+                      &userScheduler, 5555);
+    
+    whatsapp.begin(PHONE_NUMBER, API_KEY);
+    mesh.onReceive(&receivedCallback);
+}
+
+void receivedCallback(uint32_t from, String& msg) {
+    DynamicJsonDocument doc(1024);
+    deserializeJson(doc, msg);
+    
+    // Check for alarm messages from mesh nodes
+    if (doc["alarm"] == true) {
+        String alertMsg = "ALARM from sensor " + String(from);
+        alertMsg += ": " + doc["message"].as<String>();
+        
+        // Bridge can send WhatsApp messages
+        if (WiFi.status() == WL_CONNECTED) {
+            whatsapp.sendMessage(alertMsg);
+            Serial.println("WhatsApp alert sent!");
+        }
+    }
+}
+
+// ==== SENSOR NODE ====
+void checkSensorAndAlert() {
+    float oxygenLevel = readO2Sensor();
+    
+    if (oxygenLevel < CRITICAL_THRESHOLD) {
+        // Send alarm to bridge (not directly to WhatsApp!)
+        String alarm = "{\"alarm\":true,\"sensor\":\"O2\",";
+        alarm += "\"value\":" + String(oxygenLevel) + ",";
+        alarm += "\"message\":\"Critical O2 level!\"}";
+        
+        mesh.sendSingle(bridgeNodeId, alarm);
+        Serial.println("Alarm sent to bridge for WhatsApp notification");
+    }
+}
+```
+
+## Summary: Architecture Best Practices
+
+1. ✅ **One bridge node**: Connects to router and mesh, has internet access
+2. ✅ **Regular nodes**: Connect to mesh only, NO internet access
+3. ✅ **Forward pattern**: Regular nodes send data to bridge, bridge forwards to internet
+4. ✅ **Bridge discovery**: Implement mechanism for nodes to find the bridge
+5. ✅ **Error handling**: Bridge checks internet connectivity before forwarding
+6. ✅ **Failover option**: Use bridge failover for high availability (v1.8.0+)
+
+## Additional Resources
+
+- [BRIDGE_TO_INTERNET.md](../../BRIDGE_TO_INTERNET.md) - Complete bridge setup guide
+- [BRIDGE_FAILOVER.md](../BRIDGE_FAILOVER.md) - Automatic failover for reliability
+- [examples/mqttBridge/](../../examples/mqttBridge/) - Working example of bridge pattern
+- [Mesh Architecture](../architecture/mesh-architecture.md) - Understanding mesh design
+- [FAQ](faq.md) - Common questions and answers

package/docs/troubleshooting/common-issues.md

@@ -2,6 +2,34 @@
 
 This guide covers the most frequently encountered problems when working with painlessMesh and their solutions.
 
+## Architecture & Design Issues
+
+### Regular Nodes Cannot Access Internet / HTTP Requests Fail
+
+**Symptoms:**
+- HTTP/HTTPS requests fail with "connection refused"
+- `WiFi.status()` shows disconnected on regular mesh nodes
+- Internet services (APIs, WhatsApp bot, etc.) only work on bridge node
+
+**Cause:**
+
+This is **expected behavior**, not a bug. Only bridge nodes have internet access.
+
+**Solution:**
+
+See the dedicated guide for this common architecture mistake:
+
+📖 **[Common Architecture Mistakes](common-architecture-mistakes.md)**
+
+**Quick Summary:**
+
+painlessMesh uses a bridge-forwarding pattern:
+- **Bridge node**: Has internet access, forwards data to/from internet
+- **Regular nodes**: No internet access, send data to bridge
+- **Architecture**: Regular nodes → Bridge → Internet
+
+Regular nodes must send data to the bridge, which then forwards to internet services.
+
 ## Platform-Specific Issues
 
 ### ESP32-C6 Crashes on Startup

package/docs/troubleshooting/faq.md

@@ -293,30 +293,131 @@ String createSecureMessage(String data) {
 
 ### Q: Can I connect the mesh to the internet?
 
-**A:** Yes, using bridge nodes:
+**A:** Yes, using bridge nodes. **Important:** Only the bridge node has internet access - regular mesh nodes do NOT have internet access.
+
+**Architecture:**
+```text
+Internet
+   |
+Router (WiFi)
+   |
+Bridge Node (AP+STA mode) ← Only this node has internet access
+   |
+Mesh Network
+ / | \
+Node1 Node2 Node3... ← These nodes do NOT have internet access
+```
 
+**Bridge Node Setup:**
 ```cpp
 // Bridge node connects to both mesh and internet
 void setup() {
-    // Connect to mesh
+    // Modern approach: Auto-detect channel and connect
+    mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
+                      ROUTER_SSID, ROUTER_PASSWORD,
+                      &userScheduler, MESH_PORT);
+    
+    mesh.onReceive(&receivedCallback);
+}
+
+// Forward mesh data to internet services
+void receivedCallback(uint32_t from, String& msg) {
+    // Bridge forwards messages to HTTP server, MQTT broker, etc.
+    if (WiFi.status() == WL_CONNECTED) {
+        httpClient.POST("http://myserver.com/api/data", msg);
+    }
+}
+```
+
+**Regular Nodes:**
+```cpp
+// Regular nodes send data TO the bridge (no direct internet access)
+void setup() {
     mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+    mesh.onReceive(&receivedCallback);
+}
+
+void sendDataToInternet() {
+    // Regular nodes send to bridge, which forwards to internet
+    String data = "{\"sensor\":\"temp\",\"value\":25.5}";
+    mesh.sendSingle(bridgeNodeId, data);
+    // Bridge will forward this to internet services
+}
+```
+
+See [BRIDGE_TO_INTERNET.md](../../BRIDGE_TO_INTERNET.md) for complete documentation.
+
+### Q: Why can't my regular mesh nodes access the Internet / make HTTP requests?
+
+**A:** This is expected behavior. **Only the bridge node has internet access** - regular mesh nodes only communicate with other mesh nodes.
+
+**Why this happens:**
+
+ESP8266/ESP32 WiFi hardware can only operate on one channel at a time. In a mesh network:
+
+- **Bridge node** uses `WIFI_AP_STA` mode:
+  - Access Point (AP) for mesh on channel X
+  - Station (STA) connected to router on channel X
+  - Has internet access via router
+
+- **Regular nodes** use `WIFI_AP` mode:
+  - Access Point (AP) for mesh only
+  - No router connection
+  - No internet access
+
+**Solution - Forward through bridge:**
+
+```cpp
+// ==== BRIDGE NODE ====
+#include "HTTPClient.h"
+
+void receivedCallback(uint32_t from, String& msg) {
+    // Parse message from mesh nodes
+    DynamicJsonDocument doc(1024);
+    deserializeJson(doc, msg);
     
-    // Also connect to home WiFi
-    WiFi.begin("HomeWiFi", "password");
-    while (WiFi.status() != WL_CONNECTED) {
-        delay(500);
+    // Forward to internet service
+    if (WiFi.status() == WL_CONNECTED) {
+        HTTPClient http;
+        http.begin("http://api.example.com/data");
+        http.addHeader("Content-Type", "application/json");
+        http.POST(msg);
+        http.end();
     }
+}
+
+// ==== REGULAR NODE ====
+void sendDataToCloud() {
+    // Create message
+    String msg = "{\"sensor\":\"temp\",\"value\":25.5}";
+    
+    // Send to bridge (NOT directly to internet!)
+    mesh.sendSingle(bridgeNodeId, msg);
     
-    Serial.println("Bridge node: Connected to both mesh and internet");
+    // Bridge will forward to internet service
 }
+```
 
-// Forward mesh data to internet services
-mesh.onReceive([](uint32_t from, String& msg) {
-    // Forward to HTTP server, MQTT broker, etc.
-    httpClient.POST("http://myserver.com/api/data", msg);
-});
+**Common mistake:**
+
+```cpp
+// ❌ This will NOT work on regular mesh nodes:
+HTTPClient http;
+http.begin("http://api.example.com/data");
+http.POST(data);  // ERROR: No internet connection!
+
+// ✅ Correct approach - send to bridge:
+mesh.sendSingle(bridgeNodeId, data);  // Bridge forwards to internet
 ```
 
+**Architecture patterns:**
+
+1. **Single bridge**: One node connects to router, others forward through it
+2. **Bridge failover**: Multiple nodes have router credentials, automatic failover
+3. **Multi-bridge**: Multiple simultaneous bridges for load balancing
+
+See [BRIDGE_TO_INTERNET.md](../../BRIDGE_TO_INTERNET.md) and [BRIDGE_FAILOVER.md](../BRIDGE_FAILOVER.md).
+
 ### Q: Can I use MQTT with painlessMesh?
 
 **A:** Yes, through bridge nodes or by running MQTT alongside the mesh: