@alteriom/painlessmesh 1.7.9 → 1.8.1

package/CHANGELOG.md

@@ -7,18 +7,134 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.8.1] - 2025-11-10
+
 ### Added
 
-- TBD
+- **GitHub Copilot Custom Agent Support** - Custom agent configuration now discoverable by GitHub
+  - Moved `copilot-agents.json` to repository root for automatic GitHub Copilot integration
+  - Release Agent now available as `@release-agent` in GitHub Copilot Chat (Enterprise)
+  - Enhanced repository context for all GitHub Copilot users
+  - Complete agent documentation in `.github/agents/` directory
 
 ### Changed
 
-- TBD
+- **Documentation Updates** - Improved clarity for custom agent setup
+  - Updated `COPILOT_AGENT_SETUP.md` with root file location
+  - Enhanced `AGENTS_INDEX.md` with discovery information
+  - Added examples for using custom agents in development workflow
+
+### Fixed
+
+- **Custom Agent Visibility** - Resolved issue where custom agent tasks were not showing in GitHub
+  - GitHub Copilot now automatically discovers the release agent configuration
+  - Agent appears in Copilot Chat suggestions when available
+  - Knowledge sources properly linked for enhanced context
+
+## [1.8.0] - 2025-11-09
+
+### Added
+
+- **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
+
+- **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 |
@@ -284,23 +391,29 @@ void receivedCallback(uint32_t from, String& msg) {
 - **Event Coordination** - Synchronized displays, distributed processing
 - **Bridge Networks** - Connect mesh to WiFi/Internet/MQTT - [📖 Bridge Guide](BRIDGE_TO_INTERNET.md)
 
-## Development Version: v1.7.8
+## Latest Release: v1.8.1 (November 10, 2025)
 
-**In Development** - Next release after v1.7.7
+**GitHub Copilot Integration & Developer Experience**:
 
-See [CHANGELOG](CHANGELOG.md) for upcoming changes.
+- 🤖 **GitHub Copilot Custom Agent** - AI-assisted release management with `@release-agent`
+- 📚 **Enhanced Developer Context** - Improved repository context for all Copilot users
+- ✅ **Release Automation** - 21+ automated validation checks for quality assurance
+- 🔧 **Zero Breaking Changes** - Purely additive developer experience improvements
+- 📖 **Complete Documentation** - Agent setup guides and knowledge sources
 
-## Latest Release: v1.7.7 (November 5, 2025)
+**[📋 Full Release Notes](RELEASE_NOTES_v1.8.1.md)** | **[🔖 CHANGELOG](CHANGELOG.md)**
 
-**MQTT Schema v0.7.2 Compliance with Enhanced Monitoring**:
+## Previous Release: v1.8.0 (November 9, 2025)
 
-- ✅ **MetricsPackage (Type 204)** - Comprehensive performance metrics for real-time monitoring
-- ✅ **HealthCheckPackage (Type 605)** - Proactive health monitoring with problem detection
-- ✅ **Mesh Topology Packages** - Complete network visualization (Types 600-603)
-- ✅ **Enhanced MQTT Bridge** - On-demand metrics, health checks, and aggregated statistics
-- ✅ **100% Backward Compatible** - All existing code continues to work
+**Bridge-Centric Architecture & Comprehensive Monitoring**:
 
-**[📋 Full Release Notes](docs/releases/RELEASE_SUMMARY_v1.7.7.md)** | **[🔖 CHANGELOG](CHANGELOG.md)**
+- ✅ **Bridge Auto-Detection** - One-line bridge setup with automatic channel detection
+- 📊 **Diagnostics API** - Comprehensive monitoring and debugging tools
+- 🕐 **RTC Integration** - Hardware RTC support for offline timekeeping
+- 🔄 **Bridge Failover** - Automatic bridge election and high availability
+- ⚡ **Production Ready** - All features tested, documented, and backward compatible
+
+**[📋 Full Release Notes](RELEASE_NOTES_v1.8.0.md)**
 
 ## Getting Help
 
@@ -311,6 +424,40 @@ See [CHANGELOG](CHANGELOG.md) for upcoming changes.
 
 ## Development
 
+### GitHub Copilot Integration (v1.8.1+)
+
+AlteriomPainlessMesh includes GitHub Copilot custom agent support for AI-assisted development:
+
+- **🤖 Release Agent** - AI assistant for release management and quality assurance
+- **📚 Enhanced Context** - Repository knowledge available to all Copilot users
+- **🎯 Enterprise Features** - Use `@release-agent` in Copilot Chat (Enterprise)
+
+**For GitHub Copilot Enterprise Users:**
+```
+@release-agent How do I prepare a release?
+@release-agent Check version consistency
+@release-agent Validate release readiness
+```
+
+**Configuration:** The custom agent is defined in `copilot-agents.json` at the repository root.
+
+**Documentation:** [Copilot Agent Setup](.github/COPILOT_AGENT_SETUP.md) | [Agent Index](.github/AGENTS_INDEX.md)
+
+### Release Agent & Automation
+
+AlteriomPainlessMesh includes a comprehensive release automation system:
+
+- **📋 [Release Agent Documentation](.github/agents/release-agent.md)** - Complete release process specification
+- **🤖 Release Validation Script**: `./scripts/release-agent.sh` - Automated pre-release checks
+- **⚙️ CI/CD Integration**: Workflows validate every release automatically
+
+**Quick Release Validation:**
+```bash
+./scripts/release-agent.sh  # Run all pre-release checks
+```
+
+See [Release Agent Guide](.github/agents/README.md) for complete documentation.
+
 ### Building from Source
 
 ```bash