RELEASE_SUMMARY_v1.7.7 - Alteriom/painlessMesh GitHub Wiki

painlessMesh v1.7.7 Release Summary

Release Date: November 5, 2025
Version: 1.7.7
Type: Feature Release
Compatibility: 100% backward compatible with v1.7.6

🎯 Executive Summary

Version 1.7.7 introduces comprehensive MQTT communication improvements for efficient monitoring of mesh networks. Two new package types (MetricsPackage and HealthCheckPackage) provide detailed performance metrics and proactive health monitoring, while an enhanced MQTT bridge enables on-demand metric requests and aggregated network statistics.

🚀 What's New

New Package Types

MetricsPackage (Type 204)

Comprehensive performance metrics package for real-time monitoring and dashboards.

Key Capabilities:

  • 22 performance fields covering CPU, memory, network, timing, and connection quality
  • Configurable collection intervals
  • Minimal network overhead (~200 bytes per message)
  • Full integration with painlessMesh plugin system

Use Cases:

  • Real-time performance dashboards (Grafana, InfluxDB)
  • Capacity planning and optimization
  • Network throughput analysis
  • Troubleshooting and diagnostics

HealthCheckPackage (Type 605)

Proactive health monitoring with problem detection and predictive maintenance. Uses MESH_METRICS code (605) per mqtt-schema v0.7.2+ for mesh performance health.

Key Capabilities:

  • 3-level health status (healthy/warning/critical)
  • 10+ problem flags for specific issue detection
  • Component health scores (memory, network, performance)
  • Memory leak detection with trend analysis
  • Predictive maintenance indicators (estimated time to failure)
  • Actionable recommendations for operators

Use Cases:

  • Proactive problem detection
  • Predictive maintenance
  • Automated alerting
  • Memory leak detection
  • System health monitoring

Enhanced MQTT Bridge

The new enhanced_mqtt_bridge.hpp extends the basic MQTT bridge with powerful new capabilities.

Command Handlers:

  • Request metrics from any node or all nodes on-demand
  • Request health checks from specific nodes
  • Get current aggregated statistics instantly
  • Dedicated response topics for clear command/response flow

Aggregated Statistics:

  • Automatic mesh-wide metrics aggregation
  • Health summary with node status counts
  • Problem flag aggregation
  • Configurable aggregation intervals (default 60s)

Alert System:

  • Automatic critical health alerts
  • Per-node and aggregated health monitoring
  • Customizable alert thresholds
  • Integration with monitoring systems

MQTT Topics:

Subscribe (Commands):

  • mesh/command/request_metrics - Request metrics
  • mesh/command/request_health - Request health check
  • mesh/command/get_aggregated - Get aggregated stats

Publish (Data):

  • mesh/metrics/{node_id} - Individual node metrics
  • mesh/health/{node_id} - Individual node health
  • mesh/aggregated/metrics - Mesh-wide metrics
  • mesh/aggregated/health - Mesh health summary
  • mesh/alerts/critical - Critical health alerts

📊 Performance Characteristics

Memory Usage

  • MetricsPackage: ~200 bytes per message
  • HealthCheckPackage: ~250 bytes per message
  • Enhanced Bridge: ~2KB (including cache for 20 nodes)
  • Total Overhead: <3KB for full feature set

Network Bandwidth

With 10 nodes and recommended intervals (30s metrics, 60s health):

  • Per-node metrics: 10 × 200 bytes / 30s = ~67 bytes/sec
  • Per-node health: 10 × 250 bytes / 60s = ~42 bytes/sec
  • Aggregated stats: ~400 bytes / 60s = ~7 bytes/sec
  • Total: ~116 bytes/sec = minimal overhead

CPU Overhead

  • Metric collection: <0.5% CPU per collection
  • Health monitoring: <0.5% CPU per check
  • Bridge processing: <0.1% CPU
  • Total: <1% additional CPU usage

