@alteriom/painlessmesh 1.7.8 → 1.8.0

package/CHANGELOG.md

@@ -7,19 +7,155 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.8.0] - 2025-11-09
+
 ### Added
 
-- TBD
+- **Diagnostics API for Bridge Operations** - Comprehensive monitoring and debugging tools
+  - New diagnostic methods for bridge state, topology, and connectivity
+  - Election history tracking with detailed event logging
+  - Network topology visualization with neighbor information
+  - Connectivity testing and validation tools
+  - Comprehensive diagnostic report generation
+  - Minimal overhead when diagnostics enabled
+  - Examples: `examples/diagnostics/` directory
+  - Documentation: `DIAGNOSTICS_API.md`
+
+- **Bridge Health Monitoring & Metrics Collection** - Real-time bridge performance metrics
+  - New `BridgeHealthMetrics` struct with connectivity, signal, traffic, and performance data
+  - Four API methods: `getBridgeHealthMetrics()`, `resetHealthMetrics()`, `getHealthMetricsJSON()`, `onHealthMetricsUpdate()`
+  - Automatic tracking of uptime, disconnects, RSSI, traffic bytes, latency, and packet loss
+  - JSON export for integration with MQTT, Prometheus, Grafana, CloudWatch
+  - Periodic callback support for automated monitoring
+  - Zero overhead when not used
+  - Comprehensive unit tests (63 assertions)
+  - Example: `examples/bridge/bridge_health_monitoring_example.ino`
+  - Documentation: `docs/BRIDGE_HEALTH_MONITORING.md`
+
+- **RTC (Real-Time Clock) Integration** - Hardware RTC support for offline timekeeping
+  - Support for DS3231, DS1307, and PCF8523 RTC modules
+  - Automatic time persistence across reboots and power failures
+  - Seamless integration with NTP time sync
+  - Comprehensive unit tests for RTC functionality
+  - Example sketches demonstrating RTC usage
+
+- **Bridge Status Broadcast & Callback (Type 610)** - Real-time Internet connectivity monitoring
+  - Bridge nodes automatically broadcast connectivity status every 30 seconds
+  - New `onBridgeStatusChanged()` callback for connectivity state changes
+  - API methods: `hasInternetConnection()`, `getPrimaryBridge()`, `getBridges()`, `isBridge()`
+  - Status includes Internet connectivity, router RSSI, channel, uptime, gateway IP
+  - Enable offline mode and message queueing when Internet unavailable
+  - Support for bridge failover scenarios
+  - Documentation: `BRIDGE_STATUS_FEATURE.md`
+
+- **Automatic Bridge Failover with RSSI-Based Election (Types 611, 612)** - High-availability bridge management
+  - Distributed bridge election protocol when primary bridge fails
+  - RSSI-based node selection for optimal bridge placement
+  - New `BridgeElectionPackage` (Type 611) for election coordination
+  - New `BridgeTakeoverPackage` (Type 612) for bridge transition announcements
+  - API methods: `enableBridgeFailover()`, `setRouterCredentials()`, `onBridgeRoleChanged()`
+  - Automatic promotion of best-positioned node to bridge role
+  - Tiebreaker rules: uptime, free memory, node ID
+  - Split-brain prevention and oscillation protection
+  - Graceful handling of multiple sequential failures
+  - Critical for production high-availability systems (Issue #64)
+
+- **NTP Time Synchronization (Type 614)** - Bridge-to-mesh NTP time distribution
+  - New `NTPTimeSyncPackage` for broadcasting NTP time from bridge nodes
+  - Bridge nodes with Internet distribute authoritative time to entire mesh
+  - Eliminates per-node NTP queries (saves bandwidth and power)
+  - Supports RTC synchronization for offline operation
+  - Includes accuracy field for time uncertainty tracking
+  - Comprehensive unit tests (5 scenarios, 38 assertions)
+  - Example sketches: `ntpTimeSyncBridge.ino` and `ntpTimeSyncNode.ino`
+  - Documentation: `NTP_TIME_SYNC_FEATURE.md`
+
+- **Bridge-Centric Architecture** - New `initAsBridge()` method for automatic channel detection
+  - Bridge nodes now connect to router first and auto-detect its channel
+  - Mesh network automatically configured on router's channel
+  - Eliminates need for manual channel configuration
+  - Automatically sets root node flags
+  - Graceful fallback to channel 1 if router connection fails
+  
+- **Auto Channel Detection for Regular Nodes** - Support for `channel=0` in `init()`
+  - Regular nodes can now auto-detect mesh channel by scanning all channels
+  - Falls back to channel 1 if mesh not found
+  - Simplifies multi-node deployments
+  
+- **Helper Function** - New `scanForMeshChannel()` static method
+  - Scans all 13 WiFi channels to find mesh SSID
+  - Supports hidden networks
+  - Returns detected channel or 0 if not found
+  - Detailed logging for troubleshooting
 
 ### Changed
 
-- TBD
+- **Enhanced Documentation** - Updated bridge and basic examples
+  - `examples/bridge/bridge.ino` now uses `initAsBridge()` API
+  - `examples/basic/basic.ino` demonstrates auto channel detection
+  - `BRIDGE_TO_INTERNET.md` rewritten with bridge-centric approach
+  - `README.md` includes bridge quick start guide
+  
+- **StationScan Enhancement** - Modified `stationScan()` to support all-channel scanning
+  - When `channel=0`, automatically scans all channels before connecting
+  - Auto-updates mesh channel based on detected network
 
 ### Fixed
 
 - TBD
 
-## [1.7.8] - 2025-11-04
+### Backward Compatibility
+
+- All existing code continues to work without changes
+- Manual channel configuration (`mesh.init(..., channel)`) still supported
+- Legacy `stationManual()` approach still available
+- No breaking API changes
+
+## [1.7.9] - 2025-11-08
+
+### Fixed
+
+- **CI/CD Pipeline** - Fixed submodule initialization failures and PlatformIO test configuration in GitHub Actions workflows
+  - Added explicit `submodules: recursive` to checkout action in CI workflow
+  - Added manual `git submodule update --init --recursive` step for robustness
+  - Ensures test dependencies (ArduinoJson and TaskScheduler) are properly initialized
+  - Fixes build failures where submodules were not available during CI runs
+  - Removed redundant matrix strategy from PlatformIO build test (script builds both platforms anyway)
+  - Changed PlatformIO tests from random to deterministic (tests critical examples: basic, alteriomSensorNode, alteriomMetricsHealth)
+  - Improved concurrency grouping to properly handle PR branch names and prevent premature cancellations
+  - Affects all workflows: ci.yml, release.yml, docs.yml
+
+- **Workflow Triggers** - Fixed duplicate CI runs and cancellation issues on PR branches
+  - Removed unnecessary `copilot/**` pattern from validate-release workflow branches filter
+  - Added explicit branch check in validate-release job condition to only run on main/develop
+  - Prevents validate-release workflow from running on PR branches
+  - Fixed concurrency grouping to use `github.head_ref` for PRs (branch name) instead of `github.ref` (commit SHA)
+  - Ensures proper workflow cancellation behavior and prevents confusion from cancelled runs
+
+- **Example Code** - Fixed compilation errors in alteriomMetricsHealth example
+  - Removed incorrect `userScheduler.size()` call (TaskScheduler API doesn't expose queue size)
+  - Replaced non-existent `toJsonString()` methods with proper JSON serialization pattern
+  - Updated deprecated `DynamicJsonDocument` to `JsonDocument` for ArduinoJson v7 compatibility
+  - Changed `msgType` from `uint8_t` to `uint16_t` to support message types > 255 (400, 604, 605)
+
+### Technical Details
+
+- GitHub Actions now properly initializes git submodules before build steps
+- Both automated checkout with `submodules: recursive` and manual initialization step included
+- Prevents "No such file or directory" errors for test/ArduinoJson and test/TaskScheduler
+- Critical fix for maintaining CI/CD reliability across all build and test workflows
+- Example code now uses proper serialization: `JsonDocument doc; JsonObject obj = doc.to<JsonObject>(); package.addTo(std::move(obj)); serializeJson(doc, msg);`
+
+## [1.7.8] - 2025-11-05
+
+### Added
+
+- **MQTT Schema v0.7.3 Compliance** - Upgraded from v0.7.2 to v0.7.3
+  - Added `message_type` field to SensorPackage (Type 200)
+  - Added `message_type` field to StatusPackage (Type 202)
+  - Added `message_type` field to CommandPackage (Type 400)
+  - All packages now have `message_type` for 90% faster message classification
+  - Full alignment with @alteriom/mqtt-schema v0.7.3 specification
 
 ### Added
 

package/README.md

@@ -97,7 +97,27 @@ This fork includes specialized packages for structured IoT communication:
   - Gateway node identification
   - Enables heterogeneous mesh networks
 
-All packages provide type-safe serialization, automatic JSON conversion, and mesh-wide broadcasting or targeted messaging. They align with mqtt-schema v0.7.2+ for enterprise IoT integration.
+**Bridge Failover & High Availability (v1.8.0):**
+
+- **`BridgeStatusPackage`** (Type 610) - Bridge health monitoring (BRIDGE_STATUS per mqtt-schema v0.7.3+)
+  - Internet connectivity status
+  - Router signal strength (RSSI)
+  - Gateway IP and router channel
+  - Heartbeat for failure detection
+
+- **`BridgeElectionPackage`** (Type 611) - Automatic failover election (BRIDGE_ELECTION per mqtt-schema v0.7.3+)
+  - Router RSSI measurement
+  - Node uptime and free memory
+  - Distributed consensus protocol
+  - RSSI-based winner selection
+
+- **`BridgeTakeoverPackage`** (Type 612) - Bridge role announcement (BRIDGE_TAKEOVER per mqtt-schema v0.7.3+)
+  - New bridge identification
+  - Previous bridge tracking
+  - Takeover reason and timestamp
+  - Seamless failover notification
+
+All packages provide type-safe serialization, automatic JSON conversion, and mesh-wide broadcasting or targeted messaging. They align with mqtt-schema v0.7.3+ for enterprise IoT integration.
 
 #### 🚀 Phase 2 Features (v1.7.0+)
 
@@ -117,6 +137,38 @@ All packages provide type-safe serialization, automatic JSON conversion, and mes
 
 See [Phase 2 Guide](docs/PHASE2_GUIDE.md) for complete documentation.
 
+#### 🔄 Automatic Bridge Failover (v1.8.0)
+
+**High Availability for Critical Systems**
+
+- 🎯 **RSSI-Based Election** - Best signal strength wins bridge role
+- 🔍 **Automatic Detection** - 60-second failure detection via heartbeats
+- ⚡ **Fast Failover** - 60-70 second typical recovery time
+- 🌐 **Distributed Consensus** - No single coordinator, deterministic winner selection
+- 🛡️ **Split-Brain Prevention** - State machine prevents concurrent elections
+- 📊 **Tiebreaker Rules** - RSSI → Uptime → Memory → Node ID
+
+**Use Cases:**
+- Fish farm alarm systems requiring 24/7 Internet connectivity
+- Industrial IoT networks with critical sensor monitoring
+- Smart building systems needing continuous cloud connectivity
+
+**Example:**
+```cpp
+// Enable automatic bridge failover
+mesh.setRouterCredentials(ROUTER_SSID, ROUTER_PASSWORD);
+mesh.enableBridgeFailover(true);
+mesh.onBridgeRoleChanged(&bridgeRoleCallback);
+
+void bridgeRoleCallback(bool isBridge, String reason) {
+  if (isBridge) {
+    Serial.printf("🎯 Promoted to bridge: %s\n", reason.c_str());
+  }
+}
+```
+
+See [Bridge Failover Guide](docs/BRIDGE_FAILOVER.md) and [bridge_failover example](examples/bridge_failover/) for complete documentation.
+
 #### MQTT Bridge Commands
 
 The MQTT bridge enables bidirectional communication between MQTT brokers and mesh networks:
@@ -134,7 +186,7 @@ The MQTT bridge enables bidirectional communication between MQTT brokers and mes
 **Examples:**
 
 - 🌉 [MQTT Command Bridge](examples/mqttCommandBridge/mqttCommandBridge.ino) - Gateway bridge with bidirectional MQTT-mesh routing
-- 📡 [Mesh Command Node](examples/alteriom/mesh_command_node.ino) - Node that receives and handles MQTT commands
+- 📡 [Alteriom Sensor Node](examples/alteriom/alteriom.ino) - Example node using SensorPackage, CommandPackage, and StatusPackage
 
 ### 🌐 Core Features
 
@@ -187,10 +239,12 @@ painlessMesh makes use of the following libraries, which can be installed throug
 - [ArduinoJson](https://github.com/bblanchon/ArduinoJson)
 - [TaskScheduler](https://github.com/arkhipenko/TaskScheduler)
 - [ESPAsyncTCP](https://github.com/me-no-dev/ESPAsyncTCP) (ESP8266)
-- [AsyncTCP](https://github.com/me-no-dev/AsyncTCP) (ESP32)
+- [AsyncTCP](https://github.com/ESP32Async/AsyncTCP) (ESP32) - v3.3.0+ required for ESP32-C6
 
 If platformio is used to install the library, then the dependencies will be installed automatically.
 
+> **⚠️ ESP32-C6 Users:** If you experience crashes with `tcp_alloc` errors, you need AsyncTCP v3.3.0+ with LWIP locking support. Use the [ESP32Async/AsyncTCP](https://github.com/ESP32Async/AsyncTCP) library or see the [ESP32-C6 Compatibility Guide](docs/troubleshooting/ESP32_C6_COMPATIBILITY.md) for details.
+
 ## Quick Start with Alteriom Packages
 
 ### Basic Sensor Node
@@ -240,6 +294,61 @@ void receivedCallback(uint32_t from, String& msg) {
 }
 ```
 
+### Bridge to Internet (Auto Channel Detection)
+
+The new bridge-centric architecture makes it easy to connect your mesh to the Internet via a router. The bridge node automatically detects the router's channel and configures the mesh accordingly.
+
+#### Bridge Node
+
+```cpp
+#include "painlessMesh.h"
+
+#define MESH_PREFIX     "MyMeshNetwork"
+#define MESH_PASSWORD   "somethingSneaky"
+#define ROUTER_SSID     "YourRouterSSID"
+#define ROUTER_PASSWORD "YourRouterPassword"
+
+Scheduler userScheduler;
+painlessMesh mesh;
+
+void setup() {
+  Serial.begin(115200);
+  mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+  
+  // Single call does everything:
+  // 1. Connects to router and detects its channel
+  // 2. Initializes mesh on detected channel
+  // 3. Sets node as root/bridge
+  mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
+                    ROUTER_SSID, ROUTER_PASSWORD,
+                    &userScheduler, 5555);
+  
+  mesh.onReceive(&receivedCallback);
+}
+
+void loop() { mesh.update(); }
+
+void receivedCallback(uint32_t from, String& msg) {
+  // Forward mesh data to Internet services (MQTT, HTTP, etc.)
+}
+```
+
+#### Regular Nodes (Auto Channel Detection)
+
+```cpp
+void setup() {
+  Serial.begin(115200);
+  
+  // channel=0 means auto-detect the mesh channel
+  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, 5555, 
+            WIFI_AP_STA, 0);
+  
+  mesh.onReceive(&receivedCallback);
+}
+```
+
+See [BRIDGE_TO_INTERNET.md](BRIDGE_TO_INTERNET.md) for complete documentation.
+
 ### Package Types
 
 | Type | Class | Purpose | Fields |
@@ -280,7 +389,7 @@ void receivedCallback(uint32_t from, String& msg) {
 - **Home Automation** - Distributed lighting, HVAC control
 - **Industrial Monitoring** - Equipment status, predictive maintenance  
 - **Event Coordination** - Synchronized displays, distributed processing
-- **Bridge Networks** - Connect mesh to WiFi/Internet/MQTT
+- **Bridge Networks** - Connect mesh to WiFi/Internet/MQTT - [📖 Bridge Guide](BRIDGE_TO_INTERNET.md)
 
 ## Development Version: v1.7.8
 
@@ -412,6 +521,7 @@ You can tip me using ko-fi:
 | Topic | Description | Link |
 |-------|-------------|------|
 | **🌳 Architecture** | How painlessMesh works internally | [📖 Architecture](https://alteriom.github.io/painlessMesh/#/architecture/mesh-architecture) |
+| **🌉 Bridge to Internet** | Connect mesh to WiFi/Internet/MQTT | [📖 Bridge Guide](BRIDGE_TO_INTERNET.md) |
 | **🔌 Plugin System** | Create custom message packages | [📖 Plugins](https://alteriom.github.io/painlessMesh/#/architecture/plugin-system) |
 | **🎓 Tutorials** | Step-by-step examples and patterns | [📖 Tutorials](https://alteriom.github.io/painlessMesh/#/tutorials/basic-examples) |
 | **🛠️ Troubleshooting** | Common issues and solutions | [📖 Help](https://alteriom.github.io/painlessMesh/#/troubleshooting/common-issues) |

package/RELEASE_GUIDE.md

@@ -13,9 +13,12 @@ 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. Commit and trigger release
+# 3. 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
-git commit -m "release: v1.6.1"
+git commit -m "release: v1.7.9 - Brief description"
 git push origin main
 ```
 
@@ -76,7 +79,7 @@ version=1.6.1
 
 The release workflow triggers on commits to `main` that:
 1. Modify `library.properties`, `library.json`, `package.json`, or `CHANGELOG.md`
-2. Have a commit message starting with `release:`
+2. Have version files modified OR commit message starting with `release:`
 
 ### What Gets Automated
 
@@ -277,6 +280,43 @@ Note: Manual changes may be overwritten by automatic synchronization.
 
 ## 🔧 Scripts Reference
 
+### `./scripts/release-agent.sh` ⭐ NEW
+
+**Comprehensive release validation and quality assurance.**
+
+The Release Agent performs 21+ automated checks to ensure release readiness:
+
+- ✅ Version consistency across all package files
+- ✅ CHANGELOG completeness and format validation
+- ✅ Build system configuration
+- ✅ Dependency validation
+- ✅ Git tag existence check
+- ✅ Release workflow configuration
+- ✅ Documentation link validation
+- ✅ Test suite status (when available)
+
+**Usage:**
+```bash
+./scripts/release-agent.sh           # Full validation
+./scripts/release-agent.sh --help    # Show help
+./scripts/release-agent.sh --version # Show version
+```
+
+**Benefits:**
+- 🎯 Catches issues before they reach CI/CD
+- 📊 Clear, color-coded output for easy scanning
+- 🔧 Specific solutions for each type of issue
+- 🚀 Comprehensive validation in under 5 seconds
+- ✨ Professional release summary with next steps
+
+**When to Use:**
+- Before every release commit
+- After making version changes
+- When troubleshooting release issues
+- As part of your local release workflow
+
+**See Also:** `.github/agents/release-agent.md` for complete documentation
+
 ### `./scripts/bump-version.sh`
 Updates version in all library files with consistency checks.
 
@@ -346,17 +386,26 @@ npm whoami
 
 **NPM/GitHub Packages Not Published Automatically**
 
-If the automated release ran but NPM and GitHub Packages weren't published, it's likely due to the commit message not matching the required pattern.
+The automated workflow triggers a release in two ways:
+
+1. **Automatic (Recommended)**: When version files are updated in a commit
+   - The workflow detects changes to `library.properties`, `library.json`, or `package.json`
+   - Automatically creates tag, release, and publishes packages when these files are modified
+   - Works seamlessly with PR merges and direct commits
+
+2. **Manual trigger**: Commit message starts with `release:` (lowercase with colon):
 
-The automated workflow requires the commit message to start with `release:` (lowercase with colon):
 ```bash
-# ✅ Correct - Will trigger NPM/GitHub Packages publishing
+# ✅ Correct - Will trigger full release
 git commit -m "release: v1.7.7 - Complete mqtt-schema implementation"
 
-# ❌ Wrong - Will create tag/release but skip NPM publishing  
-git commit -m "Release v1.7.7 - Complete mqtt-schema implementation"
+# ✅ Also works - Version file changes detected automatically
+# (No special commit message needed when library.properties/json/package.json are modified)
+git commit -m "Bump version to 1.7.8"
 ```
 
+**Note**: If version files weren't modified and commit message doesn't start with "release:", the workflow will skip publishing.
+
 **Solution: Use Manual Publishing Workflow**
 
 If this happens, you can manually publish packages: