@alteriom/painlessmesh 1.8.14 → 1.9.0

package/docs/archive/ota-status-quick-reference.md

@@ -1,284 +0,0 @@
-# OTA and Status Enhancements - Quick Reference
-
-**TL;DR:** Five options each for OTA distribution improvements and mesh status monitoring, with phased implementation recommendations.
-
----
-
-## 🚀 OTA Distribution Options
-
-### ⚡ Option 1A: Mesh-Wide Broadcast OTA ★★★★★ (RECOMMENDED - Phase 2)
-**What:** Broadcast firmware chunks to all nodes simultaneously  
-**Speed:** Very Fast | **Memory:** +2-5KB | **Complexity:** Medium  
-**Best For:** Medium to large meshes (10-100 nodes)
-
-### 🛡️ Option 1B: Progressive Rollout OTA ★★★★☆ (RECOMMENDED - Phase 3)
-**What:** Deploy firmware in waves (canary → early adopters → all)  
-**Speed:** Slow | **Memory:** +3-7KB | **Complexity:** High  
-**Best For:** Production deployments requiring safety
-
-### 🌐 Option 1C: Peer-to-Peer Distribution ★★★☆☆
-**What:** Updated nodes become distribution sources  
-**Speed:** Very Fast | **Memory:** +200-500KB | **Complexity:** Very High  
-**Best For:** Very large meshes (50+ nodes) with sufficient flash
-
-### 🔗 Option 1D: MQTT-Integrated OTA ★★★★☆
-**What:** Standardized MQTT interface for OTA operations  
-**Speed:** Medium | **Memory:** +5-10KB | **Complexity:** Medium  
-**Best For:** Existing MQTT infrastructure
-
-### 📦 Option 1E: Compressed OTA Transfer ★★★★★ (RECOMMENDED - Phase 1)
-**What:** Gzip compression for firmware transfers  
-**Speed:** Fast | **Memory:** +4-8KB | **Complexity:** Low  
-**Best For:** All deployments (40-60% bandwidth reduction)
-
----
-
-## 📊 Mesh Status Options
-
-### 📡 Option 2A: Enhanced StatusPackage ★★★★★ (RECOMMENDED - Phase 1)
-**What:** Extend Alteriom StatusPackage with comprehensive metrics  
-**Overhead:** Low | **Memory:** +500 bytes | **Complexity:** Low  
-**Best For:** Alteriom users, simple integration
-
-### 🔍 Option 2B: Mesh Status Service ★★★★☆ (RECOMMENDED - Phase 2)
-**What:** Query-based status collection with aggregation  
-**Overhead:** Medium | **Memory:** +2-4KB node, +10-20KB root | **Complexity:** Medium  
-**Best For:** Centralized monitoring, on-demand queries
-
-### 📈 Option 2C: Telemetry Stream ★★★★☆ (RECOMMENDED - Phase 3)
-**What:** Continuous low-bandwidth telemetry with delta encoding  
-**Overhead:** Low | **Memory:** +1-2KB node, +50-100KB root | **Complexity:** High  
-**Best For:** Real-time monitoring, large-scale deployments
-
-### 🖥️ Option 2D: Health Dashboard ★★★☆☆
-**What:** Complete web-based monitoring solution  
-**Overhead:** Medium | **Memory:** +50-100KB code, +200KB assets | **Complexity:** Very High  
-**Best For:** User-facing applications, visual monitoring
-
-### 🔗 Option 2E: MQTT Status Bridge ★★★★★ (RECOMMENDED - Phase 2)
-**What:** Publish mesh status to MQTT topics  
-**Overhead:** Low | **Memory:** +5-8KB | **Complexity:** Low  
-**Best For:** Cloud integration, existing monitoring tools
-
----
-
-## 🎯 Recommended Implementation Path
-
-### ✅ Phase 1: Quick Wins (3-4 weeks)
-```
-Option 1E (Compressed OTA) + Option 2A (Enhanced StatusPackage)
-```
-- Immediate 40-60% OTA speed improvement
-- Standardized status reporting
-- Low risk, high value
-- Builds on existing code
-
-### ✅ Phase 2: Production Ready (6-8 weeks)
-```
-Option 1A (Broadcast OTA) + Option 2E (MQTT Bridge)
-```
-- Scalable OTA for larger meshes
-- Cloud monitoring integration
-- Enterprise features
-- Professional deployment
-
-### ✅ Phase 3: Advanced (3-4 months)
-```
-Option 1B (Progressive OTA) + Option 2C (Telemetry)
-```
-- Zero-downtime updates
-- Real-time monitoring
-- Proactive alerting
-- Large-scale support
-
----
-
-## 📋 Quick Comparison
-
-### OTA Options at a Glance
-
-| Option | Speed | Memory | Complexity | When to Use |
-|--------|-------|--------|------------|-------------|
-| **1E: Compression** | ⭐⭐⭐⭐ | +4-8KB | ⭐⭐ | **Start here** - Universal benefit |
-| **1A: Broadcast** | ⭐⭐⭐⭐⭐ | +2-5KB | ⭐⭐⭐ | Medium-large mesh (10-100 nodes) |
-| **1B: Progressive** | ⭐⭐ | +3-7KB | ⭐⭐⭐⭐ | Production safety critical |
-| 1C: P2P | ⭐⭐⭐⭐⭐ | +200KB | ⭐⭐⭐⭐⭐ | Very large mesh (50+ nodes) |
-| 1D: MQTT | ⭐⭐⭐ | +5-10KB | ⭐⭐⭐ | Already using MQTT |
-
-### Status Options at a Glance
-
-| Option | Real-time | Overhead | Complexity | When to Use |
-|--------|-----------|----------|------------|-------------|
-| **2A: Enhanced Pkg** | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ | **Start here** - Simple integration |
-| **2E: MQTT Bridge** | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ | Cloud monitoring needed |
-| **2B: Status Service** | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | Centralized control |
-| 2C: Telemetry | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ | Real-time critical |
-| 2D: Dashboard | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | User-facing app |
-
----
-
-## 💡 Decision Guide
-
-### Choose OTA Option Based On:
-
-**If mesh size < 10 nodes:**
-- Start with **1E (Compression)** only
-- Add **1A (Broadcast)** if frequent updates
-
-**If mesh size 10-50 nodes:**
-- Use **1E + 1A** (Compression + Broadcast)
-- Add **1B (Progressive)** for production
-
-**If mesh size > 50 nodes:**
-- Use **1E + 1C** (Compression + P2P)
-- Or **1E + 1A + 1B** if flash limited
-
-**If MQTT already used:**
-- Consider **1D (MQTT Bridge)** for integration
-- Combine with **1E** for speed
-
-### Choose Status Option Based On:
-
-**For simple monitoring:**
-- **2A (Enhanced StatusPackage)** - easiest start
-
-**For cloud integration:**
-- **2E (MQTT Bridge)** - Grafana, InfluxDB, etc.
-
-**For real-time monitoring:**
-- **2C (Telemetry Stream)** - continuous updates
-
-**For user dashboards:**
-- **2D (Health Dashboard)** - visual interface
-
-**For API access:**
-- **2B (Status Service)** - RESTful queries
-
----
-
-## 🔧 Implementation Examples
-
-### Phase 1 Code (Compression + Enhanced Status)
-
-**Enable Compressed OTA:**
-```cpp
-// In sender node
-#define PAINLESSMESH_ENABLE_OTA
-#define OTA_COMPRESSION_ENABLED
-
-mesh.initOTASend(firmwareCallback, OTA_PART_SIZE);
-mesh.offerOTA("sensor", "ESP32", md5, parts, false, false, true); // last param = compressed
-```
-
-**Enhanced Status Reporting:**
-```cpp
-#include "examples/alteriom/alteriom_sensor_package.hpp"
-
-alteriom::EnhancedStatusPackage status;
-status.uptime = millis() / 1000;
-status.freeMemory = ESP.getFreeHeap() / 1024;
-status.nodeCount = mesh.getNodeList().size();
-status.firmwareVersion = "v1.2.3";
-
-mesh.sendBroadcast(status.toJsonString());
-```
-
-### Phase 2 Code (Broadcast OTA + MQTT Status)
-
-**Broadcast OTA:**
-```cpp
-// Sender enables broadcast mode
-mesh.offerOTA("sensor", "ESP32", md5, parts, 
-              false,  // not forced
-              true);  // broadcast mode
-
-// Receivers auto-detect broadcast
-mesh.initOTAReceive("sensor", progressCallback);
-```
-
-**MQTT Status Bridge:**
-```cpp
-#include "examples/bridge/mqtt_status_bridge.hpp"
-
-MqttStatusBridge bridge(mesh, mqttClient);
-bridge.setPublishInterval(30000);  // 30s
-bridge.enableTopology(true);
-bridge.enableMetrics(true);
-bridge.begin();
-
-// Status published to:
-// - mesh/status/nodes
-// - mesh/status/topology
-// - mesh/status/metrics
-```
-
----
-
-## 📈 Performance Expectations
-
-### OTA Distribution Time (100KB firmware, 10 nodes)
-
-| Method | Time | Bandwidth | Memory |
-|--------|------|-----------|--------|
-| Current | ~60s | 1MB | +1KB |
-| + Compression (1E) | ~35s | 600KB | +5KB |
-| + Broadcast (1A) | ~25s | 600KB | +7KB |
-| + P2P (1C) | ~15s | 400KB | +205KB |
-
-### Status Update Overhead
-
-| Method | Frequency | Per Update | Total/hour |
-|--------|-----------|------------|------------|
-| Manual | On-demand | ~200B | Varies |
-| Enhanced Pkg (2A) | 5 min | ~500B | ~6KB |
-| MQTT Bridge (2E) | 30s | ~800B | ~96KB |
-| Telemetry (2C) | 60s | ~64B | ~3.8KB |
-
----
-
-## ⚠️ Common Pitfalls
-
-### OTA Implementation
-- ❌ Don't forget to include OTA support in updated firmware (will brick nodes)
-- ❌ Don't skip MD5 validation (corrupted firmware)
-- ❌ Don't update all nodes at once without testing (mesh failure)
-- ✅ DO test OTA on single node first
-- ✅ DO implement rollback mechanism
-- ✅ DO use progressive rollout for production
-
-### Status Monitoring
-- ❌ Don't poll status too frequently (network congestion)
-- ❌ Don't ignore memory warnings (node crashes)
-- ❌ Don't assume all nodes respond (timeouts happen)
-- ✅ DO use appropriate update intervals (30-60s typically)
-- ✅ DO implement timeout handling
-- ✅ DO cache status at collection point
-
----
-
-## 🔗 Related Resources
-
-- **Full Proposal:** `docs/improvements/ota-and-status-enhancements.md`
-- **Current OTA Example:** `examples/otaSender/otaSender.ino`
-- **Metrics System:** `src/painlessmesh/metrics.hpp`
-- **Alteriom Packages:** `examples/alteriom/alteriom_sensor_package.hpp`
-- **MQTT Bridge:** `examples/mqttBridge/mqttBridge.ino`
-
----
-
-## 🤝 Contributing
-
-To implement any of these features:
-
-1. Review full proposal document
-2. Create design doc for specific option
-3. Submit RFC to team
-4. Implement with tests
-5. Create examples
-6. Update documentation
-
----
-
-**Quick Start:** Begin with **Phase 1** (Option 1E + 2A) for immediate benefits with minimal risk.
-
-**Questions?** See full proposal or open a GitHub issue.

