@alteriom/painlessmesh 1.8.14 → 1.9.0

package/docs/releases/RELEASE_NOTES_v1.8.0.md

@@ -1,685 +0,0 @@
-# painlessMesh v1.8.0 Release Notes
-
-**Release Date:** November 9, 2025  
-**Version:** 1.8.0  
-**Type:** Major Feature Release  
-**Compatibility:** 100% backward compatible with v1.7.x
-
----
-
-## 🎯 Executive Summary
-
-Version 1.8.0 is a major feature release that transforms painlessMesh into a production-ready solution for bridged mesh networks with comprehensive monitoring, diagnostics, and time synchronization capabilities. This release focuses on bridge operations, adding eight major features that enable robust Internet connectivity, real-time monitoring, automatic failover, and offline operation.
-
-### Key Highlights
-
-✨ **Bridge-Centric Architecture** - Zero-configuration bridge setup with automatic channel detection  
-📊 **Comprehensive Monitoring** - Real-time health metrics and diagnostics API  
-🕐 **Time Synchronization** - NTP distribution with RTC backup  
-🔍 **Diagnostics Tools** - Deep insights into bridge operations and network topology  
-⚡ **Production Ready** - All features tested, documented, and backward compatible
-
----
-
-## 🚀 What's New
-
-### 1. Bridge-Centric Architecture with Auto Channel Detection
-
-The most significant improvement to bridge setup, eliminating manual configuration entirely.
-
-**Before (v1.7.x):**
-```cpp
-mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT, WIFI_AP_STA, 6);
-mesh.stationManual(ROUTER_SSID, ROUTER_PASSWORD);
-mesh.setRoot(true);
-mesh.setContainsRoot(true);
-```
-
-**After (v1.8.0):**
-```cpp
-mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
-                  ROUTER_SSID, ROUTER_PASSWORD,
-                  &userScheduler, MESH_PORT);
-```
-
-**Features:**
-- ✅ Automatic WiFi channel detection from router
-- ✅ One-line bridge initialization
-- ✅ Graceful fallback on connection failure
-- ✅ Support for channel auto-detection on regular nodes (`channel=0`)
-- ✅ New `scanForMeshChannel()` helper function
-- ✅ Comprehensive logging and error handling
-
-**Benefits:**
-- No manual channel configuration required
-- Works with any router out of the box
-- Eliminates most common bridge setup errors
-- Reduces support burden significantly
-
-**PR:** #72 | **Docs:** `BRIDGE_ARCHITECTURE_IMPLEMENTATION.md`
-
----
-
-### 2. Diagnostics API for Bridge Operations
-
-Comprehensive tools for monitoring, debugging, and analyzing bridge operations.
-
-**New API Methods:**
-```cpp
-// Get current bridge status and role
-BridgeStatus status = mesh.getBridgeStatus();
-
-// Get election history (when diagnostics enabled)
-std::vector<ElectionEvent> history = mesh.getElectionHistory();
-
-// Get network topology with neighbor info
-std::vector<TopologyNode> topology = mesh.getNetworkTopology();
-
-// Test connectivity to specific node
-ConnectivityTestResult result = mesh.testConnectivity(nodeId);
-
-// Generate comprehensive diagnostic report
-String report = mesh.generateDiagnosticReport();
-
-// Enable/disable diagnostics tracking
-mesh.enableDiagnostics(true);
-```
-
-**Data Structures:**
-- `BridgeStatus` - Current bridge state and role
-- `ElectionEvent` - Historical bridge election data
-- `TopologyNode` - Network topology information
-- `ConnectivityTestResult` - Connectivity validation
-
-**Use Cases:**
-- Real-time bridge monitoring
-- Troubleshooting connectivity issues
-- Network topology visualization
-- Performance analysis
-- Automated testing
-
-**PR:** #79 | **Docs:** `DIAGNOSTICS_API.md`
-
----
-
-### 3. Bridge Health Monitoring & Metrics Collection
-
-Real-time performance metrics for production monitoring and integration with standard tools.
-
-**New API:**
-```cpp
-// Get comprehensive health metrics
-BridgeHealthMetrics metrics = mesh.getBridgeHealthMetrics();
-
-// Export as JSON for MQTT/Prometheus/Grafana
-String json = mesh.getHealthMetricsJSON();
-
-// Periodic callback (every 60 seconds)
-mesh.onHealthMetricsUpdate(&metricsCallback, 60000);
-
-// Reset counters
-mesh.resetHealthMetrics();
-```
-
-**Metrics Tracked:**
-- **Connectivity:** Uptime, Internet uptime, disconnect count
-- **Signal Quality:** Current/avg/min/max RSSI
-- **Traffic:** Bytes and messages sent/received/queued/dropped
-- **Performance:** Average latency, packet loss, node count
-
-**Integration Examples:**
-- MQTT publishing for cloud monitoring
-- Prometheus exporter for Grafana dashboards
-- CloudWatch metrics for AWS
-- Custom monitoring solutions
-
-**PR:** #78 | **Docs:** `docs/BRIDGE_HEALTH_MONITORING.md` | **Example:** `examples/bridge/bridge_health_monitoring_example.ino`
-
----
-
-### 4. Automatic Bridge Failover with RSSI-Based Election
-
-Production-ready high-availability bridge management with automatic failover when primary bridge fails.
-
-**Architecture:**
-When the primary bridge loses Internet connectivity, mesh nodes automatically:
-1. Detect bridge failure through missing heartbeats
-2. Initiate distributed election protocol
-3. Scan router signal strength (RSSI)
-4. Elect node with best signal as new bridge
-5. Winner promotes itself to bridge role
-
-**New API:**
-```cpp
-// Enable automatic failover
-mesh.enableBridgeFailover(true);
-mesh.setRouterCredentials(ROUTER_SSID, ROUTER_PASSWORD);
-
-// Callback when this node's role changes
-mesh.onBridgeRoleChanged([](bool isBridge, String reason) {
-  if (isBridge) {
-    Serial.printf("🎯 Promoted to bridge: %s\n", reason.c_str());
-  }
-});
-```
-
-**Election Process:**
-1. Nodes broadcast `BridgeElectionPackage` (Type 611) with RSSI
-2. All nodes collect candidates for 5 seconds
-3. Node with best RSSI wins (tiebreaker: uptime → memory → node ID)
-4. Winner broadcasts `BridgeTakeoverPackage` (Type 612)
-5. Winner promotes to bridge using `initAsBridge()`
-
-**Features:**
-- Distributed consensus (no single coordinator)
-- Optimal bridge selection (best signal strength)
-- Split-brain prevention
-- Oscillation protection (60s minimum between changes)
-- Handles multiple sequential failures
-- Critical for life-safety systems (fish farm O2 monitoring)
-
-**PR:** #64 (Issue #64) | **Message Types:** 611 (Election), 612 (Takeover)
-
----
-
-### 5. Bridge Status Broadcast & Callback
-
-Real-time Internet connectivity monitoring for intelligent node behavior.
-
-**New Callback:**
-```cpp
-mesh.onBridgeStatusChanged([](uint32_t bridgeNodeId, bool hasInternet) {
-  if (hasInternet) {
-    Serial.println("✓ Internet available - sending queued data");
-    flushQueuedMessages();
-  } else {
-    Serial.println("⚠ Internet offline - queueing messages");
-    enableOfflineMode();
-  }
-});
-```
-
-**New API Methods:**
-```cpp
-// Check if any bridge has Internet
-bool hasInternet = mesh.hasInternetConnection();
-
-// Get primary (best) bridge
-BridgeInfo* primary = mesh.getPrimaryBridge();
-
-// Get all known bridges
-std::vector<BridgeInfo> bridges = mesh.getBridges();
-
-// Check if this node is a bridge
-bool isBridge = mesh.isBridge();
-```
-
-**Status Information:**
-- Internet connectivity state
-- Router signal strength (RSSI)
-- WiFi channel
-- Bridge uptime
-- Gateway IP address
-
-**Use Cases:**
-- Message queueing during Internet outages
-- Bridge failover implementation
-- User feedback about connectivity
-- Intelligent routing decisions
-
-**PR:** #73 | **Docs:** `BRIDGE_STATUS_FEATURE.md`
-
----
-
-### 6. NTP Time Synchronization (Type 614)
-
-Bridge-to-mesh NTP time distribution, eliminating the need for per-node NTP queries.
-
-**Architecture:**
-```
-Internet → Bridge (NTP Client) → Mesh → All Nodes (Synchronized)
-```
-
-**Features:**
-- Bridge nodes fetch NTP time and distribute to mesh
-- Eliminates per-node NTP queries (saves bandwidth and power)
-- Automatic fallback to mesh time if NTP unavailable
-- Accuracy field for time uncertainty tracking
-- RTC integration for offline operation
-
-**New Package Type:**
-```cpp
-// Type 614: NTP_TIME_SYNC
-NTPTimeSyncPackage pkg;
-pkg.unixTimestamp = ntpTime;
-pkg.accuracyMs = 50;  // ±50ms accuracy
-mesh.sendBroadcast(pkg.toJson());
-```
-
-**Benefits:**
-- Centralized time management
-- Reduced Internet bandwidth usage
-- Power savings on battery nodes
-- Coordinated time-based operations
-
-**PR:** #77 | **Docs:** `NTP_TIME_SYNC_FEATURE.md` | **Examples:** `ntpTimeSyncBridge.ino`, `ntpTimeSyncNode.ino`
-
----
-
-### 7. RTC (Real-Time Clock) Integration
-
-Hardware RTC support for time persistence across reboots and offline operation.
-
-**Supported Modules:**
-- DS3231 (high precision, temperature compensated)
-- DS1307 (basic RTC)
-- PCF8523 (low power)
-
-**Features:**
-- Automatic time persistence across power failures
-- Seamless integration with NTP time sync
-- RTC updates from NTP when available
-- Fallback to RTC when offline
-- Comprehensive unit tests
-
-**Use Cases:**
-- Offline time tracking
-- Time-critical operations without Internet
-- Data timestamping during outages
-- Scheduled tasks without network
-
-**PR:** #76 | **Tests:** `test/catch/catch_rtc.cpp`
-
----
-
-### 8. Enhanced Documentation & Examples
-
-**New Documentation Files:**
-- `DIAGNOSTICS_API.md` - Comprehensive diagnostics guide
-- `BRIDGE_ARCHITECTURE_IMPLEMENTATION.md` - Technical bridge details
-- `BRIDGE_STATUS_FEATURE.md` - Status broadcast documentation
-- `BRIDGE_HEALTH_MONITORING.md` - Metrics collection guide
-- `NTP_TIME_SYNC_FEATURE.md` - NTP implementation details
-- `BRIDGE_TO_INTERNET.md` - Updated bridge setup guide
-
-**New Examples:**
-- `examples/diagnostics/` - Diagnostics API usage
-- `examples/bridge/bridge_health_monitoring_example.ino` - Metrics collection
-- `ntpTimeSyncBridge.ino` - NTP distribution from bridge
-- `ntpTimeSyncNode.ino` - NTP reception on nodes
-
-**Updated Examples:**
-- `examples/bridge/bridge.ino` - Uses new `initAsBridge()` API
-- `examples/basic/basic.ino` - Demonstrates auto channel detection
-
----
-
-## 📊 Technical Statistics
-
-### Code Delivered
-
-- **New Files:** 15+ files
-- **Modified Files:** 20+ files
-- **Lines Added:** 5,000+ lines of production code
-- **Test Assertions:** 1,500+ (including 300+ new tests)
-- **Documentation:** 50+ pages
-
-### Test Coverage
-
-✅ All existing tests passing (1,200+ assertions)  
-✅ 300+ new test assertions for new features  
-✅ Zero compilation warnings  
-✅ Zero security vulnerabilities  
-✅ ESP32 and ESP8266 compatibility verified
-
-### Performance Characteristics
-
-- **Memory Overhead:** <5KB for all new features
-- **CPU Overhead:** <2% additional usage
-- **Network Bandwidth:** ~150 bytes/sec for full feature set (10 nodes)
-- **Latency Impact:** Negligible (<1ms)
-
----
-
-## 🔄 Migration Guide
-
-### From v1.7.x to v1.8.0
-
-**No breaking changes!** Version 1.8.0 is 100% backward compatible.
-
-### Adopting New Features (Optional)
-
-#### 1. Upgrade Bridge Nodes
-
-**Simple (recommended):**
-```cpp
-// Replace old initialization code with:
-mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
-                  ROUTER_SSID, ROUTER_PASSWORD,
-                  &userScheduler, MESH_PORT);
-```
-
-**Advanced (with monitoring):**
-```cpp
-mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
-                  ROUTER_SSID, ROUTER_PASSWORD,
-                  &userScheduler, MESH_PORT);
-
-// Enable health monitoring
-mesh.onHealthMetricsUpdate([](BridgeHealthMetrics metrics) {
-  String json = mesh.getHealthMetricsJSON();
-  mqttClient.publish("bridge/metrics", json.c_str());
-}, 60000);
-
-// Enable diagnostics
-mesh.enableDiagnostics(true);
-```
-
-#### 2. Add Bridge Status Monitoring to Nodes
-
-```cpp
-mesh.onBridgeStatusChanged([](uint32_t bridgeNodeId, bool hasInternet) {
-  if (hasInternet) {
-    flushQueuedMessages();
-  } else {
-    enableOfflineMode();
-  }
-});
-```
-
-#### 3. Enable Auto Channel Detection
-
-```cpp
-// For regular nodes, use channel=0 for auto-detection
-mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT, WIFI_AP_STA, 0);
-```
-
-#### 4. Add NTP Time Sync
-
-**Bridge:**
-```cpp
-#include <NTPClient.h>
-WiFiUDP ntpUDP;
-NTPClient timeClient(ntpUDP);
-
-// In setup()
-timeClient.begin();
-
-// In loop()
-timeClient.update();
-NTPTimeSyncPackage pkg;
-pkg.unixTimestamp = timeClient.getEpochTime();
-mesh.sendBroadcast(pkg.toJson());
-```
-
-**Node:**
-```cpp
-mesh.onReceive([](uint32_t from, String& msg) {
-  // Parse NTP time and sync local clock
-  // See examples for complete implementation
-});
-```
-
----
-
-## 🎯 Use Cases Enabled
-
-### Production IoT Deployments
-
-- **Enterprise Networks:** Robust bridge connectivity with failover
-- **Industrial IoT:** Real-time monitoring and diagnostics
-- **Smart Buildings:** Time-synchronized operations
-- **Environmental Monitoring:** Reliable data collection with offline support
-
-### Commercial Applications
-
-- **Professional Monitoring:** Integration with Grafana, Prometheus, CloudWatch
-- **SLA Compliance:** Detailed uptime and performance metrics
-- **Predictive Maintenance:** Early problem detection
-- **Automated Alerting:** Critical event notifications
-
-### Development & Testing
-
-- **Troubleshooting:** Comprehensive diagnostic tools
-- **Performance Analysis:** Real-time metrics collection
-- **Network Visualization:** Topology mapping
-- **Quality Assurance:** Connectivity testing
-
----
-
-## 🔧 Configuration Examples
-
-### Complete Bridge Setup
-
-```cpp
-#include "painlessMesh.h"
-#include <NTPClient.h>
-
-#define MESH_PREFIX "MyMesh"
-#define MESH_PASSWORD "meshpass"
-#define ROUTER_SSID "MyRouter"
-#define ROUTER_PASSWORD "routerpass"
-#define MESH_PORT 5555
-
-painlessMesh mesh;
-WiFiUDP ntpUDP;
-NTPClient timeClient(ntpUDP);
-
-void setup() {
-  Serial.begin(115200);
-  
-  // Initialize as bridge with auto channel detection
-  mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
-                    ROUTER_SSID, ROUTER_PASSWORD,
-                    &userScheduler, MESH_PORT);
-  
-  // Enable diagnostics
-  mesh.enableDiagnostics(true);
-  
-  // Health metrics callback (every 60 seconds)
-  mesh.onHealthMetricsUpdate([](BridgeHealthMetrics metrics) {
-    Serial.printf("Uptime: %us, Nodes: %u, RSSI: %d dBm\n",
-                  metrics.uptimeSeconds,
-                  metrics.meshNodeCount,
-                  metrics.currentRSSI);
-  }, 60000);
-  
-  // Start NTP client
-  timeClient.begin();
-  
-  Serial.println("Bridge node initialized");
-}
-
-void loop() {
-  mesh.update();
-  timeClient.update();
-  
-  // Distribute NTP time every 10 seconds
-  static unsigned long lastNTP = 0;
-  if (millis() - lastNTP > 10000) {
-    lastNTP = millis();
-    NTPTimeSyncPackage pkg;
-    pkg.unixTimestamp = timeClient.getEpochTime();
-    pkg.accuracyMs = 50;
-    mesh.sendBroadcast(pkg.toJson());
-  }
-}
-```
-
-### Complete Regular Node Setup
-
-```cpp
-#include "painlessMesh.h"
-
-#define MESH_PREFIX "MyMesh"
-#define MESH_PASSWORD "meshpass"
-#define MESH_PORT 5555
-
-painlessMesh mesh;
-bool offlineMode = false;
-
-void setup() {
-  Serial.begin(115200);
-  
-  // Initialize with auto channel detection
-  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT, WIFI_AP_STA, 0);
-  
-  // Bridge status callback
-  mesh.onBridgeStatusChanged([](uint32_t bridgeNodeId, bool hasInternet) {
-    offlineMode = !hasInternet;
-    if (hasInternet) {
-      Serial.println("✓ Internet available");
-    } else {
-      Serial.println("⚠ Internet offline");
-    }
-  });
-  
-  // Message receiver
-  mesh.onReceive(&receivedCallback);
-  
-  Serial.println("Regular node initialized");
-}
-
-void loop() {
-  mesh.update();
-  
-  // Your application logic here
-}
-
-void receivedCallback(uint32_t from, String& msg) {
-  // Handle NTP time sync and other messages
-}
-```
-
----
-
-## ⚠️ Known Limitations
-
-1. **Single Bridge Support** - Current architecture assumes one bridge node (multi-bridge in v1.8.1)
-2. **2.4GHz Only** - Channels 1-13, no 5GHz support (hardware limitation)
-3. **Blocking Bridge Init** - Bridge initialization blocks for up to 30s during router connection
-4. **No Dynamic Channel Switching** - Requires restart if router changes channel
-
----
-
-## 🔮 Future Roadmap (v1.8.1)
-
-Planned features for next release:
-
-- **Message Queuing (#66)** - Automatic message queuing during Internet outages
-- **Multi-Bridge Coordination (#65)** - Load balancing across multiple bridges
-- **Automatic Bridge Failover (#64)** - RSSI-based election when primary fails
-- **Enhanced Diagnostics** - Machine learning-based failure prediction
-- **Cloud Integration** - Native AWS IoT and Azure IoT Hub support
-
----
-
-## 📋 Upgrade Checklist
-
-### For Bridge Nodes
-
-- [ ] Update to v1.8.0
-- [ ] Replace old initialization with `initAsBridge()`
-- [ ] Enable health metrics (optional)
-- [ ] Enable diagnostics (optional)
-- [ ] Add NTP time distribution (optional)
-- [ ] Test bridge connectivity
-- [ ] Monitor metrics in production
-
-### For Regular Nodes
-
-- [ ] Update to v1.8.0
-- [ ] Enable auto channel detection (`channel=0`)
-- [ ] Add bridge status callback (optional)
-- [ ] Add NTP time sync receiver (optional)
-- [ ] Test connectivity
-- [ ] Verify time synchronization
-
-### For Monitoring Infrastructure
-
-- [ ] Subscribe to health metrics topics
-- [ ] Configure Grafana/Prometheus dashboards
-- [ ] Set up alerting rules
-- [ ] Test end-to-end monitoring
-- [ ] Document alert procedures
-
----
-
-## 🐛 Bug Fixes
-
-This release also includes several important bug fixes from v1.7.9:
-
-- Fixed submodule initialization in CI/CD pipeline
-- Fixed compilation errors in alteriomMetricsHealth example
-- Fixed workflow triggers and concurrency issues
-- Updated deprecated ArduinoJson API usage
-- Improved PlatformIO test reliability
-
----
-
-## 📚 Resources
-
-### Documentation
-
-- **Release Notes:** `RELEASE_NOTES_v1.8.0.md` (this file)
-- **Changelog:** `CHANGELOG.md`
-- **API Reference:** See individual feature docs
-- **Examples:** `examples/` directory
-- **Website:** https://alteriom.github.io/painlessMesh/
-
-### Support
-
-- **GitHub Issues:** https://github.com/Alteriom/painlessMesh/issues
-- **Discussions:** https://github.com/Alteriom/painlessMesh/discussions
-- **Examples:** Complete working examples included
-
-### Getting Help
-
-1. Check documentation and examples
-2. Search existing issues
-3. Test with provided examples
-4. Report issues with logs and configuration
-
----
-
-## 🎉 Credits
-
-**Contributors:**
-- Alteriom Team - Feature design and implementation
-- GitHub Copilot - Development assistance
-- painlessMesh Community - Testing and feedback
-- @woodlist - Feature requests and real-world use cases
-
-**Special Thanks:**
-- Original painlessMesh authors and maintainers
-- ArduinoJson and TaskScheduler libraries
-- ESP32/ESP8266 communities
-
----
-
-## 📄 License
-
-LGPL-3.0 - Same as painlessMesh
-
----
-
-**Ready to Upgrade?** Follow the migration guide above to get started with v1.8.0 today!
-
-**Questions?** Open an issue on GitHub or join our discussions.
-
----
-
-## Quick Links
-
-- 📦 [Download v1.8.0](https://github.com/Alteriom/painlessMesh/releases/tag/v1.8.0)
-- 📖 [Full Documentation](https://alteriom.github.io/painlessMesh/)
-- 🐛 [Report Issues](https://github.com/Alteriom/painlessMesh/issues)
-- 💬 [Community Discussions](https://github.com/Alteriom/painlessMesh/discussions)
-- 🔧 [Examples Directory](examples/)
-
----
-
-**Version:** 1.8.0  
-**Release Date:** November 9, 2025  
-**Build Status:** ✅ All tests passing  
-**Compatibility:** 100% backward compatible with v1.7.x