@alteriom/painlessmesh 1.7.4 → 1.7.5

package/docs/releases/RELEASE_NOTES_1.7.0.md

@@ -1,539 +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
+# 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