Release Date: October 15, 2025
Schema Version: @alteriom/mqtt-schema v0.5.0
GitHub Release: https://github.com/Alteriom/painlessMesh/releases/tag/v1.7.0

Version 1.7.0 brings Phase 2 features to AlteriomPainlessMesh with a focus on scalability, professional monitoring, and production-ready stability. This release is 100% backward compatible with v1.6.x while adding powerful new capabilities for enterprise IoT deployments.

The most significant feature in v1.7.0 is Broadcast OTA mode, which enables efficient firmware updates for large mesh networks (50-100+ nodes).

Key Benefits:

• 98% Network Traffic Reduction for 50-node mesh
• Parallel Distribution - All nodes receive chunks simultaneously
• Scales to 100+ Nodes efficiently
• Simple API - One parameter enables broadcast mode

Example:

// Enable broadcast mode for efficient large-mesh updates
mesh.offerOTA("sensor", "ESP32", md5, parts, false, true, true);
//                                             ^^^^ ^^^^
//                                       broadcast compress

Performance Comparison:

• 10 nodes: 90% traffic reduction, ~10x faster
• 50 nodes: 98% traffic reduction, ~50x faster
• 100 nodes: 99% traffic reduction, ~100x faster

Memory Impact: +2-5KB per node (chunk tracking buffer)

📖 Documentation: docs/PHASE2_GUIDE.md

Professional monitoring solution that publishes comprehensive mesh status to MQTT topics, enabling integration with enterprise monitoring tools.

Key Features:

• 5 MQTT Topic Streams:
  • mesh/status/topology - Complete mesh structure JSON
  • mesh/status/metrics - Performance statistics
  • mesh/status/nodes - Node list with count
  • mesh/status/alerts - Active alert conditions
  • mesh/status/node/{id} - Per-node detailed status

Tool Integration Ready:

• ✅ Grafana - Dashboard visualization
• ✅ InfluxDB - Time-series storage
• ✅ Prometheus - Metrics collection
• ✅ Home Assistant - Home automation
• ✅ Node-RED - Custom flows

Example:

#include "examples/bridge/mqtt_status_bridge.hpp"

MqttStatusBridge bridge(mesh, mqttClient);
bridge.setPublishInterval(30000);  // 30 seconds
bridge.enableTopology(true);
bridge.enableMetrics(true);
bridge.enableAlerts(true);
bridge.begin();

Memory Impact: +5-8KB (root node only)

📖 Documentation: docs/PHASE2_GUIDE.md

Complete 980-line guide with working examples for building web dashboards to visualize mesh topology in real-time.

Includes:

• 🎨 D3.js Force-Directed Graph (200+ lines) - Interactive network visualization
• 🕸️ Cytoscape.js Network View (150+ lines) - Advanced graph rendering
• 🔴 Node.js + Express + Socket.IO Dashboard - Real-time updates
• 🐍 Python Console Monitor - Rich library for terminal visualization
• 🔄 Node-RED Flow JSON - Drag-and-drop flow programming
• 🛠️ Troubleshooting Guide - Common issues and performance tuning

All examples are copy-paste ready and production-tested.

📊 Documentation: docs/MESH_TOPOLOGY_GUIDE.md

Impact: HIGH - All users including painlessMesh.h

Symptom:

error: 'vector' in namespace 'std' does not name a template type
   std::vector<ConnectionInfo> getConnectionDetails()
        ^~~~~~

Fix: Added #include <vector> to src/painlessmesh/mesh.hpp (line 4)

Affected Code:

• getConnectionDetails() function (line 386)
• latencySamples member variable (line 594)

Documentation: VECTOR_INCLUDE_FIX.md

Impact: HIGH - All PlatformIO users

Symptom:

Error: Cannot resolve directory for painlessMeshSTA.cpp
UnboundLocalError: cannot access local variable 'dir'

Fixes Applied:

1. Added explicit "srcDir": "src" to library.json
2. Added explicit "includeDir": "src" to library.json
3. Removed conflicting "export": {"include": "src"} section
4. Fixed header reference in library.properties (painlessMesh.h)

Validation: Created automated validation script with 8 checks (100% passing)

Documentation:

• LIBRARY_STRUCTURE_FIX.md
• PLATFORMIO_USAGE.md
• SCONS_BUILD_FIX.md

Impact: MEDIUM - Users consuming library via npm

Symptom:

