@alteriom/painlessmesh 1.8.6 → 1.8.7

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.8.7] - 2025-11-12
+
+### Fixed
+
+- **Bridge Internet Connectivity Detection (Bridge_fallover)** - Fixed incorrect internet status reporting
+  - Bridge nodes now properly check for actual Internet connectivity, not just WiFi connection
+  - Check verifies both `WiFi.status() == WL_CONNECTED` AND valid gateway IP (not 0.0.0.0)
+  - **Before**: Bridge connected to router → reports "Internet: NO" even when router has Internet
+  - **After**: Bridge connected to router with valid gateway → correctly reports "Internet: YES"
+  - Fixes `hasInternetConnection()` returning false positives on regular nodes
+  - Core fix in `src/arduino/wifi.hpp` line 1188-1192
+  - Updated bridge_failover/README.md with troubleshooting guidance
+
+- **Version Documentation Consistency** - Updated header file version comments to match library version
+  - Updated `painlessMesh.h` header comment from version 1.8.4 to 1.8.6
+  - Updated `AlteriomPainlessMesh.h` version defines from 1.6.1 to 1.8.6
+  - Header file version comments now accurately reflect the current library version
+  - Clarified that version comments in headers indicate documentation update, not file-specific versioning
+  - Resolves user confusion about whether files have been modified since specific versions
+
 ## [1.8.6] - 2025-11-12
 
 ### Fixed

package/README.md

@@ -595,6 +595,8 @@ These are the message types used by applications built on painlessMesh:
 ## Getting Help
 
 - **[FAQ](docs/troubleshooting/faq.md)** - Common questions and solutions
