@alteriom/painlessmesh 1.8.13 → 1.8.15

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

@@ -0,0 +1,299 @@
+# 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/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"