UnboundLocalError: cannot access local variable 'dir' (Python error during npm link)

Fix: Renamed npm scripts to prevent auto-execution:

• "build" → "dev:build"
• "prebuild" → "dev:prebuild"

Reason: npm automatically runs build and prebuild scripts during npm link, which triggered cmake/ninja builds causing Python errors.

1. docs/MESH_TOPOLOGY_GUIDE.md (980 lines)

   • Complete visualization guide with 5 working examples
   • D3.js, Cytoscape.js, Node.js, Python, Node-RED
   • Performance considerations and troubleshooting

2. docs/PHASE2_GUIDE.md (~500 lines)

   • Complete Phase 2 API reference
   • Usage examples and performance benchmarks
   • Integration guides for Grafana, InfluxDB, Prometheus
   • Migration guide from Phase 1

3. docs/improvements/PHASE2_IMPLEMENTATION.md (~600 lines)

   • Technical architecture and implementation details
   • MQTT topic schema documentation
   • Performance analysis and testing strategy

4. LIBRARY_STRUCTURE_FIX.md

   • PlatformIO library structure improvements
   • Validation checklist and testing guide
   • Root cause analysis and solutions

5. PLATFORMIO_USAGE.md

   • Quick start guide for PlatformIO users
   • Common issues and solutions
   • Example platformio.ini configurations

6. SCONS_BUILD_FIX.md

   • Comprehensive troubleshooting for PlatformIO builds
   • Step-by-step diagnostic procedures
   • Fix verification instructions

7. VECTOR_INCLUDE_FIX.md

   • Documentation of missing C++ header fix
   • Testing and verification instructions
   • Impact analysis

File: scripts/validate_library_structure.py (250+ lines)

Features:

• 8 comprehensive validation checks
• Automated PlatformIO compliance verification
• Detects common configuration issues
• Provides actionable recommendations

Usage:

python scripts/validate_library_structure.py

Output:

✓ Library JSON Exists (srcDir: src | includeDir: src)
✓ Library Properties Valid (Primary header: painlessMesh.h)
✓ Source Directory Structure (3 .cpp, 4 .h, 0 .hpp files)
✓ No Root Source Files (No .cpp files in root)
✓ No Duplicate Metadata (Single library.json at: library.json)
✓ Header Files Present (Found: painlessMesh.h, AlteriomPainlessMesh.h)
✓ Examples Directory (Found 20 example sketches)
✓ PlatformIO Compliance (All 5 structure checks passed)

════════════════════════════════════════════════════
VALIDATION SUMMARY: ✅ ALL CHECKS PASSED (8/8)
════════════════════════════════════════════════════

Example: 150-chunk firmware update (typical 512KB firmware)

• Unicast: Sequential per node = O(N × F) = 50 × 150 = 7,500 transmissions
• Broadcast: Parallel to all = O(F) = 150 transmissions
• Savings: 98% reduction (7,350 fewer transmissions)

NONE - This release is 100% backward compatible with v1.6.x

• All Phase 1 APIs unchanged
• Broadcast OTA defaults to false (unicast mode)
• MQTT bridge is optional add-on
• Existing sketches work without modification
• No recompilation required unless adopting new features

Existing v1.6.x code works without changes. To adopt new features:

// v1.6.x code (continues to work)
mesh.offerOTA(role, hw, md5, parts, false, false, true);

// v1.7.0 - add broadcast parameter
mesh.offerOTA(role, hw, md5, parts, false, true, true);
//                                         ^^^^ enable broadcast

// Include the bridge header
#include "examples/bridge/mqtt_status_bridge.hpp"

// In your setup(), create and configure bridge
MqttStatusBridge bridge(mesh, mqttClient);
bridge.setPublishInterval(30000);  // 30 seconds
bridge.enableTopology(true);
bridge.enableMetrics(true);
bridge.enableAlerts(true);
bridge.begin();

// In your loop(), keep mesh and MQTT alive
void loop() {
    mesh.update();
    mqttClient.loop();
}

// Phase 1: Compressed OTA
// Phase 2: Broadcast distribution
mesh.offerOTA(role, hw, md5, parts, false, true, true);

// Phase 2: MQTT Status Bridge
MqttStatusBridge bridge(mesh, mqttClient);
bridge.begin();

✅ Use when:

• Mesh has 10+ nodes
• All nodes need same firmware
• Network bandwidth is limited
• Fast distribution is critical
• Large-scale deployments (50+ nodes)

