@alteriom/painlessmesh 1.6.1 → 1.7.2

package/docs/improvements/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/platformio-publishing.md

@@ -0,0 +1,255 @@
+# PlatformIO Library Publishing Guide
+
+This guide explains how to publish the AlteriomPainlessMesh library to the PlatformIO Library Registry.
+
+## Prerequisites
+
+### 1. PlatformIO Account Setup
+
+1. Visit [https://platformio.org/](https://platformio.org/) and create an account
+2. Verify your email address
+3. Log in to your PlatformIO account
+
+### 2. Authentication Token
+
+1. Go to [https://platformio.org/account/token](https://platformio.org/account/token)
+2. Generate a new Personal Access Token
+3. Copy the token and store it securely
+4. Set up the token in your local environment:
+
+   ```powershell
+   # Set environment variable (Windows PowerShell)
+   $env:PLATFORMIO_AUTH_TOKEN="YOUR_TOKEN_HERE"
+   
+   # Or for Command Prompt
+   set PLATFORMIO_AUTH_TOKEN=YOUR_TOKEN_HERE
+   
+   # Or use login command
+   pio account login
+   ```
+
+## Library Configuration
+4. Set up the token in your local environment:
+   ```powershell
+   pio account token --set YOUR_TOKEN_HERE
+   ```
+
+## Library Configuration
+
+### Required Files
+Ensure these files are properly configured:
+
+#### 1. `library.json` (Primary PlatformIO Configuration)
+```json
+{
+    "name": "AlteriomPainlessMesh",
+    "keywords": "ethernet, m2m, iot, mesh, alteriom, sensor, esp32, esp8266, json, time-sync, wireless, communication",
+    "description": "painlessMesh library with Alteriom extensions for sensor networks",
+    "repository": {
+        "type": "git", 
+        "url": "https://github.com/Alteriom/painlessMesh"
+    },
+    "version": "1.6.1",
+    "frameworks": ["arduino"],
+    "platforms": ["espressif8266", "espressif32"],
+    "dependencies": [...],
+    "authors": [...],
+    "license": "LGPL-3.0",
+    "homepage": "https://github.com/Alteriom/painlessMesh",
+    "headers": "painlessMesh.h",
+    "examples": ["examples/basic/basic.ino", "examples/alteriom/alteriom_sensor_node.ino"],
+    "export": {
+        "include": "src"
+    }
+}
+```
+
+#### 2. `library.properties` (Arduino Library Manager)
+Should remain compatible for dual publishing:
+```properties
+name=AlteriomPainlessMesh
+version=1.6.1
+author=Coopdis,Scotty Franzyshen,Edwin van Leeuwen,Germán Martín,Maximilian Schwarz,Doanh Doanh,Alteriom
+maintainer=Alteriom
+sentence=A painless way to setup a mesh with ESP8266 and ESP32 devices with Alteriom extensions
+paragraph=...
+category=Communication
+url=https://github.com/Alteriom/painlessMesh
+architectures=esp8266,esp32
+includes=AlteriomPainlessMesh.h
+depends=ArduinoJson, TaskScheduler
+```
+
+## Publishing Process
+
+### Method 1: Git Tag Publishing (Recommended)
+
+This method automatically publishes when you create a Git tag:
+
+1. **Ensure all files are committed and pushed:**
+   ```powershell
+   git add .
+   git commit -m "Prepare v1.6.1 for PlatformIO Library Registry"
+   git push origin main
+   ```
+
+2. **Create and push a Git tag:**
+   ```powershell
+   git tag v1.6.1
+   git push origin v1.6.1
+   ```
+
+3. **PlatformIO will automatically detect the new tag and import the library**
+   - Monitor at: [https://platformio.org/lib/show/LIBRARY_ID/AlteriomPainlessMesh](https://platformio.org/lib)
+   - It may take 5-15 minutes for the library to appear
+
+### Method 2: Manual Package Upload
+
+If automatic detection doesn't work:
+
+1. **Create a tarball of your library:**
+   ```powershell
+   # Create archive excluding unnecessary files
+   tar --exclude='.git' --exclude='test' --exclude='bin' --exclude='.vscode' --exclude='node_modules' -czf AlteriomPainlessMesh-1.6.1.tar.gz .
+   ```
+
+2. **Submit via PlatformIO Library Registry:**
+   - Visit [https://platformio.org/lib/register](https://platformio.org/lib/register)
+   - Upload the created tarball
+   - Fill in any additional metadata
+
+### Method 3: Using PlatformIO CLI
+
+```powershell
+# Ensure you're authenticated
+pio account token --set YOUR_TOKEN_HERE
+
+# Publish the library
+pio pkg publish .
+```
+
+## Verification
+
+### 1. Check Library Status
+```powershell
+# Search for your published library
+pio pkg search "AlteriomPainlessMesh"
+
+# View detailed information
+pio pkg show alteriom/AlteriomPainlessMesh
+```
+
+### 2. Test Installation
+Create a test project to verify the library can be installed:
+```powershell
+mkdir test_project
+cd test_project
+pio project init --board esp32dev
+
+# Add to platformio.ini:
+# lib_deps = alteriom/AlteriomPainlessMesh@^1.6.1
+
+pio pkg install
+```
+
+## Updating the Library
+
+For future releases:
+
+1. **Update version numbers:**
+   - `library.json` → `"version": "1.6.2"`
+   - `library.properties` → `version=1.6.2`
+   - `package.json` → `"version": "1.6.2"`
+
+2. **Commit changes:**
+   ```powershell
+   git add .
+   git commit -m "Bump version to 1.6.2"
+   git push origin main
+   ```
+
+3. **Create new tag:**
+   ```powershell
+   git tag v1.6.2
+   git push origin v1.6.2
+   ```
+
+4. **Verify update appears in registry**
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Library name conflicts:**
+   - Use a unique name like "AlteriomPainlessMesh" instead of "painlessMesh"
+   - Check existing libraries: `pio pkg search "painless"`
+
+2. **Authentication errors:**
+   - Verify token: `pio account show`
+   - Regenerate token if needed
+
+3. **Dependency resolution errors:**
+   - Ensure all dependencies exist in PlatformIO Registry
+   - Check version constraints (use `^` for flexible versions)
+
+4. **Git repository requirements:**
+   - Repository must be publicly accessible
+   - Tags must follow semantic versioning (v1.6.1)
+   - library.json must be in repository root
+
+### Useful Commands
+
+```powershell
+# Check authentication status
+pio account show
+
+# List all your published packages
+pio pkg search --owner="YOUR_USERNAME"
+
+# View package statistics
+pio pkg stats
+
+# Update package metadata
+pio pkg update
+```
+
+## Best Practices
+
+1. **Semantic Versioning:**
+   - Use format: MAJOR.MINOR.PATCH (e.g., 1.6.1)
+   - Increment MAJOR for breaking changes
+   - Increment MINOR for new features
+   - Increment PATCH for bug fixes
+
+2. **Documentation:**
+   - Include comprehensive README.md
+   - Provide working examples in examples/ directory
+   - Document all public APIs
+
+3. **Testing:**
+   - Test library installation in clean environments
+   - Verify examples compile successfully
+   - Test on both ESP8266 and ESP32 platforms
+
+4. **Dependency Management:**
+   - Specify minimum required versions
+   - Use version ranges (^1.6.0) for flexibility
+   - Platform-specific dependencies when needed
+
+## PlatformIO Library Registry URLs
+
+- **Library Registry:** [https://platformio.org/lib](https://platformio.org/lib)
+- **Account Management:** [https://platformio.org/account](https://platformio.org/account)
+- **Submit Library:** [https://platformio.org/lib/register](https://platformio.org/lib/register)
+- **Documentation:** [https://docs.platformio.org/en/latest/librarymanager/index.html](https://docs.platformio.org/en/latest/librarymanager/index.html)
+
+---
+
+**Note:** After successful publication, users will be able to install your library using:
+```ini
+[env:esp32dev]
+platform = espressif32
+board = esp32dev
+framework = arduino
+lib_deps = alteriom/AlteriomPainlessMesh@^1.6.1
+```

package/docs/platformio-setup-summary.md

@@ -0,0 +1,121 @@
+# PlatformIO Publishing Setup Summary
+
+## ✅ What's Been Implemented
+
+### 1. Dedicated PlatformIO Publishing Workflow
+- **File**: `.github/workflows/platformio-publish.yml`
+- **Triggers**: Automatic on releases, manual dispatch for testing
+- **Features**: Complete validation, authentication, and publishing pipeline
+
+### 2. Library Configuration Enhanced
+- **Updated `library.json`**: PlatformIO-specific optimizations
+- **Name**: Changed to "AlteriomPainlessMesh" for uniqueness
+- **Dependencies**: All verified available in PlatformIO Registry
+- **Metadata**: Enhanced with license, examples, export configuration
+
+### 3. Release Process Integration
+- **Main release workflow** now references PlatformIO publishing
+- **Documentation updated** in `RELEASE_GUIDE.md`
+- **Comprehensive instructions** in `docs/platformio-publishing.md`
+
+## 🚀 How It Works
+
+### Automatic Publishing
+1. **Release Created**: GitHub release triggers PlatformIO workflow
+2. **Validation**: Library.json format and dependencies checked
+3. **Authentication**: Uses `PLATFORMIO_AUTH_TOKEN` secret
+4. **Publication**: Direct publishing via PlatformIO CLI
+5. **Verification**: Registry confirmation and user notification
+
+### Manual Publishing (Alternative)
+1. Go to GitHub Actions → PlatformIO Library Publishing
+2. Click "Run workflow"
+3. Enter version number and optional force publish
+4. Workflow handles the rest
+
+## 🔧 Setup Required
+
+### One-Time Setup: PlatformIO Account
+
+1. **Create Account**: <https://platformio.org/account/register>
+2. **Generate Token**: <https://platformio.org/account/token>
+3. **Add to Secrets**: Repository Settings → Secrets → Actions
+   - Name: `PLATFORMIO_AUTH_TOKEN`
+   - Value: [your token from step 2]
+
+**Local Testing (Optional):**
+```powershell
+# Method 1: Environment variable
+$env:PLATFORMIO_AUTH_TOKEN="YOUR_TOKEN_HERE"
+pio account show  # Verify authentication
+
+# Method 2: Interactive login (if token doesn't work)
+pio account login
+
+# Test publishing
+pio pkg publish . --no-interactive
+```
+
+**Troubleshooting Authentication:**
+```powershell
+# If authentication fails:
+1. Go to https://platformio.org/account/token
+2. Copy your existing token OR generate a new one
+3. Set it as environment variable: $env:PLATFORMIO_AUTH_TOKEN="token"
+4. Test: pio account show
+```
+
+### Current Status for v1.6.1
+Since v1.6.1 is already released and published to other platforms:
+
+#### Option A: Test with Manual Workflow
+```
+1. Go to: https://github.com/Alteriom/painlessMesh/actions/workflows/platformio-publish.yml
+2. Click "Run workflow"
+3. Set version: 1.6.1
+4. Enable force_publish: true
+5. Click "Run workflow"
+```
+
+#### Option B: Wait for Next Release
+The PlatformIO workflow will automatically trigger on your next release (v1.6.2, etc.)
+
+## 📋 Future Releases
+
+For all future releases, PlatformIO publishing is now **fully automated**:
+
+```bash
+# Standard release process remains the same
+./scripts/bump-version.sh patch
+# Edit CHANGELOG.md
+git add . && git commit -m "release: v1.6.2" && git push
+```
+
+This will now automatically:
+- ✅ Create GitHub release
+- ✅ Publish to NPM 
+- ✅ **Publish to PlatformIO Registry**
+- ✅ Update GitHub Wiki
+- ✅ Prepare Arduino Library Manager package
+
+## 🔍 Verification
+
+After publishing, verify at:
+- **Registry**: <https://registry.platformio.org/libraries>
+- **Search**: Search for "AlteriomPainlessMesh"
+- **Installation**: `pio pkg install --library "alteriom/AlteriomPainlessMesh@^1.6.1"`
+
+## 📚 Documentation
+
+Complete documentation available:
+- **Publishing Guide**: `docs/platformio-publishing.md`
+- **Release Process**: `RELEASE_GUIDE.md` (updated)
+- **Workflow Details**: `.github/workflows/platformio-publish.yml`
+
+## 🎯 Next Steps
+
+1. **Add PlatformIO Token**: Set up the `PLATFORMIO_AUTH_TOKEN` secret
+2. **Test Workflow**: Run manual workflow for v1.6.1 (optional)
+3. **Next Release**: PlatformIO publishing will be automatic
+
+The PlatformIO publishing is now fully integrated into your release pipeline! 🎉