@alteriom/painlessmesh 1.6.1 → 1.7.3

package/CHANGELOG.md

@@ -1,144 +1,435 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-### Added
-
-- TBD
-
-### Changed
-
-- TBD
-
-### Fixed
-
-- TBD
-
-## [1.6.1] - 2025-09-29
-
-### Added
-
-- **Arduino Library Manager Support**: Updated library name to "Alteriom PainlessMesh" for better discoverability
-- **NPM Package Publishing**: Complete NPM publication setup with dual registry support
-  - Public NPM registry: `@alteriom/painlessmesh`
-  - GitHub Packages registry: `@alteriom/painlessmesh` (scoped)
-  - Automated version consistency across library.properties, library.json, and package.json
-- **GitHub Wiki Automation**: Automatic wiki synchronization on releases
-  - Home page generated from README.md
-  - API Reference with auto-generated documentation
-  - Examples page with links to repository examples
-  - Installation guide for multiple platforms
-- **Enhanced Release Workflow**: Comprehensive publication automation
-  - NPM publishing to both public and GitHub Packages registries
-  - GitHub Wiki updates with structured documentation
-  - Arduino Library Manager submission instructions
-  - Release validation with multi-file version consistency
-- **Arduino IDE Support**: Added keywords.txt for syntax highlighting
-- **Distribution Documentation**: Complete guides for all publication channels
-  - RELEASE_SUMMARY.md template for release notes
-  - TRIGGER_RELEASE.md for step-by-step release instructions
-  - Enhanced RELEASE_GUIDE.md with comprehensive publication workflow
-- **Version Management**: Enhanced bump-version script
-  - Updates all three version files simultaneously (library.properties, library.json, package.json)
-  - Comprehensive version consistency validation
-  - Clear instructions for NPM and GitHub Packages publication
-
-### Changed  
-- **Library Name**: Updated from "Painless Mesh" to "Alteriom PainlessMesh" for Arduino Library Manager
-- **Release Process**: Streamlined to support multiple package managers
-  - Single commit with "release:" prefix triggers full publication pipeline
-  - Automated testing, building, and publishing across all channels
-  - Wiki documentation automatically synchronized
-- **CI/CD Pipeline**: Enhanced with NPM publication capabilities
-  - Dual NPM registry publishing (public + GitHub Packages)
-  - Automated wiki updates with generated content
-  - Comprehensive pre-release validation
-- **Documentation Structure**: Reorganized for multi-channel distribution
-  - Clear separation between automatic and manual processes
-  - Platform-specific installation instructions
-  - Troubleshooting guides for each distribution channel
-
-### Fixed
-- **NPM Publishing**: Fixed registry configuration issues that prevented NPM publication
-- **GitHub Pages**: Improved workflow to handle cases where Pages is not configured
-- **PlatformIO Build**: Fixed include paths in improved_sensor_node.ino example
-- **Package Configuration**: Consistent version management across all package files
-- **Release Documentation**: Complete coverage of all distribution channels
-- **Version Validation**: Prevents releases with inconsistent version numbers
-
-## [1.6.0] - 2025-09-29
-
-### Added
-- Enhanced Alteriom-specific package documentation and examples
-- Updated repository URLs and metadata for Alteriom fork
-- Improved release process documentation
-- Fixed deprecated GitHub Actions in release workflow
-- Added concurrency controls to prevent duplicate workflow runs
-- Comprehensive Alteriom package documentation and quick start guide
-
-### Changed  
-- Migrated from deprecated `actions/create-release@v1` to GitHub CLI for releases
-- Updated library.properties and library.json to reflect Alteriom ownership
-- Enhanced package descriptions to highlight Alteriom extensions
-
-### Fixed
-- Fixed deprecated GitHub Actions in release workflow  
-- Corrected undefined variable references in upload workflow steps
-- Updated repository URLs from GitLab to GitHub in library files
-
-## [1.5.6] - Current Release
-
-### Features
-- painlessMesh is a user-friendly library for creating mesh networks with ESP8266 and ESP32 devices
-- Automatic routing and network management
-- JSON-based messaging system
-- Time synchronization across all nodes
-- Support for coordinated behaviors like synchronized displays
-- Sensor network patterns for IoT applications
-
-### Platforms Supported
-- ESP32 (espressif32)
-- ESP8266 (espressif8266)
-
-### Dependencies
-- ArduinoJson ^7.4.2
-- TaskScheduler ^3.8.5
-- AsyncTCP ^3.4.7 (ESP32)
-- ESPAsyncTCP ^2.0.0 (ESP8266)
-
-### Alteriom Extensions
-- SensorPackage for environmental monitoring
-- CommandPackage for device control
-- StatusPackage for health monitoring
-- Type-safe message handling
-
----
-
-## Release Notes
-
-### How to Release
-
-1. Update version in both `library.properties` and `library.json`
-2. Add changes to this CHANGELOG.md under the new version
-3. Commit with message starting with `release:` (e.g., `release: v1.6.0`)
-4. Push to main branch
-5. GitHub Actions will automatically:
-   - Create a git tag
-   - Generate GitHub release
-   - Package library for distribution
-   - Update documentation
-
-### Version Numbering
-
-This project follows [Semantic Versioning](https://semver.org/):
-
-- **MAJOR** version when you make incompatible API changes
-- **MINOR** version when you add functionality in a backwards compatible manner  
-- **PATCH** version when you make backwards compatible bug fixes
-
-Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- TBD
+
+### Changed
+
+- TBD
+
+### Fixed
+
+- TBD
+
+## [1.7.3] - 2025-10-16
+
+### Fixed
+
+- **Router Memory Safety**: Replaced dangerous escalating memory allocation workaround with safe pre-calculated capacity
+  - Removed static `baseCapacity` variable that grew indefinitely (512B → 20KB)
+  - Implemented single-allocation strategy with pre-calculated capacity based on message size and nesting depth
+  - Added 8KB safety cap to protect ESP8266 devices from OOM crashes
+  - Support for both ArduinoJson v6 and v7 with version-aware capacity calculation
+
+### Performance
+
+- **Small messages (50B)**: +512B predictable overhead (vs. variable 512B-20KB in v1.7.0)
+- **Medium messages (500B)**: -3596B saved by eliminating retry allocations
+- **Large messages (2KB)**: -17KB saved by preventing escalation to 20KB
+
+### Added
+
+- **Tests**: New comprehensive memory safety test suite (`test/catch/catch_router_memory.cpp`)
+  - Simple message parsing tests
+  - Deeply nested JSON structure tests (10+ levels)
+  - Oversized message handling tests
+  - Predictable capacity allocation verification
+  - 14 new assertions, all passing
+
+### Documentation
+
+- **CODE_REFACTORING_RECOMMENDATIONS.md**: Comprehensive code analysis document with 8 prioritized refactoring recommendations (P0-P3)
+- **PATCH_v1.7.3.md**: Complete release notes with before/after comparison, performance metrics, and migration guide
+
+### Technical Details
+
+- Fixes issue #521: ArduinoJson copy constructor segmentation fault workaround
+- All 710+ test assertions passing across 18 test suites
+- Docker-based testing on Linux x86_64 with CMake + Ninja
+
+## [1.7.2] - 2025-10-15
+
+### Fixed
+
+- **NPM Configuration**: Updated `.npmrc` to use public NPM registry instead of GitHub Packages
+- **Dependencies**: Moved `@alteriom/mqtt-schema` back to `devDependencies` now that it's publicly available
+- **Automated Releases**: Fixed npm install failures during automated release workflow
+- **Package Availability**: Package now accessible at <https://www.npmjs.com/package/@alteriom/mqtt-schema>
+
+## [1.7.1] - 2025-10-15
+
+### Fixed
+
+- **mqttStatusBridge**: Fixed scheduler access by using external `Scheduler` reference instead of protected `mScheduler` member
+- **mqttStatusBridge**: Corrected Task handling - `publishTask` is an object, not a pointer
+- **mqttStatusBridge**: Fixed node list iteration using proper iterators instead of array-style indexing
+- **alteriomSensorNode**: Updated to ArduinoJson v7 API - replaced deprecated `DynamicJsonDocument` with `JsonDocument`
+- **alteriomSensorNode**: Removed usage of deprecated `jsonObjectSize()` method
+- Resolved compilation errors preventing ESP32/ESP8266 builds
+
+### Technical Details
+
+- `mesh.getNodeList()` returns `std::list<uint32_t>` which doesn't support `operator[]` indexing
+- Changed from `mesh.mScheduler.addTask()` to `scheduler.addTask()` with external scheduler
+- Changed from `DynamicJsonDocument doc(size)` to `JsonDocument doc` for ArduinoJson v7 compatibility
+
+## [1.7.0] - 2025-10-15
+
+### 🚀 Major Features
+
+#### Phase 2: Broadcast OTA & MQTT Status Bridge
+
+**Broadcast OTA Distribution**
+
+- ✨ **Broadcast Mode OTA**: True mesh-wide firmware distribution with ~98% network traffic reduction for 50+ node meshes
+- 📡 **Parallel Updates**: All nodes receive firmware chunks simultaneously instead of sequential unicast
+- ⚡ **Performance**: ~50x faster for 50-node mesh, ~100x faster for 100-node mesh
+- 🔧 **Simple API**: Single parameter change: `mesh.offerOTA(..., true)` enables broadcast mode
+- 🔄 **Backward Compatible**: Defaults to unicast mode (Phase 1), no breaking changes
+- 📊 **Scalability**: Efficiently handles 50-100+ node meshes with minimal overhead
+
+**MQTT Status Bridge**
+
+- 🌉 **Professional Monitoring**: Complete MQTT bridge for publishing mesh status to monitoring tools
+- 📈 **Multiple Topics**: Publishes topology, metrics, alerts, and per-node status
+- 🔗 **Tool Integration**: Ready for Grafana, InfluxDB, Prometheus, Home Assistant, Node-RED
+- ⚙️ **Configurable**: Adjustable publish intervals, enable/disable features per need
+- 🎯 **Production Ready**: Designed for enterprise IoT and commercial deployments
+- 📋 **Schema Compliant**: Uses @alteriom/mqtt-schema v0.5.0 for standardized messaging
+
+#### Mesh Topology Visualization
+
+- 📊 **Visualization Guide**: Comprehensive 980-line guide for building web dashboards (docs/MESH_TOPOLOGY_GUIDE.md)
+- 🎨 **D3.js Examples**: Complete force-directed graph visualization (200+ lines)
+- 🕸️ **Cytoscape.js Examples**: Network topology view (150+ lines)
+- 🔴 **Node.js Dashboard**: Real-time dashboard with Express + Socket.IO
+- 🐍 **Python Monitor**: Console monitoring with Rich library
+- 🔄 **Node-RED Flows**: Ready-to-import flow JSON for rapid development
+- 🛠️ **Troubleshooting Guide**: Common issues and performance tuning
+
+### 🐛 Critical Bug Fixes
+
+#### Compilation & Build Fixes
+
+- 🔧 **Fixed Missing `#include <vector>`**: Added missing C++ standard library header to `src/painlessmesh/mesh.hpp`
+  - **Impact**: Fixes compilation errors: "'vector' in namespace 'std' does not name a template type"
+  - **Affected**: All projects using getConnectionDetails() or latencySamples
+  - **File**: src/painlessmesh/mesh.hpp (line 4)
+  - **Documentation**: VECTOR_INCLUDE_FIX.md
+
+- 📦 **PlatformIO Library Structure**: Fixed SCons build errors for external projects
+  - Added explicit `srcDir` and `includeDir` to library.json
+  - Removed conflicting `export.include` section
+  - Fixed header references in library.properties (painlessMesh.h)
+  - **Impact**: Fixes "cannot resolve directory for painlessMeshSTA.cpp" errors
+  - **Documentation**: LIBRARY_STRUCTURE_FIX.md, PLATFORMIO_USAGE.md, SCONS_BUILD_FIX.md
+
+- 📝 **npm Build Scripts**: Fixed UnboundLocalError during `npm link`
+  - Renamed `build` → `dev:build` and `prebuild` → `dev:prebuild`
+  - Prevents automatic build execution during package installation
+  - **Impact**: Fixes Python errors when using library as npm dependency
+
+### 📚 Documentation
+
+#### New Documentation Files (7 files)
+
+1. **docs/MESH_TOPOLOGY_GUIDE.md** (980 lines)
+   - Complete visualization guide with 5 working examples
+   - D3.js, Cytoscape.js, Python, Node-RED implementations
+   - Performance considerations and troubleshooting
+
+2. **docs/PHASE2_GUIDE.md** (~500 lines)
+   - Complete API reference for Phase 2 features
+   - Usage examples and performance benchmarks
+   - Integration guides for monitoring tools
+   - 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
+
+5. **PLATFORMIO_USAGE.md**
+   - Quick start guide for PlatformIO users
+   - Common issues and solutions
+
+6. **SCONS_BUILD_FIX.md**
+   - Comprehensive troubleshooting for PlatformIO builds
+   - Step-by-step diagnostic procedures
+
+7. **VECTOR_INCLUDE_FIX.md**
+   - Documentation of missing C++ header fix
+   - Testing and verification instructions
+
+#### Updated Documentation
+
+- **README.md**: Enhanced with Phase 2 features and schema v0.5.0
+- **docs/MQTT_BRIDGE_COMMANDS.md**: Updated version references
+- **examples/**: New Phase 2 examples added
+
+### 🛠️ New Tools & Scripts
+
+- **scripts/validate_library_structure.py** (250+ lines)
+  - Automated validation of PlatformIO library structure
+  - 8 comprehensive checks (all passing)
+  - Detects common configuration issues
+
+### 🔄 Enhanced Examples
+
+- **examples/alteriom/phase2_features.ino**: Demonstrates broadcast OTA
+- **examples/bridge/mqtt_status_bridge.hpp**: Complete MQTT bridge implementation
+- **examples/bridge/mqtt_status_bridge_example.ino**: Full working bridge example
+
+### ⚙️ Configuration Changes
+
+**library.json**
+
+- Added `"srcDir": "src"` for explicit source directory
+- Added `"includeDir": "src"` for explicit include directory
+- Removed conflicting `"export": {"include": "src"}` section
+
+**library.properties**
+
+- Updated `includes=painlessMesh.h` (was AlteriomPainlessMesh.h)
+
+**package.json**
+
+- Renamed `build` → `dev:build` (prevents auto-execution)
+- Renamed `prebuild` → `dev:prebuild` (prevents auto-execution)
+- Updated to @alteriom/mqtt-schema v0.5.0
+
+### 📊 Performance Improvements
+
+**Broadcast OTA Performance**
+
+- **Network Traffic**: 90% reduction (10 nodes), 98% reduction (50 nodes), 99% reduction (100 nodes)
+- **Update Speed**: ~N times faster (parallel vs sequential)
+- **Example**: 150-chunk firmware to 50 nodes
+  - Unicast: 7,500 transmissions
+  - Broadcast: 150 transmissions
+  - **Savings: 98% (7,350 transmissions)**
+
+**Memory Impact**
+
+- Broadcast OTA: +2-5KB per node (chunk tracking)
+- MQTT Bridge: +5-8KB (root node only)
+- Minimal overhead for ESP32, acceptable for ESP8266
+
+### 🔐 Schema Compliance
+
+- ✅ Fully compliant with @alteriom/mqtt-schema v0.5.0
+- ✅ Topology messages include all required envelope fields
+- ✅ Node objects include firmware_version, uptime_seconds, connection_count
+- ✅ Schema versioning for forward compatibility
+
+### ⚠️ Breaking Changes
+
+**None** - This release is 100% backward compatible with v1.6.x
+
+- Broadcast OTA defaults to `false` (unicast mode preserved)
+- MQTT bridge is optional add-on
+- All Phase 1 APIs unchanged
+- Existing sketches work without modification
+
+### 🔄 Migration Guide
+
+**No migration required** for existing code. To adopt new features:
+
+**Enable Broadcast OTA:**
+
+```cpp
+// Before (v1.6.x)
+mesh.offerOTA(role, hw, md5, parts, false, false, true);
+
+// After (v1.7.0) - add broadcast parameter
+mesh.offerOTA(role, hw, md5, parts, false, true, true);
+//                                         ^^^^ broadcast
+```
+
+**Add MQTT Status Bridge:**
+
+```cpp
+#include "examples/bridge/mqtt_status_bridge.hpp"
+
+MqttStatusBridge bridge(mesh, mqttClient);
+bridge.setPublishInterval(30000);
+bridge.begin();
+```
+
+### 🎯 Recommended For
+
+- ✅ Production IoT deployments with 10-100+ nodes
+- ✅ Commercial systems requiring professional monitoring
+- ✅ Enterprise environments needing Grafana/Prometheus integration
+- ✅ Projects with limited network bandwidth
+- ✅ Systems requiring rapid firmware distribution
+
+### 📖 Complete Documentation
+
+- [Phase 2 User Guide](docs/PHASE2_GUIDE.md) - API reference and usage
+- [Phase 2 Implementation](docs/improvements/PHASE2_IMPLEMENTATION.md) - Technical details
+- [Mesh Topology Guide](docs/MESH_TOPOLOGY_GUIDE.md) - Visualization examples
+- [MQTT Bridge Commands](docs/MQTT_BRIDGE_COMMANDS.md) - Command reference
+- [Library Structure Fix](LIBRARY_STRUCTURE_FIX.md) - Build system improvements
+- [Vector Include Fix](VECTOR_INCLUDE_FIX.md) - Compilation fix details
+
+### 🧪 Testing
+
+- ✅ All Phase 1 tests passing (80 assertions in 7 test cases)
+- ✅ Backward compatibility verified
+- ✅ No regressions introduced
+- ✅ Library structure validation: 8/8 checks passing
+- ✅ Compilation successful on ESP32 and ESP8266
+
+### 🙏 Acknowledgments
+
+This release includes contributions from Phase 2 implementation, bug fixes discovered by the community, and comprehensive documentation improvements based on user feedback.
+
+**Next**: Phase 3 features (progressive rollout OTA, real-time telemetry streams) as outlined in FEATURE_PROPOSALS.md
+
+---
+
+## [1.6.1] - 2025-09-29
+
+### Added
+
+- **Arduino Library Manager Support**: Updated library name to "Alteriom PainlessMesh" for better discoverability
+- **NPM Package Publishing**: Complete NPM publication setup with dual registry support
+  - Public NPM registry: `@alteriom/painlessmesh`
+  - GitHub Packages registry: `@alteriom/painlessmesh` (scoped)
+  - Automated version consistency across library.properties, library.json, and package.json
+- **GitHub Wiki Automation**: Automatic wiki synchronization on releases
+  - Home page generated from README.md
+  - API Reference with auto-generated documentation
+  - Examples page with links to repository examples
+  - Installation guide for multiple platforms
+- **Enhanced Release Workflow**: Comprehensive publication automation
+  - NPM publishing to both public and GitHub Packages registries
+  - GitHub Wiki updates with structured documentation
+  - Arduino Library Manager submission instructions
+  - Release validation with multi-file version consistency
+- **Arduino IDE Support**: Added keywords.txt for syntax highlighting
+- **Distribution Documentation**: Complete guides for all publication channels
+  - docs/archive/RELEASE_SUMMARY.md template for release notes (archived)
+  - docs/archive/TRIGGER_RELEASE.md for step-by-step release instructions (archived, see RELEASE_GUIDE.md)
+  - Enhanced RELEASE_GUIDE.md with comprehensive publication workflow
+- **Version Management**: Enhanced bump-version script
+  - Updates all three version files simultaneously (library.properties, library.json, package.json)
+  - Comprehensive version consistency validation
+  - Clear instructions for NPM and GitHub Packages publication
+
+### Changed  
+
+- **Library Name**: Updated from "Painless Mesh" to "Alteriom PainlessMesh" for Arduino Library Manager
+- **Release Process**: Streamlined to support multiple package managers
+  - Single commit with "release:" prefix triggers full publication pipeline
+  - Automated testing, building, and publishing across all channels
+  - Wiki documentation automatically synchronized
+- **CI/CD Pipeline**: Enhanced with NPM publication capabilities
+  - Dual NPM registry publishing (public + GitHub Packages)
+  - Automated wiki updates with generated content
+  - Comprehensive pre-release validation
+- **Documentation Structure**: Reorganized for multi-channel distribution
+  - Clear separation between automatic and manual processes
+  - Platform-specific installation instructions
+  - Troubleshooting guides for each distribution channel
+
+### Fixed
+
+- **NPM Publishing**: Fixed registry configuration issues that prevented NPM publication
+- **GitHub Pages**: Improved workflow to handle cases where Pages is not configured
+- **PlatformIO Build**: Fixed include paths in improved_sensor_node.ino example
+- **Package Configuration**: Consistent version management across all package files
+- **Release Documentation**: Complete coverage of all distribution channels
+- **Version Validation**: Prevents releases with inconsistent version numbers
+
+## [1.6.0] - 2025-09-29
+
+### Added
+
+- Enhanced Alteriom-specific package documentation and examples
+- Updated repository URLs and metadata for Alteriom fork
+- Improved release process documentation
+- Fixed deprecated GitHub Actions in release workflow
+- Added concurrency controls to prevent duplicate workflow runs
+- Comprehensive Alteriom package documentation and quick start guide
+
+### Changed  
+
+- Migrated from deprecated `actions/create-release@v1` to GitHub CLI for releases
+- Updated library.properties and library.json to reflect Alteriom ownership
+- Enhanced package descriptions to highlight Alteriom extensions
+
+### Fixed
+
+- Fixed deprecated GitHub Actions in release workflow  
+- Corrected undefined variable references in upload workflow steps
+- Updated repository URLs from GitLab to GitHub in library files
+
+## [1.5.6] - Current Release
+
+### Features
+
+- painlessMesh is a user-friendly library for creating mesh networks with ESP8266 and ESP32 devices
+- Automatic routing and network management
+- JSON-based messaging system
+- Time synchronization across all nodes
+- Support for coordinated behaviors like synchronized displays
+- Sensor network patterns for IoT applications
+
+### Platforms Supported
+
+- ESP32 (espressif32)
+- ESP8266 (espressif8266)
+
+### Dependencies
+
+- ArduinoJson ^7.4.2
+- TaskScheduler ^3.8.5
+- AsyncTCP ^3.4.7 (ESP32)
+- ESPAsyncTCP ^2.0.0 (ESP8266)
+
+### Alteriom Extensions
+
+- SensorPackage for environmental monitoring
+- CommandPackage for device control
+- StatusPackage for health monitoring
+- Type-safe message handling
+
+---
+
+## Release Notes
+
+### How to Release
+
+1. Update version in both `library.properties` and `library.json`
+2. Add changes to this CHANGELOG.md under the new version
+3. Commit with message starting with `release:` (e.g., `release: v1.6.0`)
+4. Push to main branch
+5. GitHub Actions will automatically:
+   - Create a git tag
+   - Generate GitHub release
+   - Package library for distribution
+   - Update documentation
+
+### Version Numbering
+
+This project follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** version when you make incompatible API changes
+- **MINOR** version when you add functionality in a backwards compatible manner  
+- **PATCH** version when you make backwards compatible bug fixes
+
+Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.