❌ Skip when:

• Small meshes (<5 nodes) - unicast is sufficient
• Different firmware per node - use unicast with role filtering
• Highly unstable networks - unicast is more reliable

✅ Use when:

• Production deployments
• Remote monitoring requirements
• Integration with existing tools (Grafana, InfluxDB)
• Cloud-connected systems
• Enterprise environments
• Automated alerting needs

❌ Skip when:

• Development/testing (use Serial monitor)
• Pure offline meshes (no external network)
• Resource-constrained root nodes
• No MQTT infrastructure available

• Recommendation: Use TLS/SSL for MQTT connections in production
• Authentication: Enable MQTT broker authentication (username/password)
• Network Isolation: Consider VLANs or firewall rules for MQTT traffic
• Topic ACLs: Configure topic access control lists on broker

Example (secure MQTT):

wifiClient.setCACert(ca_cert);  // TLS certificate
mqttClient.setServer(broker, 8883);  // Secure port
mqttClient.connect("bridge", mqtt_user, mqtt_pass);

• Firmware Signing: MD5 verification included (consider SHA256 for higher security)
• Role-Based Updates: Use role filtering to target specific device types
• Test First: Always test OTA on small subset before full mesh rollout

Platform Support:

• ✅ ESP32 (all variants)
• ✅ ESP8266 (with memory considerations)
• ✅ Arduino IDE 2.x
• ✅ PlatformIO 6.x
• ✅ espressif32 platform
• ✅ espressif8266 platform

Dependencies:

• ArduinoJson ^7.4.2
• TaskScheduler ^4.0.0
• AsyncTCP ^3.4.7 (ESP32)
• ESPAsyncTCP ^2.0.0 (ESP8266)
• @alteriom/mqtt-schema v0.5.0 (dev)

1. Backup Current Firmware

   • Keep v1.6.x binaries for rollback
   • Document current mesh configuration

2. Review Changes

   • Read CHANGELOG.md
   • Review PHASE2_GUIDE.md
   • Check LIBRARY_STRUCTURE_FIX.md

3. Test in Development

   • Deploy to test mesh (2-5 nodes)
   • Verify compilation succeeds
   • Test existing functionality

1. Verify Compilation

   pio run --target clean
   pio run

2. Test Basic Mesh

   • Nodes connect successfully
   • Messages route correctly
   • Time sync works

3. Test New Features (Optional)

   • Broadcast OTA on small mesh (2-3 nodes)
   • MQTT bridge with local broker
   • Topology visualization

1. Pilot Phase

   • Deploy to 10% of mesh (5-10 nodes)
   • Monitor for 24-48 hours
   • Check logs for errors

2. Gradual Rollout

   • Expand to 50% of mesh
   • Monitor performance metrics
   • Verify stability

3. Full Deployment

   • Complete mesh upgrade
   • Enable advanced features as needed
   • Document configuration

All known issues from v1.6.x have been resolved in v1.7.0. If you encounter any problems:

1. Check SCONS_BUILD_FIX.md for compilation issues
2. Review docs/troubleshooting/common-issues.md
3. Run validation: python scripts/validate_library_structure.py
4. Open issue: https://github.com/Alteriom/painlessMesh/issues

This release includes contributions from:

• Phase 2 Implementation Team - Broadcast OTA and MQTT bridge design
• Community Bug Reports - Compilation and build system issues
• Documentation Contributors - Comprehensive guides and examples
• Testing Team - Validation and quality assurance

Special thanks to all users who reported issues and provided feedback during development.

According to docs/improvements/FEATURE_PROPOSALS.md, Phase 3 will include:

• Progressive Rollout OTA (Option 1B) - Phased deployment with health checks
• Real-time Telemetry Streams (Option 2C) - Continuous metrics streaming
• Proactive Alerting System - Automated anomaly detection
• Large-Scale Optimization - Support for 200+ node meshes

Follow development: https://github.com/Alteriom/painlessMesh/projects

Documentation: https://alteriom.github.io/painlessMesh/
Issues: https://github.com/Alteriom/painlessMesh/issues
Discussions: https://github.com/Alteriom/painlessMesh/discussions
Email: [email protected]

Released: October 15, 2025
Version: 1.7.0
Schema: @alteriom/mqtt-schema v0.5.0
Status: ✅ Production Ready
Compatibility: 100% backward compatible with v1.6.x