@alteriom/painlessmesh 1.8.14 → 1.9.0

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:

package/examples/basic/test/simulator/CMakeLists.txt

@@ -0,0 +1,40 @@
+cmake_minimum_required(VERSION 3.10)
+project(BasicExampleSimulatorTests)
+
+set(CMAKE_CXX_STANDARD 14)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# Path to the simulator (submodule)
+set(SIMULATOR_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../../../../test/simulator")
+
+# Include simulator's CMake configuration
+if(EXISTS "${SIMULATOR_ROOT}/CMakeLists.txt")
+    # Add simulator as subdirectory
+    add_subdirectory(${SIMULATOR_ROOT} ${CMAKE_CURRENT_BINARY_DIR}/simulator)
+else()
+    message(FATAL_ERROR "Simulator not found at ${SIMULATOR_ROOT}. Did you initialize the submodule?")
+endif()
+
+# Include painlessMesh library
+set(PAINLESS_MESH_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../../../..")
+include_directories(
+    ${PAINLESS_MESH_ROOT}/src
+    ${CMAKE_CURRENT_SOURCE_DIR}/firmware
+)
+
+# Register our custom firmware with the simulator
+# This allows the YAML scenarios to reference "basic_example" template
+add_library(basic_example_firmware INTERFACE)
+target_include_directories(basic_example_firmware INTERFACE
+    ${CMAKE_CURRENT_SOURCE_DIR}/firmware
+)
+
+# Link with simulator
+target_link_libraries(basic_example_firmware INTERFACE
+    painlessmesh_simulator
+)
+
+# The simulator executable will be built by the simulator's CMakeLists.txt
+# We just need to ensure our firmware headers are available
+message(STATUS "Basic example firmware tests configured")
+message(STATUS "Run tests with: ./painlessmesh-simulator --config scenarios/basic_mesh_test.yaml")

package/examples/basic/test/simulator/README.md

@@ -0,0 +1,149 @@
+# Basic Example - Simulator Tests
+
+This directory contains simulator-based tests for the `basic.ino` example using the [painlessMesh-simulator](https://github.com/Alteriom/painlessMesh-simulator).
+
+## Overview
+
+The simulator allows testing the basic example with 10+ virtual nodes without physical hardware, validating:
+- Mesh formation with multiple nodes
+- Message broadcasting to all nodes
+- Callback functionality
+- Dynamic node joining
+- Time synchronization
+
+## Quick Start
+
+### Prerequisites
+
+Install dependencies (Ubuntu/Debian):
+```bash
+sudo apt-get install cmake ninja-build libboost-dev libboost-program-options-dev libyaml-cpp-dev
+```
+
+### Initialize Submodule
+
+If not already done:
+```bash
+cd ../../../../test
+git submodule update --init simulator
+cd -
+```
+
+### Build and Run
+
+```bash
+# Build simulator
+mkdir build && cd build
+cmake -G Ninja ..
+ninja
+
+# Run test scenario
+bin/painlessmesh-simulator --config ../scenarios/basic_mesh_test.yaml
+
+# Or using the simulator from test/simulator
+cd ../../../../test/simulator
+mkdir -p build && cd build
+cmake -G Ninja ..
+ninja
+bin/painlessmesh-simulator --config ../../../examples/basic/test/simulator/scenarios/basic_mesh_test.yaml
+```
+
+## Test Scenarios
+
+### basic_mesh_test.yaml
+
+Tests basic functionality with 10 nodes:
+- ✓ Mesh formation
+- ✓ Message broadcasting
+- ✓ Callback triggering
+- ✓ Dynamic node joining (node added at 30s)
+- ✓ Time synchronization
+
+**Expected Results:**
+- All nodes connect within 30 seconds
+- Each node receives 5+ messages within 60 seconds
+- Time differences < 10ms after 45 seconds
+
+## Firmware Adapter
+
+The `firmware/basic_firmware.hpp` file wraps the `basic.ino` logic for simulation:
+
+```cpp
+#include "simulator/firmware/firmware_base.hpp"
+
+class BasicFirmware : public FirmwareBase {
+    // Implements same logic as basic.ino
+    // - setup() initializes mesh and callbacks
+    // - loop() calls mesh.update()
+    // - sendMessage() broadcasts periodically
+};
+```
+
+This allows running the **exact same code** that runs on hardware.
+
+## Adding More Tests
+
+Create new YAML scenarios in `scenarios/`:
+
+```yaml
+simulation:
+  name: "Stress Test"
+  duration: 120
+
+nodes:
+  - template: "basic_example"
+    count: 50  # Test with 50 nodes
+    
+topology:
+  type: "ring"  # Different topology
+
+events:
+  - type: "network_partition"  # Inject failures
+    time: 60
+```
+
+## Metrics and Validation
+
+Test results are saved to `results/basic_test_results.csv`:
+
+```csv
+timestamp,node_id,messages_sent,messages_received,topology_changes
+0,6481,0,0,1
+1,6481,1,0,1
+2,6481,1,2,1
+...
+```
+
+Analyze with:
+```python
+import pandas as pd
+df = pd.read_csv('results/basic_test_results.csv')
+print(df.groupby('node_id')['messages_received'].sum())
+```
+
+## Documentation
+
+- [Simulator Documentation](../../../../test/simulator/README.md)
+- [Integration Guide](../../../../test/simulator/docs/INTEGRATING_INTO_YOUR_PROJECT.md)
+- [Configuration Reference](../../../../test/simulator/docs/CONFIGURATION_GUIDE.md)
+
+## Troubleshooting
+
+**Simulator not found:**
+```bash
+cd ../../../../test
+git submodule update --init simulator
+```
+
+**Build errors:**
+```bash
+# Check dependencies
+sudo apt-get install libboost-dev libyaml-cpp-dev
+
+# Clean build
+rm -rf build && mkdir build && cd build
+cmake -G Ninja ..
+```
+
+**Test failures:**
+Check the simulator output for details on which validation failed.

package/examples/basic/test/simulator/firmware/basic_firmware.hpp

@@ -0,0 +1,117 @@
+#pragma once
+
+#include "simulator/firmware/firmware_base.hpp"
+#include <painlessMesh.h>
+
+/**
+ * @brief Firmware adapter for basic.ino example
+ * 
+ * This wraps the basic example sketch logic for testing with the simulator.
+ * It allows running the exact same code that runs on ESP32/ESP8266 hardware
+ * in a simulated environment with 100+ virtual nodes.
+ */
+class BasicFirmware : public FirmwareBase {
+public:
+    BasicFirmware() : mesh_(nullptr), userScheduler_(nullptr) {}
+    
+    ~BasicFirmware() override {
+        if (taskSendMessage_) {
+            delete taskSendMessage_;
+        }
+    }
+
+    void setup(painlessMesh* mesh, Scheduler* userScheduler) override {
+        mesh_ = mesh;
+        userScheduler_ = userScheduler;
+        
+        // Same configuration as basic.ino
+        const char* MESH_PREFIX = "whateverYouLike";
+        const char* MESH_PASSWORD = "somethingSneaky";
+        const uint16_t MESH_PORT = 5555;
+        
+        // Set debug message types (same as basic.ino)
+        mesh_->setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+        
+        // Initialize mesh
+        mesh_->init(MESH_PREFIX, MESH_PASSWORD, userScheduler_, MESH_PORT);
+        
+        // Register callbacks
+        mesh_->onReceive([this](uint32_t from, String& msg) {
+            this->receivedCallback(from, msg);
+        });
+        
+        mesh_->onNewConnection([this](uint32_t nodeId) {
+            this->newConnectionCallback(nodeId);
+        });
+        
+        mesh_->onChangedConnections([this]() {
+            this->changedConnectionCallback();
+        });
+        
+        mesh_->onNodeTimeAdjusted([this](int32_t offset) {
+            this->nodeTimeAdjustedCallback(offset);
+        });
+        
+        // Setup periodic message sending task
+        taskSendMessage_ = new Task(TASK_SECOND * 1, TASK_FOREVER, 
+            [this]() { this->sendMessage(); });
+        userScheduler_->addTask(*taskSendMessage_);
+        taskSendMessage_->enable();
+    }
+
+    void loop() override {
+        if (mesh_) {
+            mesh_->update();
+        }
+    }
+
+    const char* getName() const override {
+        return "BasicExample";
+    }
+
+private:
+    painlessMesh* mesh_;
+    Scheduler* userScheduler_;
+    Task* taskSendMessage_ = nullptr;
+    
+    void sendMessage() {
+        if (!mesh_) return;
+        
+        String msg = "Hello from node ";
+        msg += mesh_->getNodeId();
+        mesh_->sendBroadcast(msg);
+        
+        // Random interval between 1 and 5 seconds (same as basic.ino)
+        taskSendMessage_->setInterval(random(TASK_SECOND * 1, TASK_SECOND * 5));
+    }
+    
+    void receivedCallback(uint32_t from, String& msg) {
+        // In simulator, we can log to stdout or collect metrics
+        printf("Node %u: Received from %u msg=%s\n", 
+               mesh_->getNodeId(), from, msg.c_str());
+        
+        // Track metrics for validation
+        messagesReceived_++;
+    }
+    
+    void newConnectionCallback(uint32_t nodeId) {
+        printf("Node %u: New Connection, nodeId = %u\n", 
+               mesh_->getNodeId(), nodeId);
+        connectionsEstablished_++;
+    }
+    
+    void changedConnectionCallback() {
+        printf("Node %u: Changed connections\n", mesh_->getNodeId());
+        topologyChanges_++;
+    }
+    
+    void nodeTimeAdjustedCallback(int32_t offset) {
+        printf("Node %u: Adjusted time %u. Offset = %d\n", 
+               mesh_->getNodeId(), mesh_->getNodeTime(), offset);
+    }
+    
+    // Metrics for test validation
+    uint32_t messagesReceived_ = 0;
+    uint32_t connectionsEstablished_ = 0;
+    uint32_t topologyChanges_ = 0;
+};

package/examples/basic/test/simulator/scenarios/basic_mesh_test.yaml

@@ -0,0 +1,81 @@
+# Test scenario for basic.ino example
+# This validates that the basic example works correctly with multiple nodes
+
+simulation:
+  name: "Basic Example - Mesh Formation and Broadcasting"
+  description: "Validates basic.ino with 10 nodes forming a mesh and exchanging messages"
+  duration: 60  # seconds
+  time_scale: 1.0
+  seed: 12345
+
+network:
+  default_latency:
+    min_ms: 1
+    max_ms: 10
+  default_packet_loss:
+    rate: 0.0
+  default_bandwidth:
+    bits_per_second: 1000000
+
+nodes:
+  # Create individual nodes - simulator doesn't support template/count syntax
+  - id: "node1"
+    firmware: "SimpleBroadcast"
+    config:
+      mesh_prefix: "whateverYouLike"
+      mesh_password: "somethingSneaky"
+      mesh_port: 5555
+      broadcast_interval: "1000"
+      broadcast_message: "Hello from node"
+  
+  - id: "node2"
+    firmware: "SimpleBroadcast"
+    config:
+      mesh_prefix: "whateverYouLike"
+      mesh_password: "somethingSneaky"
+      mesh_port: 5555
+      broadcast_interval: "1000"
+      broadcast_message: "Hello from node"
+  
+  - id: "node3"
+    firmware: "SimpleBroadcast"
+    config:
+      mesh_prefix: "whateverYouLike"
+      mesh_password: "somethingSneaky"
+      mesh_port: 5555
+      broadcast_interval: "1000"
+      broadcast_message: "Hello from node"
+  
+  - id: "node4"
+    firmware: "SimpleBroadcast"
+    config:
+      mesh_prefix: "whateverYouLike"
+      mesh_password: "somethingSneaky"
+      mesh_port: 5555
+      broadcast_interval: "1000"
+      broadcast_message: "Hello from node"
+  
+  - id: "node5"
+    firmware: "SimpleBroadcast"
+    config:
+      mesh_prefix: "whateverYouLike"
+      mesh_password: "somethingSneaky"
+      mesh_port: 5555
+      broadcast_interval: "1000"
+      broadcast_message: "Hello from node"
+
+topology:
+  type: "mesh"  # Full mesh - all nodes connected
+
+# No events - nodes start automatically
+events: []
+
+# Metrics to collect
+metrics:
+  output: "basic_test_results.csv"
+  interval: 5
+  collect:
+    - "messages_sent"
+    - "messages_received"
+    - "bytes_sent"
+    - "bytes_received"

package/examples/bridge/bridge.ino

@@ -47,9 +47,22 @@ void setup() {
   // 3. Set this node as root
   // 4. Maintain router connection
   // 5. Start broadcasting bridge status (Type 610) every 30 seconds
-  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 mesh node");
+    Serial.println("The node will join the mesh without bridge functionality");
+    
+    // Fallback: Initialize as regular mesh node
+    // This allows the device to still participate in the mesh
+    mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+    
+    Serial.println("✓ Initialized as regular mesh node");
+    Serial.println("Note: To function as a bridge, fix router connectivity and restart");
+  }
 
   // Optional: Configure bridge status broadcasting
   // mesh.setBridgeStatusInterval(60000);  // Change to 60 seconds
@@ -61,7 +74,7 @@ void setup() {
   // Set up message callback
   mesh.onReceive(&receivedCallback);
   
-  Serial.println("Bridge node initialized and ready!");
+  Serial.println("✓ Bridge node initialized and ready!");
   Serial.println("Broadcasting bridge status to mesh every 30 seconds");
 }