@alteriom/painlessmesh 1.8.10 → 1.8.12

package/CHANGELOG.md

@@ -7,23 +7,82 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.8.12] - 2025-11-19
+
+### Changed
+
+- **Documentation Updates** - Comprehensive documentation improvements
+  - Updated all documentation to reflect current library state
+  - Improved code examples and usage instructions
+  - Enhanced API reference documentation
+  - Verified all links and references
+  - Merged via PRs #152, #153
+
+### Fixed
+
+- **Code Quality** - Resolved linting and formatting issues
+  - Fixed clang-format compliance across codebase
+  - Ensured prettier formatting consistency
+  - Improved code quality and maintainability
+
+## [1.8.11] - 2025-11-18
+
+### Fixed
+
+- **Bridge Discovery Race Condition** - Fixed routing table timing issue that prevented reliable bridge status delivery
+  - **Root Cause**: Bridge was sending status messages before routing tables were fully established after connection
+  - Changed from `newConnectionCallback` to `changedConnectionCallbacks` for routing table readiness
+  - Ensures routing tables are properly configured before attempting to send bridge status
+  - Bridge now waits for routing table convergence before sending status messages to new nodes
+  - **Before Fix**: Messages sent too early could fail to reach destination due to incomplete routing
+  - **After Fix**: Bridge status reliably delivered once routing is properly established
+  - Core fix in `src/arduino/wifi.hpp` - uses connection change callbacks instead of new connection callbacks
+  - More robust than timing-based delays (previous 500ms approach)
+  - Resolves GitHub issue #142
+  - Merged via PR #142
+
+- **Windows MSVC Compilation Compatibility** - Fixed access modifier issues for Windows builds
+  - MSVC compiler does not grant friend status to lambdas inside friend functions
+  - Changed semaphore methods (`semaphoreTake()`, `semaphoreGive()`) from protected to public
+  - Changed `droppedConnectionCallbacks` access for lambda compatibility
+  - **Impact**: Library now compiles successfully on Windows with MSVC compiler
+  - **Affected Platforms**: Windows desktop builds, Visual Studio projects
+  - Core fix in `src/painlessmesh/mesh.hpp` line ~2060
+  - Also updated access modifiers in `buffer.hpp`, `ntp.hpp`, and `router.hpp` for consistency
+  - No functional changes - purely compatibility improvements
+  - Maintains full compatibility with GCC/Clang compilers
+
+- **Code Security Improvements** - Fixed multiple code scanning alerts
+  - Fixed wrong type of arguments to formatting functions (alerts #3, #5)
+  - Fixed potentially overrunning write with float to string conversion (alert #2)
+  - Fixed use of potentially dangerous function (alert #1)
+  - Improved type safety in string formatting operations
+  - Enhanced buffer safety for float conversions
+  - Merged via PRs #144, #145, #146, #147
+
+### Changed
+
+- **CI/CD Reliability** - Added retry logic for Arduino package index updates
+  - Handles transient network failures during package publication
+  - Improves reliability of automated release workflow
+  - Reduces false failures in CI pipeline
+
 ## [1.8.10] - 2025-11-18
 
 ### Fixed
 
-- **Bridge Status Discovery - Direct Messaging** - Fixed newly connected nodes not receiving bridge status
-  - **Root Cause**: Broadcast messages were not reaching newly connected nodes reliably
-    - Time sync (NTP) was interfering with bridge discovery
-    - Broadcast routing may not be fully established immediately after connection
-  - **Solution**: Send bridge status directly to new node using `sendSingle()`
-    - Changed from broadcast (`routing=2`) to single (`routing=1`) 
-    - Minimal 500ms delay (just for connection stability)
-    - Direct targeted delivery ensures message reaches the new node
-    - Time sync no longer affects bridge discovery
-  - Location: `src/arduino/wifi.hpp` line ~809 in `initBridgeStatusBroadcast()`
-  - Impact: Nodes discover bridges immediately (within 500ms) after connecting
-  - Backward compatible: No API changes, internal delivery mechanism improved
+- **Bridge Status Discovery - Direct Messaging** - Fixed newly connected nodes not receiving bridge status reliably
+  - Changed bridge status delivery mechanism from broadcast to direct single message
+  - Bridge now sends status directly to newly connected nodes using `sendSingle()` (routing=1)
+  - Added minimal 500ms delay for connection stability before sending status
+  - **Root Cause**: Broadcast routing may not be established immediately after connection; time sync (NTP) operations were interfering with bridge discovery
+  - **Before Fix**: Nodes could wait up to 30 seconds for bridge status via periodic broadcast; "No primary bridge available" errors
+  - **After Fix**: Nodes discover bridges within 500ms of connection; reliable bridge discovery regardless of NTP sync activity
+  - Direct targeted delivery ensures message reaches new node immediately
+  - Core fix in `src/arduino/wifi.hpp` line ~809 in `initBridgeStatusBroadcast()`
   - Resolves GitHub issue #135 "The latest fix does not work"
+  - 100% backward compatible - no API changes
+  - **Note**: Further improved in v1.8.11 with routing table readiness detection
 
 ## [1.8.9] - 2025-11-12
 

package/DOCUMENTATION_INDEX.md

@@ -0,0 +1,146 @@
+# AlteriomPainlessMesh Documentation Index
+
+Complete guide to finding documentation in the AlteriomPainlessMesh library.
+
+## Quick Links
+
+- 🌐 **[Online Documentation](https://alteriom.github.io/painlessMesh/)** - Interactive documentation website
+- 📖 **[API Reference](https://alteriom.github.io/painlessMesh/#/api/doxygen)** - Complete API documentation
+- 🎯 **[Examples](https://alteriom.github.io/painlessMesh/#/tutorials/basic-examples)** - Code examples and tutorials
+
+## Core Documentation
+
+### Getting Started
+- **[README.md](README.md)** - Project overview, features, and quick start
+- **[docs/getting-started/quickstart.md](docs/getting-started/quickstart.md)** - Quick start guide
+- **[docs/getting-started/installation.md](docs/getting-started/installation.md)** - Installation instructions
+- **[docs/getting-started/first-mesh.md](docs/getting-started/first-mesh.md)** - Your first mesh network
+
+### Release Information
+- **[CHANGELOG.md](CHANGELOG.md)** - Complete version history
+- **[RELEASE_GUIDE.md](RELEASE_GUIDE.md)** - Release process for maintainers
+- **[RELEASE_NOTES_1.8.12.md](RELEASE_NOTES_1.8.12.md)** - Latest release notes
+- **[RELEASE_CHECKLIST_1.8.12.md](RELEASE_CHECKLIST_1.8.12.md)** - Release checklist
+
+### Contributing
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** - How to contribute to the project
+- **[LICENSE](LICENSE)** - LGPL-3.0 license terms
+
+## Technical Documentation
+
+### Alteriom Extensions
+- **[docs/alteriom/overview.md](docs/alteriom/overview.md)** - Alteriom extensions overview
+- **[examples/alteriom/README.md](examples/alteriom/README.md)** - Alteriom package documentation
+- **[examples/alteriom/alteriom_sensor_package.hpp](examples/alteriom/alteriom_sensor_package.hpp)** - Package definitions with extensive inline documentation
+
+### MQTT Integration
+- **[docs/MQTT_BRIDGE_COMMANDS.md](docs/MQTT_BRIDGE_COMMANDS.md)** - MQTT command API
+- **[docs/MQTT_BRIDGE_IMPLEMENTATION_SUMMARY.md](docs/MQTT_BRIDGE_IMPLEMENTATION_SUMMARY.md)** - Implementation details
+- **[docs/MQTT_SCHEMA_COMPLIANCE.md](docs/MQTT_SCHEMA_COMPLIANCE.md)** - Schema validation
+- **[docs/OTA_COMMANDS_REFERENCE.md](docs/OTA_COMMANDS_REFERENCE.md)** - OTA update commands
+
+### Advanced Features
+- **[docs/MESH_TOPOLOGY_GUIDE.md](docs/MESH_TOPOLOGY_GUIDE.md)** - Network topology reporting
+- **[docs/BRIDGE_FAILOVER.md](docs/BRIDGE_FAILOVER.md)** - Bridge failover documentation
+- **[docs/BRIDGE_HEALTH_MONITORING.md](docs/BRIDGE_HEALTH_MONITORING.md)** - Bridge health monitoring
+- **[BRIDGE_TO_INTERNET.md](BRIDGE_TO_INTERNET.md)** - Connecting mesh to internet
+
+### Development
+- **[docs/API_DESIGN_GUIDELINES.md](docs/API_DESIGN_GUIDELINES.md)** - API design patterns
+- **[docs/VERSION_MANAGEMENT.md](docs/VERSION_MANAGEMENT.md)** - Version management guide
+- **[docs/development/DOCKER_TESTING.md](docs/development/DOCKER_TESTING.md)** - Docker testing guide
+- **[docs/development/TESTING_SUMMARY.md](docs/development/TESTING_SUMMARY.md)** - Test suite overview
+- **[docs/development/ARDUINO_COMPLIANCE_SUMMARY.md](docs/development/ARDUINO_COMPLIANCE_SUMMARY.md)** - Arduino standards
+
+### Phase Documentation
+- **[docs/PHASE1_GUIDE.md](docs/PHASE1_GUIDE.md)** - Phase 1 features (v1.6.x)
+- **[docs/PHASE2_GUIDE.md](docs/PHASE2_GUIDE.md)** - Phase 2 features (v1.7.x+)
+- **[docs/releases/FEATURE_HISTORY.md](docs/releases/FEATURE_HISTORY.md)** - Consolidated feature history
+
+## Example Code
+
+### Basic Examples
+- **[examples/basic/](examples/basic/)** - Basic mesh networking
+- **[examples/startHere/](examples/startHere/)** - Simple starting point
+
+### Alteriom Examples
+- **[examples/alteriom/](examples/alteriom/)** - Core Alteriom package examples
+- **[examples/alteriomSensorNode/](examples/alteriomSensorNode/)** - Sensor node implementation
+- **[examples/alteriomImproved/](examples/alteriomImproved/)** - Enhanced sensor node
+- **[examples/alteriomMetricsHealth/](examples/alteriomMetricsHealth/)** - Metrics and health monitoring
+- **[examples/alteriomPhase1/](examples/alteriomPhase1/)** - Phase 1 features demo
+- **[examples/alteriomPhase2/](examples/alteriomPhase2/)** - Phase 2 features demo
+
+### Bridge Examples
+- **[examples/bridge/](examples/bridge/)** - Basic bridge examples
+- **[examples/bridge_failover/](examples/bridge_failover/)** - Bridge failover implementation
+- **[examples/multi_bridge/](examples/multi_bridge/)** - Multiple bridge setup
+- **[examples/bridgeAwareSensorNode/](examples/bridgeAwareSensorNode/)** - Bridge-aware nodes
+
+### MQTT Examples
+- **[examples/mqttBridge/](examples/mqttBridge/)** - MQTT bridge
+- **[examples/mqttCommandBridge/](examples/mqttCommandBridge/)** - Command bridge
+- **[examples/mqttStatusBridge/](examples/mqttStatusBridge/)** - Status reporting bridge
+- **[examples/mqttTopologyTest/](examples/mqttTopologyTest/)** - Topology testing
+
+### Advanced Examples
+- **[examples/otaReceiver/](examples/otaReceiver/)** - OTA update receiver
+- **[examples/otaSender/](examples/otaSender/)** - OTA update sender
+- **[examples/ntpTimeSyncBridge/](examples/ntpTimeSyncBridge/)** - NTP time sync bridge
+- **[examples/ntpTimeSyncNode/](examples/ntpTimeSyncNode/)** - NTP time sync node
+- **[examples/webServer/](examples/webServer/)** - Mesh web server
+- **[examples/diagnosticsExample/](examples/diagnosticsExample/)** - Diagnostics tools
+
+## Troubleshooting
+
+- **[docs/troubleshooting/common-issues.md](docs/troubleshooting/common-issues.md)** - Common problems and solutions
+- **[docs/troubleshooting/ESP32_C6_COMPATIBILITY.md](docs/troubleshooting/ESP32_C6_COMPATIBILITY.md)** - ESP32-C6 issues
+- **[docs/troubleshooting/debugging.md](docs/troubleshooting/debugging.md)** - Debugging techniques
+- **[docs/troubleshooting/faq.md](docs/troubleshooting/faq.md)** - Frequently asked questions
+
+## Architecture Documentation
+
+- **[docs/architecture/mesh-architecture.md](docs/architecture/mesh-architecture.md)** - Mesh architecture overview
+- **[docs/architecture/plugin-system.md](docs/architecture/plugin-system.md)** - Plugin architecture
+- **[docs/architecture/routing.md](docs/architecture/routing.md)** - Message routing
+- **[docs/architecture/time-sync.md](docs/architecture/time-sync.md)** - Time synchronization
+
+## Support & Community
+
+### Getting Help
+- **GitHub Issues**: https://github.com/Alteriom/painlessMesh/issues
+- **GitHub Discussions**: https://github.com/Alteriom/painlessMesh/discussions
+
+### Package Registries
+- **NPM**: https://www.npmjs.com/package/@alteriom/painlessmesh
+- **PlatformIO**: https://registry.platformio.org/libraries/alteriom/painlessMesh
+- **Arduino Library Manager**: Search for "AlteriomPainlessMesh"
+
+## Version-Specific Documentation
+
+### Current Version (1.8.12)
+- Focus on documentation improvements and code quality
+- Added prettier configuration for consistent formatting
+- Enhanced inline documentation
+- See [RELEASE_NOTES_1.8.12.md](RELEASE_NOTES_1.8.12.md) for details
+
+### Previous Versions
+- **v1.8.11** - Bridge discovery and Windows MSVC compatibility fixes
+- **v1.8.10** - Bridge status direct messaging improvements
+- **v1.8.9** - Bridge self-registration fixes
+- **v1.8.0** - Bridge failover introduction
+- **v1.7.0** - Phase 2 features (broadcast OTA, MQTT status bridge)
+- **v1.6.0** - Phase 1 features (Alteriom packages)
+
+See [CHANGELOG.md](CHANGELOG.md) for complete version history.
+
+## Contributing to Documentation
+
+To contribute to documentation:
+1. Follow the style guide in existing documentation
+2. Update this index when adding new documentation files
+3. Ensure all links are functional
+4. Use Markdown for all documentation
+5. Include code examples where appropriate
+
+For detailed contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).

package/README.md

@@ -1,6 +1,6 @@
 # AlteriomPainlessMesh
 
-> **📚 [Complete Documentation](https://alteriom.github.io/painlessMesh/)** | **📖 [API Reference](https://alteriom.github.io/painlessMesh/#/api/doxygen)** | **🎯 [Examples](https://alteriom.github.io/painlessMesh/#/tutorials/basic-examples)**
+> **📚 [Complete Documentation](https://alteriom.github.io/painlessMesh/)** | **📖 [API Reference](https://alteriom.github.io/painlessMesh/#/api/doxygen)** | **🎯 [Examples](https://alteriom.github.io/painlessMesh/#/tutorials/basic-examples)** | **🗂️ [Documentation Index](DOCUMENTATION_INDEX.md)**
 
 <div align="center">
 

package/RELEASE_NOTES_1.8.12.md

@@ -0,0 +1,96 @@
+# Release Notes - Version 1.8.12
+
+**Release Date:** 2025-11-19
+
+## Overview
+
+Version 1.8.12 is a maintenance release focused on documentation improvements and code quality enhancements. This release includes changes from PRs #152 and #153, ensuring comprehensive documentation coverage and adherence to code formatting standards.
+
+## What's New
+
+### Documentation Enhancements
+
+- **Comprehensive Documentation Review** - All documentation has been reviewed and updated to reflect the current state of the library
+- **API Reference Updates** - Improved clarity and completeness in API documentation
+- **Example Code Documentation** - Enhanced inline documentation for example projects
+- **Package Documentation** - Updated documentation for all Alteriom custom packages
+
+### Code Quality Improvements
+
+- **Prettier Configuration** - Added prettier configuration for consistent JSON and Markdown formatting
+  - New `.prettierrc` configuration file
+  - New `.prettierignore` file to exclude build artifacts and dependencies
+  - Added `npm run format` and `npm run format:check` scripts
+- **Clang-Format Compliance** - Ensured all C++ code follows established formatting standards
+- **Code Organization** - Improved code structure and maintainability
+
+### Version Updates
+
+- Updated all version references across:
+  - `package.json` - NPM package version
+  - `library.json` - PlatformIO library version
+  - `library.properties` - Arduino library version
+  - `src/painlessMesh.h` - Header file version comments
+  - `src/AlteriomPainlessMesh.h` - Version defines and comments
+
+## Installation
+
+### Arduino Library Manager
+```
+Sketch → Include Library → Manage Libraries → Search "AlteriomPainlessMesh" → Install
+```
+
+### PlatformIO
+```ini
+[env:myenv]
+lib_deps = 
+    alteriom/AlteriomPainlessMesh @ ^1.8.12
+```
+
+### NPM
+```bash
+npm install @alteriom/painlessmesh@1.8.12
+```
+
+## Compatibility
+
+- **ESP32** - All variants supported
+- **ESP8266** - All variants supported
+- **Arduino IDE** - Version 1.8.0 or higher
+- **PlatformIO** - Latest version
+- **ArduinoJson** - Version 7.4.2 or higher
+- **TaskScheduler** - Version 4.0.0 or higher
+
+## Migration Guide
+
+This is a patch release with no breaking changes. Users can upgrade from any 1.8.x version without code modifications.
+
+## Known Issues
+
+None identified in this release.
+
+## Pull Requests Included
+
+- PR #152 - Documentation improvements
+- PR #153 - Code quality enhancements
+
+## Contributors
+
+Special thanks to all contributors who helped make this release possible!
+
+## Documentation
+
+- **Main Documentation**: https://alteriom.github.io/painlessMesh/
+- **API Reference**: https://alteriom.github.io/painlessMesh/#/api/doxygen
+- **Examples**: https://alteriom.github.io/painlessMesh/#/tutorials/basic-examples
+- **GitHub Repository**: https://github.com/Alteriom/painlessMesh
+
+## Support
+
+For questions, issues, or feature requests:
+- **GitHub Issues**: https://github.com/Alteriom/painlessMesh/issues
+- **Documentation**: https://alteriom.github.io/painlessMesh/
+
+## License
+
+This project is licensed under LGPL-3.0. See the LICENSE file for details.

package/docs/CHANNEL_SYNCHRONIZATION.md

@@ -0,0 +1,209 @@
+# Channel Synchronization in painlessMesh
+
+## Problem Statement
+
+When a mesh network operates on one channel and a node promotes to bridge via election, it may connect to a router operating on a different channel. This creates a channel mismatch where:
+
+1. Bridge node switches to router's channel (e.g., channel 6)
+2. Other mesh nodes remain on original channel (e.g., channel 1)
+3. Bridge takeover announcements sent on new channel are not heard by nodes on old channel
+4. Nodes cannot find the mesh network and become isolated
+
+## Solution Overview
+
+The solution has two complementary parts:
+
+### Part 1: Automatic Channel Re-detection
+
+Nodes automatically detect when they can't find the mesh on their current channel and trigger a full channel scan to locate it.
+
+**Implementation:** `src/painlessMeshSTA.cpp` and `src/painlessMeshSTA.h`
+
+**Key Components:**
+- `consecutiveEmptyScans` counter tracks scans with no mesh nodes found
+- `EMPTY_SCAN_THRESHOLD` constant (6 scans) determines when to trigger re-scan
+- Full channel scan using `scanForMeshChannel()` when threshold reached
+- Automatic channel update and AP restart when mesh found on different channel
+
+**Flow:**
+```
+1. Node scans on current channel (e.g., channel 1)
+2. Finds no mesh nodes → increment consecutiveEmptyScans
+3. Repeat for EMPTY_SCAN_THRESHOLD scans (~30 seconds with fast scanning)
+4. Trigger scanForMeshChannel() to scan ALL channels (1-13)
+5. If mesh found on different channel:
+   a. Update mesh->_meshChannel to detected channel
+   b. Restart AP on new channel
+   c. Reset consecutiveEmptyScans counter
+6. Continue normal scanning on new channel
+```
+
+**Safeguards:**
+- Only triggers when WiFi.status() != WL_CONNECTED (not when stably connected)
+- Only triggers when channel > 0 (channel 0 already means auto-detect)
+- Resets counter when mesh nodes are found (prevents false triggers)
+
+### Part 2: Dual-Channel Takeover Announcements
+
+Bridge promotion sends takeover announcements on both the old and new channels to ensure all nodes are notified.
+
+**Implementation:** `src/arduino/wifi.hpp` in `promoteToBridge()` method
+
+**Flow:**
+```
+1. Node wins bridge election
+2. Send takeover announcement on CURRENT channel (e.g., channel 1)
+   → Nodes still on channel 1 receive this announcement
+3. Wait 1 second for announcement to propagate
+4. Stop mesh and reinitialize as bridge via initAsBridge()
+   → Connects to router, detects router's channel (e.g., channel 6)
+   → Initializes mesh on channel 6
+5. Schedule follow-up takeover announcement on NEW channel (channel 6)
+   → Sent 3 seconds after initialization
+   → Nodes that switched to channel 6 receive this announcement
+```
+
+**Benefits:**
+- Early announcement notifies nodes on old channel before bridge switches
+- Delayed announcement notifies nodes that switched early or quickly found new channel
+- Ensures complete mesh awareness regardless of node timing
+
+## Expected Behavior
+
+### Scenario: Bridge Promotion with Channel Change
+
+**Setup:**
+- Node1: Regular mesh node on channel 1
+- Node2: Regular mesh node on channel 1 (weak router signal)
+- Router: Operating on channel 6
+
+**Sequence:**
+1. Node2 starts mesh on channel 1 (default, no router connection)
+2. Node1 joins mesh on channel 1
+3. Node1 wins bridge election (better router signal)
+4. Node1 sends "Becoming bridge" announcement on channel 1
+5. Node2 receives announcement
+6. Node1 connects to router on channel 6, initializes mesh on channel 6
+7. Node1 sends follow-up "I'm the bridge" announcement on channel 6
+8. Node2 can't find mesh on channel 1 for 6 consecutive scans
+9. Node2 triggers full channel scan, finds mesh on channel 6
+10. Node2 updates to channel 6, restarts AP on channel 6
+11. Node2 reconnects to Node1 on channel 6
+12. Mesh network is now unified on channel 6
+
+**Timeline:**
+- T+0s: Node1 wins election, sends announcement on channel 1
+- T+1s: Node1 stops mesh on channel 1
+- T+2s: Node1 initializes mesh on channel 6
+- T+5s: Node1 sends follow-up announcement on channel 6
+- T+30s: Node2 can't find mesh on channel 1 (fast scanning)
+- T+30s: Node2 triggers channel re-scan
+- T+31s: Node2 finds mesh on channel 6
+- T+32s: Node2 restarts AP on channel 6
+- T+35s: Node2 reconnects to mesh on channel 6
+
+## Configuration
+
+### Adjusting Re-scan Threshold
+
+The `EMPTY_SCAN_THRESHOLD` is defined in `src/painlessMeshSTA.h`:
+
+```cpp
+static const uint16_t EMPTY_SCAN_THRESHOLD = 6; // ~30 seconds at default SCAN_INTERVAL
+```
+
+**Trade-offs:**
+- **Lower value** (e.g., 3): Faster channel detection, but more susceptible to false triggers
+- **Higher value** (e.g., 10): More stable, but slower response to channel changes
+
+### Scan Timing
+
+Default scan intervals defined in `src/painlessmesh/configuration.hpp`:
+
+```cpp
+#define SCAN_INTERVAL 30 * TASK_SECOND  // AP scan period in ms
+```
+
+When no mesh nodes found, scanning switches to fast mode:
+```cpp
+task.setInterval(0.5 * SCAN_INTERVAL);  // 15 seconds
+```
+
+With EMPTY_SCAN_THRESHOLD=6 and fast scanning:
+- Time to trigger re-scan: 6 × 15s = 90 seconds (~1.5 minutes)
+
+## Debugging
+
+### Log Messages
+
+**Channel Re-detection:**
+```
+CONNECTION: connectToAP(): No mesh nodes found for 6 scans, triggering channel re-detection
+CONNECTION: scanForMeshChannel(): Scanning all channels for mesh 'YourMesh'...
+CONNECTION: scanForMeshChannel(): Found mesh on channel 6 (RSSI: -45)
+CONNECTION: connectToAP(): Mesh found on different channel 6 (was 1), updating...
+CONNECTION: connectToAP(): Restarting AP from channel 1 to channel 6
+CONNECTION: connectToAP(): AP restarted on channel 6
+```
+
+**Bridge Promotion:**
+```
+STARTUP: === Becoming Bridge Node ===
+STARTUP: Sending takeover announcement on current channel before switching...
+STARTUP: ✓ Takeover announcement sent on channel 1
+STARTUP: Step 1: Connecting to router YourRouter...
+STARTUP: ✓ Router connected on channel 6
+STARTUP: Step 2: Initializing mesh on channel 6...
+STARTUP: ✓ Bridge promotion complete on channel 6
+STARTUP: Sending follow-up takeover announcement on new channel 6
+STARTUP: ✓ Follow-up takeover announcement sent
+```
+
+### Common Issues
+
+**Issue:** Nodes don't switch channels
+- **Check:** Ensure `channel=0` in init() for auto-detection
+- **Check:** Verify nodes are not connected via stationManual() to router
+- **Check:** Increase log level to see scanning activity
+
+**Issue:** Channel switching takes too long
+- **Solution:** Reduce EMPTY_SCAN_THRESHOLD in painlessMeshSTA.h
+- **Trade-off:** May increase false triggers during temporary network instability
+
+**Issue:** Bridge promotion doesn't work
+- **Check:** Verify router credentials are configured
+- **Check:** Ensure router has good signal strength (> -80 dBm)
+- **Check:** Confirm router is on a valid channel (1-13 for 2.4GHz)
+
+## Testing
+
+### Manual Testing Procedure
+
+1. Setup two ESP32/ESP8266 nodes with painlessMesh
+2. Configure router on channel 6
+3. Start both nodes without router credentials (will use channel 1)
+4. Configure one node with router credentials and trigger election
+5. Monitor serial output for channel switching messages
+6. Verify both nodes eventually operate on channel 6
+7. Verify mesh connectivity is maintained
+
+### Expected Results
+
+- Bridge node switches to router channel within 5 seconds
+- Non-bridge nodes detect channel change within 90 seconds
+- All nodes reconnect on new channel
+- No loss of mesh connectivity (except during transition)
+
+## Related Files
+
+- `src/painlessMeshSTA.h` - StationScan class definition with channel re-detection
+- `src/painlessMeshSTA.cpp` - Channel re-detection implementation
+- `src/arduino/wifi.hpp` - Bridge promotion with dual announcements
+- `test/catch/catch_channel_resync.cpp` - Unit tests for channel synchronization
+- `BRIDGE_TO_INTERNET.md` - Bridge setup documentation
+
+## References
+
+- Issue #137: Bridge takeover announcements not heard across channels
+- WiFi channels: 1-13 for 2.4GHz (channels 12-13 restricted in some regions)
+- ESP32/ESP8266 can only operate on one channel at a time in AP+STA mode