@alteriom/painlessmesh 1.9.18 → 1.9.20

package/docs/README.md

@@ -1,132 +0,0 @@
-# 📚 AlteriomPainlessMesh Documentation
-
-Welcome to the comprehensive documentation for the Alteriom fork of painlessMesh - a user-friendly ESP8266/ESP32 mesh networking library with advanced OTA updates, MQTT integration, and structured IoT packages.
-
-## 🌟 What's New in Alteriom Fork
-
-- **Broadcast OTA Distribution** - 98% network traffic reduction for large meshes
-- **MQTT Status Bridge** - Enterprise monitoring integration (Grafana, InfluxDB)
-- **Structured Packages** - SensorPackage, CommandPackage, StatusPackage
-- **Enhanced CI/CD** - Automated releases to NPM, PlatformIO, Arduino Library Manager
-
-## 📖 Documentation Structure
-
-### Getting Started
-
-- [Quick Start Guide](getting-started/quickstart.md) - Get up and running in minutes
-- [Installation](getting-started/installation.md) - Detailed installation instructions
-- [First Mesh Network](getting-started/first-mesh.md) - Your first working mesh
-
-### Architecture & Design  
-
-- [Mesh Architecture](architecture/mesh-architecture.md) - How painlessMesh works internally
-- [Plugin System](architecture/plugin-system.md) - Understanding the plugin architecture
-- [Message Routing](architecture/routing.md) - Message routing algorithms and strategies
-- [Time Synchronization](architecture/time-sync.md) - Mesh-wide time synchronization
-
-### API Reference
-
-- [Core API](api/core-api.md) - Main painlessMesh class methods
-- [Shared Gateway API](api/shared-gateway.md) - Shared Gateway Mode reference (v1.9.0+)
-- [Plugin API](api/plugin-api.md) - Creating custom packages and plugins
-- [Configuration](api/configuration.md) - Configuration options and constants
-- [Callbacks](api/callbacks.md) - Event handling and callbacks
-
-### Tutorials & Examples
-
-- [Basic Examples](tutorials/basic-examples.md) - Simple mesh networking examples
-- [Custom Packages](tutorials/custom-packages.md) - Creating your own message types
-- [Sensor Networks](tutorials/sensor-networks.md) - Building IoT sensor networks
-- [Bridge to Internet](../BRIDGE_TO_INTERNET.md) - Connecting mesh to WiFi/Internet/MQTT
-
-### Alteriom Extensions
-
-- [Alteriom Overview](alteriom/overview.md) - Alteriom-specific functionality
-- [Sensor Packages](alteriom/sensor-packages.md) - Environmental sensor data handling
-- [Command System](alteriom/command-system.md) - Device command and control
-- [Status Monitoring](alteriom/status-monitoring.md) - Device health and diagnostics
-
-### 📡 MQTT Integration
-
-- **[MQTT Bridge Commands](MQTT_BRIDGE_COMMANDS.md)** - Complete MQTT command API
-- **[MQTT Bridge Implementation](MQTT_BRIDGE_IMPLEMENTATION_SUMMARY.md)** - Implementation details
-- **[MQTT Schema Compliance](MQTT_SCHEMA_COMPLIANCE.md)** - Schema validation
-- **[OTA Commands Reference](OTA_COMMANDS_REFERENCE.md)** - OTA update commands
-- **[Mesh Topology Guide](MESH_TOPOLOGY_GUIDE.md)** - Topology reporting over MQTT
-
-### Advanced Topics
-
-- [Performance Optimization](advanced/performance.md) - Optimizing mesh performance
-- [Memory Management](advanced/memory.md) - Managing ESP8266/ESP32 memory constraints
-- [Security Considerations](advanced/security.md) - Securing your mesh network
-- [OTA Updates](advanced/ota.md) - Over-the-air firmware updates in mesh
-
-### Troubleshooting
-
-- [Common Issues](troubleshooting/common-issues.md) - Solutions to frequent problems
-- [ESP32-C6 Compatibility](troubleshooting/ESP32_C6_COMPATIBILITY.md) - ESP32-C6 specific issues and solutions
-- [Debugging Guide](troubleshooting/debugging.md) - Tools and techniques for debugging
-- [FAQ](troubleshooting/faq.md) - Frequently asked questions
-- [Network Issues](troubleshooting/network-issues.md) - Connectivity and mesh topology problems
-
-### Development
-
-- [Contributing](development/contributing.md) - How to contribute to painlessMesh
-- [Building & Testing](development/building.md) - Development environment setup
-- [Documentation](development/documentation.md) - Contributing to documentation
-- [Release Process](development/releases.md) - Understanding releases and versioning
-- **[Docker Testing](development/DOCKER_TESTING.md)** - Containerized testing environment
-- **[Testing Summary](development/TESTING_SUMMARY.md)** - Complete test suite overview
-- **[Arduino Compliance](development/ARDUINO_COMPLIANCE_SUMMARY.md)** - Arduino Library Manager standards
-- **[PlatformIO Usage](development/PLATFORMIO_USAGE.md)** - PlatformIO integration guide
-
-### 📦 Releases & Changelogs
-
-- **[Feature History](releases/FEATURE_HISTORY.md)** - ⭐ Consolidated Phase 1 & 2 development history
-- **[Release Notes v1.7.0](releases/RELEASE_NOTES_1.7.0.md)** - Detailed v1.7.0 release notes
-- **[CHANGELOG](../CHANGELOG.md)** - Complete version history
-- **[RELEASE_GUIDE](../RELEASE_GUIDE.md)** - Maintainer release process
-- [Phase 1 Details](releases/PHASE1_SUMMARY.md) - v1.6.x detailed summary (archived)
-- [Phase 2 Details](releases/PHASE2_SUMMARY.md) - v1.7.x detailed summary (archived)
-
-### 🗂️ Core Documentation (Root)
-
-- **[Main README](../README.md)** - Project overview and quick start
-- **[CONTRIBUTING](../CONTRIBUTING.md)** - Contribution guidelines
-- **[LICENSE](../LICENSE)** - LGPL-3.0 license terms
-
-### 🗃️ Historical & Archive
-
-- **[Archive](archive/)** - Historical bug fixes and obsolete documentation
-  - Bug fix documentation (SCONS, VECTOR, LIBRARY fixes)
-  - Legacy deployment guides
-  - Superseded release documentation
-
-### 🚀 Improvements & Enhancements
-
-- **[Improvements Overview](improvements/README.md)** - Complete guide to library enhancements
-- **[OTA & Status Enhancements](improvements/OTA_STATUS_ENHANCEMENTS.md)** 📋 - Complete reference for all options
-  - ✅ Phase 1 (v1.6.x): Compressed OTA + Enhanced Status
-  - ✅ Phase 2 (v1.7.0): Broadcast OTA + MQTT Bridge
-  - 📋 Phase 3 (Future): Progressive rollout, P2P distribution, real-time telemetry
-- **[Implementation History](improvements/IMPLEMENTATION_HISTORY.md)** 🔧 - Technical details for Phases 1-2
-- **[Future Proposals](improvements/FUTURE_PROPOSALS.md)** 🚀 - Phase 3+ roadmap and specifications
-
-## Quick Links
-
-- **[GitHub Repository](https://github.com/Alteriom/painlessMesh)**
-- **[API Documentation](https://alteriom.github.io/painlessMesh/#/api/doxygen)**
-- **[Community Forum](https://groups.google.com/forum/#!forum/painlessmesh-user)**
-- **[Issue Tracker](https://github.com/Alteriom/painlessMesh/issues)**
-
-## Need Help?
-
-- Start with the [Quick Start Guide](getting-started/quickstart.md)
-- Check the [FAQ](troubleshooting/faq.md) for common questions
-- Browse [Examples](tutorials/basic-examples.md) for practical use cases
-- Join our [Community Forum](https://groups.google.com/forum/#!forum/painlessmesh-user)
-- Report bugs on the [Issue Tracker](https://github.com/Alteriom/painlessMesh/issues)
-
----
-
-This documentation is maintained by the painlessMesh community. Contributions are welcome! See our [Documentation Contributing Guide](development/documentation.md) to get started.

package/docs/alteriom/overview.md

@@ -1,531 +0,0 @@
-# Alteriom Extensions Overview
-
-The Alteriom extensions provide production-ready, type-safe packages for common IoT scenarios. These extensions demonstrate best practices for the painlessMesh plugin system while providing immediately useful functionality for sensor networks, device control, and system monitoring.
-
-## What are Alteriom Extensions?
-
-Alteriom extensions are pre-built painlessMesh packages that handle common IoT communication patterns:
-
-- **Environmental Monitoring**: Temperature, humidity, pressure sensors
-- **Device Control**: Commands for actuators, displays, relays  
-- **Health Monitoring**: Device status, diagnostics, and telemetry
-- **Type Safety**: Compile-time validation and automatic serialization
-- **Production Ready**: Tested, documented, and optimized implementations
-
-## Package Types
-
-### SensorPackage (Type 200)
-For broadcasting environmental sensor data across the mesh.
-
-```cpp
-alteriom::SensorPackage sensor;
-sensor.temperature = 23.5;
-sensor.humidity = 65.0;
-sensor.pressure = 1013.25;
-sensor.sensorId = 1001;
-sensor.timestamp = mesh.getNodeTime();
-sensor.batteryLevel = 85;
-
-mesh.sendPackage(&sensor);
-```
-
-**Use Cases:**
-- Weather stations
-- Environmental monitoring
-- HVAC system feedback
-- Greenhouse automation
-- Industrial sensor networks
-
-### CommandPackage (Type 400)
-For sending control commands to specific devices.
-
-```cpp
-alteriom::CommandPackage cmd;
-cmd.dest = targetNodeId;
-cmd.command = 1; // LED_CONTROL
-cmd.targetDevice = 100; // LED strip ID
-cmd.parameters = "{\"brightness\":75,\"color\":\"blue\"}";
-cmd.commandId = generateCommandId();
-
-mesh.sendPackage(&cmd);
-```
-
-**Use Cases:**
-- Remote device control
-- Actuator management
-- Display updates
-- System configuration
-- Automation triggers
-
-### StatusPackage (Type 202)
-For broadcasting device health and operational status.
-
-```cpp
-alteriom::StatusPackage status;
-status.deviceStatus = 1; // OPERATIONAL
-status.uptime = millis() / 1000;
-status.freeMemory = ESP.getFreeHeap();
-status.wifiStrength = WiFi.RSSI();
-status.firmwareVersion = "1.2.3";
-
-mesh.sendPackage(&status);
-```
-
-**Use Cases:**
-- System monitoring
-- Predictive maintenance
-- Network diagnostics
-- Performance tracking
-- Remote troubleshooting
-
-## Key Features
-
-### Type Safety
-Compile-time validation prevents common messaging errors:
-
-```cpp
-// Compile error if field types don't match
-sensor.temperature = "invalid"; // ❌ Compiler error
-sensor.temperature = 25.0;      // ✅ Correct
-
-// IDE autocomplete for all fields
-sensor.| // IDE shows: temperature, humidity, pressure, etc.
-```
-
-### Automatic Serialization
-No manual JSON handling required:
-
-```cpp
-// Automatic serialization to JSON
-mesh.sendPackage(&sensor);
-
-// Automatic deserialization from JSON
-mesh.onPackage(200, [](protocol::Variant& variant) {
-    alteriom::SensorPackage received = variant.to<alteriom::SensorPackage>();
-    // All fields automatically populated
-});
-```
-
-### Cross-Platform Compatibility
-Works on ESP32, ESP8266, and desktop platforms:
-
-```cpp
-// TSTRING adapts to platform
-#ifdef ESP32
-    // Uses Arduino String class
-#else
-    // Uses std::string on desktop
-#endif
-```
-
-### Memory Optimization
-Efficient memory usage for resource-constrained devices:
-
-```cpp
-// Accurate buffer sizing
-size_t bufferSize = sensor.jsonObjectSize();
-
-// Minimal memory footprint
-// No unnecessary string copies or allocations
-```
-
-## Architecture Integration
-
-### Plugin System
-Alteriom packages integrate seamlessly with painlessMesh's plugin architecture:
-
-```
-Application Layer (Your Code)
-    ↓
-Alteriom Packages (SensorPackage, CommandPackage, StatusPackage)  
-    ↓
-painlessMesh Plugin System (SinglePackage, BroadcastPackage)
-    ↓
-painlessMesh Core (Mesh, Protocol, Network)
-```
-
-### Message Flow
-```
-Sensor Reading → SensorPackage → JSON → Mesh Network → JSON → SensorPackage → Handler
-```
-
-### Type ID Allocation
-Alteriom uses reserved type ID range 200-299:
-
-```cpp
-enum AlteriomTypes {
-    ALTERIOM_SENSOR = 200,    // SensorPackage
-    ALTERIOM_COMMAND = 400,   // CommandPackage  
-    ALTERIOM_STATUS = 202,    // StatusPackage
-    // 203-299 reserved for future Alteriom packages
-};
-```
-
-## Getting Started
-
-### 1. Include Alteriom Headers
-
-```cpp
-#include "painlessMesh.h"
-#include "examples/alteriom/alteriom_sensor_package.hpp"
-
-using namespace alteriom; // For convenience
-```
-
-### 2. Register Package Handlers
-
-```cpp
-void setup() {
-    mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
-    
-    // Register handlers for Alteriom packages
-    mesh.onPackage(ALTERIOM_SENSOR, handleSensorData);
-    mesh.onPackage(ALTERIOM_COMMAND, handleCommand);
-    mesh.onPackage(ALTERIOM_STATUS, handleStatus);
-}
-```
-
-### 3. Implement Handlers
-
-```cpp
-void handleSensorData(protocol::Variant& variant) {
-    SensorPackage sensor = variant.to<SensorPackage>();
-    
-    Serial.printf("Sensor %u: T=%.1f°C, H=%.1f%%, P=%.1f hPa\n",
-                 sensor.sensorId, sensor.temperature, 
-                 sensor.humidity, sensor.pressure);
-    
-    // Process sensor data (store, analyze, forward, etc.)
-    if (sensor.temperature > 30.0) {
-        triggerCooling();
-    }
-}
-
-void handleCommand(protocol::Variant& variant) {
-    CommandPackage cmd = variant.to<CommandPackage>();
-    
-    if (cmd.dest != mesh.getNodeId()) {
-        return; // Not for this node
-    }
-    
-    Serial.printf("Command %u for device %u: %u\n",
-                 cmd.commandId, cmd.targetDevice, cmd.command);
-    
-    // Execute command
-    executeDeviceCommand(cmd);
-    
-    // Send acknowledgment
-    sendCommandAcknowledgment(cmd);
-}
-```
-
-### 4. Send Packages
-
-```cpp
-// Send sensor data every 30 seconds
-Task taskSensorData(30000, TASK_FOREVER, [](){
-    SensorPackage sensor;
-    sensor.from = mesh.getNodeId();
-    sensor.temperature = readTemperature();
-    sensor.humidity = readHumidity();
-    sensor.pressure = readPressure();
-    sensor.sensorId = SENSOR_ID;
-    sensor.timestamp = mesh.getNodeTime();
-    sensor.batteryLevel = readBatteryLevel();
-    
-    mesh.sendPackage(&sensor);
-});
-```
-
-## Advanced Usage
-
-### Custom Command Types
-
-Define application-specific command types:
-
-```cpp
-enum DeviceCommands {
-    LED_CONTROL = 1,
-    SERVO_POSITION = 2,
-    RELAY_SWITCH = 3,
-    DISPLAY_UPDATE = 4,
-    SENSOR_CALIBRATION = 5
-};
-
-void executeDeviceCommand(const CommandPackage& cmd) {
-    switch(cmd.command) {
-        case LED_CONTROL:
-            handleLEDCommand(cmd);
-            break;
-        case SERVO_POSITION:
-            handleServoCommand(cmd);
-            break;
-        // ... other commands
-    }
-}
-```
-
-### Command Parameters
-
-Use JSON parameters for complex commands:
-
-```cpp
-void handleLEDCommand(const CommandPackage& cmd) {
-    // Parse JSON parameters
-    DynamicJsonDocument doc(256);
-    deserializeJson(doc, cmd.parameters);
-    
-    int brightness = doc["brightness"];
-    String color = doc["color"];
-    int duration = doc["duration"];
-    
-    // Execute LED control
-    setLEDColor(color);
-    setLEDBrightness(brightness);
-    if (duration > 0) {
-        scheduleAutoOff(duration);
-    }
-}
-```
-
-### Status Monitoring
-
-Implement comprehensive device monitoring:
-
-```cpp
-void sendStatusUpdate() {
-    StatusPackage status;
-    status.from = mesh.getNodeId();
-    status.deviceStatus = getDeviceStatus();
-    status.uptime = millis() / 1000;
-    status.freeMemory = ESP.getFreeHeap();
-    status.wifiStrength = WiFi.RSSI();
-    status.firmwareVersion = FIRMWARE_VERSION;
-    
-    // Add custom diagnostics
-    if (ESP.getFreeHeap() < 10000) {
-        status.deviceStatus |= STATUS_LOW_MEMORY;
-    }
-    if (WiFi.RSSI() < -80) {
-        status.deviceStatus |= STATUS_WEAK_SIGNAL;
-    }
-    
-    mesh.sendPackage(&status);
-}
-```
-
-### Error Handling
-
-Implement robust error handling:
-
-```cpp
-void handleSensorData(protocol::Variant& variant) {
-    try {
-        SensorPackage sensor = variant.to<SensorPackage>();
-        
-        // Validate sensor data
-        if (!isValidSensorReading(sensor)) {
-            Serial.printf("Invalid sensor data from node %u\n", sensor.from);
-            return;
-        }
-        
-        // Check data age
-        uint32_t age = mesh.getNodeTime() - sensor.timestamp;
-        if (age > MAX_DATA_AGE) {
-            Serial.printf("Stale sensor data (age: %u µs)\n", age);
-            return;
-        }
-        
-        processSensorData(sensor);
-        
-    } catch (const std::exception& e) {
-        Serial.printf("Error processing sensor data: %s\n", e.what());
-    }
-}
-```
-
-## Integration Patterns
-
-### Sensor Network Pattern
-
-Central collector with multiple sensor nodes:
-
-```cpp
-class SensorCollector {
-private:
-    std::map<uint32_t, SensorData> sensorReadings;
-    
-public:
-    void setup() {
-        mesh.onPackage(ALTERIOM_SENSOR, [this](protocol::Variant& variant) {
-            SensorPackage sensor = variant.to<SensorPackage>();
-            storeSensorReading(sensor);
-            return false;
-        });
-    }
-    
-    void storeSensorReading(const SensorPackage& sensor) {
-        sensorReadings[sensor.from] = {
-            sensor.temperature,
-            sensor.humidity, 
-            sensor.pressure,
-            sensor.timestamp
-        };
-        
-        // Trigger analysis
-        analyzeEnvironmentalData();
-    }
-};
-```
-
-### Command and Control Pattern
-
-Central controller managing multiple devices:
-
-```cpp
-class DeviceController {
-private:
-    std::map<uint32_t, DeviceInfo> devices;
-    
-public:
-    void controlDevice(uint32_t nodeId, uint32_t deviceId, 
-                      uint8_t command, const String& parameters) {
-        CommandPackage cmd;
-        cmd.dest = nodeId;
-        cmd.command = command;
-        cmd.targetDevice = deviceId;
-        cmd.parameters = parameters;
-        cmd.commandId = generateCommandId();
-        
-        mesh.sendPackage(&cmd);
-        
-        // Track pending command
-        pendingCommands[cmd.commandId] = {nodeId, millis()};
-    }
-    
-    void handleCommandAck(const CommandPackage& ack) {
-        auto it = pendingCommands.find(ack.commandId);
-        if (it != pendingCommands.end()) {
-            Serial.printf("Command %u acknowledged by node %u\n", 
-                         ack.commandId, ack.from);
-            pendingCommands.erase(it);
-        }
-    }
-};
-```
-
-### Health Monitoring Pattern
-
-Network-wide device health monitoring:
-
-```cpp
-class HealthMonitor {
-private:
-    std::map<uint32_t, DeviceHealth> deviceHealth;
-    
-public:
-    void setup() {
-        mesh.onPackage(ALTERIOM_STATUS, [this](protocol::Variant& variant) {
-            StatusPackage status = variant.to<StatusPackage>();
-            updateDeviceHealth(status);
-            return false;
-        });
-        
-        // Check for unhealthy devices every minute
-        userScheduler.addTask(Task(60000, TASK_FOREVER, [this]() {
-            checkDeviceHealth();
-        }));
-    }
-    
-    void updateDeviceHealth(const StatusPackage& status) {
-        deviceHealth[status.from] = {
-            status.deviceStatus,
-            status.uptime,
-            status.freeMemory,
-            status.wifiStrength,
-            mesh.getNodeTime() // Last seen
-        };
-    }
-    
-    void checkDeviceHealth() {
-        uint32_t now = mesh.getNodeTime();
-        
-        for (auto& [nodeId, health] : deviceHealth) {
-            uint32_t timeSinceLastSeen = now - health.lastSeen;
-            
-            if (timeSinceLastSeen > DEVICE_TIMEOUT) {
-                Serial.printf("Device %u appears offline\n", nodeId);
-                triggerAlert(nodeId, "Device offline");
-            }
-            
-            if (health.freeMemory < LOW_MEMORY_THRESHOLD) {
-                Serial.printf("Device %u low memory: %u bytes\n", 
-                             nodeId, health.freeMemory);
-                triggerAlert(nodeId, "Low memory");
-            }
-        }
-    }
-};
-```
-
-## Best Practices
-
-### Performance Optimization
-
-1. **Batch sensor readings** when possible
-2. **Use appropriate message frequency** (don't spam the network)
-3. **Implement message filtering** to avoid processing irrelevant data
-4. **Monitor memory usage** especially on ESP8266
-
-### Reliability
-
-1. **Validate all received data** before processing
-2. **Implement timeouts** for commands and responses
-3. **Handle network partitions** gracefully
-4. **Add retry logic** for critical commands
-
-### Security
-
-1. **Validate message sources** in handlers
-2. **Sanitize command parameters** before execution
-3. **Implement rate limiting** for commands
-4. **Consider encryption** for sensitive data
-
-### Testing
-
-1. **Test with realistic network loads**
-2. **Simulate node failures** and recovery
-3. **Validate under memory pressure**
-4. **Test with maximum expected node count**
-
-## Code Conventions
-
-### Boolean Field Naming
-
-Alteriom packages follow a consistent naming convention for boolean fields to improve code clarity:
-
-- **`*Set` suffix**: Configuration data has been provided (e.g., `deviceSecretSet`)
-- **`*Enabled` suffix**: Feature is currently active (e.g., `displayEnabled`)
-- **`is*` prefix or `*Connected`**: Current runtime state (e.g., `mqttConnected`)
-
-See [Boolean Naming Convention](../BOOLEAN_NAMING_CONVENTION.md) for complete guidelines.
-
-### Time Field Naming
-
-Time-based configuration fields follow a dual-unit convention:
-
-- **Internal storage**: Always milliseconds (e.g., `sensorReadInterval`)
-- **JSON serialization**: Both milliseconds (`_ms`) and seconds (`_s`) variants
-- **JSON deserialization**: Read from milliseconds (`_ms`) variant
-
-See package header documentation for complete details.
-
-## Next Steps
-
-- Learn about [Sensor Packages](sensor-packages.md) in detail
-- Explore [Command System](command-system.md) implementation
-- Study [Status Monitoring](status-monitoring.md) patterns
-- Review [Boolean Naming Convention](../BOOLEAN_NAMING_CONVENTION.md) guidelines
-- See [Tutorial Examples](../tutorials/sensor-networks.md) for hands-on practice
-
-The Alteriom extensions provide a solid foundation for building robust IoT applications with painlessMesh. They demonstrate production-ready patterns while remaining flexible enough to adapt to your specific needs.