@alteriom/painlessmesh 1.7.8 → 1.8.0

package/src/painlessmesh/mesh.hpp

@@ -10,6 +10,7 @@
 #include "painlessmesh/ntp.hpp"
 #include "painlessmesh/plugin.hpp"
 #include "painlessmesh/protocol.hpp"
+#include "painlessmesh/rtc.hpp"
 #include "painlessmesh/tcp.hpp"
 
 #ifdef PAINLESSMESH_ENABLE_OTA
@@ -23,6 +24,119 @@ typedef std::function<void(uint32_t from, TSTRING &msg)> receivedCallback_t;
 typedef std::function<void()> changedConnectionsCallback_t;
 typedef std::function<void(int32_t offset)> nodeTimeAdjustedCallback_t;
 typedef std::function<void(uint32_t nodeId, int32_t delay)> nodeDelayCallback_t;
+typedef std::function<void(uint32_t bridgeNodeId, bool internetAvailable)> bridgeStatusChangedCallback_t;
+typedef std::function<void(uint32_t timestamp)> rtcSyncCompleteCallback_t;
+
+/**
+ * Bridge information structure
+ * 
+ * Tracks the status and health of bridge nodes in the mesh network
+ */
+class BridgeInfo {
+public:
+  uint32_t nodeId = 0;              // Bridge node ID
+  bool internetConnected = false;   // Is bridge connected to Internet?
+  int8_t routerRSSI = 0;           // Router WiFi signal strength in dBm
+  uint8_t routerChannel = 0;       // Router WiFi channel
+  uint32_t lastSeen = 0;           // Timestamp when last status received (millis)
+  uint32_t uptime = 0;             // Bridge uptime in milliseconds
+  TSTRING gatewayIP = "";          // Router gateway IP address
+  uint32_t timestamp = 0;          // Timestamp from bridge status message
+  
+  /**
+   * Check if this bridge is considered healthy
+   * A bridge is healthy if we've received a status update within the timeout period
+   */
+  bool isHealthy(uint32_t timeoutMs = 60000) const {
+    return (millis() - lastSeen) < timeoutMs;
+  }
+};
+
+/**
+ * Bridge Health Metrics structure
+ * 
+ * Comprehensive metrics for monitoring bridge health, connectivity quality,
+ * and performance. Useful for troubleshooting and capacity planning.
+ */
+struct BridgeHealthMetrics {
+  // Connectivity
+  uint32_t uptimeSeconds = 0;
+  uint32_t internetUptimeSeconds = 0;
+  uint32_t totalDisconnects = 0;
+  uint32_t currentUptime = 0;
+  
+  // Signal Quality
+  int8_t currentRSSI = 0;
+  int8_t avgRSSI = 0;
+  int8_t minRSSI = 0;
+  int8_t maxRSSI = -127;
+  
+  // Traffic
+  uint64_t bytesRx = 0;
+  uint64_t bytesTx = 0;
+  uint32_t messagesRx = 0;
+  uint32_t messagesTx = 0;
+  uint32_t messagesQueued = 0;
+  uint32_t messagesDropped = 0;
+  
+  // Performance
+  uint32_t avgLatencyMs = 0;
+  uint8_t packetLossPercent = 0;
+  uint32_t meshNodeCount = 0;
+};
+
+/**
+ * Bridge Status structure
+ * 
+ * Current status of this node's bridge role and connectivity
+ */
+struct BridgeStatus {
+  bool isBridge = false;              // Is this node acting as a bridge?
+  bool internetConnected = false;     // Is Internet connection available?
+  TSTRING role = "regular";           // Role: "regular", "bridge", "root"
+  uint32_t bridgeNodeId = 0;          // Current bridge node ID (0 if none)
+  int8_t bridgeRSSI = 0;             // Signal strength to bridge/router (dBm)
+  uint32_t timeSinceBridgeChange = 0; // Time since last bridge change (ms)
+};
+
+/**
+ * Election Record structure
+ * 
+ * Records information about bridge election events
+ */
+struct ElectionRecord {
+  uint32_t timestamp = 0;          // When election occurred (millis)
+  uint32_t winnerNodeId = 0;       // Node that won election
+  int8_t winnerRSSI = 0;          // Winner's router RSSI
+  uint32_t candidateCount = 0;    // Number of candidates
+  TSTRING reason = "";             // Why election was triggered
+};
+
+/**
+ * Bridge Change Event structure
+ * 
+ * Records the last bridge change event
+ */
+struct BridgeChangeEvent {
+  uint32_t timestamp = 0;            // When change occurred (millis)
+  uint32_t oldBridgeId = 0;         // Previous bridge node ID
+  uint32_t newBridgeId = 0;         // New bridge node ID
+  TSTRING reason = "";               // Reason for change
+  bool internetAvailable = false;    // Internet available after change
+};
+
+/**
+ * Bridge Connectivity Test Result
+ * 
+ * Results from bridge connectivity testing
+ */
+struct BridgeTestResult {
+  bool success = false;              // Overall test success
+  bool bridgeReachable = false;      // Can reach bridge node
+  bool internetReachable = false;    // Can reach Internet (if bridge available)
+  uint32_t latencyMs = 0;           // Round-trip latency to bridge
+  TSTRING message = "";              // Detailed test message
+};
 
 /**
  * Main api class for the mesh
@@ -49,6 +163,38 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     this->callbackList = painlessmesh::router::addPackageCallback(
         std::move(this->callbackList), (*this));
 
+    // Add bridge status package handler (Type 610)
+    // This will be called when any node receives a bridge status broadcast
+    this->callbackList.onPackage(
+        610,  // BRIDGE_STATUS type
+        [this](protocol::Variant& variant, std::shared_ptr<T>, uint32_t) {
+          // We need to manually parse the JSON since BridgeStatusPackage is in alteriom namespace
+          // and may not be available in all contexts. We'll parse the critical fields directly.
+          JsonDocument doc;
+          TSTRING str;
+          variant.printTo(str);
+          deserializeJson(doc, str);
+          JsonObject obj = doc.as<JsonObject>();
+          
+          if (obj["internetConnected"].is<bool>()) {
+            uint32_t bridgeNodeId = obj["from"];
+            bool internetConnected = obj["internetConnected"];
+            int8_t routerRSSI = obj["routerRSSI"] | 0;
+            uint8_t routerChannel = obj["routerChannel"] | 0;
+            uint32_t uptime = obj["uptime"] | 0;
+            TSTRING gatewayIP = obj["gatewayIP"].as<TSTRING>();
+            uint32_t timestamp = obj["timestamp"] | 0;
+            
+            // Update bridge status
+            this->updateBridgeStatus(bridgeNodeId, internetConnected, routerRSSI, 
+                                    routerChannel, uptime, gatewayIP, timestamp);
+            
+            Log(GENERAL, "Bridge status received from %u: Internet %s\n",
+                bridgeNodeId, internetConnected ? "Connected" : "Disconnected");
+          }
+          return false;  // Don't consume the package, allow other handlers
+        });
+
     this->changedConnectionCallbacks.push_back([this](uint32_t nodeId) {
       Log(MESH_STATUS, "Changed connections in neighbour %u\n", nodeId);
       if (nodeId != 0) layout::syncLayout<T>((*this), nodeId);
@@ -56,6 +202,7 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     this->droppedConnectionCallbacks.push_back([this](uint32_t nodeId,
                                                       bool station) {
       Log(MESH_STATUS, "Dropped connection %u, station %d\n", nodeId, station);
+      this->metricsDisconnectCount++;
       this->eraseClosedConnections();
     });
     this->newConnectionCallbacks.push_back([](uint32_t nodeId) {
@@ -340,6 +487,329 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     nodeDelayReceivedCallback = onDelayReceived;
   }
 
+  /** Callback that gets called when bridge status changes.
+   *
+   * This fires when a bridge node reports a change in Internet connectivity status.
+   * Useful for implementing failover logic or message queueing.
+   *
+   * \code
+   * mesh.onBridgeStatusChanged([](auto bridgeNodeId, auto hasInternet) {
+   *    if (hasInternet) {
+   *      Serial.println("Internet available - sending queued data");
+   *    } else {
+   *      Serial.println("Internet offline - queueing messages");
+   *    }
+   * });
+   * \endcode
+   */
+  void onBridgeStatusChanged(bridgeStatusChangedCallback_t onBridgeStatusChanged) {
+    Log(logger::GENERAL, "onBridgeStatusChanged():\n");
+    bridgeStatusChangedCallback = onBridgeStatusChanged;
+  }
+
+  /**
+   * Check if any bridge in the mesh has Internet connectivity
+   * 
+   * @return true if at least one healthy bridge reports Internet connection
+   */
+  bool hasInternetConnection() {
+    for (const auto& bridge : knownBridges) {
+      if (bridge.isHealthy(bridgeTimeoutMs) && bridge.internetConnected) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Get list of all known bridges in the mesh
+   * 
+   * @return vector of BridgeInfo objects for all tracked bridges
+   */
+  std::vector<BridgeInfo> getBridges() {
+    return knownBridges;
+  }
+
+  /**
+   * Get the primary (best) bridge node
+   * 
+   * Primary bridge is selected based on:
+   * 1. Must be healthy (seen within timeout)
+   * 2. Must have Internet connection
+   * 3. Best WiFi RSSI to router
+   * 
+   * @return pointer to BridgeInfo of primary bridge, or nullptr if no suitable bridge
+   */
+  BridgeInfo* getPrimaryBridge() {
+    BridgeInfo* primary = nullptr;
+    int8_t bestRSSI = -127;  // Worst possible RSSI
+    
+    for (auto& bridge : knownBridges) {
+      if (bridge.isHealthy(bridgeTimeoutMs) && bridge.internetConnected) {
+        if (bridge.routerRSSI > bestRSSI) {
+          bestRSSI = bridge.routerRSSI;
+          primary = &bridge;
+        }
+      }
+    }
+    
+    return primary;
+  }
+
+  /**
+   * Check if this node is acting as a bridge
+   * 
+   * @return true if this node is configured as a root node (typically bridges)
+   */
+  bool isBridge() {
+    return this->root;
+  }
+
+  /**
+   * Set the interval for bridge status broadcasts (bridge nodes only)
+   * 
+   * @param intervalMs Broadcast interval in milliseconds (default: 30000 = 30 seconds)
+   */
+  void setBridgeStatusInterval(uint32_t intervalMs) {
+    bridgeStatusIntervalMs = intervalMs;
+  }
+
+  /**
+   * Set the timeout for considering a bridge offline
+   * 
+   * @param timeoutMs Timeout in milliseconds (default: 60000 = 60 seconds)
+   */
+  void setBridgeTimeout(uint32_t timeoutMs) {
+    bridgeTimeoutMs = timeoutMs;
+  }
+
+  /**
+   * Enable or disable bridge status broadcasting (bridge nodes only)
+   * 
+   * @param enabled true to enable broadcasting (default), false to disable
+   */
+  void enableBridgeStatusBroadcast(bool enabled) {
+    bridgeStatusBroadcastEnabled = enabled;
+  }
+
+  /**
+   * Update bridge information from received status package
+   * Internal method called when bridge status is received
+   * 
+   * @param bridgeNodeId ID of the bridge node
+   * @param internetConnected Internet connectivity status
+   * @param routerRSSI Router signal strength
+   * @param routerChannel Router WiFi channel
+   * @param uptime Bridge uptime
+   * @param gatewayIP Router gateway IP
+   * @param timestamp Status timestamp
+   */
+  void updateBridgeStatus(uint32_t bridgeNodeId, bool internetConnected, 
+                         int8_t routerRSSI, uint8_t routerChannel,
+                         uint32_t uptime, TSTRING gatewayIP, uint32_t timestamp) {
+    // Find existing bridge or add new one
+    BridgeInfo* bridge = nullptr;
+    uint32_t oldPrimaryBridgeId = 0;
+    auto oldPrimary = this->getPrimaryBridge();
+    if (oldPrimary != nullptr) {
+      oldPrimaryBridgeId = oldPrimary->nodeId;
+    }
+    
+    for (auto& b : knownBridges) {
+      if (b.nodeId == bridgeNodeId) {
+        bridge = &b;
+        break;
+      }
+    }
+    
+    bool wasConnected = false;
+    bool isNewBridge = false;
+    if (bridge == nullptr) {
+      // New bridge - add to list
+      BridgeInfo newBridge;
+      newBridge.nodeId = bridgeNodeId;
+      knownBridges.push_back(newBridge);
+      bridge = &knownBridges.back();
+      isNewBridge = true;
+    } else {
+      wasConnected = bridge->internetConnected;
+    }
+    
+    // Update bridge info
+    bridge->internetConnected = internetConnected;
+    bridge->routerRSSI = routerRSSI;
+    bridge->routerChannel = routerChannel;
+    bridge->lastSeen = millis();
+    bridge->uptime = uptime;
+    bridge->gatewayIP = gatewayIP;
+    bridge->timestamp = timestamp;
+    
+    // Check if primary bridge changed
+    auto newPrimary = this->getPrimaryBridge();
+    uint32_t newPrimaryBridgeId = (newPrimary != nullptr) ? newPrimary->nodeId : 0;
+    
+    if (diagnosticsEnabled && oldPrimaryBridgeId != newPrimaryBridgeId) {
+      // Record bridge change
+      lastBridgeChange.timestamp = millis();
+      lastBridgeChange.oldBridgeId = oldPrimaryBridgeId;
+      lastBridgeChange.newBridgeId = newPrimaryBridgeId;
+      lastBridgeChange.internetAvailable = internetConnected;
+      if (isNewBridge) {
+        lastBridgeChange.reason = "New bridge discovered";
+      } else if (internetConnected && !wasConnected) {
+        lastBridgeChange.reason = "Bridge Internet restored";
+      } else if (!internetConnected && wasConnected) {
+        lastBridgeChange.reason = "Bridge Internet lost";
+      } else {
+        lastBridgeChange.reason = "Primary bridge changed";
+      }
+      
+      lastBridgeChangeTime = millis();
+      Log(logger::GENERAL, "updateBridgeStatus(): Bridge change recorded\n");
+    }
+    
+    // Trigger callback if status changed
+    if (wasConnected != internetConnected && bridgeStatusChangedCallback) {
+      bridgeStatusChangedCallback(bridgeNodeId, internetConnected);
+    }
+  }
+
+  /**
+   * Enable RTC integration for offline timekeeping
+   * 
+   * Allows nodes to maintain accurate timestamps even when Internet/bridge
+   * is unavailable. User must provide an implementation of RTCInterface
+   * for their specific RTC hardware.
+   * 
+   * \code
+   * // Example with DS3231 RTC
+   * class MyRTC : public painlessmesh::rtc::RTCInterface {
+   *   // ... implement interface methods ...
+   * };
+   * MyRTC myRTC;
+   * mesh.enableRTC(&myRTC);
+   * \endcode
+   * 
+   * @param rtcInterface Pointer to user's RTC implementation
+   * @return true if RTC enabled successfully, false otherwise
+   */
+  bool enableRTC(rtc::RTCInterface* rtcInterface) {
+    using namespace logger;
+    Log(GENERAL, "enableRTC(): Initializing RTC\n");
+    return rtcManager.enable(rtcInterface);
+  }
+
+  /**
+   * Disable RTC integration
+   */
+  void disableRTC() {
+    using namespace logger;
+    Log(GENERAL, "disableRTC(): Disabling RTC\n");
+    rtcManager.disable();
+  }
+
+  /**
+   * Sync RTC from NTP/Internet time source
+   * 
+   * Should be called when Internet connection is available to update
+   * the RTC with accurate time. Typically called in onBridgeStatusChanged
+   * callback when Internet becomes available.
+   * 
+   * \code
+   * mesh.onBridgeStatusChanged([](auto bridgeNodeId, auto hasInternet) {
+   *   if (hasInternet) {
+   *     // Get NTP time and sync RTC
+   *     uint32_t ntpTime = getNTPTime();  // User implements this
+   *     if (mesh.syncRTCFromNTP(ntpTime)) {
+   *       Serial.println("RTC synced successfully");
+   *     }
+   *   }
+   * });
+   * \endcode
+   * 
+   * @param ntpTimestamp Unix timestamp from NTP source
+   * @return true if sync successful, false otherwise
+   */
+  bool syncRTCFromNTP(uint32_t ntpTimestamp) {
+    using namespace logger;
+    Log(GENERAL, "syncRTCFromNTP(): Syncing RTC to timestamp %u\n", ntpTimestamp);
+    
+    if (!rtcManager.isEnabled()) {
+      Log(ERROR, "syncRTCFromNTP(): RTC not enabled\n");
+      return false;
+    }
+    
+    bool success = rtcManager.syncFromNTP(ntpTimestamp);
+    
+    if (success && rtcSyncCompleteCallback) {
+      rtcSyncCompleteCallback(ntpTimestamp);
+    }
+    
+    return success;
+  }
+
+  /**
+   * Get accurate time with RTC fallback
+   * 
+   * Returns time from RTC if available, otherwise falls back to mesh time.
+   * This provides the most accurate timestamp available to the node.
+   * 
+   * @return Unix timestamp in seconds, or mesh time in microseconds if RTC unavailable
+   */
+  uint32_t getAccurateTime() {
+    if (rtcManager.isEnabled()) {
+      uint32_t rtcTime = rtcManager.getTime();
+      if (rtcTime > 0) {
+        return rtcTime;
+      }
+    }
+    // Fallback to mesh time (microseconds)
+    return this->getNodeTime();
+  }
+
+  /**
+   * Check if RTC is enabled and available
+   * 
+   * @return true if RTC can be used, false otherwise
+   */
+  bool hasRTC() const {
+    return rtcManager.isEnabled();
+  }
+
+  /**
+   * Get RTC type
+   * 
+   * @return RTCType enum value, or RTC_NONE if no RTC enabled
+   */
+  rtc::RTCType getRTCType() const {
+    return rtcManager.getType();
+  }
+
+  /**
+   * Get time since last RTC sync
+   * 
+   * @return Milliseconds since last RTC sync, or 0 if never synced
+   */
+  uint32_t getTimeSinceRTCSync() const {
+    return rtcManager.getTimeSinceLastSync();
+  }
+
+  /**
+   * Callback when RTC sync completes
+   * 
+   * This fires when syncRTCFromNTP() successfully updates the RTC.
+   * 
+   * \code
+   * mesh.onRTCSyncComplete([](auto timestamp) {
+   *   Serial.printf("RTC synced to: %u\n", timestamp);
+   * });
+   * \endcode
+   */
+  void onRTCSyncComplete(rtcSyncCompleteCallback_t onRTCSyncComplete) {
+    Log(logger::GENERAL, "onRTCSyncComplete():\n");
+    rtcSyncCompleteCallback = onRTCSyncComplete;
+  }
+
   /**
    * Are we connected/know a route to the given node?
    *
@@ -456,6 +926,634 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     return table;
   }
 
+  /**
+   * Get bridge health metrics
+   * 
+   * Collects comprehensive health metrics including connectivity, signal quality,
+   * traffic, and performance data. Useful for monitoring and troubleshooting.
+   * 
+   * \code
+   * auto metrics = mesh.getBridgeHealthMetrics();
+   * Serial.printf("Uptime: %u s, Messages RX: %u, Avg Latency: %u ms\n",
+   *               metrics.uptimeSeconds, metrics.messagesRx, metrics.avgLatencyMs);
+   * \endcode
+   * 
+   * @return BridgeHealthMetrics structure with current metrics
+   */
+  BridgeHealthMetrics getBridgeHealthMetrics() {
+    BridgeHealthMetrics metrics;
+    
+    // Connectivity metrics
+    metrics.uptimeSeconds = millis() / 1000;
+    metrics.currentUptime = millis();
+    
+    // Check for primary bridge with Internet connection
+    auto primaryBridge = getPrimaryBridge();
+    if (primaryBridge != nullptr) {
+      metrics.internetUptimeSeconds = (millis() - primaryBridge->lastSeen) / 1000;
+      metrics.currentRSSI = primaryBridge->routerRSSI;
+    }
+    
+    // Aggregate traffic and performance from all connections
+    uint64_t totalBytesRx = 0;
+    uint64_t totalBytesTx = 0;
+    uint32_t totalMessagesRx = 0;
+    uint32_t totalMessagesTx = 0;
+    uint32_t totalMessagesDropped = 0;
+    uint32_t totalLatency = 0;
+    uint32_t latencySampleCount = 0;
+    int8_t sumRSSI = 0;
+    int8_t minRSSI = 0;
+    int8_t maxRSSI = -127;
+    uint32_t rssiCount = 0;
+    
+    for (auto conn : this->subs) {
+      if (conn->connected()) {
+        totalBytesRx += conn->bytesRx;
+        totalBytesTx += conn->bytesTx;
+        totalMessagesRx += conn->messagesRx;
+        totalMessagesTx += conn->messagesTx;
+        totalMessagesDropped += conn->messagesDropped;
+        
+        // Latency
+        int latency = conn->getLatency();
+        if (latency >= 0) {
+          totalLatency += latency;
+          latencySampleCount++;
+        }
+        
+        // RSSI
+        int rssi = conn->getRSSI();
+        if (rssi != 0) {
+          sumRSSI += rssi;
+          rssiCount++;
+          if (rssi < minRSSI || minRSSI == 0) minRSSI = rssi;
+          if (rssi > maxRSSI) maxRSSI = rssi;
+        }
+      }
+    }
+    
+    // Set traffic metrics
+    metrics.bytesRx = totalBytesRx;
+    metrics.bytesTx = totalBytesTx;
+    metrics.messagesRx = totalMessagesRx;
+    metrics.messagesTx = totalMessagesTx;
+    metrics.messagesDropped = totalMessagesDropped;
+    
+    // Calculate averages
+    if (latencySampleCount > 0) {
+      metrics.avgLatencyMs = totalLatency / latencySampleCount;
+    }
+    
+    if (rssiCount > 0) {
+      metrics.avgRSSI = sumRSSI / rssiCount;
+      metrics.minRSSI = minRSSI;
+      metrics.maxRSSI = maxRSSI;
+    }
+    
+    // Calculate packet loss percentage
+    uint32_t totalAttempted = totalMessagesTx + totalMessagesDropped;
+    if (totalAttempted > 0) {
+      metrics.packetLossPercent = (totalMessagesDropped * 100) / totalAttempted;
+    }
+    
+    // Mesh node count
+    metrics.meshNodeCount = this->getNodeList(true).size();
+    
+    // Track disconnects (stored in protected member)
+    metrics.totalDisconnects = metricsDisconnectCount;
+    
+    return metrics;
+  }
+
+  /**
+   * Reset health metrics counters
+   * 
+   * Resets all counters to zero but keeps current state metrics (RSSI, node count, etc.)
+   * Useful for periodic monitoring windows.
+   * 
+   * \code
+   * // Reset metrics at the start of each monitoring period
+   * mesh.resetHealthMetrics();
+   * \endcode
+   */
+  void resetHealthMetrics() {
+    using namespace logger;
+    Log(GENERAL, "resetHealthMetrics(): Resetting all metric counters\n");
+    
+    // Reset connection metrics
+    for (auto conn : this->subs) {
+      if (conn->connected()) {
+        conn->messagesRx = 0;
+        conn->messagesTx = 0;
+        conn->messagesDropped = 0;
+        conn->bytesRx = 0;
+        conn->bytesTx = 0;
+        conn->latencySamples.clear();
+      }
+    }
+    
+    // Reset disconnect counter
+    metricsDisconnectCount = 0;
+  }
+
+  /**
+   * Export health metrics as JSON string
+   * 
+   * Generates a JSON representation of current health metrics for easy integration
+   * with monitoring tools, MQTT publishing, or logging.
+   * 
+   * \code
+   * String json = mesh.getHealthMetricsJSON();
+   * mqttClient.publish("bridge/metrics", json.c_str());
+   * \endcode
+   * 
+   * @return JSON string containing all health metrics
+   */
+  TSTRING getHealthMetricsJSON() {
+    auto metrics = getBridgeHealthMetrics();
+    
+    TSTRING json = "{";
+    json += "\"connectivity\":{";
+    json += "\"uptimeSeconds\":";
+    json += std::to_string(metrics.uptimeSeconds);
+    json += ",\"internetUptimeSeconds\":";
+    json += std::to_string(metrics.internetUptimeSeconds);
+    json += ",\"totalDisconnects\":";
+    json += std::to_string(metrics.totalDisconnects);
+    json += ",\"currentUptime\":";
+    json += std::to_string(metrics.currentUptime);
+    json += "},";
+    
+    json += "\"signalQuality\":{";
+    json += "\"currentRSSI\":";
+    json += std::to_string(metrics.currentRSSI);
+    json += ",\"avgRSSI\":";
+    json += std::to_string(metrics.avgRSSI);
+    json += ",\"minRSSI\":";
+    json += std::to_string(metrics.minRSSI);
+    json += ",\"maxRSSI\":";
+    json += std::to_string(metrics.maxRSSI);
+    json += "},";
+    
+    json += "\"traffic\":{";
+    json += "\"bytesRx\":";
+    json += std::to_string(metrics.bytesRx);
+    json += ",\"bytesTx\":";
+    json += std::to_string(metrics.bytesTx);
+    json += ",\"messagesRx\":";
+    json += std::to_string(metrics.messagesRx);
+    json += ",\"messagesTx\":";
+    json += std::to_string(metrics.messagesTx);
+    json += ",\"messagesQueued\":";
+    json += std::to_string(metrics.messagesQueued);
+    json += ",\"messagesDropped\":";
+    json += std::to_string(metrics.messagesDropped);
+    json += "},";
+    
+    json += "\"performance\":{";
+    json += "\"avgLatencyMs\":";
+    json += std::to_string(metrics.avgLatencyMs);
+    json += ",\"packetLossPercent\":";
+    json += std::to_string(metrics.packetLossPercent);
+    json += ",\"meshNodeCount\":";
+    json += std::to_string(metrics.meshNodeCount);
+    json += "}";
+    
+    json += "}";
+    return json;
+  }
+
+  /**
+   * Set periodic health metrics callback
+   * 
+   * Registers a callback that will be invoked periodically with current health metrics.
+   * Useful for automated monitoring, MQTT publishing, or Prometheus export.
+   * 
+   * \code
+   * mesh.onHealthMetricsUpdate([](BridgeHealthMetrics metrics) {
+   *   String json = mesh.getHealthMetricsJSON();
+   *   mqttClient.publish("bridge/metrics", json.c_str());
+   * }, 60000);  // Every 60 seconds
+   * \endcode
+   * 
+   * @param callback Function to call with metrics
+   * @param intervalMs Callback interval in milliseconds (default: 60000 = 60 seconds)
+   */
+  void onHealthMetricsUpdate(std::function<void(BridgeHealthMetrics)> callback, 
+                             uint32_t intervalMs = 60000) {
+    using namespace logger;
+    Log(GENERAL, "onHealthMetricsUpdate(): Setting up periodic callback every %u ms\n", intervalMs);
+    
+    // Create a task that periodically collects and reports metrics
+    auto metricsTask = this->addTask(intervalMs, TASK_FOREVER, [this, callback]() {
+      auto metrics = this->getBridgeHealthMetrics();
+      callback(metrics);
+    });
+    
+    metricsTask->enable();
+  }
+
+  // ==================== Enhanced Diagnostics API ====================
+
+  /**
+   * Enable or disable diagnostics collection
+   * 
+   * When enabled, the mesh will track election history, bridge changes,
+   * and other diagnostic information. This has minimal overhead.
+   * 
+   * @param enabled true to enable diagnostics (default), false to disable
+   */
+  void enableDiagnostics(bool enabled = true) {
+    diagnosticsEnabled = enabled;
+    if (enabled) {
+      Log(logger::GENERAL, "enableDiagnostics(): Diagnostics enabled\n");
+    } else {
+      Log(logger::GENERAL, "enableDiagnostics(): Diagnostics disabled\n");
+    }
+  }
+
+  /**
+   * Get current bridge status
+   * 
+   * Returns information about this node's bridge role and connectivity status
+   * 
+   * \code
+   * auto status = mesh.getBridgeStatus();
+   * if (status.isBridge && status.internetConnected) {
+   *   Serial.println("I am bridge with Internet");
+   * }
+   * \endcode
+   * 
+   * @return BridgeStatus structure with current status
+   */
+  BridgeStatus getBridgeStatus() {
+    BridgeStatus status;
+    
+    status.isBridge = this->isBridge();
+    status.internetConnected = this->hasInternetConnection();
+    
+    if (status.isBridge) {
+      status.role = "bridge";
+    } else if (this->root) {
+      status.role = "root";
+    } else {
+      status.role = "regular";
+    }
+    
+    // Get primary bridge info
+    auto primaryBridge = this->getPrimaryBridge();
+    if (primaryBridge != nullptr) {
+      status.bridgeNodeId = primaryBridge->nodeId;
+      status.bridgeRSSI = primaryBridge->routerRSSI;
+    }
+    
+    // Calculate time since last bridge change
+    if (lastBridgeChangeTime > 0) {
+      status.timeSinceBridgeChange = millis() - lastBridgeChangeTime;
+    }
+    
+    return status;
+  }
+
+  /**
+   * Get election history
+   * 
+   * Returns list of recent bridge elections if diagnostics are enabled.
+   * History is limited to last 10 elections.
+   * 
+   * \code
+   * auto history = mesh.getElectionHistory();
+   * for (const auto& record : history) {
+   *   Serial.printf("Election: winner=%u, RSSI=%d, candidates=%u\n",
+   *                 record.winnerNodeId, record.winnerRSSI, record.candidateCount);
+   * }
+   * \endcode
+   * 
+   * @return Vector of ElectionRecord structures
+   */
+  std::vector<ElectionRecord> getElectionHistory() {
+    if (!diagnosticsEnabled) {
+      Log(logger::GENERAL, "getElectionHistory(): Diagnostics not enabled\n");
+      return std::vector<ElectionRecord>();
+    }
+    return electionHistory;
+  }
+
+  /**
+   * Get last bridge change event
+   * 
+   * Returns information about the most recent bridge change
+   * 
+   * \code
+   * auto event = mesh.getLastBridgeChange();
+   * if (event.timestamp > 0) {
+   *   Serial.printf("Bridge changed from %u to %u: %s\n",
+   *                 event.oldBridgeId, event.newBridgeId, event.reason.c_str());
+   * }
+   * \endcode
+   * 
+   * @return BridgeChangeEvent structure
+   */
+  BridgeChangeEvent getLastBridgeChange() {
+    return lastBridgeChange;
+  }
+
+  /**
+   * Get Internet path to specific node
+   * 
+   * Returns the routing path from the specified node to the Internet bridge.
+   * Path includes all intermediate nodes from source to bridge.
+   * 
+   * \code
+   * auto path = mesh.getInternetPath(targetNodeId);
+   * Serial.print("Path to Internet: ");
+   * for (auto nodeId : path) {
+   *   Serial.printf("%u -> ", nodeId);
+   * }
+   * Serial.println("Internet");
+   * \endcode
+   * 
+   * @param nodeId Node to find path from
+   * @return Vector of node IDs representing the path (empty if no path)
+   */
+  std::vector<uint32_t> getInternetPath(uint32_t nodeId) {
+    std::vector<uint32_t> path;
+    
+    // Get primary bridge
+    auto primaryBridge = this->getPrimaryBridge();
+    if (primaryBridge == nullptr) {
+      Log(logger::GENERAL, "getInternetPath(): No bridge available\n");
+      return path;
+    }
+    
+    // If requesting path for the bridge itself
+    if (nodeId == primaryBridge->nodeId) {
+      path.push_back(nodeId);
+      return path;
+    }
+    
+    // Start with the target node
+    path.push_back(nodeId);
+    
+    // For now, simplified routing: if direct connection, add bridge
+    // TODO: Implement proper multi-hop path discovery
+    if (this->isConnected(primaryBridge->nodeId)) {
+      path.push_back(primaryBridge->nodeId);
+    }
+    
+    return path;
+  }
+
+  /**
+   * Get bridge node ID for specific node
+   * 
+   * Returns the bridge node ID that the specified node should use to reach Internet.
+   * For most cases, this is the primary bridge.
+   * 
+   * \code
+   * uint32_t bridgeId = mesh.getBridgeForNodeId(targetNodeId);
+   * if (bridgeId != 0) {
+   *   Serial.printf("Node %u uses bridge %u\n", targetNodeId, bridgeId);
+   * }
+   * \endcode
+   * 
+   * @param nodeId Node to find bridge for
+   * @return Bridge node ID, or 0 if no bridge available
+   */
+  uint32_t getBridgeForNodeId(uint32_t nodeId) {
+    auto primaryBridge = this->getPrimaryBridge();
+    if (primaryBridge != nullptr) {
+      return primaryBridge->nodeId;
+    }
+    return 0;
+  }
+
+  /**
+   * Export topology as DOT format (Graphviz)
+   * 
+   * Generates a GraphViz DOT format representation of the mesh topology.
+   * Can be visualized using Graphviz tools.
+   * 
+   * \code
+   * String dot = mesh.exportTopologyDOT();
+   * Serial.println(dot);
+   * // Save to file or send to visualization tool
+   * \endcode
+   * 
+   * @return String containing DOT format graph
+   */
+  TSTRING exportTopologyDOT() {
+    TSTRING dot = "digraph mesh {\n";
+    dot += "  rankdir=TB;\n";
+    dot += "  node [shape=box];\n\n";
+    
+    // Add this node
+    dot += "  \"" + TSTRING(std::to_string(this->nodeId).c_str()) + "\" ";
+    if (this->isBridge()) {
+      dot += "[style=filled,fillcolor=lightblue,label=\"" + TSTRING(std::to_string(this->nodeId).c_str()) + "\\nBridge\"];\n";
+    } else {
+      dot += "[label=\"" + TSTRING(std::to_string(this->nodeId).c_str()) + "\"];\n";
+    }
+    
+    // Add Internet node if bridge exists
+    auto primaryBridge = this->getPrimaryBridge();
+    if (primaryBridge != nullptr && primaryBridge->internetConnected) {
+      dot += "  \"Internet\" [shape=cloud,style=filled,fillcolor=lightgreen];\n";
+      dot += "  \"" + TSTRING(std::to_string(primaryBridge->nodeId).c_str()) + "\" -> \"Internet\" [style=dashed,color=green];\n";
+    }
+    
+    // Add all known nodes and connections
+    auto nodeList = this->getNodeList(false);
+    for (auto node : nodeList) {
+      dot += "  \"" + TSTRING(std::to_string(node).c_str()) + "\";\n";
+    }
+    
+    // Add edges for direct connections
+    for (auto conn : this->subs) {
+      if (conn->connected()) {
+        dot += "  \"" + TSTRING(std::to_string(this->nodeId).c_str()) + "\" -> \"" + TSTRING(std::to_string(conn->nodeId).c_str()) + "\"";
+        
+        // Add edge labels with latency
+        int latency = conn->getLatency();
+        if (latency >= 0) {
+          dot += " [label=\"" + TSTRING(std::to_string(latency).c_str()) + "ms\"]";
+        }
+        dot += ";\n";
+      }
+    }
+    
+    dot += "}\n";
+    return dot;
+  }
+
+  /**
+   * Test bridge connectivity
+   * 
+   * Runs a connectivity test to the primary bridge and optionally to Internet.
+   * Measures latency and reachability.
+   * 
+   * \code
+   * auto result = mesh.testBridgeConnectivity();
+   * if (result.success) {
+   *   Serial.printf("Bridge test passed: %s (latency: %u ms)\n", 
+   *                 result.message.c_str(), result.latencyMs);
+   * } else {
+   *   Serial.printf("Bridge test failed: %s\n", result.message.c_str());
+   * }
+   * \endcode
+   * 
+   * @return BridgeTestResult with test results
+   */
+  BridgeTestResult testBridgeConnectivity() {
+    BridgeTestResult result;
+    
+    // Check if we have a bridge
+    auto primaryBridge = this->getPrimaryBridge();
+    if (primaryBridge == nullptr) {
+      result.success = false;
+      result.message = "No bridge available";
+      return result;
+    }
+    
+    // Check if bridge is reachable
+    result.bridgeReachable = this->isConnected(primaryBridge->nodeId);
+    if (!result.bridgeReachable) {
+      result.success = false;
+      result.message = "Bridge not reachable";
+      return result;
+    }
+    
+    // Estimate latency from connection info
+    for (auto conn : this->subs) {
+      if (conn->nodeId == primaryBridge->nodeId && conn->connected()) {
+        int latency = conn->getLatency();
+        if (latency >= 0) {
+          result.latencyMs = latency;
+        }
+        break;
+      }
+    }
+    
+    // Check Internet connectivity through bridge
+    result.internetReachable = primaryBridge->internetConnected;
+    
+    result.success = result.bridgeReachable;
+    if (result.internetReachable) {
+      result.message = "Bridge reachable with Internet";
+    } else {
+      result.message = "Bridge reachable, no Internet";
+    }
+    
+    return result;
+  }
+
+  /**
+   * Check if specific bridge is reachable
+   * 
+   * Tests if the specified bridge node can be reached from this node.
+   * 
+   * \code
+   * if (mesh.isBridgeReachable(bridgeNodeId)) {
+   *   Serial.println("Bridge is reachable");
+   * }
+   * \endcode
+   * 
+   * @param bridgeNodeId Bridge node ID to test
+   * @return true if bridge is reachable, false otherwise
+   */
+  bool isBridgeReachable(uint32_t bridgeNodeId) {
+    return this->isConnected(bridgeNodeId);
+  }
+
+  /**
+   * Get comprehensive diagnostic report
+   * 
+   * Generates a human-readable diagnostic report with mesh status, bridge info,
+   * connectivity, and performance metrics. Useful for debugging and monitoring.
+   * 
+   * \code
+   * Serial.println(mesh.getDiagnosticReport());
+   * // Example output:
+   * // === painlessMesh Diagnostics ===
+   * // Mode: Regular Node
+   * // Mesh: ProductionMesh (25 nodes)
+   * // Bridge: 123456789 (RSSI: -42 dBm, Internet: ✓)
+   * // Queue: 3 messages (2 CRITICAL, 1 NORMAL)
+   * // Uptime: 02:15:33
+   * // Last Election: 00:45:12 ago (Winner: 123456789)
+   * \endcode
+   * 
+   * @return String containing formatted diagnostic report
+   */
+  TSTRING getDiagnosticReport() {
+    TSTRING report = "=== painlessMesh Diagnostics ===\n";
+    
+    // Node info
+    auto status = this->getBridgeStatus();
+    report += "Node ID: " + TSTRING(std::to_string(this->nodeId).c_str()) + "\n";
+    report += "Mode: " + status.role + "\n";
+    
+    // Mesh info
+    auto nodeList = this->getNodeList(true);
+    report += "Mesh Nodes: " + TSTRING(std::to_string(nodeList.size()).c_str()) + "\n";
+    
+    // Bridge info
+    if (status.isBridge) {
+      report += "Bridge: " + TSTRING(std::to_string(this->nodeId).c_str()) + " (this node)\n";
+    } else {
+      auto primaryBridge = this->getPrimaryBridge();
+      if (primaryBridge != nullptr) {
+        report += "Bridge: " + TSTRING(std::to_string(primaryBridge->nodeId).c_str());
+        report += " (RSSI: " + TSTRING(std::to_string(primaryBridge->routerRSSI).c_str()) + " dBm";
+        report += ", Internet: " + TSTRING(primaryBridge->internetConnected ? "✓" : "✗") + ")\n";
+      } else {
+        report += "Bridge: None available\n";
+      }
+    }
+    
+    // Connection info
+    report += "Direct Connections: " + TSTRING(std::to_string(this->subs.size()).c_str()) + "\n";
+    
+    // Health metrics
+    auto metrics = this->getBridgeHealthMetrics();
+    report += "Messages RX: " + TSTRING(std::to_string(metrics.messagesRx).c_str()) + "\n";
+    report += "Messages TX: " + TSTRING(std::to_string(metrics.messagesTx).c_str()) + "\n";
+    report += "Messages Dropped: " + TSTRING(std::to_string(metrics.messagesDropped).c_str()) + "\n";
+    
+    if (metrics.avgLatencyMs > 0) {
+      report += "Avg Latency: " + TSTRING(std::to_string(metrics.avgLatencyMs).c_str()) + " ms\n";
+    }
+    
+    // Uptime
+    uint32_t uptimeSeconds = millis() / 1000;
+    uint32_t hours = uptimeSeconds / 3600;
+    uint32_t minutes = (uptimeSeconds % 3600) / 60;
+    uint32_t seconds = uptimeSeconds % 60;
+    
+    char uptimeStr[32];
+    snprintf(uptimeStr, sizeof(uptimeStr), "%02u:%02u:%02u", hours, minutes, seconds);
+    report += "Uptime: " + TSTRING(uptimeStr) + "\n";
+    
+    // Election info
+    if (diagnosticsEnabled && !electionHistory.empty()) {
+      auto& lastElection = electionHistory.back();
+      uint32_t timeSinceElection = millis() - lastElection.timestamp;
+      uint32_t electionMinutes = (timeSinceElection / 1000) / 60;
+      uint32_t electionSeconds = (timeSinceElection / 1000) % 60;
+      
+      char electionTimeStr[32];
+      snprintf(electionTimeStr, sizeof(electionTimeStr), "%02u:%02u", electionMinutes, electionSeconds);
+      
+      report += "Last Election: " + TSTRING(electionTimeStr) + " ago";
+      report += " (Winner: " + TSTRING(std::to_string(lastElection.winnerNodeId).c_str());
+      report += ", " + TSTRING(std::to_string(lastElection.candidateCount).c_str()) + " candidates)\n";
+    }
+    
+    report += "================================\n";
+    return report;
+  }
+
   inline std::shared_ptr<Task> addTask(unsigned long aInterval,
                                        long aIterations,
                                        std::function<void()> aCallback) {
@@ -521,6 +1619,8 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
   callback::List<uint32_t> changedConnectionCallbacks;
   nodeTimeAdjustedCallback_t nodeTimeAdjustedCallback;
   nodeDelayCallback_t nodeDelayReceivedCallback;
+  bridgeStatusChangedCallback_t bridgeStatusChangedCallback;
+  rtcSyncCompleteCallback_t rtcSyncCompleteCallback;
 #ifdef ESP32
   SemaphoreHandle_t xSemaphore = NULL;
 #endif
@@ -558,6 +1658,25 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
 #endif
   }
 
+  // Bridge status tracking
+  std::vector<BridgeInfo> knownBridges;
+  uint32_t bridgeStatusIntervalMs = 30000;  // Default 30 seconds
+  uint32_t bridgeTimeoutMs = 60000;         // Default 60 seconds
+  bool bridgeStatusBroadcastEnabled = true;
+
+  // Health metrics tracking
+  uint32_t metricsDisconnectCount = 0;
+
+  // RTC management
+  rtc::RTCManager rtcManager;
+
+  // Diagnostics tracking
+  bool diagnosticsEnabled = false;
+  std::vector<ElectionRecord> electionHistory;
+  static const size_t MAX_ELECTION_HISTORY = 10;
+  BridgeChangeEvent lastBridgeChange;
+  uint32_t lastBridgeChangeTime = 0;
+
   friend T;
   friend void onDataCb(void *, AsyncClient *, void *, size_t);
   friend void tcpSentCb(void *, AsyncClient *, size_t, uint32_t);
@@ -589,6 +1708,8 @@ class Connection : public painlessmesh::layout::Neighbour,
   uint32_t messagesTx = 0;
   uint32_t messagesDropped = 0;
   uint32_t timeLastReceived = 0;
+  uint64_t bytesRx = 0;
+  uint64_t bytesTx = 0;
   
   // Latency tracking (rolling window)
   std::vector<uint32_t> latencySamples;
@@ -660,19 +1781,21 @@ class Connection : public painlessmesh::layout::Neighbour,
   }
 
   /**
-   * Record message received timestamp
+   * Record message received timestamp and bytes
    */
-  void onMessageReceived() {
+  void onMessageReceived(size_t bytes = 0) {
     messagesRx++;
+    bytesRx += bytes;
     timeLastReceived = millis();
   }
 
   /**
-   * Record message sent
+   * Record message sent and bytes
    */
-  void onMessageSent(bool success) {
+  void onMessageSent(bool success, size_t bytes = 0) {
     if (success) {
       messagesTx++;
+      bytesTx += bytes;
     } else {
       messagesDropped++;
     }