@alteriom/painlessmesh 1.8.9 → 1.8.11

package/docs/releases/RELEASE_NOTES_1.8.10.md

@@ -0,0 +1,239 @@
+# Release Notes: v1.8.10
+
+**Release Date**: November 18, 2025  
+**Type**: Patch Release (Bug Fix)
+
+---
+
+## 🎯 Overview
+
+Version 1.8.10 is a focused patch release that fixes a critical bridge discovery issue where newly connected nodes were not reliably receiving bridge status information. This release improves the reliability of bridge-to-node communication in mesh networks.
+
+---
+
+## 🐛 Bug Fixes
+
+### Bridge Status Discovery - Direct Messaging
+
+**Issue**: Newly connected nodes were not reliably receiving bridge status broadcasts, causing delays or failures in bridge discovery.
+
+**Root Cause Analysis**:
+- Broadcast messages (`routing=2`) were not reaching newly connected nodes consistently
+- Time synchronization (NTP) operations were interfering with bridge discovery timing
+- Broadcast routing tables may not be fully established immediately after a node connects to the mesh
+- This led to nodes reporting "No primary bridge available" despite bridges being active
+
+**Solution Implemented**:
+- Changed bridge status delivery mechanism from broadcast to direct single message
+- Bridge now sends status directly to newly connected nodes using `sendSingle()` (routing=1)
+- Minimal 500ms delay added for connection stability before sending status
+- Direct targeted delivery ensures the message reaches the new node reliably
+- Time sync operations no longer interfere with critical bridge discovery
+
+**Technical Details**:
+- **File Modified**: `src/arduino/wifi.hpp`
+- **Location**: Line ~809 in `initBridgeStatusBroadcast()`
+- **Change**: Modified `newConnectionCallback` to use `sendSingle(nodeId, ...)` instead of `sendBroadcast(...)`
+- **Routing Mode**: Changed from `routing=2` (broadcast) to `routing=1` (single destination)
+
+**Impact**:
+- ✅ Nodes discover bridges immediately (within 500ms) after connecting
+- ✅ Eliminates "No primary bridge available" errors for newly connected nodes
+- ✅ More reliable mesh network initialization
+- ✅ Better handling of nodes joining/rejoining the mesh
+- ✅ Reduced dependency on broadcast routing table convergence
+
+**Backward Compatibility**:
+- ✅ No API changes
+- ✅ Internal delivery mechanism improved
+- ✅ All existing code continues to work without modification
+- ✅ No breaking changes to bridge status packet format
+
+**Related Issues**:
+- Resolves GitHub issue #135 "The latest fix does not work"
+
+---
+
+## 📦 What's Included
+
+### Core Changes
+- **Bridge Discovery**: Enhanced reliability for newly connected nodes
+- **Message Delivery**: Direct messaging replaces broadcast for critical status updates
+- **Connection Stability**: Added minimal delay for connection stabilization
+
+### Files Modified
+- `src/arduino/wifi.hpp` - Bridge status delivery mechanism
+- `library.properties` - Version update to 1.8.10
+- `library.json` - Version update to 1.8.10
+- `package.json` - Version update to 1.8.10
+- `src/painlessMesh.h` - Header version and date update
+- `src/AlteriomPainlessMesh.h` - Version defines update
+- `CHANGELOG.md` - Release entry added
+
+---
+
+## 🚀 Upgrade Guide
+
+### Installation
+
+**Arduino Library Manager**:
+```
+Search for "Alteriom PainlessMesh" and update to v1.8.10
+```
+
+**PlatformIO**:
+```ini
+lib_deps = alteriom/AlteriomPainlessMesh@^1.8.10
+```
+
+**NPM**:
+```bash
+npm install @alteriom/painlessmesh@1.8.10
+```
+
+### Migration from v1.8.9
+
+**No changes required!** This is a drop-in replacement for v1.8.9.
+
+- ✅ All existing bridge code works unchanged
+- ✅ All existing node code works unchanged
+- ✅ No API modifications
+- ✅ No configuration changes needed
+
+Simply update the library version and redeploy.
+
+---
+
+## 🧪 Testing Recommendations
+
+After upgrading to v1.8.10, test these scenarios:
+
+### 1. **New Node Connection Test**
+```cpp
+// Expected behavior:
+// - Node connects to mesh
+// - Receives bridge status within 500ms
+// - No "No primary bridge available" errors
+```
+
+### 2. **Bridge Discovery Test**
+```cpp
+// Expected behavior:
+// - Multiple nodes connecting simultaneously
+// - All nodes discover bridge reliably
+// - Fast discovery regardless of NTP sync activity
+```
+
+### 3. **Bridge Failover Test**
+```cpp
+// Expected behavior:
+// - Bridge disconnects
+// - New bridge elected
+// - All nodes discover new bridge within 500ms
+```
+
+### 4. **Network Rejoin Test**
+```cpp
+// Expected behavior:
+// - Node loses connection and reconnects
+// - Bridge status received immediately on rejoin
+// - No discovery delays
+```
+
+---
+
+## 🎯 Recommendations
+
+### Who Should Upgrade
+
+**Immediate Upgrade Recommended**:
+- ✅ Systems with frequent node connections/disconnections
+- ✅ Networks experiencing bridge discovery delays
+- ✅ Deployments with NTP time synchronization enabled
+- ✅ Multi-bridge mesh networks
+- ✅ Production systems requiring fast startup
+
+**Can Upgrade at Convenience**:
+- Networks with stable connections and infrequent joins
+- Single-bridge setups without time sync
+- Development/testing environments
+
+### Deployment Strategy
+
+**Low-Risk Deployment**:
+1. Test in development environment first
+2. Deploy to one bridge node
+3. Monitor for 24 hours
+4. Roll out to remaining nodes
+
+**Zero-Downtime Deployment**:
+- Bridge nodes can be updated one at a time
+- Regular nodes can be updated in batches
+- No mesh network restart required
+
+---
+
+## 📊 Performance Characteristics
+
+### Resource Usage
+- **Memory Impact**: Negligible (no additional allocations)
+- **CPU Impact**: Minimal (one additional `sendSingle()` per connection)
+- **Network Traffic**: Slightly reduced (targeted delivery vs broadcast)
+
+### Timing Improvements
+- **Before v1.8.10**: Bridge discovery could take up to 30 seconds (periodic broadcast interval)
+- **After v1.8.10**: Bridge discovery within 500ms of connection
+
+### Network Efficiency
+- **Broadcast Method**: Message sent to all nodes (even if not needed)
+- **Direct Method**: Message sent only to newly connected node (more efficient)
+
+---
+
+## 🔍 Known Issues
+
+### None
+
+This release has no known issues. The fix has been tested and validated.
+
+### Reporting Issues
+
+If you encounter any problems with v1.8.10, please report them:
+- **GitHub Issues**: https://github.com/Alteriom/painlessMesh/issues
+- **Include**: Library version, platform (ESP32/ESP8266), and detailed description
+- **Attach**: Serial logs and minimal reproduction code if possible
+
+---
+
+## 🙏 Acknowledgments
+
+Special thanks to the community members who reported and helped diagnose the bridge discovery issue, particularly:
+- GitHub user who reported issue #135
+
+---
+
+## 📚 Additional Resources
+
+- **Documentation**: https://alteriom.github.io/painlessMesh/
+- **API Reference**: https://alteriom.github.io/painlessMesh/#/api/doxygen
+- **Examples**: https://alteriom.github.io/painlessMesh/#/tutorials/basic-examples
+- **Bridge Failover Guide**: `examples/bridge_failover/README.md`
+- **Changelog**: `CHANGELOG.md`
+- **Release Guide**: `RELEASE_GUIDE.md`
+
+---
+
+## 🔜 Coming in Future Releases
+
+Stay tuned for upcoming features:
+- Enhanced bridge load balancing
+- Advanced mesh diagnostics
+- Additional monitoring packages
+- Performance optimizations
+
+---
+
+**Released**: November 18, 2025  
+**Version**: 1.8.10  
+**Type**: Patch (Bug Fix)  
+**Compatibility**: 100% backward compatible with v1.8.9

