@alteriom/painlessmesh 1.7.2 → 1.7.3

package/docs/releases/RELEASE_NOTES_1.7.0.md

@@ -0,0 +1,539 @@
+# AlteriomPainlessMesh v1.7.0 Release Notes
+
+**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
+
+---
+
+## 🎉 What's New in 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.
+
+### 🚀 Major Features
+
+#### 1. Broadcast OTA Distribution
+
+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:**
+```cpp
+// 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](docs/PHASE2_GUIDE.md)
+
+---
+
+#### 2. MQTT Status Bridge
+
+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:**
+```cpp
+#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](docs/PHASE2_GUIDE.md)
+
+---
+
+#### 3. Mesh Topology Visualization Guide
+
+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](docs/MESH_TOPOLOGY_GUIDE.md)
+
+---
+
+### 🐛 Critical Bug Fixes
+
+#### Fixed: Missing `#include <vector>` Compilation Error
+
+**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](VECTOR_INCLUDE_FIX.md)
+
+---
+
+#### Fixed: PlatformIO SCons Build Errors
+
+**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](LIBRARY_STRUCTURE_FIX.md)
+- [PLATFORMIO_USAGE.md](PLATFORMIO_USAGE.md)
+- [SCONS_BUILD_FIX.md](SCONS_BUILD_FIX.md)
+
+---
+
+#### Fixed: npm Link Errors
+
+**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.
+
+---
+
+### 📚 New Documentation (7 Files)
+
+1. **[docs/MESH_TOPOLOGY_GUIDE.md](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](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](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](LIBRARY_STRUCTURE_FIX.md)**
+   - PlatformIO library structure improvements
+   - Validation checklist and testing guide
+   - Root cause analysis and solutions
+
+5. **[PLATFORMIO_USAGE.md](PLATFORMIO_USAGE.md)**
+   - Quick start guide for PlatformIO users
+   - Common issues and solutions
+   - Example platformio.ini configurations
+
+6. **[SCONS_BUILD_FIX.md](SCONS_BUILD_FIX.md)**
+   - Comprehensive troubleshooting for PlatformIO builds
+   - Step-by-step diagnostic procedures
+   - Fix verification instructions
+
+7. **[VECTOR_INCLUDE_FIX.md](VECTOR_INCLUDE_FIX.md)**
+   - Documentation of missing C++ header fix
+   - Testing and verification instructions
+   - Impact analysis
+
+---
+
+### 🛠️ New Tools
+
+#### Library Structure Validation Script
+
+**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:**
+```bash
+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)
+════════════════════════════════════════════════════
+```
+
+---
+
+### 📊 Performance Improvements
+
+#### Broadcast OTA Performance
+
+| Mesh Size | Unicast Transmissions | Broadcast Transmissions | Traffic Reduction | Speed Improvement |
+|-----------|----------------------|------------------------|-------------------|-------------------|
+| 10 nodes  | 1,500               | 150                    | 90%               | ~10x faster       |
+| 50 nodes  | 7,500               | 150                    | 98%               | ~50x faster       |
+| 100 nodes | 15,000              | 150                    | 99%               | ~100x faster      |
+
+**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)
+
+#### Memory Impact
+
+| Feature | Memory Usage | Impact |
+|---------|-------------|--------|
+| Broadcast OTA | +2-5KB per node | Chunk tracking buffer |
+| MQTT Bridge | +5-8KB (root only) | Bridge state and buffers |
+| Total (both features) | +7-13KB | Acceptable for ESP32, tight on ESP8266 |
+
+---
+
+### ⚠️ Breaking Changes
+
+**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
+
+---
+
+### 🔄 Migration Guide
+
+#### No Migration Required
+
+Existing v1.6.x code works without changes. To adopt new features:
+
+#### Option 1: Enable Broadcast OTA
+
+```cpp
+// 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
+```
+
+#### Option 2: Add MQTT Status Bridge
+
+```cpp
+// 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();
+}
+```
+
+#### Option 3: Use Both Features
+
+```cpp
+// 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();
+```
+
+---
+
+### 🎯 When to Use Each Feature
+
+#### Broadcast OTA
+
+✅ **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
+
+#### MQTT Status Bridge
+
+✅ **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
+
+---
+
+### 🔐 Security Considerations
+
+#### MQTT Bridge Security
+
+- **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):**
+```cpp
+wifiClient.setCACert(ca_cert);  // TLS certificate
+mqttClient.setServer(broker, 8883);  // Secure port
+mqttClient.connect("bridge", mqtt_user, mqtt_pass);
+```
+
+#### OTA Security
+
+- **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
+
+---
+
+### 📋 Compatibility Matrix
+
+| Component | v1.6.x | v1.7.0 | Compatible |
+|-----------|--------|--------|------------|
+| Basic OTA | ✅ | ✅ | ✅ Yes |
+| Compressed OTA | ✅ | ✅ | ✅ Yes |
+| Broadcast OTA | ❌ | ✅ | ✅ Yes (new) |
+| Basic Status Packages | ✅ | ✅ | ✅ Yes |
+| Enhanced Status Packages | ✅ | ✅ | ✅ Yes |
+| MQTT Bridge | ❌ | ✅ | ✅ Yes (new) |
+| Custom Packages (200-203) | ✅ | ✅ | ✅ Yes |
+| Mesh Topology | ❌ | ✅ | ✅ Yes (new) |
+
+**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)
+
+---
+
+### 🧪 Testing Recommendations
+
+#### Before Upgrading
+
+1. **Backup Current Firmware**
+   - Keep v1.6.x binaries for rollback
+   - Document current mesh configuration
+
+2. **Review Changes**
+   - Read [CHANGELOG.md](CHANGELOG.md)
+   - Review [PHASE2_GUIDE.md](docs/PHASE2_GUIDE.md)
+   - Check [LIBRARY_STRUCTURE_FIX.md](LIBRARY_STRUCTURE_FIX.md)
+
+3. **Test in Development**
+   - Deploy to test mesh (2-5 nodes)
+   - Verify compilation succeeds
+   - Test existing functionality
+
+#### After Upgrading
+
+1. **Verify Compilation**
+   ```bash
+   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
+
+#### Production Rollout
+
+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
+
+---
+
+### 🐛 Known Issues
+
+#### None Currently Identified
+
+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](SCONS_BUILD_FIX.md) for compilation issues
+2. Review [docs/troubleshooting/common-issues.md](docs/troubleshooting/common-issues.md)
+3. Run validation: `python scripts/validate_library_structure.py`
+4. Open issue: https://github.com/Alteriom/painlessMesh/issues
+
+---
+
+### 📖 Complete Documentation
+
+| Topic | Document | Description |
+|-------|----------|-------------|
+| **Release Overview** | RELEASE_NOTES_1.7.0.md | This document |
+| **Changelog** | [CHANGELOG.md](CHANGELOG.md) | Detailed change history |
+| **Phase 2 Features** | [docs/PHASE2_GUIDE.md](docs/PHASE2_GUIDE.md) | Complete API and usage guide |
+| **Implementation Details** | [docs/improvements/PHASE2_IMPLEMENTATION.md](docs/improvements/PHASE2_IMPLEMENTATION.md) | Technical architecture |
+| **Visualization Guide** | [docs/MESH_TOPOLOGY_GUIDE.md](docs/MESH_TOPOLOGY_GUIDE.md) | Dashboard examples |
+| **Bug Fixes** | [VECTOR_INCLUDE_FIX.md](VECTOR_INCLUDE_FIX.md) | Compilation fix details |
+| **Library Structure** | [LIBRARY_STRUCTURE_FIX.md](LIBRARY_STRUCTURE_FIX.md) | PlatformIO fixes |
+| **Build Troubleshooting** | [SCONS_BUILD_FIX.md](SCONS_BUILD_FIX.md) | Comprehensive diagnostics |
+| **PlatformIO Usage** | [PLATFORMIO_USAGE.md](PLATFORMIO_USAGE.md) | Quick start guide |
+| **MQTT Commands** | [docs/MQTT_BRIDGE_COMMANDS.md](docs/MQTT_BRIDGE_COMMANDS.md) | Command reference |
+
+---
+
+### 🙏 Acknowledgments
+
+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.
+
+---
+
+### 🚀 What's Next: Phase 3
+
+According to [docs/improvements/FEATURE_PROPOSALS.md](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
+
+---
+
+### 📞 Support
+
+**Documentation:** https://alteriom.github.io/painlessMesh/  
+**Issues:** https://github.com/Alteriom/painlessMesh/issues  
+**Discussions:** https://github.com/Alteriom/painlessMesh/discussions  
+**Email:** support@alteriom.com
+
+---
+
+**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