@alteriom/painlessmesh 1.7.9 → 1.8.0

package/CHANGELOG.md

@@ -7,18 +7,110 @@ 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
 
+### 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

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:
@@ -242,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 |