package/docs/design/.gitkeep

@@ -1 +0,0 @@
-Created

package/docs/design/STATION_CREDENTIALS_DESIGN.md

@@ -1,182 +0,0 @@
-# Station Credentials Design Rationale
-
-## Question
-
-Why does `mesh.init()` require a separate `mesh.stationManual()` call to connect to a router, instead of accepting station credentials directly?
-
-## Answer: Multiple Valid Approaches
-
-The library now supports **three approaches** for connecting a bridge node to a router, each with different use cases:
-
-### 1. Separate stationManual() Call (Original Design)
-
-```cpp
-mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT, WIFI_AP_STA, 6);
-mesh.stationManual(STATION_SSID, STATION_PASSWORD);
-mesh.setRoot(true);
-mesh.setContainsRoot(true);
-```
-
-**When to use:**
-- Maximum flexibility - can change router connection without reinitializing mesh
-- Dynamic router selection at runtime
-- Need to call `setHostname()` or other WiFi configuration between init and connection
-- Following existing examples or legacy code
-
-**Advantages:**
-- Separation of concerns: mesh setup vs router connection
-- Can reconnect to different routers without mesh reinitialization
-- More control over connection timing and error handling
-
-### 2. Optional Parameters in init() (New Convenience Feature)
-
-```cpp
-mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT, 
-          WIFI_AP_STA, 6, 0, MAX_CONN,
-          STATION_SSID, STATION_PASSWORD);  // Optional parameters
-mesh.setRoot(true);
-mesh.setContainsRoot(true);
-```
-
-**When to use:**
-- Simple bridge setup with known credentials
-- Static configuration (credentials won't change)
-- Want slightly more concise code
-- Don't need hostname or other WiFi customization
-
-**Advantages:**
-- One line instead of two for basic bridge setup
-- All connection parameters in one place
-- Still maintains full flexibility of other options
-
-### 3. initAsBridge() Method (Recommended for New Projects)
-
-```cpp
-mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
-                  STATION_SSID, STATION_PASSWORD,
-                  &userScheduler, MESH_PORT);
-```
-
-**When to use:**
-- New bridge implementations (recommended)
-- Want automatic channel detection
-- Need simplest possible setup
-- Following modern best practices
-
-**Advantages:**
-- **Automatic channel detection** - no manual channel configuration needed
-- Automatically sets node as root
-- Maintains router connection through channel switches
-- Broadcasts bridge status (Type 610) automatically
-- Comprehensive initialization in one call
-
-## Design Rationale for Original Separation
-
-The original design separated `init()` and `stationManual()` for good architectural reasons:
-
-### 1. Separation of Concerns
-
-**Mesh Setup (`init()`):**
-- Creates mesh network (AP mode)
-- Sets up mesh routing and protocol
-- Configures mesh-specific parameters
-- Lifetime: typically never changes
-
-**Router Connection (`stationManual()`):**
-- Connects to external WiFi (STA mode)
-- Different lifecycle - may connect/disconnect/change
-- Network-specific credentials and settings
-- Can be reconfigured at runtime
-
-This separation allows clean code organization and different lifecycles for each concern.
-
-### 2. Not All Nodes Need Router Connection
-
-In a typical mesh network:
-- **1 bridge node**: Needs router connection (AP+STA mode)
-- **N regular nodes**: Mesh only (AP mode, or AP+STA for mesh connections)
-
-Regular nodes use:
-```cpp
-mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT, WIFI_AP_STA);
-// No stationManual() call - not a bridge
-```
-
-If `init()` always required station credentials, it would be confusing for regular nodes.
-
-### 3. Dynamic Router Switching
-
-Some advanced use cases require changing router connections at runtime:
-
-```cpp
-// Initial setup
-mesh.init(...);
-mesh.stationManual("Router1", "pass1");
-
-// Later, switch to different router
-mesh.stationManual("Router2", "pass2");
-
-// Or respond to failover
-void onRouterDisconnect() {
-    mesh.stationManual(backupSSID, backupPassword);
-}
-```
-
-With station credentials baked into `init()`, this flexibility would be lost.
-
-### 4. Additional WiFi Configuration
-
-Many users need to configure WiFi settings between initialization and connection:
-
-```cpp
-mesh.init(...);
-mesh.setHostname("MESH_BRIDGE");  // Must be before stationManual()
-mesh.stationManual(...);
-```
-
-The separation provides a natural place for these configurations.
-
-### 5. Error Handling and Retry Logic
-
-Separating the calls allows better error handling:
-
-```cpp
-mesh.init(...);  // This typically doesn't fail
-
-// Retry router connection with backoff
-for (int retry = 0; retry < 3; retry++) {
-    if (tryStationConnect()) break;
-    delay(1000 * (retry + 1));
-}
-```
-
-## Comparison Table
-
-| Approach | Setup Complexity | Flexibility | Channel Detection | Best For |
-|----------|-----------------|-------------|-------------------|----------|
-| **stationManual()** | Medium | Highest | Manual | Dynamic configs, legacy code |
-| **init() params** | Low-Medium | High | Manual | Simple static bridges |
-| **initAsBridge()** | Lowest | Medium | Automatic | New projects, recommended |
-
-## Recommendation
-
-**For new projects:** Use `initAsBridge()` - it's the modern, recommended approach with automatic channel detection.
-
-**For existing projects:** The original `init()` + `stationManual()` pattern remains fully supported and appropriate.
-
-**For simple bridges:** The new optional parameters in `init()` provide a middle ground with good flexibility.
-
-All three approaches are valid and will continue to be supported. Choose based on your specific needs.
-
-## Implementation Note
-
-When station credentials are passed to `init()`, the implementation internally calls `stationManual()` after mesh initialization. This maintains consistency and code reuse while providing convenience.
-
-```cpp
-// Inside init() implementation
-if (!stationSSID.empty() && (connectMode & WIFI_STA)) {
-    this->stationManual(stationSSID, stationPassword);
-}
-```
-
-This design ensures all three approaches use the same underlying connection logic.

package/docs/development/ARDUINO_COMPLIANCE_SUMMARY.md

@@ -1,71 +0,0 @@
-# Arduino Library Manager Compliance - Summary of Changes
-
-## Issues Fixed
-
-### 1. Library Name Conflict (Fixed ✅)
-- **Problem**: Library name "Alteriom painlessMesh" contained spaces and was not unique
-- **Solution**: Changed to "AlteriomPainlessMesh" (no spaces, unique identifier)
-- **Files Modified**: `library.properties`
-
-### 2. Missing Primary Header File (Fixed ✅)
-- **Problem**: No header file matching the library name
-- **Solution**: Created `src/AlteriomPainlessMesh.h` as the primary include
-- **Files Created**: `src/AlteriomPainlessMesh.h`
-- **Files Modified**: `library.properties` (updated includes field)
-
-### 3. Example Sketch Naming Mismatch (Fixed ✅)
-- **Problem**: Example folder `alteriom` didn't have a matching `alteriom.ino` file
-- **Solution**: Created `examples/alteriom/alteriom.ino` with proper header inclusion
-- **Files Created**: `examples/alteriom/alteriom.ino`
-
-### 4. Test Sketches in Wrong Location (Fixed ✅)
-- **Problem**: Arduino sketches found in `test/` directory (not allowed by Library Manager)
-- **Solution**: Moved problematic sketches to `extras/test-sketches/`
-- **Directories Moved**:
-  - `test/issue_521/` → `extras/test-sketches/issue_521/`
-  - `test/performance/` → `extras/test-sketches/performance/`
-  - `test/startHere/` → `extras/test-sketches/startHere/`
-  - `test/start_stop/` → `extras/test-sketches/start_stop/`
-  - `test/wifi/` → `extras/test-sketches/wifi/`
-
-## Current Compliance Status
-
-✅ **Library Properties**: All required fields present and valid  
-✅ **Naming Convention**: Library name "AlteriomPainlessMesh" is unique and compliant  
-✅ **Header File**: Primary header `src/AlteriomPainlessMesh.h` exists and matches library name  
-✅ **Examples Structure**: All example folders have matching .ino files  
-✅ **Directory Structure**: No Arduino sketches in prohibited locations  
-
-## Files Created/Modified
-
-### New Files
-- `src/AlteriomPainlessMesh.h` - Primary library header with comprehensive documentation
-- `examples/alteriom/alteriom.ino` - Primary example matching folder name
-- `extras/test-sketches/` - Directory for test sketches (moved from test/)
-
-### Modified Files
-- `library.properties` - Updated name, includes, and description for compliance
-
-## Validation Results
-
-The custom validation script confirms all major Arduino Library Manager requirements are met:
-
-```
-🎉 All checks passed! Library should be compliant.
-```
-
-## Next Steps
-
-1. **Optional**: Run official Arduino Lint tool when available for final verification
-2. **Submit**: Library is ready for Arduino Library Manager submission
-3. **Monitor**: Check for any additional feedback from Arduino Library Manager review process
-
-## Documentation Integration
-
-The library now includes:
-- Complete Docsify documentation website in `docsify-site/`
-- Automated Doxygen API documentation generation
-- GitHub Actions workflow for documentation deployment
-- Embedded API documentation viewing within the website
-
-All changes maintain compatibility with existing painlessMesh functionality while adding Alteriom-specific enhancements and ensuring Arduino Library Manager compliance.