@alteriom/painlessmesh 1.8.15 → 1.9.0

package/docs/troubleshooting/internet-access-faq.md

@@ -1,299 +0,0 @@
-# Internet Access in painlessMesh - Quick Reference
-
-## Quick Answer
-
-**Q: Why can't my mesh nodes access the internet?**
-
-**A: Only the bridge node has internet access. Regular mesh nodes must forward data through the bridge.**
-
-```text
-Internet
-   |
-Router ← Your WiFi
-   |
-Bridge Node ← Only this node can access internet
-   |
-Mesh Network ← These nodes cannot access internet directly
- / | \
-Node1 Node2 Node3
-```
-
-## Common Error Messages
-
-If you see these errors on regular mesh nodes, you're trying to access the internet directly:
-
-```
-[HTTPS] GET... failed, error: connection refused
-WiFi.status() != WL_CONNECTED
-HTTP request timeout
-Connection failed
-```
-
-## Quick Fix
-
-### ❌ Wrong Approach (Doesn't Work)
-
-```cpp
-// Regular mesh node trying to access internet
-HTTPClient http;
-http.begin("http://api.example.com/data");
-http.POST(sensorData);  // FAILS!
-```
-
-### ✅ Correct Approach (Works)
-
-```cpp
-// Regular mesh node sends to bridge
-mesh.sendSingle(bridgeNodeId, sensorData);
-
-// Bridge node forwards to internet
-void receivedCallback(uint32_t from, String& msg) {
-    if (WiFi.status() == WL_CONNECTED) {
-        HTTPClient http;
-        http.begin("http://api.example.com/data");
-        http.POST(msg);  // WORKS!
-        http.end();
-    }
-}
-```
-
-## Architecture Patterns
-
-### Pattern 1: Single Bridge (Basic)
-
-One designated node is the bridge:
-
-```cpp
-// ==== BRIDGE NODE ====
-mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
-                  ROUTER_SSID, ROUTER_PASSWORD,
-                  &userScheduler, 5555);
-
-// ==== SENSOR NODES ====
-mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, 5555);
-```
-
-### Pattern 2: Bridge Failover (High Availability)
-
-Multiple nodes can become bridge automatically:
-
-```cpp
-// All nodes have router credentials
-mesh.setRouterCredentials(ROUTER_SSID, ROUTER_PASSWORD);
-mesh.enableBridgeFailover(true);
-
-mesh.onBridgeRoleChanged(&bridgeRoleCallback);
-```
-
-### Pattern 3: Multi-Bridge (Load Balancing)
-
-Multiple simultaneous bridges:
-
-```cpp
-// Primary bridge (priority 10)
-mesh.initAsBridge(..., 10);
-
-// Secondary bridge (priority 5)
-mesh.initAsBridge(..., 5);
-```
-
-## By Use Case
-
-### HTTP/HTTPS Requests
-
-```cpp
-// Bridge forwards HTTP requests
-void receivedCallback(uint32_t from, String& msg) {
-    HTTPClient http;
-    http.begin("https://api.example.com/endpoint");
-    http.addHeader("Content-Type", "application/json");
-    http.POST(msg);
-    http.end();
-}
-```
-
-### MQTT Publishing
-
-```cpp
-// Bridge publishes to MQTT
-#include "PubSubClient.h"
-PubSubClient mqtt(wifiClient);
-
-void receivedCallback(uint32_t from, String& msg) {
-    String topic = "mesh/sensor/" + String(from);
-    mqtt.publish(topic.c_str(), msg.c_str());
-}
-```
-
-### WhatsApp Notifications
-
-```cpp
-// Bridge sends WhatsApp messages
-#include "Callmebot_ESP32.h"
-Callmebot_ESP32 whatsapp;
-
-void receivedCallback(uint32_t from, String& msg) {
-    DynamicJsonDocument doc(1024);
-    deserializeJson(doc, msg);
-    
-    if (doc["alarm"] == true) {
-        String alert = "Alarm from sensor " + String(from);
-        whatsapp.sendMessage(alert);
-    }
-}
-```
-
-### Cloud Services (AWS, Azure, GCP)
-
-```cpp
-// Bridge forwards to cloud
-void receivedCallback(uint32_t from, String& msg) {
-    // AWS IoT Core
-    awsClient.publish("iot/sensor/data", msg);
-    
-    // Azure IoT Hub
-    azureClient.sendEvent(msg);
-    
-    // Google Cloud IoT
-    googleClient.publishTelemetry(msg);
-}
-```
-
-### Email Notifications
-
-```cpp
-// Bridge sends email
-#include "ESP_Mail_Client.h"
-
-void receivedCallback(uint32_t from, String& msg) {
-    SMTPData smtpData;
-    smtpData.setLogin(SMTP_HOST, SMTP_PORT, EMAIL, PASSWORD);
-    smtpData.setMessage("Sensor Alert", msg);
-    MailClient.sendMail(smtpData);
-}
-```
-
-## Technical Explanation
-
-### Why Only Bridge Has Internet?
-
-ESP8266/ESP32 WiFi hardware operates on a single channel:
-
-**Bridge Node (WIFI_AP_STA):**
-- Creates mesh Access Point (AP) on channel X
-- Connects to router Station (STA) on channel X
-- Both on same channel = Internet access ✅
-
-**Regular Node (WIFI_AP):**
-- Creates mesh Access Point (AP) on channel X
-- No router connection
-- No internet access ❌
-
-### Can I Make All Nodes Bridges?
-
-Technically yes, but **not recommended** because:
-
-1. **Memory overhead**: +5-10KB RAM per node
-2. **Performance degradation**: All compete for router
-3. **Router limits**: Max clients (typically 10-32)
-4. **Power consumption**: Extra WiFi connection
-5. **Loses mesh benefits**: Defeats purpose of mesh
-
-## Complete Examples
-
-### Sensor Network with Cloud Upload
-
-**Bridge:**
-```cpp
-#include "painlessMesh.h"
-#include "HTTPClient.h"
-
-painlessMesh mesh;
-
-void setup() {
-    mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
-                      ROUTER_SSID, ROUTER_PASSWORD,
-                      &userScheduler, 5555);
-    mesh.onReceive(&receivedCallback);
-}
-
-void receivedCallback(uint32_t from, String& msg) {
-    if (WiFi.status() == WL_CONNECTED) {
-        HTTPClient http;
-        http.begin("https://cloud.example.com/api/sensor");
-        http.addHeader("Authorization", "Bearer " + API_KEY);
-        http.addHeader("Content-Type", "application/json");
-        
-        int httpCode = http.POST(msg);
-        if (httpCode == HTTP_CODE_OK) {
-            Serial.println("Data uploaded to cloud");
-        }
-        http.end();
-    }
-}
-```
-
-**Sensor Node:**
-```cpp
-#include "painlessMesh.h"
-
-painlessMesh mesh;
-#define BRIDGE_NODE_ID 1234567890
-
-void setup() {
-    mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, 5555);
-}
-
-void loop() {
-    mesh.update();
-    sendSensorData();
-}
-
-void sendSensorData() {
-    static unsigned long lastSend = 0;
-    if (millis() - lastSend < 60000) return;
-    lastSend = millis();
-    
-    String data = "{\"sensor\":\"temp\",\"value\":" + 
-                  String(readTemperature()) + ",\"nodeId\":" + 
-                  String(mesh.getNodeId()) + "}";
-    
-    mesh.sendSingle(BRIDGE_NODE_ID, data);
-}
-```
-
-## Troubleshooting Checklist
-
-- [ ] Verify which node is the bridge
-- [ ] Check bridge has `initAsBridge()` or router credentials
-- [ ] Confirm bridge shows `WiFi.status() == WL_CONNECTED`
-- [ ] Verify regular nodes use `mesh.init()` without router
-- [ ] Check sensor nodes send to bridge, not directly to internet
-- [ ] Verify bridge forwards received messages to internet
-- [ ] Test bridge internet connection with simple HTTP request
-- [ ] Check serial output for connection errors
-- [ ] Monitor memory usage on bridge node
-- [ ] Verify firewall/router allows bridge's outbound connections
-
-## More Information
-
-- **[Common Architecture Mistakes](common-architecture-mistakes.md)** - Detailed guide
-- **[BRIDGE_TO_INTERNET.md](../../BRIDGE_TO_INTERNET.md)** - Complete setup guide
-- **[Bridge Failover](../BRIDGE_FAILOVER.md)** - High availability
-- **[FAQ](faq.md)** - Common questions
-- **[examples/mqttBridge/](../../examples/mqttBridge/)** - Working example
-
-## Still Having Issues?
-
-When asking for help, provide:
-
-1. Which node is the bridge? (show setup code)
-2. Which nodes are sensors? (show setup code)
-3. Serial output from bridge (with debug enabled)
-4. Serial output from sensor node (with debug enabled)
-5. Complete error message
-6. What you're trying to access (HTTP API, MQTT, etc.)
-
-Post in:
-- [GitHub Issues](https://github.com/Alteriom/painlessMesh/issues)
-- [Community Forum](https://groups.google.com/forum/#!forum/painlessmesh-user)

package/docs/troubleshooting/station-reconnection-issues.md

@@ -1,172 +0,0 @@
-# Station Reconnection Issues in Bridge Mode
-
-## Problem Description
-
-When using `stationManual()` to create a bridge node that connects to a router while also maintaining a mesh network, users may experience issues where the station (router) connection drops during mesh initialization and fails to reconnect automatically.
-
-### Symptoms
-
-- Initial connection to router succeeds
-- Mesh network initializes successfully
-- Station connection drops with `ARDUINO_EVENT_WIFI_STA_DISCONNECTED` events
-- Station never reconnects despite reconnection logic being triggered
-- Serial output shows repeated disconnect events without successful reconnection
-
-### Example Serial Output
-
-```
-=== WiFi Connectivity Diagnostics ===
-Step 1: Connecting to router to detect channel...
-✓ Successfully connected to router!
-  Router Channel: 6 ← Auto-detected!
-  Router IP: 192.168.18.11
-
-Step 2: Initializing mesh on channel 6...
-STARTUP: init(): 1
-STARTUP: init(): Mesh channel set to 6
-STARTUP: AP tcp server established on port 5555
-STARTUP: stationManual(): Connecting to MyRouter
-STARTUP: stationManual(): Connection initiated
-✓ Mesh initialized
-
-Step 3: Waiting for station reconnection...
-CONNECTION: eventSTADisconnectedHandler: ARDUINO_EVENT_WIFI_STA_DISCONNECTED
-CONNECTION: eraseClosedConnections():
-CONNECTION: eventSTADisconnectedHandler: ARDUINO_EVENT_WIFI_STA_DISCONNECTED
-CONNECTION: eraseClosedConnections():
-⚠ Station not connected yet (may connect later)
-```
-
-## Root Cause
-
-The issue was in the `connectToAP()` method in `src/painlessMeshSTA.cpp`. When operating in manual mode (for router connections via `stationManual()`):
-
-1. Station disconnects during mesh initialization (normal behavior in AP+STA mode)
-2. Disconnect callback triggers `yieldConnectToAP()` to reconnect
-3. `connectToAP()` checks if router SSID is in the scan results
-4. Router SSID is NOT in scan results (scan only looks for mesh nodes on mesh channel)
-5. Function returns without calling `WiFi.begin()` to reconnect
-6. Station remains disconnected indefinitely
-
-### Code Analysis
-
-**Before Fix** (lines 192-195 in `painlessMeshSTA.cpp`):
-
-```cpp
-} else if (aps.empty() || !ssid.equals(aps.begin()->ssid)) {
-    task.enableDelayed(SCAN_INTERVAL);
-    return;  // ← Just delays, never attempts reconnection!
-}
-```
-
-The problem: This conditional assumes the router SSID will appear in the `aps` list from `stationScan()`. However, `stationScan()` only scans on the mesh channel for mesh nodes, not for routers which may be on the same or different channel.
-
-## Solution
-
-**After Fix** (v1.8.1+):
-
-```cpp
-} else {
-    // For manual router connections, reconnect directly using WiFi.begin()
-    // Don't rely on scan results since router may be on different channel
-    Log(CONNECTION, 
-        "connectToAP(): Manual connection - attempting to reconnect to %s\n",
-        ssid.c_str());
-    WiFi.begin(ssid.c_str(), password.c_str());
-    task.enableDelayed(SCAN_INTERVAL);
-    return;
-}
-```
-
-The fix:
-- Removes dependency on scan results for manual connections
-- Calls `WiFi.begin()` directly to reconnect to the router
-- Lets ESP hardware auto-detect the router's channel (as designed)
-- Adds clear logging to show reconnection attempts
-
-## Verification
-
-After applying the fix, the expected behavior is:
-
-```
-Step 3: Waiting for station reconnection...
-CONNECTION: eventSTADisconnectedHandler: ARDUINO_EVENT_WIFI_STA_DISCONNECTED
-CONNECTION: eraseClosedConnections():
-CONNECTION: connectToAP(): Manual connection - attempting to reconnect to MyRouter
-✓ Station reconnected successfully!
-  IP Address: 192.168.18.11
-```
-
-## Workaround (for older versions)
-
-If you're using a version before v1.8.1, you can work around this issue by implementing explicit reconnection logic:
-
-```cpp
-void setup() {
-  // ... mesh initialization ...
-  
-  // Add a task to monitor and reconnect station
-  userScheduler.addTask(Task(5000, TASK_FOREVER, [](){
-    if (WiFi.status() != WL_CONNECTED) {
-      Serial.println("Station disconnected, reconnecting...");
-      WiFi.begin(ROUTER_SSID, ROUTER_PASSWORD);
-    }
-  }));
-}
-```
-
-## Related Issues
-
-- Issue #21: Original user report from @woodlist
-- Issue #50: Bug tracking for stationManual() channel issues
-- Issue #59: Bridge-centric architecture proposal
-- PR #[number]: Fix implementation
-
-## Affected Versions
-
-- **Affected**: v1.5.0 - v1.8.0
-- **Fixed**: v1.8.1+
-
-## Platforms
-
-This issue affects all ESP platforms:
-- ESP32 (all variants including ESP32-C6, ESP32-S3)
-- ESP8266
-
-## Additional Notes
-
-### Why Does Station Disconnect During Mesh Init?
-
-When the ESP switches from pure STA mode to AP+STA mode during mesh initialization, the WiFi subsystem may briefly disconnect from the station to reconfigure. This is normal behavior and the library should automatically reconnect.
-
-### Channel Matching
-
-Remember that in AP+STA mode, both the AP (mesh) and STA (router connection) **must use the same WiFi channel**. This is a hardware limitation. The fix ensures reconnection works regardless of channel, but both interfaces will still operate on the same channel.
-
-### Best Practice
-
-For production bridge nodes, consider using the "Station First" pattern to auto-detect the router's channel before initializing the mesh:
-
-```cpp
-void setup() {
-  // Step 1: Connect to router first to detect its channel
-  WiFi.mode(WIFI_STA);
-  WiFi.begin(ROUTER_SSID, ROUTER_PASSWORD);
-  while (WiFi.status() != WL_CONNECTED) {
-    delay(500);
-  }
-  
-  uint8_t detectedChannel = WiFi.channel();
-  Serial.printf("Router channel: %d\n", detectedChannel);
-  
-  WiFi.disconnect();
-  delay(1000);
-  
-  // Step 2: Initialize mesh on the detected channel
-  mesh.init(MESH_SSID, MESH_PASSWORD, &userScheduler, MESH_PORT, 
-            WIFI_AP_STA, detectedChannel);
-  mesh.stationManual(ROUTER_SSID, ROUTER_PASSWORD);
-}
-```
-
-This approach guarantees channel compatibility and more reliable connections.