Ota_status_quick_reference - Alteriom/painlessMesh GitHub Wiki
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:
// 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:
#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:
// 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:
#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:
- Review full proposal document
- Create design doc for specific option
- Submit RFC to team
- Implement with tests
- Create examples
- 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.