+- **[Version Numbers FAQ](docs/FAQ_VERSION_NUMBERS.md)** - Understanding version numbers in header files
+- **[Version Management Guide](docs/VERSION_MANAGEMENT.md)** - Complete versioning documentation
 - **[GitHub Issues](https://github.com/Alteriom/painlessMesh/issues)** - Bug reports and feature requests  
 - **[Community Forum](https://groups.google.com/forum/#!forum/painlessmesh-user)** - Community support
 - **[API Documentation](http://painlessmesh.gitlab.io/painlessMesh/index.html)** - Generated API docs

package/RELEASE_GUIDE.md

@@ -13,11 +13,15 @@ This document provides comprehensive instructions for releasing new versions of
 # 2. Update CHANGELOG.md with your changes
 # Add your changes under the new version section
 
-# 3. Run the Release Agent to validate readiness
+# 3. Update header file version comments (recommended)
+# Edit src/painlessMesh.h and src/AlteriomPainlessMesh.h
+# Update @version comments to match the new library version
+
+# 4. Run the Release Agent to validate readiness
 ./scripts/release-agent.sh
 
-# 4. If all checks pass, commit and trigger release
-git add library.properties library.json package.json CHANGELOG.md
+# 5. If all checks pass, commit and trigger release
+git add library.properties library.json package.json CHANGELOG.md src/*.h
 git commit -m "release: v1.7.9 - Brief description"
 git push origin main
 ```
@@ -49,6 +53,8 @@ git push origin main
 
 ### Version Management
 
+> **📖 For detailed information about version management, see [VERSION_MANAGEMENT.md](docs/VERSION_MANAGEMENT.md)**
+
 **File Consistency**: All three files must have matching versions:
 
 ```properties

package/docs/FAQ_VERSION_NUMBERS.md

@@ -0,0 +1,152 @@
+# FAQ: Version Numbers in Header Files
+
+## ❓ Question: Does the version in `painlessMesh.h` mean the file hasn't been altered since that version?
+
+### Short Answer
+
+**No.** The version comment in header files indicates the library version when the documentation was last reviewed, not when the file was last modified.
+
+### Detailed Explanation
+
+When you see this in `painlessMesh.h`:
+
+```cpp
+/**
+ * @file painlessMesh.h
+ * @version 1.8.7
+ * @date 2025-11-12
+ */
+```
+
+This means:
+- ✅ The library version is 1.8.7
+- ✅ The header documentation was reviewed as of version 1.8.7
+- ❌ It does NOT mean the file hasn't changed since 1.8.7
+
+### Why This Can Be Confusing
+
+During active development, code files may be modified in multiple releases, but documentation comments might not be updated every time. This led to the situation where:
+
+- `library.properties` showed version 1.8.6
+- `library.json` showed version 1.8.6
+- `package.json` showed version 1.8.6
+- But `painlessMesh.h` header comment still showed 1.8.4
+
+This created confusion about whether the file had been modified in versions 1.8.5 and 1.8.6.
+
+### How to Find When a File Was Last Modified
+
+Use Git to see the actual modification history:
+
+```bash
+# See all commits that modified a file
+git log --oneline -- src/painlessMesh.h
+
+# See when a file was last modified
+git log -1 --format="%ai %an" -- src/painlessMesh.h
+
+# See detailed changes to a file
+git log -p -- src/painlessMesh.h
+```
+
+### Where to Find the Official Library Version
+
+The official library version is always defined in these three files (and they must match):
+
+1. **`library.properties`** - Arduino Library Manager
+   ```properties
+   version=1.8.7
+   ```
+
+2. **`library.json`** - PlatformIO Registry
+   ```json
+   "version": "1.8.7"
+   ```
+
+3. **`package.json`** - NPM Package
+   ```json
+   "version": "1.8.7"
+   ```
+
+### Best Practice Going Forward
+
+As of version 1.8.7, we've established a best practice:
+
+1. **Update header version comments during releases** to keep them synchronized with the library version
+2. **Refer to VERSION_MANAGEMENT.md** for complete versioning guidelines
+3. **Use Git for file history** to track actual modifications
+4. **Check library.properties** for the official version number
+
+### Complete Version Management Documentation
+
+For comprehensive information about version management in this library, see:
+
+**📖 [VERSION_MANAGEMENT.md](VERSION_MANAGEMENT.md)**
+
+This document covers:
+- Official version file locations
+- Header comment meanings and purpose
+- How to track file modifications
+- Version update workflow
+- Best practices for contributors
+
+## Related Questions
+
+### Q: Why were the header versions out of sync?
+
+**A:** During rapid development cycles, header documentation comments were not updated every release. We've now established a process to keep them synchronized.
+
+### Q: Will this happen again?
+
+**A:** We've updated the release process (see RELEASE_GUIDE.md) to include header version updates as a standard step, and created comprehensive documentation to prevent future confusion.
+
+### Q: What about other version numbers I see in the code?
+
+**A:** If you see version numbers in implementation files (`.cpp`, `.hpp`), those should generally be removed. Version information should only be in:
+- Official version files (library.properties, library.json, package.json)
+- Header documentation comments (as library version references)
+- CHANGELOG.md (for release history)
+
+### Q: How do I know if my library is up to date?
+
+**A:** Check your installed version against the latest release:
+
+**Arduino IDE:**
+```
+Sketch → Include Library → Manage Libraries → Search "AlteriomPainlessMesh"
+```
+
+**PlatformIO:**
+```bash
+pio pkg show alteriom/AlteriomPainlessMesh
+```
+
+**NPM:**
+```bash
+npm view @alteriom/painlessmesh version
+```
+
+**GitHub:**
+Visit https://github.com/Alteriom/painlessMesh/releases
+
+## Summary
+
+| File Location | Purpose | Meaning |
+|---------------|---------|---------|
+| `library.properties` | Official version | **Source of truth** for library version |
+| `library.json` | Official version | **Source of truth** for library version |
+| `package.json` | Official version | **Source of truth** for library version |
+| Header comments (`@version`) | Documentation | Library version when docs were reviewed |
+| Git history (`git log`) | File tracking | **Actual modification history** |
+| `CHANGELOG.md` | Release history | Human-readable version changes |
+
+**Remember:** Always check `library.properties` for the official library version, and use `git log` to see actual file modification history.
+
+---
+
+**See Also:**
+- [VERSION_MANAGEMENT.md](VERSION_MANAGEMENT.md) - Complete version management guide
+- [RELEASE_GUIDE.md](../RELEASE_GUIDE.md) - Release process documentation
+- [CHANGELOG.md](../CHANGELOG.md) - Release history
+
+**Last Updated:** November 12, 2025

package/docs/QUICK_REFERENCE_VERSIONING.md

@@ -0,0 +1,127 @@
+# Quick Reference: Version Management
+
+## 🎯 Where to Find Version Information
+
+| File | Purpose | When to Update |
+|------|---------|----------------|
+| `library.properties` | **Official Arduino version** | Every release |
+| `library.json` | **Official PlatformIO version** | Every release |
+| `package.json` | **Official NPM version** | Every release |
+| `src/painlessMesh.h` | Header documentation | Every release (recommended) |
+| `src/AlteriomPainlessMesh.h` | Version defines | Every release (recommended) |
+| `CHANGELOG.md` | Release history | Every release |
+
+## 🚀 Quick Release Checklist
+
+```bash
+# 1. Bump version
+./scripts/bump-version.sh patch  # or minor, major
+
+# 2. Update CHANGELOG.md
+# Move [Unreleased] items to new [X.Y.Z] section
+
+# 3. Update header files
+# Edit src/painlessMesh.h - update @version comment
+# Edit src/AlteriomPainlessMesh.h - update version defines
+
+# 4. Validate
+./scripts/release-agent.sh
+
+# 5. Commit and push
+git add library.properties library.json package.json CHANGELOG.md src/*.h
+git commit -m "release: vX.Y.Z - Brief description"
+git push origin main
+```
+
+## 📝 Version Comment Format
+
+### In `src/painlessMesh.h`:
+```cpp
+/**
+ * @file painlessMesh.h
+ * @brief Main header file for Alteriom painlessMesh library
+ * 
+ * @version 1.8.7      // ← Library version
+ * @date 2025-11-12    // ← Current date
+ * 
+ * painlessMesh is a user-friendly library...
+ */
+```
+
+### In `src/AlteriomPainlessMesh.h`:
+```cpp
+/**
+ * @brief AlteriomPainlessMesh library version information
+ */
+#define ALTERIOM_PAINLESS_MESH_VERSION "1.8.7"
+#define ALTERIOM_PAINLESS_MESH_VERSION_MAJOR 1
+#define ALTERIOM_PAINLESS_MESH_VERSION_MINOR 8
+#define ALTERIOM_PAINLESS_MESH_VERSION_PATCH 7
+```
+
+## 🔍 Quick Commands
+
+### Check current version:
+```bash
+grep "version=" library.properties
+```
+
+### Verify all versions match:
+```bash
+grep -E "version|VERSION" library.properties library.json package.json src/*.h
+```
+
+### See file modification history:
+```bash
+git log --oneline -- src/painlessMesh.h
+```
+
+### See last modification date:
+```bash
+git log -1 --format="%ai" -- src/painlessMesh.h
+```
+
+## ❓ Common Questions
+
+**Q: What version is the library?**  
+→ Check `library.properties`, line 2
+
+**Q: When was a file last modified?**  
+→ Use `git log -1 -- path/to/file`
+
+**Q: Why is header version different from library.properties?**  
+→ Header comments may not have been updated. Trust `library.properties`.
+
+**Q: Do I need to update header versions?**  
+→ Recommended but not critical. Update during releases.
+
+## 📚 Full Documentation
+
+For complete information:
+- **[VERSION_MANAGEMENT.md](VERSION_MANAGEMENT.md)** - Complete guide
+- **[FAQ_VERSION_NUMBERS.md](FAQ_VERSION_NUMBERS.md)** - Common questions
+- **[RELEASE_GUIDE.md](../RELEASE_GUIDE.md)** - Release process
+
+## 🎓 Key Principles
+
+1. **Single Source of Truth**: `library.properties` / `library.json` / `package.json`
+2. **Header Comments**: Documentation only, not source of truth
+3. **Git History**: Actual record of file modifications
+4. **Synchronize on Release**: Keep all versions aligned during releases
+5. **When in Doubt**: Check `library.properties`
+
+---
+
+**Quick Access:**
+```bash
+# View this file
+cat docs/QUICK_REFERENCE_VERSIONING.md
+
+# View full guide
+cat docs/VERSION_MANAGEMENT.md
+
+# View FAQ
+cat docs/FAQ_VERSION_NUMBERS.md
+```
+
+**Last Updated:** November 12, 2025

package/docs/VERSION_MANAGEMENT.md

@@ -0,0 +1,213 @@
+# Version Management in AlteriomPainlessMesh
+
+This document explains how versioning works in the AlteriomPainlessMesh library and clarifies common questions about version numbers in different files.
+
+## 📋 Version Number Locations
+
+The library version is maintained in multiple files across the repository:
+
+### 1. **Official Version Files** (Source of Truth)
+
+These files define the official library version:
+
+- **`library.properties`** - Arduino Library Manager version
+- **`library.json`** - PlatformIO Library Registry version  
+- **`package.json`** - NPM package version
+
+**All three files must always have the same version number.**
+
+### 2. **Header File Version Comments** (Documentation)
+
+These are **documentation comments** that indicate when the header file documentation was last updated:
+
+- **`src/painlessMesh.h`** - `@version` in header comment
+- **`src/AlteriomPainlessMesh.h`** - `ALTERIOM_PAINLESS_MESH_VERSION` defines
+
+**Important:** Version numbers in header file comments reflect the overall library version at the time the header was documented, not file-specific versioning.
+
+## ❓ Common Questions
+
+### Q: Does the version in `painlessMesh.h` mean the file hasn't changed since that version?
+
+**A: No.** The version comment in header files indicates the library version when the header documentation was last reviewed/updated, not the last time the file was modified.
+
+**Example:**
+```cpp
+/**
+ * @file painlessMesh.h
+ * @version 1.8.7
+ * @date 2025-11-12
+ */
+```
+
+This means:
+- ✅ The library version is 1.8.7
+- ✅ The header documentation is current as of version 1.8.7
+- ❌ It does NOT mean the file hasn't been modified since 1.8.7
+
+### Q: Why might header version comments be out of sync?
+
+**A:** During rapid development, header file documentation may not be updated every release. The comments are updated when:
+- Significant API changes are made
+- Documentation requires updating
+- Major version milestones are reached
+- Version consistency review is performed
+
+### Q: Which version number should I trust?
+
+**A:** Always refer to the official version files:
+1. `library.properties` - Official Arduino version
+2. `library.json` - Official PlatformIO version
+3. `package.json` - Official NPM version
+4. GitHub releases - Tagged release versions
+
+Header file comments are for documentation reference only.
+
+## 🔄 Version Update Process
+
+### When Releasing a New Version:
+
+1. **Update Official Version Files** (required)
+   ```bash
+   ./scripts/bump-version.sh patch  # or minor, major
+   ```
+   This updates: `library.properties`, `library.json`, `package.json`
+
+2. **Update CHANGELOG.md** (required)
+   - Move items from `[Unreleased]` to new version section
+   - Add release date
+
+3. **Update Header File Comments** (recommended)
+   - Update `@version` in `src/painlessMesh.h`
+   - Update version defines in `src/AlteriomPainlessMesh.h`
+
+4. **Commit and Tag** (required)
+   ```bash
+   git commit -m "release: vX.Y.Z - Brief description"
+   git push origin main
+   ```
+   GitHub Actions will automatically create the tag.
+
+## 📝 Version Comment Best Practices
+
+### In Header Files:
+
+**Good Practice:**
+```cpp
+/**
+ * @file painlessMesh.h
+ * @brief Main header file for Alteriom painlessMesh library
+ * 
+ * @version 1.8.7
+ * @date 2025-11-12
+ * 
+ * painlessMesh is a user-friendly library for creating mesh networks...
+ */
+```
+
+**What This Means:**
+- The library is at version 1.8.7
+- Header documentation was reviewed/updated on 2025-11-12
+- Always synchronized with library version during releases
+
+### In Implementation Files:
+
+Implementation files (`.cpp`, `.hpp`) typically do not need version comments. Version information in these files can be misleading and is unnecessary since:
+- Git history tracks all changes with timestamps
+- Version is centrally managed in the official version files
+- Per-file versioning creates maintenance overhead
+
+## 🎯 Version Management Workflow
+
+### Developer Workflow:
+
+1. **Check Current Version**
+   ```bash
+   grep "version=" library.properties
+   ```
+
+2. **Make Changes**
+   - Implement features/fixes
+   - Update documentation as needed
+   - Add entries to CHANGELOG.md under `[Unreleased]`
+
+3. **Prepare Release**
+   ```bash
+   ./scripts/release-agent.sh  # Validate release readiness
+   ./scripts/bump-version.sh patch  # Update version
+   ```
+
+4. **Update Documentation**
+   - Review and update header file version comments
+   - Ensure CHANGELOG.md has the new version section
+   - Verify all documentation references are current
+
+5. **Release**
+   ```bash
+   git add library.properties library.json package.json CHANGELOG.md src/*.h
+   git commit -m "release: v1.8.7 - Brief description"
+   git push origin main
+   ```
+
+### Automated Process:
+
+GitHub Actions automatically handles:
+- ✅ Git tag creation
+- ✅ GitHub release with notes
+- ✅ NPM publishing
+- ✅ PlatformIO registry update
+- ✅ Documentation deployment
+
+## 🔍 Version History Tracking
+
+### To Check File History:
+
+Use Git to see actual file modification history:
+
+```bash
+# See all commits that modified a file
+git log --oneline -- src/painlessMesh.h
+
+# See detailed changes to a file
+git log -p -- src/painlessMesh.h
+
+# See when a file was last modified
+git log -1 --format="%ai %an" -- src/painlessMesh.h
+```
+
+### To Check Version History:
+
+```bash
+# List all version tags
+git tag -l "v*"
+
+# See changes in a specific version
+git show v1.8.7
+
+# Compare two versions
+git diff v1.8.6..v1.8.7
+```
+
+## 📚 Related Documentation
+
+- **[CHANGELOG.md](../CHANGELOG.md)** - Complete version history with changes
+- **[RELEASE_GUIDE.md](../RELEASE_GUIDE.md)** - Detailed release process
+- **[GitHub Releases](https://github.com/Alteriom/painlessMesh/releases)** - Official release notes
+
+## 🎓 Summary
+
+**Key Takeaways:**
+
+1. **Official version** = `library.properties` / `library.json` / `package.json`
+2. **Header comments** = Documentation reference, not file-specific versions
+3. **Git history** = Actual source of truth for file modifications
+4. **CHANGELOG.md** = Human-readable version history
+5. **GitHub releases** = Tagged versions with release notes
+
+**When in doubt:** Check `library.properties` for the official library version, and use `git log` to see actual file modification history.
+
+---
+
+**Version Management Process Owner:** @Alteriom  
+**Last Updated:** 2025-11-12  
+**Document Version:** 1.0

package/docs/releases/ANNOUNCEMENT_v1.8.6.md

@@ -0,0 +1,63 @@
+# 🎉 painlessMesh v1.8.6 Released!
+
+We're excited to announce **painlessMesh v1.8.6** - a patch release that fixes a critical bridge failover issue.
+
+## 🔧 What's Fixed
+
+**Bridge Auto-Election** - Meshes now automatically elect a bridge when all nodes start without a designated initial bridge. Previously, the network would remain bridgeless indefinitely in this scenario.
+
+### The Problem
+```
+--- Bridge Status ---
+I am bridge: NO
+Internet available: NO  
+Known bridges: 0
+No primary bridge available! ❌
+```
+
+### The Solution
+After a 60-second startup grace period, the mesh automatically detects the absence of a bridge and triggers an election. The node with the best WiFi signal (RSSI) becomes the bridge. ✅
+
+## 🚀 Key Features
+
+- **Automatic Recovery** - No manual intervention needed
+- **Smart Timing** - 60s grace period for network stabilization
+- **Randomized Delays** - Prevents election conflicts
+- **Fully Backward Compatible** - Existing setups work unchanged
+
+## 📦 Installation
+
+```bash
+# PlatformIO
+pio pkg update alteriom/AlteriomPainlessMesh@^1.8.6
+
+# NPM
+npm update @alteriom/painlessmesh
+
+# Arduino Library Manager
+Search for "AlteriomPainlessMesh" and update
+```
+
+## 🎯 Perfect For
+
+✅ Dynamic mesh networks with changing topologies  
+✅ IoT deployments requiring automatic bridge recovery  
+✅ Development environments without pre-configured bridges  
+✅ Fault-tolerant systems needing zero-touch setup  
+
+## 🙏 Thanks
+
+Special thanks to **@woodlist** for reporting the issue and providing detailed logs!
+
+## 📚 Learn More
+
+- 📖 [Full Release Notes](https://github.com/Alteriom/painlessMesh/blob/main/docs/releases/RELEASE_NOTES_v1.8.6.md)
+- 🔗 [GitHub Release](https://github.com/Alteriom/painlessMesh/releases/tag/v1.8.6)
+- 📝 [Changelog](https://github.com/Alteriom/painlessMesh/blob/main/CHANGELOG.md)
+- 💻 [Bridge Failover Example](https://github.com/Alteriom/painlessMesh/tree/main/examples/bridge_failover)
+
+---
+
+**Upgrade today and enjoy seamless bridge failover! 🎊**
+
+#painlessMesh #ESP32 #ESP8266 #IoT #MeshNetwork #Arduino #Alteriom