@alteriom/painlessmesh 1.6.1

package/docs/getting-started/first-mesh.md

@@ -0,0 +1,410 @@
+# Your First Mesh Network
+
+This tutorial builds on the [Quick Start Guide](quickstart.md) to create a more comprehensive mesh network with multiple types of nodes and practical functionality.
+
+## Overview
+
+We'll build a mesh network with three types of nodes:
+1. **Sensor Node** - Collects and broadcasts environmental data
+2. **Controller Node** - Receives sensor data and controls devices
+3. **Bridge Node** - Connects mesh to external networks (WiFi/Internet)
+
+## Node 1: Sensor Node
+
+This node simulates environmental sensors and broadcasts data to the mesh.
+
+```cpp
+#include "painlessMesh.h"
+
+#define MESH_PREFIX     "MyMeshNetwork"
+#define MESH_PASSWORD   "somethingSneaky"
+#define MESH_PORT       5555
+
+Scheduler userScheduler;
+painlessMesh mesh;
+
+// Sensor simulation
+float temperature = 22.5;
+float humidity = 65.0;
+uint32_t sensorId = 1001;
+
+// Task to send sensor data every 30 seconds
+Task taskSendSensor(30000, TASK_FOREVER, [](){
+    // Simulate sensor readings with some variation
+    temperature += random(-10, 10) / 10.0;
+    humidity += random(-50, 50) / 10.0;
+    
+    // Keep values in reasonable ranges
+    temperature = constrain(temperature, 15.0, 35.0);
+    humidity = constrain(humidity, 30.0, 90.0);
+    
+    // Create JSON message
+    String msg = "{";
+    msg += "\"type\":\"sensor\",";
+    msg += "\"nodeId\":" + String(mesh.getNodeId()) + ",";
+    msg += "\"sensorId\":" + String(sensorId) + ",";
+    msg += "\"temperature\":" + String(temperature, 1) + ",";
+    msg += "\"humidity\":" + String(humidity, 1) + ",";
+    msg += "\"timestamp\":" + String(mesh.getNodeTime());
+    msg += "}";
+    
+    mesh.sendBroadcast(msg);
+    Serial.printf("Sent sensor data: T=%.1f°C, H=%.1f%%\n", temperature, humidity);
+});
+
+void receivedCallback(uint32_t from, String &msg) {
+    Serial.printf("Sensor Node: Received from %u: %s\n", from, msg.c_str());
+    
+    // Sensor nodes can respond to commands
+    if (msg.indexOf("\"command\":\"read_sensor\"") > 0) {
+        // Force immediate sensor reading
+        taskSendSensor.forceNextIteration();
+        Serial.println("Forced sensor reading requested");
+    }
+}
+
+void newConnectionCallback(uint32_t nodeId) {
+    Serial.printf("Sensor Node: New connection to %u\n", nodeId);
+}
+
+void changedConnectionCallback() {
+    Serial.printf("Sensor Node: Changed connections. Nodes: %s\n", 
+                  mesh.subConnectionJson().c_str());
+}
+
+void setup() {
+    Serial.begin(115200);
+    Serial.println("=== Sensor Node Starting ===");
+    
+    mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+    mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+    mesh.onReceive(&receivedCallback);
+    mesh.onNewConnection(&newConnectionCallback);
+    mesh.onChangedConnections(&changedConnectionCallback);
+    
+    userScheduler.addTask(taskSendSensor);
+    taskSendSensor.enable();
+    
+    Serial.printf("Sensor Node initialized. Node ID: %u\n", mesh.getNodeId());
+}
+
+void loop() {
+    mesh.update();
+}
+```
+
+## Node 2: Controller Node
+
+This node receives sensor data and can send commands to other nodes.
+
+```cpp
+#include "painlessMesh.h"
+
+#define MESH_PREFIX     "MyMeshNetwork"
+#define MESH_PASSWORD   "somethingSneaky"
+#define MESH_PORT       5555
+
+Scheduler userScheduler;
+painlessMesh mesh;
+
+// Storage for sensor data
+struct SensorData {
+    uint32_t nodeId;
+    uint32_t sensorId;
+    float temperature;
+    float humidity;
+    uint32_t timestamp;
+    bool valid;
+};
+
+SensorData sensors[10]; // Store data from up to 10 sensors
+int sensorCount = 0;
+
+// Task to request sensor data every 60 seconds
+Task taskRequestData(60000, TASK_FOREVER, [](){
+    String cmd = "{";
+    cmd += "\"type\":\"command\",";
+    cmd += "\"command\":\"read_sensor\",";
+    cmd += "\"from\":" + String(mesh.getNodeId());
+    cmd += "}";
+    
+    mesh.sendBroadcast(cmd);
+    Serial.println("Requested sensor data from all nodes");
+});
+
+// Task to display collected data every 45 seconds
+Task taskDisplayData(45000, TASK_FOREVER, [](){
+    Serial.println("=== Collected Sensor Data ===");
+    for (int i = 0; i < sensorCount; i++) {
+        if (sensors[i].valid) {
+            Serial.printf("Node %u (Sensor %u): T=%.1f°C, H=%.1f%%, Age=%u seconds\n",
+                         sensors[i].nodeId, sensors[i].sensorId,
+                         sensors[i].temperature, sensors[i].humidity,
+                         (mesh.getNodeTime() - sensors[i].timestamp) / 1000000);
+        }
+    }
+    Serial.println("============================");
+});
+
+void storeSensorData(uint32_t nodeId, uint32_t sensorId, float temp, float hum, uint32_t timestamp) {
+    // Find existing entry or create new one
+    int index = -1;
+    for (int i = 0; i < sensorCount; i++) {
+        if (sensors[i].nodeId == nodeId && sensors[i].sensorId == sensorId) {
+            index = i;
+            break;
+        }
+    }
+    
+    if (index == -1 && sensorCount < 10) {
+        index = sensorCount++;
+    }
+    
+    if (index != -1) {
+        sensors[index].nodeId = nodeId;
+        sensors[index].sensorId = sensorId;
+        sensors[index].temperature = temp;
+        sensors[index].humidity = hum;
+        sensors[index].timestamp = timestamp;
+        sensors[index].valid = true;
+    }
+}
+
+void receivedCallback(uint32_t from, String &msg) {
+    Serial.printf("Controller: Received from %u: %s\n", from, msg.c_str());
+    
+    // Parse sensor data
+    if (msg.indexOf("\"type\":\"sensor\"") > 0) {
+        // Simple JSON parsing (in production, use ArduinoJson library)
+        int tempStart = msg.indexOf("\"temperature\":") + 14;
+        int tempEnd = msg.indexOf(",", tempStart);
+        float temperature = msg.substring(tempStart, tempEnd).toFloat();
+        
+        int humStart = msg.indexOf("\"humidity\":") + 11;
+        int humEnd = msg.indexOf(",", humStart);
+        float humidity = msg.substring(humStart, humEnd).toFloat();
+        
+        int sensorStart = msg.indexOf("\"sensorId\":") + 11;
+        int sensorEnd = msg.indexOf(",", sensorStart);
+        uint32_t sensorId = msg.substring(sensorStart, sensorEnd).toInt();
+        
+        int timeStart = msg.indexOf("\"timestamp\":") + 12;
+        int timeEnd = msg.indexOf("}", timeStart);
+        uint32_t timestamp = msg.substring(timeStart, timeEnd).toInt();
+        
+        storeSensorData(from, sensorId, temperature, humidity, timestamp);
+        
+        // Trigger actions based on sensor data
+        if (temperature > 30.0) {
+            Serial.println("WARNING: High temperature detected!");
+            // Could send cooling command here
+        }
+        if (humidity > 80.0) {
+            Serial.println("WARNING: High humidity detected!");
+            // Could trigger ventilation here
+        }
+    }
+}
+
+void newConnectionCallback(uint32_t nodeId) {
+    Serial.printf("Controller: New connection to %u\n", nodeId);
+}
+
+void changedConnectionCallback() {
+    Serial.printf("Controller: Changed connections. Nodes: %s\n", 
+                  mesh.subConnectionJson().c_str());
+}
+
+void setup() {
+    Serial.begin(115200);
+    Serial.println("=== Controller Node Starting ===");
+    
+    // Initialize sensor storage
+    for (int i = 0; i < 10; i++) {
+        sensors[i].valid = false;
+    }
+    
+    mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+    mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+    mesh.onReceive(&receivedCallback);
+    mesh.onNewConnection(&newConnectionCallback);
+    mesh.onChangedConnections(&changedConnectionCallback);
+    
+    userScheduler.addTask(taskRequestData);
+    userScheduler.addTask(taskDisplayData);
+    taskRequestData.enable();
+    taskDisplayData.enable();
+    
+    Serial.printf("Controller Node initialized. Node ID: %u\n", mesh.getNodeId());
+}
+
+void loop() {
+    mesh.update();
+}
+```
+
+## Node 3: Bridge Node
+
+This node connects the mesh to WiFi/Internet for external connectivity.
+
+```cpp
+#include "painlessMesh.h"
+#include <WiFi.h>  // Use <ESP8266WiFi.h> for ESP8266
+
+#define MESH_PREFIX     "MyMeshNetwork"
+#define MESH_PASSWORD   "somethingSneaky"
+#define MESH_PORT       5555
+
+// External WiFi credentials
+#define STATION_SSID     "YourHomeWiFi"
+#define STATION_PASSWORD "YourWiFiPassword"
+
+Scheduler userScheduler;
+painlessMesh mesh;
+
+// Task to report bridge status
+Task taskBridgeStatus(30000, TASK_FOREVER, [](){
+    String status = "{";
+    status += "\"type\":\"bridge_status\",";
+    status += "\"nodeId\":" + String(mesh.getNodeId()) + ",";
+    status += "\"wifi_connected\":" + String(WiFi.status() == WL_CONNECTED ? "true" : "false") + ",";
+    status += "\"wifi_rssi\":" + String(WiFi.RSSI()) + ",";
+    status += "\"mesh_connections\":" + String(mesh.getNodeList().size()) + ",";
+    status += "\"timestamp\":" + String(mesh.getNodeTime());
+    status += "}";
+    
+    mesh.sendBroadcast(status);
+    Serial.printf("Bridge Status: WiFi=%s, RSSI=%d, Mesh Nodes=%d\n",
+                  WiFi.status() == WL_CONNECTED ? "Connected" : "Disconnected",
+                  WiFi.RSSI(), mesh.getNodeList().size());
+});
+
+void receivedCallback(uint32_t from, String &msg) {
+    Serial.printf("Bridge: Received from %u: %s\n", from, msg.c_str());
+    
+    // Forward sensor data to external server (example)
+    if (msg.indexOf("\"type\":\"sensor\"") > 0 && WiFi.status() == WL_CONNECTED) {
+        // Here you could forward to HTTP/MQTT/etc
+        Serial.println("Would forward sensor data to external server");
+    }
+}
+
+void newConnectionCallback(uint32_t nodeId) {
+    Serial.printf("Bridge: New mesh connection to %u\n", nodeId);
+}
+
+void changedConnectionCallback() {
+    Serial.printf("Bridge: Mesh topology changed. Nodes: %s\n", 
+                  mesh.subConnectionJson().c_str());
+}
+
+void setup() {
+    Serial.begin(115200);
+    Serial.println("=== Bridge Node Starting ===");
+    
+    // Initialize mesh
+    mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+    mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+    mesh.onReceive(&receivedCallback);
+    mesh.onNewConnection(&newConnectionCallback);
+    mesh.onChangedConnections(&changedConnectionCallback);
+    
+    // Connect to external WiFi
+    WiFi.begin(STATION_SSID, STATION_PASSWORD);
+    Serial.printf("Connecting to WiFi: %s", STATION_SSID);
+    
+    while (WiFi.status() != WL_CONNECTED) {
+        delay(500);
+        Serial.print(".");
+    }
+    Serial.println();
+    Serial.printf("WiFi connected! IP: %s\n", WiFi.localIP().toString().c_str());
+    
+    userScheduler.addTask(taskBridgeStatus);
+    taskBridgeStatus.enable();
+    
+    Serial.printf("Bridge Node initialized. Node ID: %u\n", mesh.getNodeId());
+}
+
+void loop() {
+    mesh.update();
+}
+```
+
+## Deployment Steps
+
+1. **Upload Sensor Node code** to your first ESP32/ESP8266
+2. **Upload Controller Node code** to your second device  
+3. **Upload Bridge Node code** to your third device (update WiFi credentials first!)
+4. **Power up all devices** and open Serial Monitors to watch them connect
+5. **Observe the mesh in action**:
+   - Sensor nodes broadcast environmental data
+   - Controller receives and processes sensor data
+   - Bridge provides external connectivity and status updates
+
+## What You'll See
+
+### Sensor Node Output
+```
+=== Sensor Node Starting ===
+Sensor Node initialized. Node ID: 123456789
+Sensor Node: New connection to 987654321
+Sent sensor data: T=23.2°C, H=67.4%
+```
+
+### Controller Node Output
+```
+=== Controller Node Starting ===
+Controller Node initialized. Node ID: 987654321
+Requested sensor data from all nodes
+Controller: Received from 123456789: {"type":"sensor",...}
+=== Collected Sensor Data ===
+Node 123456789 (Sensor 1001): T=23.2°C, H=67.4%, Age=5 seconds
+```
+
+### Bridge Node Output
+```
+=== Bridge Node Starting ===
+Connecting to WiFi: YourHomeWiFi....
+WiFi connected! IP: 192.168.1.100
+Bridge Node initialized. Node ID: 555444333
+Bridge Status: WiFi=Connected, RSSI=-45, Mesh Nodes=2
+```
+
+## Key Features Demonstrated
+
+- **Automatic Discovery**: Nodes find each other automatically
+- **Message Broadcasting**: Sensor data reaches all interested nodes
+- **JSON Communication**: Structured data exchange
+- **Command System**: Controller can request data from sensors
+- **External Connectivity**: Bridge connects mesh to Internet
+- **Self-Healing**: Network continues working if nodes disconnect
+
+## Extending Your Mesh
+
+### Add More Sensors
+- Temperature/humidity sensors (DHT22)
+- Motion detectors (PIR)
+- Light sensors (photoresistor)
+- Soil moisture sensors
+
+### Add Actuators
+- LED strips for notifications
+- Servo motors for mechanical control
+- Relays for switching devices
+- Buzzers for alerts
+
+### External Integrations
+- MQTT broker connectivity
+- HTTP REST API calls
+- Home Assistant integration
+- Cloud database logging
+
+## Next Steps
+
+- Explore [Custom Packages](../tutorials/custom-packages.md) for type-safe messaging
+- Learn about [Alteriom Extensions](../alteriom/overview.md) for pre-built sensor packages
+- Dive into [Advanced Topics](../advanced/performance.md) for optimization
+- Check out [Troubleshooting](../troubleshooting/common-issues.md) if you encounter issues
+
+Congratulations! You now have a working multi-node mesh network with real-world functionality.

