@alteriom/painlessmesh 1.6.1

package/docs/wiki/API-Reference.md

@@ -0,0 +1,246 @@
+# API Reference
+
+This page contains the complete API reference for the Alteriom painlessMesh Library.
+
+## Core Classes
+
+### painlessMesh
+
+The main class for creating and managing mesh networks.
+
+#### Initialization Methods
+
+```cpp
+void init(String ssid, String password, Scheduler *baseScheduler, uint16_t port = 5555);
+void setDebugMsgTypes(uint16_t types);
+```
+
+#### Network Management
+
+```cpp
+void update();                                    // Call in loop()
+bool sendBroadcast(String &msg);                // Send to all nodes
+bool sendSingle(uint32_t &destId, String &msg); // Send to specific node
+```
+
+#### Event Callbacks
+
+```cpp
+void onReceive(std::function<void(uint32_t from, String &msg)> cb);
+void onNewConnection(std::function<void(uint32_t nodeId)> cb);
+void onChangedConnections(std::function<void()> cb);
+void onNodeTimeAdjusted(std::function<void(int32_t offset)> cb);
+```
+
+#### Node Information
+
+```cpp
+uint32_t getNodeId();                    // Get this node's ID
+std::list<uint32_t> getNodeList();      // Get all connected nodes
+uint32_t getNodeTime();                  // Get synchronized time
+size_t connectionCount();                // Number of direct connections
+```
+
+## Alteriom Extensions
+
+### SensorPackage (Type 200)
+
+Environmental data collection package for sensor networks.
+
+```cpp
+class SensorPackage : public painlessmesh::plugin::BroadcastPackage {
+public:
+    uint32_t sensorId = 0;        // Unique sensor identifier
+    uint32_t timestamp = 0;       // Unix timestamp
+    double temperature = 0.0;     // Temperature in Celsius
+    double humidity = 0.0;        // Relative humidity (0-100%)
+    double pressure = 0.0;        // Atmospheric pressure in hPa
+    uint8_t batteryLevel = 0;     // Battery level (0-100%)
+    
+    // Constructors
+    SensorPackage();
+    SensorPackage(JsonObject jsonObj);
+    
+    // Serialization
+    JsonObject addTo(JsonObject&& jsonObj) const;
+    size_t jsonObjectSize() const;
+};
+```
+
+**Usage Example:**
+```cpp
+SensorPackage sensor;
+sensor.sensorId = mesh.getNodeId();
+sensor.timestamp = mesh.getNodeTime();
+sensor.temperature = 23.5;
+sensor.humidity = 65.0;
+sensor.pressure = 1013.25;
+sensor.batteryLevel = 85;
+
+// Send as broadcast
+auto variant = painlessmesh::protocol::Variant(&sensor);
+String message;
+variant.printTo(message);
+mesh.sendBroadcast(message);
+```
+
+### CommandPackage (Type 201)
+
+Device control and automation commands for remote node management.
+
+```cpp
+class CommandPackage : public painlessmesh::plugin::SinglePackage {
+public:
+    uint8_t command = 0;          // Command type identifier
+    uint32_t targetDevice = 0;    // Target node ID
+    uint32_t commandId = 0;       // Unique command identifier
+    TSTRING parameters = "";      // JSON parameters string
+    
+    // Constructors
+    CommandPackage();
+    CommandPackage(JsonObject jsonObj);
+    
+    // Serialization
+    JsonObject addTo(JsonObject&& jsonObj) const;
+    size_t jsonObjectSize() const;
+};
+```
+
+**Usage Example:**
+```cpp
+CommandPackage cmd;
+cmd.dest = targetNodeId;
+cmd.command = 1;              // LED control
+cmd.targetDevice = targetNodeId;
+cmd.commandId = millis();
+cmd.parameters = "{\"state\":\"ON\",\"brightness\":75}";
+
+// Send to specific node
+auto variant = painlessmesh::protocol::Variant(&cmd);
+String message;
+variant.printTo(message);
+mesh.sendSingle(targetNodeId, message);
+```
+
+### StatusPackage (Type 202)
+
+Health monitoring and system status reporting for network diagnostics.
+
+```cpp
+class StatusPackage : public painlessmesh::plugin::BroadcastPackage {
+public:
+    uint8_t deviceStatus = 0;         // Device status flags
+    uint32_t uptime = 0;              // Uptime in seconds
+    uint16_t freeMemory = 0;          // Free memory in KB
+    uint8_t wifiStrength = 0;         // WiFi signal strength (0-100)
+    TSTRING firmwareVersion = "";     // Firmware version string
+    
+    // Constructors
+    StatusPackage();
+    StatusPackage(JsonObject jsonObj);
+    
+    // Serialization
+    JsonObject addTo(JsonObject&& jsonObj) const;
+    size_t jsonObjectSize() const;
+};
+```
+
+**Usage Example:**
+```cpp
+StatusPackage status;
+status.deviceStatus = 0x01;   // Operational
+status.uptime = millis() / 1000;
+status.freeMemory = ESP.getFreeHeap() / 1024;
+status.wifiStrength = 75;
+status.firmwareVersion = "1.6.1-alteriom";
+
+// Broadcast status
+auto variant = painlessmesh::protocol::Variant(&status);
+String message;
+variant.printTo(message);
+mesh.sendBroadcast(message);
+```
+
+## Message Handling
+
+### Receiving Messages
+
+```cpp
+void receivedCallback(uint32_t from, String& msg) {
+    DynamicJsonDocument doc(1024);
+    deserializeJson(doc, msg);
+    JsonObject obj = doc.as<JsonObject>();
+    uint8_t msgType = obj["type"];
+    
+    switch(msgType) {
+        case 200: // SensorPackage
+            handleSensorData(alteriom::SensorPackage(obj), from);
+            break;
+        case 201: // CommandPackage  
+            handleCommand(alteriom::CommandPackage(obj), from);
+            break;
+        case 202: // StatusPackage
+            handleStatus(alteriom::StatusPackage(obj), from);
+            break;
+        default:
+            Serial.printf("Unknown message type: %d\n", msgType);
+    }
+}
+```
+
+### Debug Message Types
+
+```cpp
+// Debug levels (can be combined with |)
+#define ERROR           0x00000001
+#define STARTUP         0x00000002  
+#define CONNECTION      0x00000004
+#define SYNC            0x00000008
+#define COMMUNICATION   0x00000010
+#define GENERAL         0x00000020
+#define MSG_TYPES       0x00000040
+#define REMOTE          0x00000080
+
+// Usage
+mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+```
+
+## Platform Constants
+
+### Memory Constraints
+- **ESP32**: ~320KB RAM available
+- **ESP8266**: ~80KB RAM available
+- **MAX_CONN**: Typically 4-10 connections depending on platform
+
+### Network Limits
+- **Message Size**: Recommended max 4KB
+- **String Length**: Recommended max 256 characters for compatibility
+- **Network Delay**: ~50-200ms typical mesh routing delay
+
+## Error Handling
+
+### Common Return Values
+- **`true`**: Operation successful
+- **`false`**: Operation failed (check network/memory)
+
+### Best Practices
+```cpp
+// Always check return values
+if (!mesh.sendBroadcast(message)) {
+    Serial.println("Failed to send message");
+    // Implement retry logic or error handling
+}
+
+// Monitor connection changes
+void changedConnectionCallback() {
+    auto nodeList = mesh.getNodeList();
+    Serial.printf("Network size: %d nodes\n", nodeList.size() + 1);
+}
+```
+
+## See Also
+
+- [Installation Guide](Installation)
+- [Examples](Examples)
+- [GitHub Repository](https://github.com/Alteriom/painlessMesh)
+- [Release Notes](https://github.com/Alteriom/painlessMesh/releases)

package/docs/wiki/Complete-Documentation.md

@@ -0,0 +1,123 @@
+# Complete Documentation
+
+Welcome to the complete documentation for Alteriom painlessMesh Library!
+
+## 📖 Documentation Sections
+
+### Getting Started
+- [Installation Guide](Installation) - Set up the library in your development environment
+- [Quick Start](https://github.com/Alteriom/painlessMesh/blob/main/docs/getting-started/quickstart.md) - Your first mesh network
+- [First Mesh Tutorial](https://github.com/Alteriom/painlessMesh/blob/main/docs/getting-started/first-mesh.md) - Step-by-step guide
+
+### API Documentation
+- [API Reference](API-Reference) - Complete class and method documentation
+- [Core API](https://github.com/Alteriom/painlessMesh/blob/main/docs/api/core-api.md) - painlessMesh core functionality
+- [Plugin System](https://github.com/Alteriom/painlessMesh/blob/main/docs/architecture/plugin-system.md) - Extensible architecture
+
+### Examples and Tutorials
+- [Examples](Examples) - Working code examples
+- [Basic Examples](https://github.com/Alteriom/painlessMesh/blob/main/docs/tutorials/basic-examples.md) - Fundamental usage patterns
+- [Alteriom Extensions](https://github.com/Alteriom/painlessMesh/blob/main/docs/alteriom/overview.md) - SensorPackage, CommandPackage, StatusPackage
+
+### Architecture
+- [Mesh Architecture](https://github.com/Alteriom/painlessMesh/blob/main/docs/architecture/mesh-architecture.md) - How the mesh network works
+- [Plugin System](https://github.com/Alteriom/painlessMesh/blob/main/docs/architecture/plugin-system.md) - Extensible package system
+
+### Troubleshooting
+- [FAQ](https://github.com/Alteriom/painlessMesh/blob/main/docs/troubleshooting/faq.md) - Frequently asked questions
+- [Common Issues](https://github.com/Alteriom/painlessMesh/blob/main/docs/troubleshooting/common-issues.md) - Solutions to common problems
+
+### Development
+- [Contributing Guidelines](Contributing) - How to contribute to the project
+- [Release Guide](https://github.com/Alteriom/painlessMesh/blob/main/RELEASE_GUIDE.md) - Release process documentation
+
+## 🚀 Quick Links
+
+### Installation
+```bash
+# Arduino Library Manager
+Tools → Manage Libraries → Search "Alteriom PainlessMesh"
+
+# PlatformIO
+lib_deps = alteriom/painlessMesh@^1.6.1
+
+# NPM
+npm install @alteriom/painlessmesh
+```
+
+### Basic Usage
+```cpp
+#include "painlessMesh.h"
+
+#define MESH_PREFIX     "YourMeshName"
+#define MESH_PASSWORD   "YourPassword"
+#define MESH_PORT       5555
+
+Scheduler userScheduler;
+painlessMesh mesh;
+
+void setup() {
+  Serial.begin(115200);
+  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+  mesh.onReceive([](uint32_t from, String& msg) {
+    Serial.printf("Received: %s from %u\n", msg.c_str(), from);
+  });
+}
+
+void loop() {
+  mesh.update();
+}
+```
+
+## 📦 Package Types
+
+### SensorPackage (Type 200)
+For environmental sensor data collection:
+- Temperature, humidity, pressure measurements
+- Battery level monitoring
+- Timestamp synchronization
+
+### CommandPackage (Type 201)
+For device control and automation:
+- Remote device commands
+- Parameter passing via JSON
+- Command acknowledgment tracking
+
+### StatusPackage (Type 202)
+For system health monitoring:
+- Device operational status
+- Memory usage tracking
+- Network connectivity metrics
+
+## 🌟 Key Features
+
+- **Automatic Mesh Formation** - Nodes discover and connect automatically
+- **JSON-Based Messaging** - Easy to use and extend
+- **Time Synchronization** - Coordinated behaviors across nodes
+- **Multi-Platform Support** - ESP32, ESP8266
+- **Alteriom Extensions** - Enhanced packages for common use cases
+- **Comprehensive Testing** - Full CI/CD pipeline with automated testing
+
+## 📚 External Resources
+
+- **GitHub Repository**: https://github.com/Alteriom/painlessMesh
+- **NPM Package**: https://www.npmjs.com/package/@alteriom/painlessmesh
+- **PlatformIO Registry**: https://registry.platformio.org/libraries/alteriom/painlessMesh
+- **Issue Tracker**: https://github.com/Alteriom/painlessMesh/issues
+- **Discussions**: https://github.com/Alteriom/painlessMesh/discussions
+
+## 📝 License
+
+This project is licensed under LGPL-3.0 - see the [LICENSE](https://github.com/Alteriom/painlessMesh/blob/main/LICENSE) file for details.
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guidelines](Contributing) for details on:
+- Code style and standards
+- Pull request process
+- Issue reporting
+- Feature requests
+
+---
+
+**Need Help?** Check the [FAQ](https://github.com/Alteriom/painlessMesh/blob/main/docs/troubleshooting/faq.md) or [open an issue](https://github.com/Alteriom/painlessMesh/issues).

package/examples/alteriom/README.md

@@ -0,0 +1,82 @@
+# Alteriom painlessMesh Extensions
+
+This directory contains Alteriom-specific extensions and examples for the painlessMesh library.
+
+## Package Types
+
+### SensorPackage (Type 200)
+Broadcast package for sharing environmental sensor data across the mesh.
+
+**Fields:**
+- `temperature` - Temperature in Celsius
+- `humidity` - Relative humidity percentage  
+- `pressure` - Atmospheric pressure in hPa
+- `sensorId` - Unique sensor identifier
+- `timestamp` - Unix timestamp of measurement
+- `batteryLevel` - Battery level percentage (0-100)
+
+### CommandPackage (Type 201)
+Single-destination package for sending commands to specific nodes.
+
+**Fields:**
+- `command` - Command type identifier
+- `targetDevice` - Target device ID
+- `parameters` - Command parameters as JSON string
+- `commandId` - Unique command identifier for tracking
+
+### StatusPackage (Type 202)
+Broadcast package for sharing device health and status information.
+
+**Fields:**
+- `deviceStatus` - Device status flags
+- `uptime` - Device uptime in seconds
+- `freeMemory` - Free memory in KB
+- `wifiStrength` - WiFi signal strength (0-100)
+- `firmwareVersion` - Current firmware version string
+
+## Examples
+
+### `alteriom_sensor_node.ino`
+Complete Arduino sketch demonstrating:
+- Periodic sensor data broadcasting
+- Command handling
+- Status reporting
+- Message type discrimination
+- Integration with painlessMesh
+
+## Usage
+
+```cpp
+#include "alteriom_sensor_package.hpp"
+using namespace alteriom;
+
+// Create and send sensor data
+SensorPackage sensor;
+sensor.temperature = 25.0;
+sensor.humidity = 60.0;
+// ... set other fields
+mesh.sendBroadcast(sensor.toJsonString());
+
+// Handle incoming commands
+void handleMessage(String& msg) {
+    auto doc = parseJson(msg);
+    if (doc["type"] == 201) {
+        CommandPackage cmd(doc.as<JsonObject>());
+        processCommand(cmd);
+    }
+}
+```
+
+## Testing
+
+Run the Alteriom package tests:
+```bash
+./bin/catch_alteriom_packages
+```
+
+This validates:
+- JSON serialization/deserialization
+- Package type consistency
+- Field preservation
+- Edge case handling
+- Integration with painlessMesh plugin system

package/examples/alteriom/alteriom.ino

@@ -0,0 +1,186 @@
+//************************************************************
+// AlteriomPainlessMesh Example
+//
+// This example demonstrates how to use AlteriomPainlessMesh
+// with custom packages for sensor data, commands, and status
+// 
+// This is the primary example that matches the folder name
+// for Arduino Library Manager compatibility
+//************************************************************
+
+#include "AlteriomPainlessMesh.h"
+
+#define MESH_PREFIX "AlteriomMesh"
+#define MESH_PASSWORD "somethingSneaky"
+#define MESH_PORT 5555
+
+Scheduler userScheduler;  // to control your personal task
+painlessMesh mesh;
+
+// Alteriom package handlers
+using namespace alteriom;
+
+// User stub
+void sendSensorData();
+void handleIncomingPackage(uint32_t from, String& msg);
+void handleCommandPackage(CommandPackage& cmd);
+void handleStatusRequest();
+
+Task taskSendSensorData(30000, TASK_FOREVER, &sendSensorData);
+Task taskSendStatus(60000, TASK_FOREVER, &handleStatusRequest);
+
+void setup() {
+  Serial.begin(115200);
+
+  // Initialize mesh
+  mesh.setDebugMsgTypes(ERROR | MESH_STATUS | CONNECTION | SYNC |
+                        COMMUNICATION | GENERAL | MSG_TYPES | REMOTE);
+  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+  mesh.onReceive(&handleIncomingPackage);
+  mesh.onNewConnection(&newConnectionCallback);
+  mesh.onChangedConnections(&changedConnectionCallback);
+  mesh.onNodeTimeAdjusted(&nodeTimeAdjustedCallback);
+
+  // Add tasks
+  userScheduler.addTask(taskSendSensorData);
+  taskSendSensorData.enable();
+
+  userScheduler.addTask(taskSendStatus);
+  taskSendStatus.enable();
+
+  // Initialize sensors (placeholder)
+  Serial.println("Alteriom Sensor Node initialized");
+}
+
+void loop() { mesh.update(); }
+
+void sendSensorData() {
+  // Create sensor package
+  SensorPackage sensorData;
+  sensorData.from = mesh.getNodeId();
+  sensorData.sensorId = mesh.getNodeId();  // Use node ID as sensor ID
+  sensorData.timestamp = mesh.getNodeTime();
+
+  // Read sensor values (placeholder - replace with actual sensor readings)
+  sensorData.temperature =
+      23.5 + random(-50, 50) / 10.0;  // Simulate temperature
+  sensorData.humidity = 45.0 + random(-100, 100) / 10.0;   // Simulate humidity
+  sensorData.pressure = 1013.25 + random(-50, 50) / 10.0;  // Simulate pressure
+  sensorData.batteryLevel = 85 + random(-20, 15);          // Simulate battery
+
+  // Serialize and send
+  DynamicJsonDocument doc(sensorData.jsonObjectSize());
+  JsonObject obj = doc.to<JsonObject>();
+  sensorData.addTo(std::move(obj));
+
+  String msg;
+  serializeJson(doc, msg);
+  mesh.sendBroadcast(msg);
+
+  Serial.printf("Sent sensor data: T=%.1f, H=%.1f, P=%.1f, Bat=%d%%\n",
+                sensorData.temperature, sensorData.humidity,
+                sensorData.pressure, sensorData.batteryLevel);
+}
+
+void handleStatusRequest() {
+  StatusPackage status;
+  status.from = mesh.getNodeId();
+  status.deviceStatus = 0x01;  // Device operational
+  status.uptime = millis() / 1000;
+  status.freeMemory = ESP.getFreeHeap() / 1024;  // KB
+  status.wifiStrength = 75;                      // Placeholder
+  status.firmwareVersion = "1.0.0-alteriom";
+
+  // Serialize and send
+  DynamicJsonDocument doc(status.jsonObjectSize());
+  JsonObject obj = doc.to<JsonObject>();
+  status.addTo(std::move(obj));
+
+  String msg;
+  serializeJson(doc, msg);
+  mesh.sendBroadcast(msg);
+
+  Serial.printf("Sent status: uptime=%ds, mem=%dKB\n", status.uptime,
+                status.freeMemory);
+}
+
+void handleIncomingPackage(uint32_t from, String& msg) {
+  Serial.printf("Received from %u: %s\n", from, msg.c_str());
+
+  // Parse the JSON message
+  DynamicJsonDocument doc(1024);
+  deserializeJson(doc, msg);
+  JsonObject obj = doc.as<JsonObject>();
+
+  // Check message type
+  uint8_t msgType = obj["type"];
+
+  switch (msgType) {
+    case 200:  // SensorPackage
+    {
+      SensorPackage receivedSensor(obj);
+      Serial.printf("Sensor data from %u: T=%.1f, H=%.1f\n",
+                    receivedSensor.from, receivedSensor.temperature,
+                    receivedSensor.humidity);
+      // Process sensor data (store, forward, analyze, etc.)
+    } break;
+
+    case 201:  // CommandPackage
+    {
+      CommandPackage receivedCmd(obj);
+      if (receivedCmd.dest == mesh.getNodeId()) {
+        handleCommandPackage(receivedCmd);
+      }
+    } break;
+
+    case 202:  // StatusPackage
+    {
+      StatusPackage receivedStatus(obj);
+      Serial.printf("Status from %u: uptime=%ds, mem=%dKB, fw=%s\n",
+                    receivedStatus.from, receivedStatus.uptime,
+                    receivedStatus.freeMemory,
+                    receivedStatus.firmwareVersion.c_str());
+    } break;
+
+    default:
+      Serial.printf("Unknown message type: %d\n", msgType);
+      break;
+  }
+}
+
+void handleCommandPackage(CommandPackage& cmd) {
+  Serial.printf("Received command %d for device %u\n", cmd.command,
+                cmd.targetDevice);
+
+  // Process different command types
+  switch (cmd.command) {
+    case 1:  // Reset command
+      Serial.println("Reset command received");
+      // Implement reset logic
+      break;
+
+    case 2:  // Configuration update
+      Serial.printf("Config update: %s\n", cmd.parameters.c_str());
+      // Parse and apply configuration
+      break;
+
+    case 3:  // Data request
+      Serial.println("Data request received");
+      sendSensorData();  // Send current sensor data
+      break;
+
+    default:
+      Serial.printf("Unknown command: %d\n", cmd.command);
+      break;
+  }
+}
+
+void newConnectionCallback(uint32_t nodeId) {
+  Serial.printf("New Connection, nodeId = %u\n", nodeId);
+}
+
+void changedConnectionCallback() { Serial.printf("Changed connections\n"); }
+
+void nodeTimeAdjustedCallback(int32_t offset) {
+  Serial.printf("Adjusted time %u. Offset = %d\n", mesh.getNodeTime(), offset);
+}