@alteriom/painlessmesh 1.8.14 → 1.9.0

package/src/painlessmesh/mesh.hpp

@@ -1,6 +1,8 @@
 #ifndef _PAINLESS_MESH_MESH_HPP_
 #define _PAINLESS_MESH_MESH_HPP_
 
+#include <algorithm>
+#include <list>
 #include <vector>
 #include <map>
 #include <set>
@@ -9,8 +11,10 @@
 #include "painlessmesh/configuration.hpp"
 
 #include "painlessmesh/connection.hpp"
+#include "painlessmesh/gateway.hpp"
 #include "painlessmesh/logger.hpp"
 #include "painlessmesh/message_queue.hpp"
+#include "painlessmesh/message_tracker.hpp"
 #include "painlessmesh/ntp.hpp"
 #include "painlessmesh/plugin.hpp"
 #include "painlessmesh/protocol.hpp"
@@ -30,6 +34,44 @@ 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;
+typedef std::function<void(bool available)> localInternetChangedCallback_t;
+typedef std::function<void(uint32_t oldPrimary, uint32_t newPrimary)> gatewayChangedCallback_t;
+
+/**
+ * Callback type for Internet request results
+ *
+ * @param success Whether the request was delivered successfully
+ * @param httpStatus HTTP status code from the destination (0 if not applicable)
+ * @param error Human-readable error message (empty if success)
+ */
+typedef std::function<void(bool success, uint16_t httpStatus, TSTRING error)>
+    internetResultCallback_t;
+
+/**
+ * Pending Internet request entry
+ *
+ * Tracks a pending sendToInternet() request for acknowledgment handling
+ */
+struct PendingInternetRequest {
+  uint32_t messageId = 0;          ///< Unique message ID
+  uint32_t timestamp = 0;          ///< When request was sent (millis)
+  uint8_t retryCount = 0;          ///< Number of retries attempted
+  uint8_t maxRetries = 3;          ///< Maximum retry attempts
+  uint8_t priority = 2;            ///< Priority level (0=CRITICAL to 3=LOW)
+  uint32_t timeoutMs = 30000;      ///< Timeout in milliseconds
+  uint32_t retryDelayMs = 1000;    ///< Current retry delay (for exponential backoff)
+  uint32_t gatewayNodeId = 0;      ///< Target gateway node ID
+  TSTRING destination = "";        ///< Internet destination URL
+  TSTRING payload = "";            ///< Request payload
+  internetResultCallback_t callback;  ///< User callback for result
+
+  /**
+   * Check if this request has timed out
+   */
+  bool isTimedOut() const {
+    return (static_cast<uint32_t>(millis()) - timestamp) > timeoutMs;
+  }
+};
 
 /**
  * Bridge information structure
@@ -52,7 +94,9 @@ public:
    * 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;
+    // Cast millis() to uint32_t to handle overflow correctly
+    // This ensures consistent behavior on both embedded and test environments
+    return (static_cast<uint32_t>(millis()) - lastSeen) < timeoutMs;
   }
 };
 
@@ -564,17 +608,55 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
   /**
    * Check if any bridge in the mesh has Internet connectivity
    * 
-   * @return true if at least one healthy bridge reports Internet connection
+   * When connected to mesh, requires recent bridge status (within timeout).
+   * When disconnected from mesh, returns true if any bridge previously
+   * reported Internet connectivity - allowing operations to be queued for
+   * when mesh connectivity is restored.
+   * 
+   * @return true if at least one bridge reports Internet connection
    */
   bool hasInternetConnection() {
+    bool hasConnections = hasActiveMeshConnections();
+    
     for (const auto& bridge : knownBridges) {
-      if (bridge.isHealthy(bridgeTimeoutMs) && bridge.internetConnected) {
+      // When connected: require fresh status
+      // When disconnected: use last known state
+      bool isUsable = hasConnections 
+          ? (bridge.isHealthy(bridgeTimeoutMs) && bridge.internetConnected)
+          : bridge.internetConnected;
+      
+      if (isUsable) {
         return true;
       }
     }
     return false;
   }
 
+  /**
+   * Get list of nodes that currently have Internet access
+   * 
+   * Returns node IDs of all healthy bridges with active Internet connectivity.
+   * Only bridges that have reported status within the timeout period are included.
+   * 
+   * \code
+   * auto internetNodes = mesh.getNodesWithInternet();
+   * for (auto nodeId : internetNodes) {
+   *   Serial.printf("Node %u has Internet access\n", nodeId);
+   * }
+   * \endcode
+   * 
+   * @return Vector of node IDs with Internet connectivity
+   */
+  std::vector<uint32_t> getNodesWithInternet() {
+    std::vector<uint32_t> nodesWithInternet;
+    for (const auto& bridge : knownBridges) {
+      if (bridge.isHealthy(bridgeTimeoutMs) && bridge.internetConnected) {
+        nodesWithInternet.push_back(bridge.nodeId);
+      }
+    }
+    return nodesWithInternet;
+  }
+
   /**
    * Get list of all known bridges in the mesh
    * 
@@ -588,18 +670,32 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
    * Get the primary (best) bridge node
    * 
    * Primary bridge is selected based on:
-   * 1. Must be healthy (seen within timeout)
+   * 1. Must be healthy (seen within timeout) - unless node is disconnected
    * 2. Must have Internet connection
    * 3. Best WiFi RSSI to router
    * 
+   * When this node is disconnected from the mesh (no active connections),
+   * returns the last known bridge even if lastSeen is stale. This allows
+   * nodes to attempt routing through the last known bridge once mesh
+   * connectivity is restored.
+   * 
    * @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
     
+    // Check if we have active mesh connections
+    bool hasConnections = hasActiveMeshConnections();
+    
     for (auto& bridge : knownBridges) {
-      if (bridge.isHealthy(bridgeTimeoutMs) && bridge.internetConnected) {
+      // When connected to mesh: require healthy (recent) bridge status
+      // When disconnected: use any bridge that reported Internet (stale info is better than none)
+      bool isUsable = hasConnections 
+          ? (bridge.isHealthy(bridgeTimeoutMs) && bridge.internetConnected)
+          : bridge.internetConnected;
+      
+      if (isUsable) {
         if (bridge.routerRSSI > bestRSSI) {
           bestRSSI = bridge.routerRSSI;
           primary = &bridge;
@@ -610,6 +706,58 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     return primary;
   }
 
+  /**
+   * Get the last known bridge with Internet connection (regardless of lastSeen timeout)
+   * 
+   * Unlike getPrimaryBridge(), this method returns the best known bridge even if
+   * the lastSeen timestamp is stale. This is useful when the local node is temporarily
+   * disconnected from the mesh and cannot receive bridge status updates.
+   * 
+   * The returned bridge may not be currently reachable, but represents the last
+   * known good configuration.
+   * 
+   * @return pointer to BridgeInfo of last known bridge, or nullptr if no bridge ever seen
+   */
+  BridgeInfo* getLastKnownBridge() {
+    BridgeInfo* best = nullptr;
+    int8_t bestRSSI = -127;  // Worst possible RSSI
+    
+    for (auto& bridge : knownBridges) {
+      // Include any bridge that reported Internet at some point
+      if (bridge.internetConnected) {
+        if (bridge.routerRSSI > bestRSSI) {
+          bestRSSI = bridge.routerRSSI;
+          best = &bridge;
+        }
+      }
+    }
+    
+    return best;
+  }
+
+  /**
+   * Check if this node has active mesh connections
+   * 
+   * Returns true if this node has at least one active connection to other
+   * mesh nodes. When false, the node is isolated and cannot receive any
+   * mesh messages including bridge status updates.
+   * 
+   * This is useful for distinguishing between:
+   * - Bridge genuinely unavailable (mesh connected, but bridge not responding)
+   * - Local node temporarily disconnected (cannot receive any mesh messages)
+   * 
+   * @return true if at least one mesh connection is active
+   */
+  bool hasActiveMeshConnections() {
+    // Check if we have any active connections in our subs list
+    for (auto& conn : this->subs) {
+      if (conn && conn->connected()) {
+        return true;
+      }
+    }
+    return false;
+  }
+
   /**
    * Check if this node is acting as a bridge
    * 
@@ -619,6 +767,127 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     return this->root;
   }
 
+  // ==================== Gateway Status API ====================
+
+  /**
+   * Check if this node is the primary gateway
+   * 
+   * A node is the primary gateway if it's the bridge with the best RSSI
+   * to the router and has Internet connectivity.
+   * 
+   * \code
+   * if (mesh.isPrimaryGateway()) {
+   *   Serial.println("I am the primary gateway!");
+   * }
+   * \endcode
+   * 
+   * @return true if this node is the primary gateway
+   */
+  bool isPrimaryGateway() {
+    BridgeInfo* primary = getPrimaryBridge();
+    if (primary == nullptr) {
+      return false;
+    }
+    return primary->nodeId == this->nodeId;
+  }
+
+  /**
+   * Get the node ID of the current primary gateway
+   * 
+   * Returns the node ID of the bridge with the best RSSI to the router
+   * that has Internet connectivity, or 0 if no gateway is available.
+   * 
+   * \code
+   * uint32_t gatewayId = mesh.getPrimaryGateway();
+   * if (gatewayId != 0) {
+   *   Serial.printf("Primary gateway is node %u\n", gatewayId);
+   * } else {
+   *   Serial.println("No gateway available");
+   * }
+   * \endcode
+   * 
+   * @return Node ID of the primary gateway, or 0 if none available
+   */
+  uint32_t getPrimaryGateway() {
+    BridgeInfo* primary = getPrimaryBridge();
+    if (primary == nullptr) {
+      return 0;
+    }
+    return primary->nodeId;
+  }
+
+  /**
+   * Get list of all nodes with Internet access
+   * 
+   * Returns node IDs of all healthy bridges with active Internet connectivity.
+   * Only bridges that have reported status within the timeout period are included.
+   * 
+   * This method provides the same data as getNodesWithInternet() but returns
+   * a std::list for consistency with other node list methods in painlessMesh.
+   * 
+   * \code
+   * auto gateways = mesh.getGateways();
+   * Serial.printf("Available gateways: %d\n", gateways.size());
+   * for (auto gatewayId : gateways) {
+   *   Serial.printf("  Gateway: %u\n", gatewayId);
+   * }
+   * \endcode
+   * 
+   * @return List of node IDs with Internet connectivity
+   */
+  std::list<uint32_t> getGateways() {
+    // Convert vector to list for API consistency with getNodeList()
+    // The copy overhead is acceptable since gateway lists are typically small
+    auto nodes = getNodesWithInternet();
+    return std::list<uint32_t>(nodes.begin(), nodes.end());
+  }
+
+  /**
+   * Get count of available gateways
+   * 
+   * Returns the number of healthy bridges with active Internet connectivity.
+   * 
+   * \code
+   * size_t count = mesh.getGatewayCount();
+   * if (count == 0) {
+   *   Serial.println("Warning: No gateways available!");
+   * } else {
+   *   Serial.printf("%d gateway(s) available\n", count);
+   * }
+   * \endcode
+   * 
+   * @return Number of available gateways
+   */
+  size_t getGatewayCount() {
+    return getNodesWithInternet().size();
+  }
+
+  /**
+   * Register callback for primary gateway changes
+   * 
+   * This callback fires when the primary gateway changes, either because
+   * a new gateway becomes available, the current gateway becomes unavailable,
+   * or a better gateway is discovered.
+   * 
+   * \code
+   * mesh.onGatewayChanged([](uint32_t oldPrimary, uint32_t newPrimary) {
+   *   if (newPrimary == 0) {
+   *     Serial.println("Warning: Lost all gateways!");
+   *   } else if (oldPrimary == 0) {
+   *     Serial.printf("Gateway available: %u\n", newPrimary);
+   *   } else {
+   *     Serial.printf("Gateway changed: %u -> %u\n", oldPrimary, newPrimary);
+   *   }
+   * });
+   * \endcode
+   * 
+   * @param callback Function to call when primary gateway changes
+   */
+  void onGatewayChanged(gatewayChangedCallback_t callback) {
+    Log(logger::GENERAL, "onGatewayChanged():\n");
+    gatewayChangedCallback = callback;
+  }
+
   /**
    * Set the interval for bridge status broadcasts (bridge nodes only)
    * 
@@ -646,6 +915,719 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     bridgeStatusBroadcastEnabled = enabled;
   }
 
+  /**
+   * Clean up expired bridge entries that haven't reported recently
+   * 
+   * Removes bridges that haven't sent a status update within the timeout period.
+   * This helps maintain an accurate list of available gateways and prevents
+   * the bridge list from growing unbounded.
+   * 
+   * Called periodically when bridge cleanup is enabled, or can be called manually.
+   * 
+   * \code
+   * // Manual cleanup
+   * mesh.cleanupExpiredBridges();
+   * 
+   * // Or enable automatic cleanup (recommended)
+   * mesh.enableBridgeCleanup();
+   * \endcode
+   */
+  void cleanupExpiredBridges() {
+    using namespace logger;
+    size_t sizeBefore = knownBridges.size();
+    
+    // Remove bridges that haven't reported within the timeout period
+    knownBridges.erase(
+        std::remove_if(knownBridges.begin(), knownBridges.end(),
+                       [this](const BridgeInfo& bridge) {
+                         return !bridge.isHealthy(bridgeTimeoutMs);
+                       }),
+        knownBridges.end());
+    
+    size_t removed = sizeBefore - knownBridges.size();
+    if (removed > 0) {
+      Log(GENERAL, "cleanupExpiredBridges(): Removed %u expired bridges\n", removed);
+    }
+  }
+
+  /**
+   * Enable periodic cleanup of expired bridge entries
+   * 
+   * Starts a background task that periodically removes stale bridge entries.
+   * The cleanup runs at the same interval as the bridge timeout (default 60 seconds).
+   * 
+   * This is recommended for all nodes to prevent memory growth from
+   * accumulating stale bridge entries.
+   * 
+   * \code
+   * mesh.enableBridgeCleanup();  // Start automatic cleanup
+   * \endcode
+   */
+  void enableBridgeCleanup() {
+    using namespace logger;
+    if (bridgeCleanupTask != nullptr) {
+      Log(GENERAL, "enableBridgeCleanup(): Already enabled\n");
+      return;
+    }
+    
+    Log(GENERAL, "enableBridgeCleanup(): Starting cleanup task (interval: %u ms)\n",
+        bridgeTimeoutMs);
+    
+    bridgeCleanupTask = this->addTask(
+        bridgeTimeoutMs,
+        TASK_FOREVER,
+        [this]() {
+          cleanupExpiredBridges();
+        });
+  }
+
+  /**
+   * Disable periodic cleanup of expired bridge entries
+   */
+  void disableBridgeCleanup() {
+    using namespace logger;
+    if (bridgeCleanupTask != nullptr) {
+      bridgeCleanupTask->disable();
+      bridgeCleanupTask = nullptr;
+      Log(GENERAL, "disableBridgeCleanup(): Cleanup task disabled\n");
+    }
+  }
+
+  /**
+   * Check if bridge cleanup is enabled
+   * 
+   * @return true if periodic cleanup is running
+   */
+  bool isBridgeCleanupEnabled() const {
+    return bridgeCleanupTask != nullptr && bridgeCleanupTask->isEnabled();
+  }
+
+  // ==================== Local Internet Health Check API ====================
+
+  /**
+   * Check if THIS node has direct local Internet access
+   * 
+   * This method checks whether this specific node can directly reach the Internet,
+   * as opposed to hasInternetConnection() which checks if any bridge in the mesh
+   * has Internet access.
+   * 
+   * For gateway/bridge nodes, this returns the result of the local health check.
+   * For regular nodes, this typically returns false unless they have their own
+   * Internet connection.
+   * 
+   * \code
+   * if (mesh.hasLocalInternet()) {
+   *   Serial.println("This node has direct Internet access");
+   * }
+   * \endcode
+   * 
+   * @return true if this node has verified local Internet connectivity
+   */
+  bool hasLocalInternet() {
+    return internetHealthChecker.hasLocalInternet();
+  }
+
+  /**
+   * Register callback for local Internet connectivity changes
+   * 
+   * This callback fires when THIS node's direct Internet connectivity changes,
+   * as detected by the periodic health check.
+   * 
+   * \code
+   * mesh.onLocalInternetChanged([](bool available) {
+   *   if (available) {
+   *     Serial.println("Local Internet connected");
+   *   } else {
+   *     Serial.println("Local Internet disconnected");
+   *   }
+   * });
+   * \endcode
+   * 
+   * @param callback Function to call when local Internet status changes
+   */
+  void onLocalInternetChanged(localInternetChangedCallback_t callback) {
+    Log(logger::GENERAL, "onLocalInternetChanged():\n");
+    localInternetChangedCallback = callback;
+    internetHealthChecker.onConnectivityChanged(callback);
+  }
+
+  /**
+   * Get detailed status of local Internet connectivity
+   * 
+   * Returns comprehensive information about Internet connectivity checks
+   * including success/failure counts, timing, and error messages.
+   * 
+   * \code
+   * auto status = mesh.getInternetStatus();
+   * Serial.printf("Internet %s, uptime: %d%%\n", 
+   *               status.available ? "UP" : "DOWN",
+   *               status.getUptimePercent());
+   * \endcode
+   * 
+   * @return InternetStatus structure with detailed connectivity info
+   */
+  gateway::InternetStatus getInternetStatus() {
+    return internetHealthChecker.getStatus();
+  }
+
+  /**
+   * Configure Internet health checker with gateway settings
+   * 
+   * Sets up the health checker with parameters from SharedGatewayConfig.
+   * This should be called before enabling gateway mode.
+   * 
+   * @param config Gateway configuration with check parameters
+   */
+  void configureInternetHealthCheck(const gateway::SharedGatewayConfig& config) {
+    internetHealthChecker.setConfig(config);
+  }
+
+  /**
+   * Set custom Internet check target
+   * 
+   * Override the default check host/port (8.8.8.8:53).
+   * 
+   * @param host Host to check (IP or hostname)
+   * @param port Port to connect to (default 53 for DNS)
+   */
+  void setInternetCheckTarget(const TSTRING& host, uint16_t port = 53) {
+    internetHealthChecker.setCheckTarget(host, port);
+  }
+
+  /**
+   * Set Internet check interval
+   * 
+   * @param intervalMs Interval between checks in milliseconds
+   */
+  void setInternetCheckInterval(uint32_t intervalMs) {
+    internetHealthChecker.setCheckInterval(intervalMs);
+  }
+
+  /**
+   * Set Internet check timeout
+   * 
+   * @param timeoutMs Timeout for each check in milliseconds
+   */
+  void setInternetCheckTimeout(uint32_t timeoutMs) {
+    internetHealthChecker.setCheckTimeout(timeoutMs);
+  }
+
+  /**
+   * Perform an immediate Internet connectivity check
+   * 
+   * Bypasses the periodic check schedule and performs an immediate check.
+   * Fires the onLocalInternetChanged callback if status changes.
+   * 
+   * @return true if Internet is reachable
+   */
+  bool checkInternetNow() {
+    return internetHealthChecker.checkNow();
+  }
+
+  /**
+   * Enable periodic Internet health checking
+   * 
+   * Starts a TaskScheduler task that periodically checks Internet connectivity.
+   * The check interval is configured via setInternetCheckInterval() or
+   * configureInternetHealthCheck().
+   * 
+   * \code
+   * mesh.enableInternetHealthCheck();  // Use default 30 second interval
+   * // or
+   * mesh.setInternetCheckInterval(15000);  // 15 seconds
+   * mesh.enableInternetHealthCheck();
+   * \endcode
+   */
+  void enableInternetHealthCheck() {
+    using namespace logger;
+    if (internetHealthCheckTask != nullptr) {
+      Log(GENERAL, "enableInternetHealthCheck(): Already enabled\n");
+      return;
+    }
+    
+    Log(GENERAL, "enableInternetHealthCheck(): Starting health check task (interval: %u ms)\n",
+        internetHealthChecker.getCheckInterval());
+    
+    internetHealthCheckTask = this->addTask(
+        internetHealthChecker.getCheckInterval(),
+        TASK_FOREVER,
+        [this]() {
+          this->internetHealthChecker.checkNow();
+        });
+  }
+
+  /**
+   * Disable periodic Internet health checking
+   */
+  void disableInternetHealthCheck() {
+    using namespace logger;
+    if (internetHealthCheckTask != nullptr) {
+      internetHealthCheckTask->disable();
+      internetHealthCheckTask = nullptr;
+      Log(GENERAL, "disableInternetHealthCheck(): Health check task disabled\n");
+    }
+  }
+
+  /**
+   * Check if Internet health checking is enabled
+   * 
+   * @return true if periodic health checks are running
+   */
+  bool isInternetHealthCheckEnabled() const {
+    return internetHealthCheckTask != nullptr && internetHealthCheckTask->isEnabled();
+  }
+
+  /**
+   * Reset Internet health check statistics
+   */
+  void resetInternetHealthStats() {
+    internetHealthChecker.resetStats();
+  }
+
+#ifdef PAINLESSMESH_BOOST
+  /**
+   * Set mock Internet connectivity (test environment only)
+   * 
+   * @param connected Whether to simulate connected state
+   */
+  void setMockInternetConnected(bool connected) {
+    internetHealthChecker.setMockConnected(connected);
+  }
+#endif
+
+  // ==================== Send to Internet API ====================
+
+  /**
+   * Send data to an Internet destination through the mesh gateway
+   *
+   * This method provides a high-level API for sending data to the Internet
+   * through the mesh network. It automatically handles:
+   * - Local Internet: If this node has direct Internet access, sends directly
+   * - Gateway routing: Otherwise routes through the best available gateway
+   * - Acknowledgment tracking: Tracks message delivery with callbacks
+   * - Retry logic: Implements exponential backoff for failed deliveries
+   * - Priority handling: Respects message priority levels
+   *
+   * PRIORITY LEVELS:
+   * - 0 (CRITICAL): Immediate processing, no delays
+   * - 1 (HIGH): High priority, processed before normal
+   * - 2 (NORMAL): Standard processing (default)
+   * - 3 (LOW): Background processing when idle
+   *
+   * CALLBACK BEHAVIOR:
+   * The callback is invoked when:
+   * - Success: Gateway confirms delivery to Internet destination
+   * - Failure: Timeout, no gateway available, or delivery error
+   *
+   * \code
+   * // Send sensor data to cloud API
+   * uint32_t msgId = mesh.sendToInternet(
+   *   "https://api.example.com/sensor",
+   *   "{\"temperature\": 23.5}",
+   *   [](bool success, uint16_t httpStatus, String error) {
+   *     if (success) {
+   *       Serial.printf("Delivered! HTTP %u\n", httpStatus);
+   *     } else {
+   *       Serial.printf("Failed: %s\n", error.c_str());
+   *     }
+   *   },
+   *   PRIORITY_NORMAL  // Optional priority
+   * );
+   * Serial.printf("Message ID: %u\n", msgId);
+   * \endcode
+   *
+   * @param destination The Internet destination URL (e.g., "https://api.example.com/data")
+   * @param payload The data payload to send (typically JSON)
+   * @param callback Function called with result (success, httpStatus, error)
+   * @param priority Message priority (0=CRITICAL to 3=LOW, default: 2=NORMAL)
+   * @return Unique message ID for tracking, or 0 if immediate failure
+   */
+  uint32_t sendToInternet(
+      TSTRING destination,
+      TSTRING payload,
+      internetResultCallback_t callback,
+      uint8_t priority = static_cast<uint8_t>(gateway::GatewayPriority::PRIORITY_NORMAL)) {
+    using namespace logger;
+
+    // Generate unique message ID
+    uint32_t messageId = gateway::GatewayDataPackage::generateMessageId(this->nodeId);
+
+    Log(COMMUNICATION, "sendToInternet(): msgId=%u dest=%s priority=%u\n",
+        messageId, destination.c_str(), priority);
+
+    // Check if we have local Internet access
+    // Note: Even with local Internet, we still use the gateway protocol for consistency.
+    // A future optimization could bypass the mesh for nodes with direct Internet access.
+    if (hasLocalInternet()) {
+      Log(COMMUNICATION, "sendToInternet(): Local Internet available, using gateway protocol for consistency\n");
+    }
+
+    // Find the best gateway to route through
+    BridgeInfo* gateway = getPrimaryBridge();
+    if (gateway == nullptr) {
+      Log(ERROR, "sendToInternet(): No gateway available\n");
+      if (callback) {
+        // Schedule callback to avoid blocking
+        this->addTask([callback]() {
+          callback(false, 0, "No gateway available");
+        });
+      }
+      return 0;
+    }
+
+    // Create and store the pending request
+    PendingInternetRequest request;
+    request.messageId = messageId;
+    request.timestamp = millis();
+    request.retryCount = 0;
+    request.maxRetries = internetRetryCount;
+    request.priority = priority;
+    request.timeoutMs = internetRequestTimeout;
+    request.retryDelayMs = internetRetryDelay;
+    request.gatewayNodeId = gateway->nodeId;
+    request.destination = destination;
+    request.payload = payload;
+    request.callback = callback;
+
+    // Store pending request
+    pendingInternetRequests[messageId] = request;
+
+    // Create gateway data package
+    gateway::GatewayDataPackage pkg;
+    pkg.from = this->nodeId;
+    pkg.dest = gateway->nodeId;
+    pkg.messageId = messageId;
+    pkg.originNode = this->nodeId;
+    pkg.timestamp = this->getNodeTime();
+    pkg.priority = priority;
+    pkg.destination = destination;
+    pkg.payload = payload;
+    pkg.contentType = "application/json";
+    pkg.retryCount = 0;
+    pkg.requiresAck = true;
+
+    // Send the package with priority
+    bool sent = false;
+    auto conn = painlessmesh::router::findRoute<T>((*this), gateway->nodeId);
+    if (conn) {
+      sent = painlessmesh::router::sendWithPriority(pkg, conn, priority);
+      if (!sent) {
+        Log(ERROR, "sendToInternet(): sendWithPriority failed to gateway %u (send buffer full?)\n", gateway->nodeId);
+      }
+    } else {
+      Log(ERROR, "sendToInternet(): No route to gateway %u\n", gateway->nodeId);
+    }
+
+    if (!sent) {
+      Log(ERROR, "sendToInternet(): Failed to send to gateway %u, scheduling retry\n", gateway->nodeId);
+      // Schedule retry or failure callback
+      scheduleInternetRetry(messageId);
+    } else {
+      Log(COMMUNICATION, "sendToInternet(): Sent to gateway %u\n", gateway->nodeId);
+      // Schedule timeout check
+      scheduleInternetTimeout(messageId);
+    }
+
+    return messageId;
+  }
+
+  /**
+   * Configure Internet request timeout
+   *
+   * @param timeoutMs Timeout in milliseconds (default: 30000)
+   */
+  void setInternetRequestTimeout(uint32_t timeoutMs) {
+    internetRequestTimeout = timeoutMs;
+  }
+
+  /**
+   * Configure Internet request retry count
+   *
+   * @param retryCount Number of retry attempts (default: 3)
+   */
+  void setInternetRetryCount(uint8_t retryCount) {
+    internetRetryCount = retryCount;
+  }
+
+  /**
+   * Configure base retry delay for exponential backoff
+   *
+   * @param delayMs Base delay in milliseconds (default: 1000)
+   */
+  void setInternetRetryDelay(uint32_t delayMs) {
+    internetRetryDelay = delayMs;
+  }
+
+  /**
+   * Get number of pending Internet requests
+   *
+   * @return Number of requests waiting for acknowledgment
+   */
+  size_t getPendingInternetRequestCount() const {
+    return pendingInternetRequests.size();
+  }
+
+  /**
+   * Cancel a pending Internet request
+   *
+   * @param messageId Message ID to cancel
+   * @return true if request was found and cancelled
+   */
+  bool cancelInternetRequest(uint32_t messageId) {
+    auto it = pendingInternetRequests.find(messageId);
+    if (it != pendingInternetRequests.end()) {
+      if (it->second.callback) {
+        it->second.callback(false, 0, "Request cancelled");
+      }
+      pendingInternetRequests.erase(it);
+      Log(logger::GENERAL, "cancelInternetRequest(): Cancelled msgId=%u\n", messageId);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Enable the sendToInternet() API
+   *
+   * This registers the handler for GatewayAckPackage (Type 621) and
+   * starts the periodic cleanup of timed-out requests.
+   *
+   * Call this after mesh.init() to enable the sendToInternet() functionality.
+   *
+   * \code
+   * mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+   * mesh.enableSendToInternet();  // Enable the API
+   * \endcode
+   */
+  void enableSendToInternet() {
+    using namespace logger;
+    Log(GENERAL, "enableSendToInternet(): Enabling Internet routing API\n");
+
+    // Register handler for gateway acknowledgment packages
+    this->callbackList.onPackage(
+        protocol::GATEWAY_ACK,
+        [this](protocol::Variant& variant, std::shared_ptr<T>, uint32_t) {
+          auto ack = variant.to<gateway::GatewayAckPackage>();
+          this->handleGatewayAck(ack);
+          return false;  // Don't consume, allow other handlers
+        });
+
+    // Start cleanup task for timed-out requests
+    if (internetCleanupTask == nullptr) {
+      internetCleanupTask = this->addTask(
+          5000,  // Check every 5 seconds
+          TASK_FOREVER,
+          [this]() {
+            this->cleanupTimedOutRequests();
+          });
+    }
+
+    sendToInternetEnabled = true;
+  }
+
+  /**
+   * Disable the sendToInternet() API
+   */
+  void disableSendToInternet() {
+    using namespace logger;
+    Log(GENERAL, "disableSendToInternet(): Disabling Internet routing API\n");
+
+    if (internetCleanupTask != nullptr) {
+      internetCleanupTask->disable();
+      internetCleanupTask = nullptr;
+    }
+
+    // Cancel all pending requests
+    for (auto& pair : pendingInternetRequests) {
+      if (pair.second.callback) {
+        pair.second.callback(false, 0, "API disabled");
+      }
+    }
+    pendingInternetRequests.clear();
+
+    sendToInternetEnabled = false;
+  }
+
+  /**
+   * Check if sendToInternet() API is enabled
+   *
+   * @return true if the API is enabled
+   */
+  bool isSendToInternetEnabled() const {
+    return sendToInternetEnabled;
+  }
+
+ private:
+  /**
+   * Handle incoming gateway acknowledgment package
+   */
+  void handleGatewayAck(const gateway::GatewayAckPackage& ack) {
+    using namespace logger;
+    Log(COMMUNICATION, "handleGatewayAck(): msgId=%u success=%d http=%u\n",
+        ack.messageId, ack.success, ack.httpStatus);
+
+    auto it = pendingInternetRequests.find(ack.messageId);
+    if (it == pendingInternetRequests.end()) {
+      Log(GENERAL, "handleGatewayAck(): Unknown message ID %u\n", ack.messageId);
+      return;
+    }
+
+    PendingInternetRequest& request = it->second;
+
+    // Call user callback
+    if (request.callback) {
+      request.callback(ack.success, ack.httpStatus, ack.error);
+    }
+
+    // Remove from pending
+    pendingInternetRequests.erase(it);
+  }
+
+  /**
+   * Schedule retry for a failed Internet request
+   */
+  void scheduleInternetRetry(uint32_t messageId) {
+    auto it = pendingInternetRequests.find(messageId);
+    if (it == pendingInternetRequests.end()) {
+      return;
+    }
+
+    PendingInternetRequest& request = it->second;
+
+    if (request.retryCount >= request.maxRetries) {
+      // Max retries reached - fail the request
+      Log(logger::ERROR, "scheduleInternetRetry(): Max retries reached for msgId=%u\n",
+          messageId);
+      if (request.callback) {
+        request.callback(false, 0, "Max retries exceeded");
+      }
+      pendingInternetRequests.erase(it);
+      return;
+    }
+
+    // Calculate exponential backoff delay
+    uint32_t delay = request.retryDelayMs * (1 << request.retryCount);
+    request.retryCount++;
+
+    Log(logger::COMMUNICATION, "scheduleInternetRetry(): Retry %u for msgId=%u in %u ms\n",
+        request.retryCount, messageId, delay);
+
+    // Schedule retry
+    this->addTask(delay, TASK_ONCE, [this, messageId]() {
+      this->retryInternetRequest(messageId);
+    });
+  }
+
+  /**
+   * Retry sending an Internet request
+   */
+  void retryInternetRequest(uint32_t messageId) {
+    auto it = pendingInternetRequests.find(messageId);
+    if (it == pendingInternetRequests.end()) {
+      return;
+    }
+
+    PendingInternetRequest& request = it->second;
+
+    // Find gateway (may have changed)
+    BridgeInfo* gateway = getPrimaryBridge();
+    if (gateway == nullptr) {
+      Log(logger::ERROR, "retryInternetRequest(): No gateway for retry msgId=%u\n",
+          messageId);
+      scheduleInternetRetry(messageId);
+      return;
+    }
+
+    // Update gateway node ID (may have changed)
+    request.gatewayNodeId = gateway->nodeId;
+
+    // Create gateway data package
+    gateway::GatewayDataPackage pkg;
+    pkg.from = this->nodeId;
+    pkg.dest = gateway->nodeId;
+    pkg.messageId = messageId;
+    pkg.originNode = this->nodeId;
+    pkg.timestamp = this->getNodeTime();
+    pkg.priority = request.priority;
+    pkg.destination = request.destination;
+    pkg.payload = request.payload;
+    pkg.contentType = "application/json";
+    pkg.retryCount = request.retryCount;
+    pkg.requiresAck = true;
+
+    // Send the package
+    auto conn = painlessmesh::router::findRoute<T>((*this), gateway->nodeId);
+    bool sent = false;
+    if (conn) {
+      sent = painlessmesh::router::sendWithPriority(pkg, conn, request.priority);
+    }
+
+    if (!sent) {
+      Log(logger::ERROR, "retryInternetRequest(): Retry send failed msgId=%u\n", messageId);
+      scheduleInternetRetry(messageId);
+    } else {
+      Log(logger::COMMUNICATION, "retryInternetRequest(): Retry sent msgId=%u to gateway %u\n",
+          messageId, gateway->nodeId);
+    }
+  }
+
+  /**
+   * Schedule timeout check for an Internet request
+   */
+  void scheduleInternetTimeout(uint32_t messageId) {
+    auto it = pendingInternetRequests.find(messageId);
+    if (it == pendingInternetRequests.end()) {
+      return;
+    }
+
+    uint32_t timeout = it->second.timeoutMs;
+
+    this->addTask(timeout, TASK_ONCE, [this, messageId]() {
+      this->checkInternetRequestTimeout(messageId);
+    });
+  }
+
+  /**
+   * Check if a specific request has timed out
+   */
+  void checkInternetRequestTimeout(uint32_t messageId) {
+    auto it = pendingInternetRequests.find(messageId);
+    if (it == pendingInternetRequests.end()) {
+      return;  // Already handled
+    }
+
+    PendingInternetRequest& request = it->second;
+
+    if (request.isTimedOut()) {
+      Log(logger::ERROR, "checkInternetRequestTimeout(): Request timed out msgId=%u\n",
+          messageId);
+      if (request.callback) {
+        request.callback(false, 0, "Request timed out");
+      }
+      pendingInternetRequests.erase(it);
+    }
+  }
+
+  /**
+   * Cleanup all timed-out Internet requests
+   */
+  void cleanupTimedOutRequests() {
+    auto it = pendingInternetRequests.begin();
+    while (it != pendingInternetRequests.end()) {
+      if (it->second.isTimedOut()) {
+        Log(logger::GENERAL, "cleanupTimedOutRequests(): Cleaning up msgId=%u\n",
+            it->first);
+        if (it->second.callback) {
+          it->second.callback(false, 0, "Request timed out");
+        }
+        it = pendingInternetRequests.erase(it);
+      } else {
+        ++it;
+      }
+    }
+  }
+
+ public:
   /**
    * Update bridge information from received status package
    * Internal method called when bridge status is received
@@ -679,7 +1661,30 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     bool wasConnected = false;
     bool isNewBridge = false;
     if (bridge == nullptr) {
-      // New bridge - add to list
+      // New bridge - enforce MAX_KNOWN_BRIDGES limit before adding
+      if (knownBridges.size() >= MAX_KNOWN_BRIDGES) {
+        // First try to remove expired bridges
+        cleanupExpiredBridges();
+        
+        // If still at capacity, remove the bridge with worst RSSI (lowest signal)
+        if (knownBridges.size() >= MAX_KNOWN_BRIDGES && !knownBridges.empty()) {
+          auto worstBridge = knownBridges.begin();
+          int8_t worstRSSI = worstBridge->routerRSSI;
+          
+          for (auto it = knownBridges.begin(); it != knownBridges.end(); ++it) {
+            if (it->routerRSSI < worstRSSI) {
+              worstRSSI = it->routerRSSI;
+              worstBridge = it;
+            }
+          }
+          
+          Log(logger::GENERAL, "updateBridgeStatus(): Removing bridge %u (RSSI: %d) to make room\n",
+              worstBridge->nodeId, worstBridge->routerRSSI);
+          knownBridges.erase(worstBridge);
+        }
+      }
+      
+      // Add new bridge
       BridgeInfo newBridge;
       newBridge.nodeId = bridgeNodeId;
       knownBridges.push_back(newBridge);
@@ -702,6 +1707,11 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     auto newPrimary = this->getPrimaryBridge();
     uint32_t newPrimaryBridgeId = (newPrimary != nullptr) ? newPrimary->nodeId : 0;
     
+    // Trigger gateway changed callback if primary gateway changed
+    if (oldPrimaryBridgeId != newPrimaryBridgeId && gatewayChangedCallback) {
+      gatewayChangedCallback(oldPrimaryBridgeId, newPrimaryBridgeId);
+    }
+    
     if (diagnosticsEnabled && oldPrimaryBridgeId != newPrimaryBridgeId) {
       // Record bridge change
       lastBridgeChange.timestamp = millis();
@@ -2095,6 +3105,7 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
   nodeDelayCallback_t nodeDelayReceivedCallback;
   bridgeStatusChangedCallback_t bridgeStatusChangedCallback;
   rtcSyncCompleteCallback_t rtcSyncCompleteCallback;
+  gatewayChangedCallback_t gatewayChangedCallback;
   
   // Message queue for offline mode
   MessageQueue* messageQueue = nullptr;
@@ -2143,6 +3154,10 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
   uint32_t bridgeStatusIntervalMs = 30000;  // Default 30 seconds
   uint32_t bridgeTimeoutMs = 60000;         // Default 60 seconds
   bool bridgeStatusBroadcastEnabled = true;
+  
+  // Bridge cleanup configuration
+  static const size_t MAX_KNOWN_BRIDGES = 20;  // Memory efficient limit for ESP8266
+  std::shared_ptr<Task> bridgeCleanupTask = nullptr;
 
   // Health metrics tracking
   uint32_t metricsDisconnectCount = 0;
@@ -2157,6 +3172,19 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
   BridgeChangeEvent lastBridgeChange;
   uint32_t lastBridgeChangeTime = 0;
 
+  // Local Internet health check
+  gateway::InternetHealthChecker internetHealthChecker;
+  std::shared_ptr<Task> internetHealthCheckTask = nullptr;
+  localInternetChangedCallback_t localInternetChangedCallback;
+
+  // sendToInternet API
+  std::map<uint32_t, PendingInternetRequest> pendingInternetRequests;
+  std::shared_ptr<Task> internetCleanupTask = nullptr;
+  uint32_t internetRequestTimeout = 30000;   // Default 30 seconds
+  uint8_t internetRetryCount = 3;            // Default 3 retries
+  uint32_t internetRetryDelay = 1000;        // Default 1 second base delay
+  bool sendToInternetEnabled = false;
+
   friend T;
   friend void onDataCb(void *, AsyncClient *, void *, size_t);
   friend void tcpSentCb(void *, AsyncClient *, size_t, uint32_t);