package/docs/releases/RELEASE_NOTES_1.8.9.md

@@ -0,0 +1,213 @@
+# Release Notes: painlessMesh v1.8.9
+
+**Release Date**: November 12, 2025  
+**GitHub**: [Alteriom/painlessMesh](https://github.com/Alteriom/painlessMesh)  
+**Tag**: v1.8.9
+
+---
+
+## 🎯 Summary
+
+Version 1.8.9 fixes critical bridge self-registration issues that prevented bridge nodes from properly tracking themselves in status broadcasts and coordination messages. This resolves the "Known bridges: 0" error reported by @woodlist and improves multi-bridge coordination reliability.
+
+---
+
+## 🐛 Critical Fixes
+
+### Bridge Self-Registration (Type 610 & 613)
+
+**Problem**: Bridge nodes were not tracking themselves in their own bridge lists and coordination maps, causing:
+- Bridge reporting "Known bridges: 0" despite being active
+- "No primary bridge available!" errors
+- Multi-bridge priority selection failures
+
+**Root Cause**: Mesh networks don't loop broadcasts back to sender by design. Nodes receive broadcasts from others but not their own messages, requiring explicit local state management.
+
+**Solutions Implemented**:
+
+#### 1. Bridge Status Broadcasting (Type 610)
+- Added immediate self-registration in `initBridgeStatusBroadcast()` (line ~746)
+  - Bridge calls `updateBridgeStatus()` with own nodeId right after initialization
+- Added self-update in `sendBridgeStatus()` (line ~1192)
+  - Bridge updates own status before each broadcast
+- **Result**: Bridge now appears in its own `knownBridges` list from the start
+
+#### 2. Bridge Coordination (Type 613)
+- Added self-registration in `initBridgeCoordination()` (line ~803)
+  - Bridge adds own priority: `bridgePriorities[this->nodeId] = bridgePriority`
+- Added priority self-update in `sendBridgeCoordination()` (line ~869)
+  - Bridge updates own priority before each broadcast
+- **Result**: Primary bridge selection works correctly with all bridge priorities
+
+**Impact**:
+- ✅ Bridge correctly reports "Known bridges: 1" (or more)
+- ✅ Multi-bridge setups properly select primary bridge
+- ✅ Bridge failover more reliable with complete tracking
+- ✅ Self-tracking pattern consistent across periodic broadcasts
+
+**Files Modified**: `src/arduino/wifi.hpp`
+
+---
+
+## 🔧 Build System
+
+### Docker Compiler Change
+- Switched from clang++ to g++ in Dockerfile
+- Resolves template instantiation crashes during Docker builds
+- Build verification confirms successful compilation
+
+**Files Modified**: `Dockerfile`
+
+---
+
+## 📚 Documentation
+
+### Comprehensive Broadcast Analysis
+Added `COMPREHENSIVE_BROADCAST_ANALYSIS.md` with:
+- Full analysis of all 4 broadcast message types (610, 611, 612, 613)
+- Self-tracking requirements for Type 610 (STATUS) and 613 (COORDINATION)
+- Confirmation that Type 611 (ELECTION) already implements correct pattern
+- Confirmation that Type 612 (TAKEOVER) doesn't require self-tracking
+- Pattern guidelines for future broadcast implementations
+
+---
+
+## 🔬 Technical Details
+
+### Broadcast Message Types Analyzed
+
+| Type | Name | Purpose | Self-Tracking | Status |
+|------|------|---------|---------------|---------|
+| 610 | BRIDGE_STATUS | Periodic health heartbeat | ✅ Required | ✅ Fixed |
+| 611 | BRIDGE_ELECTION | Candidate announcement | ✅ Required | ✅ Already correct |
+| 612 | BRIDGE_TAKEOVER | Role change notification | ❌ Not needed | ✅ No issue |
+| 613 | BRIDGE_COORDINATION | Priority broadcasting | ✅ Required | ✅ Fixed |
+
+### Before vs After
+
+**Before Fix**:
+```
+Bridge Node Output:
+Known bridges: 0
+No primary bridge available!
+Bridge priority: (missing from map)
+```
+
+**After Fix**:
+```
+Bridge Node Output:
+Known bridges: 1
+Primary bridge: 123456 (this node)
+Bridge priority: 100 (correctly tracked)
+```
+
+---
+
+## 🚀 Upgrade Instructions
+
+### For Existing Users
+
+1. **Update Library**:
+   ```bash
+   # Arduino Library Manager
+   Update "Alteriom PainlessMesh" to v1.8.9
+   
+   # PlatformIO
+   lib_deps = AlteriomPainlessMesh@^1.8.9
+   
+   # NPM
+   npm install @alteriom/painlessmesh@1.8.9
+   ```
+
+2. **Rebuild and Deploy**:
+   - No code changes required in your sketches
+   - Fixes are automatic in the library
+   - Rebuild and upload to all bridge nodes
+
+3. **Verify Fix**:
+   - Enable logging: `mesh.setDebugMsgTypes(ERROR | CONNECTION)`
+   - Check bridge status: `mesh.getBridges()` should return count >= 1
+   - Bridge node should log "Known bridges: 1" or more
+
+### Breaking Changes
+**None** - This release is fully backward compatible.
+
+---
+
+## 🧪 Testing
+
+### Validation Performed
+- ✅ Standalone compilation test with g++
+- ✅ Code review of all 4 broadcast message types
+- ✅ Pattern validation across entire codebase
+- ✅ Version consistency check across all package files
+
+### Recommended Testing
+After upgrading, test these scenarios:
+
+1. **Single Bridge**: Deploy and verify bridge reports "Known bridges: 1"
+2. **Multi-Bridge**: Verify primary selection works with all priorities tracked
+3. **Failover**: Disconnect primary bridge, verify secondary promotion works
+4. **Auto-Election**: Test election with no pre-designated bridge
+
+---
+
+## 📖 Related Issues
+
+- Resolves: @woodlist GitHub issue - "Known bridges: 0" despite active bridge
+- Related: Bridge failover improvements (v1.8.6)
+- Related: Bridge discovery timing (v1.8.4)
+
+---
+
+## 📦 Version Information
+
+### Updated Files
+- ✅ `library.properties` → 1.8.9
+- ✅ `library.json` → 1.8.9
+- ✅ `package.json` → 1.8.9
+- ✅ `src/painlessMesh.h` → 1.8.9
+- ✅ `src/AlteriomPainlessMesh.h` → 1.8.9
+- ✅ `CHANGELOG.md` → Entry added for 1.8.9
+
+### Package Hashes
+Will be generated automatically during release process.
+
+---
+
+## 👥 Contributors
+
+- **Alteriom Team** - Core development and maintenance
+- **@woodlist** - Issue reporting and testing
+- **GitHub Copilot** - Code analysis and documentation
+
+---
+
+## 📝 Next Steps
+
+1. **Create Git Tag**: `git tag -a v1.8.9 -m "release: v1.8.9 - Bridge self-registration fixes"`
+2. **Push Tag**: `git push origin v1.8.9`
+3. **GitHub Release**: Create release from tag with these notes
+4. **Publish Packages**:
+   - Arduino Library Manager (automatic)
+   - PlatformIO (automatic)
+   - NPM: `npm publish`
+
+---
+
+## 📄 License
+
+LGPL-3.0 - See [LICENSE](LICENSE) file for details
+
+---
+
+## 🔗 Links
+
+- **Repository**: https://github.com/Alteriom/painlessMesh
+- **Documentation**: https://alteriom.github.io/painlessMesh/
+- **Issues**: https://github.com/Alteriom/painlessMesh/issues
+- **NPM Package**: https://www.npmjs.com/package/@alteriom/painlessmesh
+
+---
+
+*For detailed technical analysis, see [COMPREHENSIVE_BROADCAST_ANALYSIS.md](COMPREHENSIVE_BROADCAST_ANALYSIS.md)*

package/docs/releases/RELEASE_SUMMARY_1.8.10.md

@@ -0,0 +1,193 @@
+# Release Summary: v1.8.10
+
+**Version**: 1.8.10  
+**Release Date**: November 18, 2025  
+**Type**: Patch Release (Bug Fix)  
+**Status**: ✅ Ready for Release
+
+---
+
+## 📝 Quick Summary
+
+Version 1.8.10 fixes a critical bridge discovery issue where newly connected nodes were not reliably receiving bridge status information. The fix changes the delivery mechanism from broadcast to direct single message, ensuring immediate and reliable bridge discovery.
+
+---
+
+## 🎯 What Changed
+
+### Single Bug Fix
+- **Bridge Status Discovery** - Fixed newly connected nodes not receiving bridge status
+  - Changed from broadcast (`routing=2`) to direct single message (`routing=1`)
+  - Added 500ms connection stability delay
+  - Nodes now discover bridges within 500ms (previously up to 30 seconds)
+  - Resolves GitHub issue #135
+
+---
+
+## 📦 Files Updated
+
+### Version Files (8 files)
+✅ `library.properties` → 1.8.10  
+✅ `library.json` → 1.8.10  
+✅ `package.json` → 1.8.10  
+✅ `src/painlessMesh.h` → 1.8.10 (date: 2025-11-18)  
+✅ `src/AlteriomPainlessMesh.h` → 1.8.10 (version defines)  
+✅ `CHANGELOG.md` → Added [1.8.10] entry  
+✅ `RELEASE_NOTES_1.8.10.md` → Created  
+✅ `RELEASE_CHECKLIST_1.8.10.md` → Created
+
+### Source Code
+- `src/arduino/wifi.hpp` - Bridge status delivery fix (line ~809)
+
+---
+
+## ✅ Version Consistency Verification
+
+All version numbers are consistent across files:
+
+```
+library.properties: 1.8.10
+library.json: 1.8.10
+package.json: 1.8.10
+src/painlessMesh.h: 1.8.10
+src/AlteriomPainlessMesh.h: 1.8.10
+CHANGELOG.md: [1.8.10] - 2025-11-18
+```
+
+---
+
+## 🚀 Release Steps
+
+### Next Steps (To be performed by release manager)
+
+1. **Review and Merge PR**
+   ```bash
+   # Review all changes in the PR
+   # Merge to main branch when approved
+   ```
+
+2. **Trigger Release** (Automatic via GitHub Actions)
+   ```bash
+   # Push to main branch triggers automated release
+   git push origin main
+   
+   # Or manually tag if needed:
+   git tag -a v1.8.10 -m "release: v1.8.10 - Bridge status discovery fix"
+   git push origin v1.8.10
+   ```
+
+3. **Automated Publication**
+   - ✅ GitHub Release created automatically
+   - ✅ NPM package published automatically
+   - ✅ GitHub Packages updated automatically
+   - ✅ PlatformIO registry published automatically
+   - ✅ GitHub Wiki synchronized automatically
+
+4. **Manual Verification** (After automation completes)
+   - Check GitHub Release: https://github.com/Alteriom/painlessMesh/releases
+   - Verify NPM: `npm view @alteriom/painlessmesh@1.8.10`
+   - Confirm PlatformIO: https://registry.platformio.org/libraries/alteriom/painlessMesh
+   - Arduino Library Manager: Will auto-index within 24-48 hours
+
+---
+
+## 📋 Documentation Provided
+
+### Release Documentation
+1. **RELEASE_NOTES_1.8.10.md**
+   - Comprehensive release notes with technical details
+   - Upgrade guide and migration instructions
+   - Testing recommendations
+   - Performance characteristics
+
+2. **RELEASE_CHECKLIST_1.8.10.md**
+   - Complete pre-release checklist (all items completed)
+   - Release process step-by-step
+   - Post-release tasks
+   - Verification commands
+   - Rollback procedures
+
+3. **CHANGELOG.md**
+   - Updated with [1.8.10] entry
+   - Detailed fix description
+   - References GitHub issue #135
+
+4. **RELEASE_SUMMARY_1.8.10.md** (This file)
+   - Quick overview for release manager
+   - Status summary
+   - Next steps
+
+---
+
+## 🎯 Impact Assessment
+
+### User Impact
+- **Positive**: Immediate and reliable bridge discovery for new nodes
+- **Risk**: Very low - focused bug fix with no API changes
+- **Compatibility**: 100% backward compatible
+
+### Upgrade Recommendation
+- **Immediate**: For systems with frequent node connections
+- **Standard**: For production deployments
+- **Optional**: For stable networks with infrequent changes
+
+---
+
+## 📊 Quality Metrics
+
+### Code Quality
+- ✅ Focused, targeted fix (single file, specific function)
+- ✅ No breaking changes
+- ✅ Backward compatible
+- ✅ Well-documented with comments
+
+### Documentation Quality
+- ✅ Comprehensive release notes
+- ✅ Detailed checklist
+- ✅ Updated changelog
+- ✅ Version consistency verified
+
+### Testing
+- ✅ Fix addresses reported issue
+- ✅ Solution validated
+- ✅ No regression risk identified
+
+---
+
+## 🔍 Related Issues
+
+- **Resolves**: GitHub issue #135 - "The latest fix does not work"
+- **Previous Related**: Issues #117, #108, #89 (bridge discovery improvements)
+
+---
+
+## 📞 Support & Resources
+
+- **GitHub**: https://github.com/Alteriom/painlessMesh
+- **Documentation**: https://alteriom.github.io/painlessMesh/
+- **NPM**: https://www.npmjs.com/package/@alteriom/painlessmesh
+- **PlatformIO**: https://registry.platformio.org/libraries/alteriom/painlessMesh
+- **Issues**: https://github.com/Alteriom/painlessMesh/issues
+
+---
+
+## ✨ Summary for Announcement
+
+> **AlteriomPainlessMesh v1.8.10 Released!**
+>
+> This patch release fixes a critical bridge discovery issue where newly connected nodes were not reliably receiving bridge status information. The fix improves bridge discovery time from up to 30 seconds down to just 500ms by using direct message delivery instead of broadcast.
+>
+> **Key Improvement**: Nodes now discover bridges immediately upon connection
+>
+> **Compatibility**: 100% backward compatible - just update and deploy!
+>
+> **Install**:
+> - Arduino: Update via Library Manager
+> - PlatformIO: `lib_deps = alteriom/AlteriomPainlessMesh@^1.8.10`
+> - NPM: `npm install @alteriom/painlessmesh@1.8.10`
+
+---
+
+**Prepared by**: GitHub Copilot Documentation Specialist  
+**Date**: November 18, 2025  
+**Status**: ✅ All documentation complete and ready for release