package/docs/getting-started/installation.md

@@ -0,0 +1,275 @@
+# Installation Guide
+
+This guide covers all the different ways to install and set up painlessMesh for your development environment.
+
+## Arduino IDE Installation
+
+### Method 1: Library Manager (Recommended)
+
+1. Open Arduino IDE
+2. Go to **Sketch → Include Library → Manage Libraries**
+3. Search for "painlessMesh"
+4. Install the latest version by "Coopdis"
+5. Install dependencies when prompted:
+   - ArduinoJson
+   - TaskScheduler
+
+### Method 2: Manual Installation
+
+1. Download the latest release from [GitHub](https://github.com/Alteriom/painlessMesh/releases)
+2. Extract the ZIP file
+3. Copy the `painlessMesh` folder to your Arduino libraries directory:
+   - **Windows**: `Documents\Arduino\libraries\`
+   - **macOS**: `~/Documents/Arduino/libraries/`
+   - **Linux**: `~/Arduino/libraries/`
+4. Restart Arduino IDE
+
+## PlatformIO Installation
+
+### Method 1: platformio.ini (Recommended)
+
+Add to your `platformio.ini` file:
+
+```ini
+[env:esp32dev]
+platform = espressif32
+board = esp32dev
+framework = arduino
+lib_deps = 
+    painlessMesh
+    bblanchon/ArduinoJson@^6.21.3
+    arkhipenko/TaskScheduler@^3.7.0
+
+# For ESP8266
+[env:esp8266]
+platform = espressif8266
+board = nodemcuv2
+framework = arduino
+lib_deps = 
+    painlessMesh
+    bblanchon/ArduinoJson@^6.21.3
+    arkhipenko/TaskScheduler@^3.7.0
+```
+
+### Method 2: PlatformIO Library Manager
+
+```bash
+# Install via PlatformIO CLI
+pio lib install "painlessMesh"
+
+# Or install specific version
+pio lib install "painlessMesh@1.5.0"
+```
+
+## Board Support
+
+### ESP32 Boards
+painlessMesh supports all ESP32 variants:
+- ESP32 DevKit
+- ESP32-S2
+- ESP32-S3  
+- ESP32-C3
+- ESP32-WROOM
+- ESP32-WROVER
+
+### ESP8266 Boards
+All ESP8266 boards are supported:
+- NodeMCU
+- Wemos D1 Mini
+- ESP-12E/F
+- ESP-01 (with limitations due to memory)
+
+## Dependencies
+
+painlessMesh requires these libraries:
+
+### Core Dependencies
+- **ArduinoJson** (v6.x) - JSON parsing and generation
+- **TaskScheduler** (v3.x) - Task scheduling system
+
+### Platform Dependencies
+- **ESP32 Arduino Core** (v2.0.0+) for ESP32 boards
+- **ESP8266 Arduino Core** (v3.0.0+) for ESP8266 boards
+
+## Development Environment Setup
+
+### For Library Development
+
+If you plan to contribute to painlessMesh or need the latest development version:
+
+```bash
+# Clone the repository
+git clone https://github.com/Alteriom/painlessMesh.git
+cd painlessMesh
+
+# Initialize submodules
+git submodule init
+git submodule update
+
+# Install test dependencies (for desktop testing)
+cd test
+git clone https://github.com/bblanchon/ArduinoJson.git
+git clone https://github.com/arkhipenko/TaskScheduler.git
+cd ..
+
+# Build tests (requires CMake and Ninja)
+cmake -G Ninja .
+ninja
+```
+
+### Desktop Testing (Linux/macOS/Windows)
+
+For development and testing on your computer:
+
+#### Requirements
+- CMake 3.10+
+- Ninja build system
+- Boost libraries
+- C++14 compatible compiler
+
+#### Ubuntu/Debian
+```bash
+sudo apt update
+sudo apt install cmake ninja-build libboost-all-dev build-essential
+
+# Clone and build
+git clone https://github.com/Alteriom/painlessMesh.git
+cd painlessMesh
+git submodule update --init
+cmake -G Ninja .
+ninja
+
+# Run tests
+run-parts --regex catch_ bin/
+```
+
+#### macOS
+```bash
+# Install dependencies
+brew install cmake ninja boost
+
+# Clone and build
+git clone https://github.com/Alteriom/painlessMesh.git
+cd painlessMesh
+git submodule update --init
+cmake -G Ninja .
+ninja
+
+# Run tests
+run-parts --regex catch_ bin/
+```
+
+#### Windows
+Use Visual Studio with CMake support or install dependencies via vcpkg:
+
+```powershell
+# Install vcpkg first, then:
+vcpkg install boost:x64-windows
+cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=path/to/vcpkg.cmake .
+ninja
+```
+
+## Version Compatibility
+
+### Current Stable Version
+- **painlessMesh**: 1.5.x
+- **ArduinoJson**: 6.21.x
+- **TaskScheduler**: 3.7.x
+
+### Legacy Support
+- painlessMesh 1.4.x - Compatible with older ESP cores
+- ArduinoJson 5.x - No longer supported
+
+## Memory Requirements
+
+### ESP32
+- **RAM**: ~50KB minimum for basic mesh functionality
+- **Flash**: ~200KB for core library + your application
+- **Recommended**: 320KB+ RAM for complex applications
+
+### ESP8266
+- **RAM**: ~20KB minimum for basic mesh functionality  
+- **Flash**: ~150KB for core library + your application
+- **Recommended**: 80KB+ RAM for stable operation
+- **Note**: ESP-01 (512KB flash) may have limitations
+
+## Configuration Options
+
+### Build Flags
+
+Add these to your build configuration if needed:
+
+```ini
+# platformio.ini
+build_flags = 
+    -DPAINLESSMESH_ENABLE_DEBUG=1     # Enable debug output
+    -DPAINLESSMESH_MAX_CONNECTIONS=10  # Maximum connections
+    -DTASK_SCHEDULER_DEBUG=1          # TaskScheduler debug
+```
+
+### Arduino IDE Defines
+
+Add at the top of your sketch:
+
+```cpp
+#define PAINLESSMESH_ENABLE_DEBUG 1
+#define PAINLESSMESH_MAX_CONNECTIONS 10
+```
+
+## IDE-Specific Setup
+
+### Visual Studio Code + PlatformIO
+
+1. Install the PlatformIO IDE extension
+2. Create new project or open existing
+3. Add library dependencies to `platformio.ini`
+4. Use Ctrl+Shift+P → "PlatformIO: Build" to compile
+
+### Arduino IDE 2.0
+
+1. Install via Library Manager (same as Arduino IDE 1.x)
+2. Use the new autocomplete features for better development experience
+3. Debugging support available with compatible boards
+
+## Verification
+
+Test your installation with this minimal example:
+
+```cpp
+#include "painlessMesh.h"
+
+painlessMesh mesh;
+
+void setup() {
+    Serial.begin(115200);
+    Serial.println("painlessMesh installation test");
+    
+    // If this compiles and uploads successfully, installation is correct
+    mesh.init("TestNetwork", "password", 5555);
+    Serial.println("painlessMesh initialized successfully!");
+}
+
+void loop() {
+    mesh.update();
+}
+```
+
+If this compiles and uploads without errors, your installation is complete!
+
+## Next Steps
+
+- Try the [Quick Start Guide](quickstart.md) to create your first mesh
+- Explore [Basic Examples](../tutorials/basic-examples.md)
+- Read about [Mesh Architecture](../architecture/mesh-architecture.md)
+
+## Troubleshooting Installation
+
+**Library not found errors?**
+- Check that ArduinoJson and TaskScheduler are installed
+- Verify library versions are compatible
+- Try cleaning and rebuilding your project
+
+**Compilation errors?**
+- Ensure you're using a supported ESP32/ESP8266 core version
+- Check that your board selection matches your hardware
+- See [Common Issues](../troubleshooting/common-issues.md) for more help