Scalability

  • Tested: Up to 50 nodes
  • Recommended: 10-20 nodes for real-time monitoring
  • Maximum: 100+ nodes with adjusted intervals
  • Cache Size: Configurable (default 20 nodes)

📚 Documentation & Examples

New Documentation Files

  1. docs/v1.7.7_MQTT_IMPROVEMENTS.md (22KB)

    • Complete implementation guide
    • MQTT bridge integration examples
    • Dashboard integration (Grafana, InfluxDB, Home Assistant)
    • Performance considerations
    • Alert configuration
    • Best practices and troubleshooting

  2. Updated CHANGELOG.md

    • Detailed feature descriptions
    • Performance metrics
    • Compatibility notes

  3. Updated README.md

    • New package type descriptions
    • Updated package table

New Example Files

  1. examples/alteriom/metrics_health_node.ino (13KB)

    • Complete metrics collection implementation
    • Health monitoring with all indicators
    • CPU usage calculation
    • Memory leak detection
    • Network quality assessment
    • Problem flag detection
    • Production-ready code

  2. examples/bridge/enhanced_mqtt_bridge.hpp (18KB)

    • Full bridge implementation
    • Command handlers
    • Aggregation engine
    • Alert detection
    • Response handling
    • Caching system

  3. examples/bridge/enhanced_mqtt_bridge_example.ino (7KB)

    • Complete gateway node example
    • MQTT broker connection
    • Command handling
    • Event publishing
    • Ready to deploy

Testing

New Test Suite: test/catch/catch_metrics_health_packages.cpp

  • 64 comprehensive test assertions
  • Edge case validation
  • Problem flag testing
  • Health status validation
  • Serialization/deserialization
  • All tests passing ✅

Existing Tests: All 710+ existing tests still passing ✅

🔄 Migration Guide

From v1.7.6 to v1.7.7

No breaking changes! Version 1.7.7 is 100% backward compatible.

Adopting New Features (Optional)

1. Add Metrics Collection:

#include "alteriom_sensor_package.hpp"
using namespace alteriom;

// In setup()
Task taskMetrics(30000, TASK_FOREVER, []() {
  MetricsPackage metrics;
  // ... populate metrics ...
  mesh.sendBroadcast(metrics.toJsonString());
});
userScheduler.addTask(taskMetrics);
taskMetrics.enable();

2. Add Health Monitoring:

Task taskHealth(60000, TASK_FOREVER, []() {
  HealthCheckPackage health;
  // ... populate health data ...
  mesh.sendBroadcast(health.toJsonString());
});
userScheduler.addTask(taskHealth);
taskHealth.enable();

3. Upgrade MQTT Bridge:

#include "enhanced_mqtt_bridge.hpp"

EnhancedMqttBridge bridge(mesh, mqttClient);
bridge.begin();

// In loop()
bridge.update();

4. No Changes Required for:

  • Existing mesh nodes
  • Existing packages (Types 200-203)
  • Existing MQTT bridges
  • Existing message handlers

🎯 Use Cases

Production IoT Deployments

  • Monitor 10-100+ nodes in real-time
  • Track performance trends
  • Detect problems early
  • Plan capacity and upgrades

Commercial Systems

  • Professional monitoring dashboards
  • SLA monitoring and reporting
  • Predictive maintenance
  • Automated alerting

Enterprise Environments

  • Integration with existing monitoring (Grafana, Prometheus)
  • Centralized health monitoring
  • Problem tracking and resolution
  • Performance optimization

Development & Testing

  • Real-time performance analysis
  • Memory leak detection
  • Network quality testing
  • Load testing and optimization

📋 Implementation Checklist

For Mesh Nodes

  • Update to v1.7.7
  • Add MetricsPackage collection (optional)
  • Add HealthCheckPackage monitoring (optional)
  • Configure collection intervals
  • Implement command handlers (if using MQTT commands)
  • Test metric accuracy

