@alteriom/painlessmesh 1.6.1 → 1.7.3

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

@@ -0,0 +1,284 @@
+# 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/development/ARDUINO_COMPLIANCE_SUMMARY.md

@@ -0,0 +1,71 @@
+# 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.