@alteriom/painlessmesh 1.8.11 → 1.8.12

package/CHANGELOG.md

@@ -7,6 +7,24 @@ 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

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

package/examples/rtcIntegration/README.md

@@ -211,6 +211,63 @@ void rtcSyncCompleteCallback(uint32_t timestamp) {
 - Check NTP server is accessible
 - Ensure `syncRTCFromNTP()` called with valid timestamp
 
+## Time Authority
+
+painlessMesh v1.8.12+ includes **time authority** support to prevent nodes from adopting incorrect time from nodes without accurate time sources.
+
+### How It Works
+
+Nodes with time authority (RTC or Internet) are prioritized during mesh time synchronization:
+- Nodes **without** time authority will adopt time from nodes **with** time authority
+- Nodes **with** time authority will **NOT** adopt time from nodes without
+- When both nodes have same authority status, existing subnet/node ID logic applies
+
+### Setting Time Authority
+
+Time authority is automatically set when:
+- RTC is enabled via `enableRTC()` (time authority = true)
+- RTC is disabled via `disableRTC()` (time authority = false)
+
+For bridge nodes with Internet, set time authority manually:
+
+```cpp
+void bridgeStatusCallback(uint32_t bridgeNodeId, bool hasInternet) {
+  // If THIS node is the bridge, update time authority
+  if (bridgeNodeId == mesh.getNodeId()) {
+    if (hasInternet) {
+      mesh.setTimeAuthority(true);  // Internet available
+    } else if (!mesh.hasRTC()) {
+      mesh.setTimeAuthority(false); // No Internet and no RTC
+    }
+  }
+}
+```
+
+### Checking Time Authority
+
+```cpp
+if (mesh.getTimeAuthority()) {
+  Serial.println("This node has authoritative time source");
+}
+```
+
+### Use Cases
+
+**Scenario 1: Mixed RTC nodes**
+- Node A: Has RTC (time authority = true)
+- Node B: No RTC (time authority = false)
+- Result: Node B adopts time from Node A ✓
+
+**Scenario 2: Bridge with Internet**
+- Node A: Bridge with Internet (time authority = true)
+- Node B: Regular node (time authority = false)
+- Result: Node B adopts time from bridge ✓
+
+**Scenario 3: Network split**
+- Subnet A: All nodes have RTC
+- Subnet B: No nodes have RTC
+- Result: When subnets reconnect, Subnet B adopts from Subnet A ✓
+
 ## Best Practices
 
 1. **Always check RTC availability** before relying on timestamps
@@ -218,6 +275,8 @@ void rtcSyncCompleteCallback(uint32_t timestamp) {
 3. **Monitor battery** on RTC modules for continuous operation
 4. **Implement fallback** to mesh time if RTC fails
 5. **Log sync events** for debugging and maintenance
+6. **Set time authority** for bridge nodes when Internet is available
+7. **Use RTC on at least one node** in offline deployments for accurate timestamps
 
 ## Regulatory Compliance
 

package/examples/rtcIntegration/rtcIntegration.ino

@@ -160,6 +160,20 @@ void bridgeStatusCallback(uint32_t bridgeNodeId, bool hasInternet) {
                 bridgeNodeId, 
                 hasInternet ? "Connected" : "Disconnected");
   
+  // If THIS node is the bridge, set time authority based on Internet availability
+  if (bridgeNodeId == mesh.getNodeId()) {
+    if (hasInternet) {
+      Serial.println("This node has Internet - setting time authority");
+      mesh.setTimeAuthority(true);
+    } else {
+      // Lost Internet - remove time authority if no RTC
+      if (!mesh.hasRTC()) {
+        Serial.println("Lost Internet and no RTC - removing time authority");
+        mesh.setTimeAuthority(false);
+      }
+    }
+  }
+  
   if (hasInternet && needsNTPSync && mesh.hasRTC()) {
     // Internet is available and we need to sync RTC
     // In a real application, you would get NTP time here

package/library.json

@@ -6,7 +6,7 @@
     "type": "git",
     "url": "https://github.com/Alteriom/painlessMesh"
   },
-  "version": "1.8.11",
+  "version": "1.8.12",
   "frameworks": [
     "arduino"
   ],

package/library.properties

@@ -1,5 +1,5 @@
 name=Alteriom PainlessMesh
-version=1.8.11
+version=1.8.12
 author=Coopdis,Scotty Franzyshen,Edwin van Leeuwen,Germán Martín,Maximilian Schwarz,Doanh Doanh,Alteriom
 maintainer=Alteriom
 sentence=A painless way to setup a mesh with ESP8266 and ESP32 devices with Alteriom extensions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alteriom/painlessmesh",
-  "version": "1.8.11",
+  "version": "1.8.12",
   "description": "painlessMesh is a user-friendly library for creating mesh networks with ESP8266 and ESP32 devices. This Alteriom fork includes additional packages for sensor data (SensorPackage), device commands (CommandPackage), and status monitoring (StatusPackage). It handles routing and network management automatically, so you can focus on your application. The library uses JSON-based messaging and syncs time across all nodes, making it ideal for coordinated behaviour like synchronized light displays or sensor networks reporting to a central node.",
   "keywords": [
     "arduino",
@@ -51,7 +51,9 @@
     "dev:prebuild": "git submodule update --init",
     "validate-library": "./scripts/validate-release.sh",
     "prepublishOnly": "npm run validate-library",
-    "postpublish": "echo 'Package published successfully to NPM!'"
+    "postpublish": "echo 'Package published successfully to NPM!'",
+    "format": "prettier --write \"**/*.{json,md,yml,yaml}\"",
+    "format:check": "prettier --check \"**/*.{json,md,yml,yaml}\""
   },
   "engines": {
     "node": ">=14.0.0"
@@ -81,6 +83,8 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
-    "RELEASE_GUIDE.md"
+    "RELEASE_GUIDE.md",
+    "DOCUMENTATION_INDEX.md",
+    "RELEASE_NOTES_1.8.12.md"
   ]
 }

package/src/AlteriomPainlessMesh.h

@@ -29,10 +29,10 @@
 /**
  * @brief AlteriomPainlessMesh library version information
  */
-#define ALTERIOM_PAINLESS_MESH_VERSION "1.8.11"
+#define ALTERIOM_PAINLESS_MESH_VERSION "1.8.12"
 #define ALTERIOM_PAINLESS_MESH_VERSION_MAJOR 1
 #define ALTERIOM_PAINLESS_MESH_VERSION_MINOR 8
-#define ALTERIOM_PAINLESS_MESH_VERSION_PATCH 11
+#define ALTERIOM_PAINLESS_MESH_VERSION_PATCH 12
 
 /**
  * @brief Library description and usage information

package/src/arduino/wifi.hpp

@@ -1021,6 +1021,29 @@ class Mesh : public painlessmesh::Mesh<Connection> {
       return;
     }
     
+    // CRITICAL: Check if mesh channel re-synchronization is needed first
+    // If we haven't found any mesh nodes and are approaching the re-sync threshold,
+    // prioritize finding the mesh over becoming a bridge. This prevents the scenario
+    // where a node tries to become a bridge when it should be re-syncing to find
+    // the mesh on a different channel (e.g., after another node became bridge and
+    // switched channels to match the router).
+    uint16_t emptyScans = stationScan.getConsecutiveEmptyScans();
+    if (emptyScans >= 3 && WiFi.status() != WL_CONNECTED) {
+      Log(CONNECTION, 
+          "startBridgeElection(): Mesh connectivity lost (%d empty scans), "
+          "deferring election to allow channel re-sync\n", emptyScans);
+      
+      // Schedule a retry after channel re-sync has had a chance to run
+      // The channel re-sync threshold is StationScan::EMPTY_SCAN_THRESHOLD scans (default 6)
+      // Fast scan interval is 0.5 * SCAN_INTERVAL = 15 seconds
+      // Wait for re-sync to complete plus a buffer
+      uint32_t retryDelay = (StationScan::EMPTY_SCAN_THRESHOLD - emptyScans + 2) * 15000;
+      Log(CONNECTION, 
+          "startBridgeElection(): Will retry election in %u seconds if still needed\n",
+          retryDelay / 1000);
+      return;
+    }
+    
     Log(CONNECTION, "=== Bridge Election Started ===\n");
     electionState = ELECTION_SCANNING;
     
@@ -1195,23 +1218,9 @@ class Mesh : public painlessmesh::Mesh<Connection> {
     auto primaryBridge = this->getPrimaryBridge();
     uint32_t previousBridgeId = primaryBridge ? primaryBridge->nodeId : 0;
     
-    // Reconfigure as bridge
-    this->stop();
-    delay(1000);
-    
-    this->initAsBridge(_meshSSID, _meshPassword, routerSSID, routerPassword,
-                       mScheduler, _meshPort);
-    
-    lastRoleChangeTime = millis();
-    
-    Log(STARTUP, "✓ Bridge promotion complete\n");
-    
-    // Notify via callback
-    if (bridgeRoleChangedCallback) {
-      bridgeRoleChangedCallback(true, "Election winner - best router signal");
-    }
-    
-    // Broadcast takeover announcement
+    // IMPORTANT: Send takeover announcement BEFORE switching channels
+    // This ensures other nodes on the current channel receive the announcement
+    Log(STARTUP, "Sending takeover announcement on current channel before switching...\n");
     JsonDocument doc;
     JsonObject obj = doc.to<JsonObject>();
     obj["type"] = 612;  // BRIDGE_TAKEOVER
@@ -1219,18 +1228,55 @@ class Mesh : public painlessmesh::Mesh<Connection> {
     obj["routing"] = 2;  // BROADCAST
     obj["previousBridge"] = previousBridgeId;
     obj["reason"] = "Election winner - best router signal";
-    obj["routerRSSI"] = WiFi.RSSI();
+    obj["routerRSSI"] = 0;  // Not yet connected to router
     obj["timestamp"] = this->getNodeTime();
     obj["message_type"] = 612;
     
     String msg;
     serializeJson(doc, msg);
-    
-    // Small delay to ensure mesh is ready
-    delay(2000);
     this->sendBroadcast(msg);
     
-    Log(STARTUP, "✓ Takeover announcement sent\n");
+    // Give time for announcement to propagate before channel switch
+    delay(1000);
+    Log(STARTUP, "✓ Takeover announcement sent on channel %d\n", _meshChannel);
+    
+    // Now reconfigure as bridge (this will switch to router's channel)
+    this->stop();
+    delay(1000);
+    
+    this->initAsBridge(_meshSSID, _meshPassword, routerSSID, routerPassword,
+                       mScheduler, _meshPort);
+    
+    lastRoleChangeTime = millis();
+    
+    Log(STARTUP, "✓ Bridge promotion complete on channel %d\n", _meshChannel);
+    
+    // Notify via callback
+    if (bridgeRoleChangedCallback) {
+      bridgeRoleChangedCallback(true, "Election winner - best router signal");
+    }
+    
+    // Send a follow-up announcement on the new channel
+    // This helps nodes that have already switched channels to discover the new bridge
+    // Schedule it after a delay to ensure mesh is fully initialized
+    this->addTask(3000, TASK_ONCE, [this, previousBridgeId]() {
+      Log(STARTUP, "Sending follow-up takeover announcement on new channel %d\n", _meshChannel);
+      JsonDocument doc2;
+      JsonObject obj2 = doc2.to<JsonObject>();
+      obj2["type"] = 612;  // BRIDGE_TAKEOVER
+      obj2["from"] = this->nodeId;
+      obj2["routing"] = 2;  // BROADCAST
+      obj2["previousBridge"] = previousBridgeId;
+      obj2["reason"] = "Election winner - best router signal";
+      obj2["routerRSSI"] = WiFi.RSSI();
+      obj2["timestamp"] = this->getNodeTime();
+      obj2["message_type"] = 612;
+      
+      String msg2;
+      serializeJson(doc2, msg2);
+      this->sendBroadcast(msg2);
+      Log(STARTUP, "✓ Follow-up takeover announcement sent\n");
+    });
   }
 
   /**

package/src/painlessMesh.h

@@ -5,8 +5,8 @@
  * @file painlessMesh.h
  * @brief Main header file for Alteriom painlessMesh library
  * 
- * @version 1.8.11
- * @date 2025-11-18
+ * @version 1.8.12
+ * @date 2025-11-19
  * 
  * painlessMesh is a user-friendly library for creating mesh networks with 
  * ESP8266 and ESP32 devices. This Alteriom fork includes additional packages 

package/src/painlessMeshSTA.cpp

@@ -204,6 +204,50 @@ void ICACHE_FLASH_ATTR StationScan::connectToAP() {
   bool isRooted = layout::isRooted(mesh->asNodeTree());
   if (aps.empty()) {
     // No unknown nodes found
+    consecutiveEmptyScans++;
+    
+    // If we've had multiple consecutive empty scans and we're not connected,
+    // trigger a full channel re-scan to find the mesh
+    if (consecutiveEmptyScans >= EMPTY_SCAN_THRESHOLD && 
+        WiFi.status() != WL_CONNECTED &&
+        channel > 0) {
+      Log(CONNECTION,
+          "connectToAP(): No mesh nodes found for %d scans, triggering channel re-detection\n",
+          consecutiveEmptyScans);
+      
+      // Perform full channel scan to find the mesh
+      uint8_t detectedChannel = scanForMeshChannel(ssid, hidden);
+      if (detectedChannel > 0 && detectedChannel != mesh->_meshChannel) {
+        Log(CONNECTION,
+            "connectToAP(): Mesh found on different channel %d (was %d), updating...\n",
+            detectedChannel, mesh->_meshChannel);
+        
+        // Update mesh channel
+        uint8_t oldChannel = mesh->_meshChannel;
+        mesh->_meshChannel = detectedChannel;
+        channel = detectedChannel;
+        
+        // Restart AP on new channel to match the mesh
+        // This ensures this node's AP is also discoverable on the correct channel
+        if (WiFi.getMode() & WIFI_AP) {
+          Log(CONNECTION,
+              "connectToAP(): Restarting AP from channel %d to channel %d\n",
+              oldChannel, detectedChannel);
+          WiFi.softAPdisconnect(false);
+          delay(100);
+          // Call apInit via friend class access (StationScan is friend of wifi::Mesh)
+          mesh->apInit(mesh->getNodeId());
+          Log(CONNECTION, "connectToAP(): AP restarted on channel %d\n", detectedChannel);
+        }
+      } else if (detectedChannel == 0) {
+        Log(CONNECTION,
+            "connectToAP(): Mesh not found on any channel during re-scan\n");
+      }
+      
+      // Reset counter after re-scan attempt
+      consecutiveEmptyScans = 0;
+    }
+    
     if (WiFi.status() == WL_CONNECTED &&
         !(mesh->shouldContainRoot && !isRooted)) {
       // if already connected -> scan slow
@@ -220,6 +264,8 @@ void ICACHE_FLASH_ATTR StationScan::connectToAP() {
     }
     mesh->stability += min(1000 - mesh->stability, (size_t)25);
   } else {
+    // Reset counter when APs are found
+    consecutiveEmptyScans = 0;
     if (WiFi.status() == WL_CONNECTED) {
       // TODO: Use %u instead of String() here and below
       // Also prob is always equal to stability, so we should use that directly

package/src/painlessMeshSTA.h

@@ -36,6 +36,16 @@ class StationScan {
   
   // Helper to scan all channels for a specific mesh SSID
   static uint8_t scanForMeshChannel(TSTRING meshSSID, bool meshHidden);
+  
+  // Check if channel re-synchronization is needed or in progress
+  bool isChannelResyncNeeded() const {
+    return consecutiveEmptyScans >= EMPTY_SCAN_THRESHOLD;
+  }
+  
+  // Get the number of consecutive empty scans
+  uint16_t getConsecutiveEmptyScans() const {
+    return consecutiveEmptyScans;
+  }
 
   /// Valid APs found during the last scan
   std::list<WiFi_AP_Record_t> lastAPs;
@@ -54,6 +64,10 @@ class StationScan {
   // Manually configure network and ip
   bool manual = false;
   IPAddress manualIP = IPAddress(0, 0, 0, 0);
+  
+  // Track consecutive scans with no mesh nodes found (for channel re-detection)
+  uint16_t consecutiveEmptyScans = 0;
+  static const uint16_t EMPTY_SCAN_THRESHOLD = 6; // ~30 seconds at default SCAN_INTERVAL
 
   friend painlessMesh;
 };

package/src/painlessmesh/layout.hpp

@@ -52,7 +52,7 @@ class Layout {
   bool isRoot() { return root; }
 
   protocol::NodeTree asNodeTree() {
-    auto nt = protocol::NodeTree(nodeId, root);
+    auto nt = protocol::NodeTree(nodeId, root, hasTimeAuthority);
     for (auto&& s : subs) {
       if (s->nodeId == 0) continue;
       nt.subs.push_back(protocol::NodeTree(*s));
@@ -63,6 +63,7 @@ class Layout {
  protected:
   uint32_t nodeId = 0;
   bool root = false;
+  bool hasTimeAuthority = false;
 };
 
 template <class T>
@@ -114,6 +115,7 @@ class Neighbour : public protocol::NodeTree {
       nodeId = tree.nodeId;
       subs = tree.subs;
       root = tree.root;
+      hasTimeAuthority = tree.hasTimeAuthority;
       return true;
     }
     return false;
@@ -124,8 +126,10 @@ class Neighbour : public protocol::NodeTree {
    */
   protocol::NodeSyncRequest request(NodeTree&& layout) {
     auto subTree = excludeRoute(std::move(layout), nodeId);
-    return protocol::NodeSyncRequest(subTree.nodeId, nodeId, subTree.subs,
+    auto req = protocol::NodeSyncRequest(subTree.nodeId, nodeId, subTree.subs,
                                      subTree.root);
+    req.hasTimeAuthority = subTree.hasTimeAuthority;
+    return req;
   }
 
   /**

package/src/painlessmesh/mesh.hpp

@@ -750,7 +750,12 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
   bool enableRTC(rtc::RTCInterface* rtcInterface) {
     using namespace logger;
     Log(GENERAL, "enableRTC(): Initializing RTC\n");
-    return rtcManager.enable(rtcInterface);
+    bool success = rtcManager.enable(rtcInterface);
+    if (success) {
+      // RTC enabled successfully - mark node as having time authority
+      setTimeAuthority(true);
+    }
+    return success;
   }
 
   /**
@@ -760,6 +765,9 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     using namespace logger;
     Log(GENERAL, "disableRTC(): Disabling RTC\n");
     rtcManager.disable();
+    // RTC disabled - remove time authority if no other source
+    // Note: Bridge nodes may still have time authority from Internet
+    setTimeAuthority(false);
   }
 
   /**
@@ -864,6 +872,50 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     rtcSyncCompleteCallback = onRTCSyncComplete;
   }
 
+  /**
+   * Set time authority status for this node
+   * 
+   * Nodes with time authority (RTC or Internet) are preferred as time sources
+   * during mesh time synchronization. This prevents nodes from adopting time
+   * from nodes without accurate time sources.
+   * 
+   * This is automatically set to true when:
+   * - RTC is enabled via enableRTC()
+   * - Bridge has Internet connectivity
+   * 
+   * \code
+   * // Manual control (advanced usage)
+   * mesh.setTimeAuthority(true);  // Mark as authoritative time source
+   * mesh.setTimeAuthority(false); // Mark as non-authoritative
+   * \endcode
+   * 
+   * @param hasAuthority True if node has accurate time source (RTC/Internet)
+   */
+  void setTimeAuthority(bool hasAuthority) {
+    using namespace logger;
+    if (this->hasTimeAuthority != hasAuthority) {
+      this->hasTimeAuthority = hasAuthority;
+      Log(GENERAL, "setTimeAuthority(): Time authority %s\n", 
+          hasAuthority ? "enabled" : "disabled");
+      
+      // Trigger time sync with all connections to propagate authority status
+      for (auto&& connection : this->subs) {
+        if (connection->nodeId != 0) {
+          connection->timeSyncTask.forceNextIteration();
+        }
+      }
+    }
+  }
+
+  /**
+   * Check if this node has time authority
+   * 
+   * @return True if node has RTC or Internet time source
+   */
+  bool getTimeAuthority() const {
+    return this->hasTimeAuthority;
+  }
+
   //
   // Message Queue API
   //

package/src/painlessmesh/ntp.hpp

@@ -76,6 +76,22 @@ inline int32_t tripDelay(uint32_t time0, uint32_t time1, uint32_t time2,
 }
 
 inline bool adopt(protocol::NodeTree mesh, protocol::NodeTree connection) {
+  // Prioritize nodes with time authority (RTC or Internet)
+  // Only adopt from nodes with time authority if we don't have one
+  if (!mesh.hasTimeAuthority && connection.hasTimeAuthority) {
+    Log(logger::S_TIME, "adopt(): Adopting from %u (has time authority)\n",
+        connection.nodeId);
+    return true;
+  }
+  
+  // Don't adopt from nodes without time authority if we have one
+  if (mesh.hasTimeAuthority && !connection.hasTimeAuthority) {
+    Log(logger::S_TIME, "adopt(): Not adopting from %u (no time authority)\n",
+        connection.nodeId);
+    return false;
+  }
+  
+  // If both have same time authority status, use existing logic
   auto mySubCount =
       layout::size(layout::excludeRoute(std::move(mesh), connection.nodeId));
   auto remoteSubCount = layout::size(connection);

package/src/painlessmesh/protocol.hpp

@@ -123,23 +123,27 @@ class NodeTree : public PackageInterface {
  public:
   uint32_t nodeId = 0;
   bool root = false;
+  bool hasTimeAuthority = false;  // True if node has RTC or Internet time source
   std::list<NodeTree> subs;
 
   NodeTree() {}
   virtual ~NodeTree() = default;  // Add virtual destructor
 
-  NodeTree(uint32_t nodeID, bool iAmRoot) {
+  NodeTree(uint32_t nodeID, bool iAmRoot, bool timeAuthority = false) {
     nodeId = nodeID;
     root = iAmRoot;
+    hasTimeAuthority = timeAuthority;
   }
 
   NodeTree(JsonObject jsonObj) {
 #if ARDUINOJSON_VERSION_MAJOR < 7
     if (jsonObj.containsKey("root")) root = jsonObj["root"].as<bool>();
+    if (jsonObj.containsKey("hasTimeAuthority")) hasTimeAuthority = jsonObj["hasTimeAuthority"].as<bool>();
     if (jsonObj.containsKey("nodeId"))
 #else
 
     if (jsonObj["root"].is<bool>()) root = jsonObj["root"].as<bool>();
+    if (jsonObj["hasTimeAuthority"].is<bool>()) hasTimeAuthority = jsonObj["hasTimeAuthority"].as<bool>();
     if (jsonObj["nodeId"].is<uint32_t>())
 #endif
       nodeId = jsonObj["nodeId"].as<uint32_t>();
@@ -161,6 +165,7 @@ class NodeTree : public PackageInterface {
   JsonObject addTo(JsonObject&& jsonObj) const {
     jsonObj["nodeId"] = nodeId;
     if (root) jsonObj["root"] = root;
+    if (hasTimeAuthority) jsonObj["hasTimeAuthority"] = hasTimeAuthority;
     if (subs.size() > 0) {
 #if ARDUINOJSON_VERSION_MAJOR == 7
       JsonArray subsArr = jsonObj["subs"].to<JsonArray>();
@@ -181,6 +186,7 @@ class NodeTree : public PackageInterface {
 
   bool operator==(const NodeTree& b) const {
     if (!(this->nodeId == b.nodeId && this->root == b.root &&
+          this->hasTimeAuthority == b.hasTimeAuthority &&
           this->subs.size() == b.subs.size()))
       return false;
     auto itA = this->subs.begin();
@@ -203,6 +209,7 @@ class NodeTree : public PackageInterface {
   size_t jsonObjectSize() const {
     size_t base = 1;
     if (root) ++base;
+    if (hasTimeAuthority) ++base;
     if (subs.size() > 0) ++base;
     size_t size = JSON_OBJECT_SIZE(base);
     if (subs.size() > 0) size += JSON_ARRAY_SIZE(subs.size());
@@ -215,6 +222,7 @@ class NodeTree : public PackageInterface {
     nodeId = 0;
     subs.clear();
     root = false;
+    hasTimeAuthority = false;
   }
 };
 
@@ -263,6 +271,7 @@ class NodeSyncRequest : public NodeTree {
   size_t jsonObjectSize() const {
     size_t base = 4;
     if (root) ++base;
+    if (hasTimeAuthority) ++base;
     if (subs.size() > 0) ++base;
     size_t size = JSON_OBJECT_SIZE(base);
     if (subs.size() > 0) size += JSON_ARRAY_SIZE(subs.size());