For Gateway Nodes

  • Update to v1.7.7
  • Integrate enhanced MQTT bridge
  • Configure MQTT topics
  • Set aggregation intervals
  • Test command handlers
  • Set up alert subscriptions

For Monitoring Systems

  • Subscribe to metric topics
  • Subscribe to health topics
  • Subscribe to aggregated stats
  • Configure dashboards
  • Set up alert rules
  • Test end-to-end flow

🔍 Comparison with v1.7.6

Feature v1.7.6 v1.7.7
Package Types 4 (200-203) 6 (200, 202, 204, 604, 605)
Metrics Detail Basic Comprehensive (22 fields)
Health Monitoring Status only Proactive with predictions
MQTT Commands None 3 command types
Aggregated Stats Manual Automatic
Alert System Manual Automatic critical alerts
Memory Overhead ~1KB ~3KB
Network Overhead Minimal Minimal (~116 bytes/sec)

🛠️ Technical Details

Package Field Summary

MetricsPackage (22 fields):

  • CPU: usage, loopIterations, taskQueueSize
  • Memory: freeHeap, minFreeHeap, heapFragmentation, maxAllocHeap
  • Network: bytesRx/Tx, packetsRx/Tx/Dropped, throughput
  • Timing: avgResponseTime, maxResponseTime, avgMeshLatency
  • Quality: connectionQuality, wifiRSSI
  • Metadata: collectionTimestamp, collectionInterval

HealthCheckPackage (20 fields):

  • Overall: healthStatus, problemFlags
  • Memory: memoryHealth, memoryTrend
  • Network: networkHealth, packetLossPercent, reconnectionCount
  • Performance: performanceHealth, missedDeadlines, maxLoopTime
  • Environmental: temperature, temperatureHealth
  • Stability: uptime, crashCount, lastRebootReason
  • Predictive: estimatedTimeToFailure, recommendations
  • Metadata: checkTimestamp, nextCheckDue

Problem Flags (10+ types)

  • 0x0001: Low memory warning
  • 0x0002: High CPU usage
  • 0x0004: Connection instability
  • 0x0008: High packet loss
  • 0x0010: Network congestion
  • 0x0020: Low battery
  • 0x0040: Thermal warning
  • 0x0080: Mesh partition detected
  • 0x0100: OTA in progress
  • 0x0200: Configuration error

Command Types

  • 210: Request metrics
  • 211: Request health
  • 212: Metrics response
  • 213: Health response

⚠️ Important Notes

Recommendations

  1. Start Conservative - Begin with 60s intervals and adjust based on needs
  2. Monitor Memory - Watch heap usage when enabling new features
  3. Test Thoroughly - Validate in your specific environment
  4. Use Aggregation - Enable aggregated stats for large meshes
  5. Set Up Alerts - Configure critical health alerting
  6. Track Trends - Use memoryTrend to detect slow leaks

Known Limitations

  • Cache Size: Limited to 20 nodes by default (configurable)
  • Memory Trend: Requires multiple samples for accuracy
  • Timestamp: Uses mesh time, may need NTP integration
  • Problem Detection: Thresholds may need tuning for your use case

Future Enhancements (Planned for v1.8.0)

  • Compressed metric packages for large meshes
  • Historical trend storage in gateway
  • Automatic threshold tuning
  • Machine learning-based failure prediction
  • Cloud monitoring service integration
  • Configurable health scoring algorithms

📞 Support & Resources

Documentation

Community

Getting Help

  1. Check documentation and examples
  2. Search existing issues
  3. Test with provided examples
  4. Report issues with logs and configuration

🎉 Credits

Thanks to the painlessMesh community and contributors for feedback and testing.

Contributors:

  • Alteriom Team - Package design and implementation
  • painlessMesh Community - Testing and feedback
  • GitHub Copilot - Development assistance

📄 License

LGPL-3.0 - Same as painlessMesh

Ready to Upgrade? Follow the migration guide above or use the provided examples to get started with v1.7.7 today!