wifi.hpp

Go to the documentation of this file.

#ifndef _PAINLESS_MESH_ARDUINO_WIFI_HPP_
#define _PAINLESS_MESH_ARDUINO_WIFI_HPP_
 
#include "painlessmesh/configuration.hpp"
 
#include "painlessmesh/logger.hpp"
#ifdef PAINLESSMESH_ENABLE_ARDUINO_WIFI
#include "painlessMeshSTA.h"
 
#include "painlessmesh/callback.hpp"
#include "painlessmesh/gateway.hpp"
#include "painlessmesh/mesh.hpp"
#include "painlessmesh/router.hpp"
#include "painlessmesh/tcp.hpp"
 
#ifdef ESP32
#include <HTTPClient.h>
#include <WiFiClientSecure.h>
#elif defined(ESP8266)
#include <ESP8266HTTPClient.h>
#include <WiFiClientSecure.h>
#endif
 
extern painlessmesh::logger::LogClass Log;
 
#define PAINLESSMESH_HAS_TCP_LISTENING 1
 
namespace painlessmesh {
namespace wifi {
class Mesh : public painlessmesh::Mesh<Connection> {
 public:
  // Multi-bridge selection strategy enum (must be declared early)
  enum BridgeSelectionStrategy {
    PRIORITY_BASED = 0,  // Use highest priority bridge (default)
    ROUND_ROBIN = 1,     // Distribute load evenly
    BEST_SIGNAL = 2      // Use bridge with best RSSI
  };
 
  void init(TSTRING ssid, TSTRING password, uint16_t port = 5555,
            WiFiMode_t connectMode = WIFI_AP_STA, uint8_t channel = 1,
            uint8_t hidden = 0, uint8_t maxconn = MAX_CONN,
            TSTRING stationSSID = "", TSTRING stationPassword = "") {
    using namespace logger;
    // Init random generator seed to generate delay variance
    randomSeed(millis());
 
    // Shut Wifi down and start with a blank slage
    if (WiFi.status() != WL_DISCONNECTED) WiFi.disconnect();
 
    // The mesh reconnects on its own terms: it scans, chooses an AP, and
    // connects. The core must not. On core 2.x this used to call
    // setAutoConnect(false) — the "connect at boot from stored
    // credentials" flag, a different thing — and left the core's
    // auto-reconnect at its default of on. After a parent's AP vanished
    // (BEACON_TIMEOUT) the core then tried the gone BSSID again every seven
    // seconds (NO_AP_FOUND, a full-channel search each time) for as long as
    // it stayed gone, and every attempt kept the radio busy so the mesh's
    // own scan "could not start": the node sat outside the mesh for the
    // rest of the test. Measured on the rig on every core-2.x board (ESP32,
    // C3, S3); the core-3.x boards, which got the right call, did not do it.
    Log(STARTUP, "init(): %d\n", WiFi.setAutoReconnect(false));
#if ESP_ARDUINO_VERSION_MAJOR < 3
    WiFi.setAutoConnect(false);
#endif
    WiFi.persistent(false);
 
    // start configuration
    if (!WiFi.mode(connectMode)) {
      Log(GENERAL, "WiFi.mode() false");
    }
#ifdef ESP32
#if SOC_WIFI_SUPPORT_5G && ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 4, 2)
    // The mesh lives on 2.4 GHz. A dual-band part left in its default band
    // mode scans the 5 GHz channels as well every time it looks for the
    // mesh: measured on an ESP32-C5, the all-channel scan took 13–14 s
    // against 4 s on a single-band part — at boot, where it is the whole
    // of the C5's 15 s to its first reply, and on every channel
    // re-detection, where it swallowed the console commands sent
    // meanwhile. Nothing the mesh does needs the other band.
    if (!WiFi.setBandMode(WIFI_BAND_MODE_2G_ONLY)) {
      Log(ERROR, "init(): could not restrict the radio to 2.4 GHz\n");
    }
#endif
#endif
 
    _meshSSID = ssid;
    _meshPassword = password;
    _meshChannel = channel;
    Log(STARTUP, "init(): Mesh channel set to %d\n", _meshChannel);
    _meshHidden = hidden;
    _meshMaxConn = maxconn;
    _meshPort = port;
 
    uint8_t MAC[] = {0, 0, 0, 0, 0, 0};
#if ESP_ARDUINO_VERSION_MAJOR >= 3
    esp_read_mac(MAC, ESP_MAC_WIFI_SOFTAP);
#else
    if (WiFi.softAPmacAddress(MAC) == 0) {
      Log(ERROR, "init(): WiFi.softAPmacAddress(MAC) failed.\n");
    }
#endif
    uint32_t nodeId = tcp::encodeNodeId(MAC);
    if (nodeId == 0) Log(ERROR, "NodeId set to 0\n");
 
    this->init(nodeId);
 
#ifdef ESP8266
    // The ESP8266 is specified for small meshes, or as a leaf in larger
    // ones. Say so at runtime when a deployment has put it in the middle of
    // one: see Mesh::capacityCheck(). Thirty seconds is often enough to
    // catch it and rare enough to cost nothing.
    this->addTask(30 * TASK_SECOND, TASK_FOREVER, [this]() {
      this->capacityCheck(ESP.getFreeHeap(),
                          painlessmesh::Mesh<Connection>::ESP8266_CAPACITY_FLOOR);
    });
#endif
 
    // Add bridge election package handler (Type BRIDGE_ELECTION)
    this->callbackList.onPackage(
        protocol::BRIDGE_ELECTION,
        [this](protocol::Variant& variant, std::shared_ptr<Connection>,
               uint32_t) {
          JsonDocument doc;
          TSTRING str;
          variant.printTo(str);
          deserializeJson(doc, str);
          JsonObject obj = doc.as<JsonObject>();
 
          if (obj["routerRSSI"].is<int>()) {
            uint32_t fromNode = obj["from"];
            int8_t routerRSSI = obj["routerRSSI"];
            uint8_t routerChannel = obj["routerChannel"] | 0;
            uint32_t uptime = obj["uptime"] | 0;
            uint32_t freeMemory = obj["freeMemory"] | 0;
 
            this->handleBridgeElection(fromNode, routerRSSI, routerChannel,
                                       uptime, freeMemory);
 
            Log(CONNECTION, "Bridge election candidate from %u: RSSI %d dBm\n",
                fromNode, routerRSSI);
          }
          return false;  // Don't consume the package
        });
 
    // Add bridge takeover package handler (Type BRIDGE_TAKEOVER)
    this->callbackList.onPackage(
        protocol::BRIDGE_TAKEOVER,
        [this](protocol::Variant& variant, std::shared_ptr<Connection>,
               uint32_t) {
          JsonDocument doc;
          TSTRING str;
          variant.printTo(str);
          deserializeJson(doc, str);
          JsonObject obj = doc.as<JsonObject>();
 
          if (obj["previousBridge"].is<unsigned int>()) {
            uint32_t newBridge = obj["from"];
            uint32_t previousBridge = obj["previousBridge"];
            TSTRING reason = obj["reason"].as<TSTRING>();
            uint8_t routerChannel = obj["routerChannel"] | 0;
 
            Log(CONNECTION,
                "Bridge takeover: Node %u replaced %u on channel %u (%s)\n",
                newBridge, previousBridge, routerChannel, reason.c_str());
 
            // AP+STA radios must use one channel. Follow the elected bridge
            // promptly instead of waiting for the slow empty-scan recovery.
            if (gateway::shouldFollowBridgeChannel(
                    this->nodeId, newBridge, _meshChannel, routerChannel)) {
              this->addTask(1000, TASK_ONCE, [this, routerChannel]() {
                stationScan.followBridgeChannel(routerChannel);
              });
            }
 
            // Notify callback if this node was not the winner
            if (newBridge != this->nodeId && bridgeRoleChangedCallback) {
              bridgeRoleChangedCallback(false, "Another node won election");
            }
          }
          return false;  // Don't consume the package
        });
 
    // Add callback to detect bridge failures and trigger elections
    this->onBridgeStatusChanged([this](uint32_t bridgeNodeId,
                                       bool hasInternet) {
      if (!hasInternet && bridgeFailoverEnabled &&
          routerCredentialsConfigured) {
        Log(CONNECTION, "Bridge %u lost Internet, considering election...\n",
            bridgeNodeId);
 
        // Check if we still have any healthy bridges
        if (!this->hasInternetConnection()) {
          Log(CONNECTION, "No healthy bridges, starting election\n");
          // Small delay to let all nodes detect the failure
          this->addTask(2000, TASK_ONCE,
                        [this]() { this->startBridgeElection(); });
        }
      }
    });
 
    // Add periodic monitoring task to detect when no bridge exists
    // This handles the case where no node was initially configured as a bridge
    this->addTask(30000, TASK_FOREVER, [this]() { this->checkForBridge(); });
 
    // Add separate periodic task for isolated bridge retry
    // This handles the case where a node:
    // - Has router credentials configured
    // - Is isolated (no mesh connections)
    // - Should attempt to become a bridge directly
    // This is different from the election mechanism which requires mesh
    // connectivity
    this->addTask(isolatedBridgeRetryIntervalMs, TASK_FOREVER, [this]() {
      // Only retry if failover is enabled and we have credentials
      if (!bridgeFailoverEnabled || !routerCredentialsConfigured) {
        return;
      }
 
      // Don't retry if we're already a bridge
      if (this->isBridge()) {
        return;
      }
 
      // Skip during startup period
      if (millis() < electionStartupDelayMs) {
        return;
      }
 
      // Only retry when isolated (no mesh connections found)
      if (this->hasActiveMeshConnections()) {
        // Reset retry counter and pending flag when mesh is active (no longer
        // isolated)
        _isolatedBridgeRetryAttempts = 0;
        _isolatedRetryPending = false;
        return;
      }
 
      // Limit retry attempts with reset after timeout
      if (_isolatedBridgeRetryAttempts >= MAX_ISOLATED_BRIDGE_RETRY_ATTEMPTS) {
        // Check if enough time has passed to reset the counter
        if (millis() > _isolatedBridgeRetryResetTime) {
          Log(CONNECTION,
              "Isolated bridge retry: Reset timeout reached, resetting attempt "
              "counter\n");
          _isolatedBridgeRetryAttempts = 0;
        } else {
          Log(CONNECTION,
              "Isolated bridge retry: Max attempts (%d) reached, reset in %u "
              "seconds\n",
              MAX_ISOLATED_BRIDGE_RETRY_ATTEMPTS,
              (_isolatedBridgeRetryResetTime - millis()) / 1000);
          return;
        }
      }
 
      // Check if mesh network exists on any channel before trying to become
      // bridge If mesh exists but we can't connect, don't try to become bridge
      // Skip this check if we already confirmed isolation from a previous
      // failed attempt
      uint16_t emptyScans = stationScan.getConsecutiveEmptyScans();
      if (!_isolatedRetryPending &&
          emptyScans < ISOLATED_BRIDGE_RETRY_SCAN_THRESHOLD) {
        Log(CONNECTION,
            "Isolated bridge retry: Only %d empty scans, waiting for more "
            "scans\n",
            emptyScans);
        return;
      }
 
      // Clear the pending flag now that we're proceeding
      _isolatedRetryPending = false;
 
      Log(CONNECTION,
          "Isolated bridge retry: Node isolated with %d empty scans, "
          "attempting bridge promotion\n",
          emptyScans);
 
      // Attempt to become bridge directly (bypassing election since we're
      // isolated) Only increment retry counter if we actually attempted
      // promotion
      if (this->attemptIsolatedBridgePromotion()) {
        _isolatedBridgeRetryAttempts++;
        // Set reset time when reaching max attempts
        if (_isolatedBridgeRetryAttempts >=
            MAX_ISOLATED_BRIDGE_RETRY_ATTEMPTS) {
          _isolatedBridgeRetryResetTime =
              millis() + isolatedBridgeRetryResetIntervalMs;
        }
      }
    });
 
    eventHandleInit();
 
    _apIp = IPAddress(0, 0, 0, 0);
 
    if (connectMode & WIFI_AP) {
      apInit(nodeId);  // setup AP
    }
 
    // Initialize TCP server AFTER AP is configured
    // This ensures the network interfaces are ready when the server starts
    // Fixes TCP connection error -14 when nodes try to connect to bridge
    tcpServerInit();
 
    if (connectMode & WIFI_STA) {
      this->initStation();
    }
 
    // If station credentials provided, connect to router
    if (!stationSSID.isEmpty() && (connectMode & WIFI_STA)) {
      Log(STARTUP, "init(): Connecting to station %s\n", stationSSID.c_str());
      this->stationManual(stationSSID, stationPassword);
    }
  }
 
  void init(TSTRING ssid, TSTRING password, Scheduler* baseScheduler,
            uint16_t port = 5555, WiFiMode_t connectMode = WIFI_AP_STA,
            uint8_t channel = 1, uint8_t hidden = 0, uint8_t maxconn = MAX_CONN,
            TSTRING stationSSID = "", TSTRING stationPassword = "") {
    this->setScheduler(baseScheduler);
    init(ssid, password, port, connectMode, channel, hidden, maxconn,
         stationSSID, stationPassword);
  }
 
  bool initAsBridge(TSTRING meshSSID, TSTRING meshPassword, TSTRING routerSSID,
                    TSTRING routerPassword, Scheduler* baseScheduler,
                    uint16_t port = 5555) {
    using namespace logger;
 
    Log(STARTUP, "=== Bridge Mode Initialization ===\n");
    Log(STARTUP, "Step 1: Attempting to connect to router %s...\n", routerSSID.c_str());
 
    // Store router credentials for future connection attempts
    setRouterCredentials(routerSSID, routerPassword);
 
    // Step 1: Attempt to connect to router first to detect its channel
    // Shut Wifi down and start with a blank slate
    if (WiFi.status() != WL_DISCONNECTED) WiFi.disconnect();
 
    // See init(): the core's auto-reconnect is off on every core version.
    Log(STARTUP, "initAsBridge(): %d\n", WiFi.setAutoReconnect(false));
#if ESP_ARDUINO_VERSION_MAJOR < 3
    WiFi.setAutoConnect(false);
#endif
    WiFi.persistent(false);
    WiFi.mode(WIFI_STA);
 
    // Connect to router and wait for connection
    WiFi.begin(routerSSID.c_str(), routerPassword.c_str());
 
    // Wait for connection (with timeout)
    int timeout = 30;  // 30 seconds timeout
    while (WiFi.status() != WL_CONNECTED && timeout > 0) {
      // Allow event loop processing during hardware settling
      for (int i = 0; i < 100; i++) { delay(10); yield(); }
      timeout--;
      Log(STARTUP, ".");
    }
 
    uint8_t detectedChannel = 1;  // Default fallback
    bool routerConnected = false;
 
    if (WiFi.status() == WL_CONNECTED) {
      detectedChannel = WiFi.channel();
      // Validate channel is in valid range (1-13 for 2.4GHz)
      if (detectedChannel < 1 || detectedChannel > 13) {
        Log(ERROR,
            "\n[FAIL] Invalid channel detected: %d, falling back to channel 1\n",
            detectedChannel);
        detectedChannel = 1;
      } else {
        Log(STARTUP, "\n[OK] Router connected on channel %d\n", detectedChannel);
        Log(STARTUP, "[OK] Router IP: %s\n", WiFi.localIP().toString().c_str());
        routerConnected = true;
      }
    } else {
      Log(STARTUP, "\n[WARN] Router connection unavailable during initialization\n");
      
      // Scan for router to detect its channel even though we can't connect
      // This minimizes channel mismatch when router becomes available later
      Log(STARTUP, "[WARN] Scanning for router '%s' to detect channel...\n", routerSSID.c_str());
      
      // ESP32 and ESP8266 have different scanNetworks signatures
#ifdef ESP32
      int16_t numNetworks = WiFi.scanNetworks(false, false, false, 300U, 0);
#elif defined(ESP8266)
      int16_t numNetworks = WiFi.scanNetworks(false, false, 0);
#endif
      
      if (numNetworks > 0) {
        for (int16_t i = 0; i < numNetworks; i++) {
          if (WiFi.SSID(i) == routerSSID) {
            uint8_t scannedChannel = WiFi.channel(i);
            if (scannedChannel >= 1 && scannedChannel <= 13) {
              detectedChannel = scannedChannel;
              Log(STARTUP, "[OK] Router found on channel %d (not connected, will retry)\n", 
                  detectedChannel);
              break;
            }
          }
        }
        WiFi.scanDelete();
      }
      
      if (detectedChannel == 1) {
        Log(STARTUP, "[WARN] Router not found in scan, using default channel %d\n", detectedChannel);
      }
      
      Log(STARTUP, "[WARN] Proceeding with bridge setup on channel %d\n", detectedChannel);
      Log(STARTUP, "[WARN] Bridge will retry router connection in background\n");
    }
 
    Log(STARTUP, "Step 2: Initializing mesh on channel %d...\n",
        detectedChannel);
 
    // Step 2: Initialize mesh on detected/default channel
    // This allows the bridge to establish the mesh network even without router
    init(meshSSID, meshPassword, baseScheduler, port, WIFI_AP_STA,
         detectedChannel, 0, MAX_CONN);
 
    // Allow network stack to stabilize after AP and TCP server initialization
    // This prevents TCP connection errors (-14) when nodes connect
    delay(100);
 
    Log(STARTUP, "Step 3: Establishing bridge connection...\n");
 
    // Step 3: Establish/re-establish router connection using stationManual
    // If router wasn't available initially, this will be retried automatically
    stationManual(routerSSID, routerPassword, 0);
 
    // Step 4: Configure as root/bridge node
    // Bridge role is established regardless of router connectivity
    // This ensures mesh nodes can connect and the bridge can provide mesh services
    this->setRoot(true);
    this->setContainsRoot(true);
 
    // Step 5: Setup bridge status broadcasting
    initBridgeStatusBroadcast();
 
    // Step 6: Setup gateway Internet handler
    initGatewayInternetHandler();
 
    // Step 7: Start the health checker that drives hasLocalInternet().
    // Without it that flag stays false for the life of the node, so the
    // local short-circuit in sendToInternet() never fires and a bridge
    // asking its own uplink fell through to the mesh-routing path -- which
    // fails with "No active mesh connections" whenever the bridge has no
    // peer yet, even though the router link is up (issue #445).
    // initAsSharedGateway() has always done this; initAsBridge() did not.
    //
    // No configureInternetHealthCheck() call here: a bridge has no
    // SharedGatewayConfig, the checker's own defaults (8.8.8.8:53, 30 s,
    // 5 s) already match that struct's, and configuring would clobber any
    // setInternetCheckTarget() the sketch made before init.
    enableInternetHealthCheck();
 
    Log(STARTUP, "=== Bridge Mode Active ===\n");
    Log(STARTUP, "  Mesh SSID: %s\n", meshSSID.c_str());
    Log(STARTUP, "  Mesh Channel: %d%s\n", detectedChannel, 
        routerConnected ? " (matches router)" : " (default, router pending)");
    Log(STARTUP, "  Router: %s%s\n", routerSSID.c_str(),
        routerConnected ? " (connected)" : " (will retry)");
    Log(STARTUP, "  Port: %d\n", port);
    
    if (!routerConnected) {
      Log(STARTUP, "\nINFO: Bridge initialized without router connection\n");
      Log(STARTUP, "INFO: Mesh network is active and accepting node connections\n");
      Log(STARTUP, "INFO: Router connection will be established automatically when available\n");
    }
    
    // Always returns true: bridge mesh functionality is active regardless of
    // router connection status. The router connection is opportunistic.
    return true;
  }
 
  bool initAsBridge(TSTRING meshSSID, TSTRING meshPassword, TSTRING routerSSID,
                    TSTRING routerPassword, Scheduler* baseScheduler,
                    uint16_t port, uint8_t priority) {
    using namespace logger;
 
    // Validate and store priority
    if (priority < 1) priority = 1;
    if (priority > 10) priority = 10;
    bridgePriority = priority;
 
    // Store role based on priority
    if (priority >= 8) {
      bridgeRole = "primary";
    } else if (priority >= 5) {
      bridgeRole = "secondary";
    } else {
      bridgeRole = "standby";
    }
 
    Log(STARTUP,
        "=== Bridge Mode Initialization (Priority: %d, Role: %s) ===\n",
        priority, bridgeRole.c_str());
 
    // Call the base initAsBridge method
    bool success = initAsBridge(meshSSID, meshPassword, routerSSID,
                                routerPassword, baseScheduler, port);
 
    // Setup multi-bridge coordination if enabled and bridge init succeeded
    if (success && multiBridgeEnabled) {
      initBridgeCoordination();
    }
 
    return success;
  }
 
  bool initAsSharedGateway(
      TSTRING meshPrefix, TSTRING meshPassword, TSTRING routerSSID,
      TSTRING routerPassword, Scheduler* userScheduler, uint16_t port = 5555,
      gateway::SharedGatewayConfig config = gateway::SharedGatewayConfig()) {
    using namespace logger;
 
    Log(STARTUP, "=== Shared Gateway Mode Initialization ===\n");
 
    // Validate configuration if enabled
    if (config.enabled) {
      auto result = config.validate();
      if (!result.valid) {
        Log(ERROR, "initAsSharedGateway(): Config validation failed: %s\n",
            result.errorMessage.c_str());
        return false;
      }
    }
 
    // Store shared gateway configuration
    _sharedGatewayConfig = config;
    _sharedGatewayConfig.routerSSID = routerSSID;
    _sharedGatewayConfig.routerPassword = routerPassword;
    _sharedGatewayConfig.enabled = true;
    _sharedGatewayMode = true;
 
    Log(STARTUP, "Step 1: Scanning for router %s to detect channel...\n",
        routerSSID.c_str());
 
    // Step 1: Scan for router to detect its channel
    // We need to ensure mesh and router operate on the same channel
    if (WiFi.status() != WL_DISCONNECTED) WiFi.disconnect();
 
    // See init(): the core's auto-reconnect is off on every core version.
    WiFi.setAutoReconnect(false);
#if ESP_ARDUINO_VERSION_MAJOR < 3
    WiFi.setAutoConnect(false);
#endif
    Log(STARTUP, "initAsSharedGateway(): AutoReconnect disabled\n");
    WiFi.persistent(false);
    WiFi.mode(WIFI_STA);
 
    // Connect to router to detect channel
    WiFi.begin(routerSSID.c_str(), routerPassword.c_str());
 
    // Wait for connection with timeout (using constant for configurability)
    int timeout = ROUTER_CONNECTION_TIMEOUT_SECONDS;
    while (WiFi.status() != WL_CONNECTED && timeout > 0) {
      // Allow event loop processing during hardware settling
      for (int i = 0; i < 100; i++) { delay(10); yield(); }
      timeout--;
      Log(STARTUP, ".");
    }
 
    uint8_t detectedChannel = 1;  // Default fallback
 
    if (WiFi.status() == WL_CONNECTED) {
      detectedChannel = WiFi.channel();
      // Validate channel is in valid range (1-14 for 2.4GHz, region-dependent)
      if (detectedChannel < MIN_WIFI_CHANNEL ||
          detectedChannel > MAX_WIFI_CHANNEL) {
        Log(ERROR,
            "\n[FAIL] Invalid channel detected: %d, falling back to channel 1\n",
            detectedChannel);
        detectedChannel = 1;
      } else {
        Log(STARTUP, "\n[OK] Router connected on channel %d\n", detectedChannel);
        Log(STARTUP, "[OK] Router IP: %s\n", WiFi.localIP().toString().c_str());
      }
    } else {
      Log(ERROR, "\n[FAIL] Failed to connect to router during channel detection\n");
      Log(ERROR,
          "Continuing with default channel 1, will retry router connection "
          "later\n");
    }
 
    // Disconnect from router, we'll reconnect after mesh init
    WiFi.disconnect();
    delay(100);
 
    Log(STARTUP, "Step 2: Initializing mesh on channel %d...\n",
        detectedChannel);
 
    // Step 2: Initialize mesh on detected channel with AP+STA mode
    // Set scheduler before init
    this->setScheduler(userScheduler);
    init(meshPrefix, meshPassword, port, WIFI_AP_STA, detectedChannel, 0,
         MAX_CONN);
 
    // Allow network stack to stabilize after AP and TCP server initialization
    // This prevents TCP connection errors (-14) when nodes connect
    delay(100);
 
    Log(STARTUP,
        "Step 3: Establishing router connection in shared gateway mode...\n");
 
    // Step 3: Establish router connection using stationManual
    // Port 0 means we don't expect TCP mesh connection to the router
    stationManual(routerSSID, routerPassword, 0);
 
    // Step 4: Setup router connection monitoring and reconnection logic
    initSharedGatewayMonitoring();
 
    // Step 5: Setup gateway Internet handler
    initGatewayInternetHandler();
 
    // Step 6: Start the health checker that drives hasLocalInternet().
    // Previously shared-gateway nodes associated and received an IP address,
    // but the checker was never configured or scheduled, so local Internet
    // availability remained false forever and every request was needlessly
    // routed toward a mesh gateway.
    configureInternetHealthCheck(_sharedGatewayConfig);
    enableInternetHealthCheck();
 
    // Store router credentials for reconnection
    setRouterCredentials(routerSSID, routerPassword);
 
    Log(STARTUP, "=== Shared Gateway Mode Active ===\n");
    Log(STARTUP, "  Mesh Prefix: %s\n", meshPrefix.c_str());
    Log(STARTUP, "  Mesh Channel: %d (synced with router)\n", detectedChannel);
    Log(STARTUP, "  Router: %s\n", routerSSID.c_str());
    Log(STARTUP, "  Port: %d\n", port);
    Log(STARTUP, "  Mode: AP+STA (all nodes can connect to router)\n");
 
    return true;
  }
 
  bool isSharedGatewayMode() const { return _sharedGatewayMode; }
 
  const gateway::SharedGatewayConfig& getSharedGatewayConfig() const {
    return _sharedGatewayConfig;
  }
 
  void stationManual(TSTRING ssid, TSTRING password, uint16_t port = 0,
                     IPAddress remote_ip = IPAddress(0, 0, 0, 0)) {
    using namespace logger;
    // Set station config
    stationScan.manualIP = remote_ip;
 
    Log(STARTUP, "stationManual(): Connecting to %s\n", ssid.c_str());
 
    // Start scan
    stationScan.init(this, ssid, password, port, _meshChannel,
                     static_cast<bool>(_meshHidden));
    stationScan.manual = true;
 
    // A manual station is the router link of a bridge or shared gateway:
    // one known AP, no mesh scan choosing among candidates. For that link
    // the core's own auto-reconnect is the right mechanism, and it is what
    // kept every bridge's upstream alive until now — by accident, on core
    // 2.x, where init() had never really turned it off. With it off
    // everywhere, a bridge whose second association with the router failed
    // (init() drops the first to start the mesh) sat at WL_IDLE_STATUS for
    // the whole run with no upstream, and no node ever learned of the
    // Internet. On for the manual link; the mesh station in init() keeps
    // it off.
    WiFi.setAutoReconnect(true);
 
    // Directly initiate connection - ESP will auto-detect router's channel
    WiFi.begin(ssid.c_str(), password.c_str());
 
    Log(STARTUP, "stationManual(): Connection initiated\n");
  }
 
  void initStation() {
    stationScan.init(this, _meshSSID, _meshPassword, _meshPort, _meshChannel,
                     static_cast<bool>(_meshHidden));
    mScheduler->addTask(stationScan.task);
    stationScan.task.enable();
 
    this->droppedConnectionCallbacks.push_back(
        [this](uint32_t nodeId, bool station) {
          if (station) {
            if (WiFi.status() == WL_CONNECTED) {
              WiFi.disconnect();
              // Schedule reconnection after disconnect completes
              // The WiFi event handler will signal when disconnect is complete
              _pendingStationReconnect = true;
            } else if (_pendingStationReconnect) {
              // A drop this node asked for: reconnect from the last scan
              handleStationDisconnectComplete();
            } else if (this->stationScan.droppedByMove()) {
              // The drop this node's own channel follow caused.
              // followBridgeChannel() closed the link and scans next;
              // nothing to do here, and above all no re-detection.
              using namespace logger;
              Log(CONNECTION,
                  "Station link closed by this node's channel move\n");
            } else if (!this->stationScan.stationLinkUp) {
              // An attempt that never got an address — the association
              // timed out, or the AP was gone by the time it was tried.
              // Not a loss: scan this channel again, where the next AP is.
              // Re-detecting here sent the sender in sweep 45 run 2, just
              // arrived on the bridge's channel after a peer there had
              // left, to look at the old channel and consider going back,
              // with the bridge's AP at -55 dBm beside it.
              using namespace logger;
              Log(CONNECTION,
                  "Station attempt failed, scanning this channel again\n");
              this->stationScan.task.forceNextIteration();
            } else {
              // A drop nobody asked for — the AP this station was on went
              // away (its node rebooted, or a bridge moved the mesh). Scan
              // now rather than when the current slow-scan delay runs out,
              // which is up to four intervals away for a node that was
              // stable a moment ago.
              using namespace logger;
              Log(CONNECTION,
                  "Station link lost unexpectedly, scanning now\n");
              if (this->shouldContainRoot && this->stationScan.atHome()) {
                // At home the bridge's AP is on this channel; the uplink
                // that went was a relay (in sweep 46 run 2, the backup
                // rebooting into its failover role). Scan this channel
                // now: the all-channel hunt below took the sender twenty
                // seconds, and its request through the bridge ran out of
                // retries in the gap.
                Log(CONNECTION,
                    "Station link lost at home: scanning this channel\n");
              } else if (this->shouldContainRoot) {
                // In a mesh that should have a root, the AP that went away
                // most likely left for the bridge's channel, and the nodes
                // still on this one are about to. Re-attaching here first
                // cost the node the failover test sends from a hundred
                // seconds at the bridge's start: it joined one remnant,
                // lost it, joined the next, lost that, and only then looked
                // at every channel. Look at every channel now; the rules in
                // scanComplete() decide whether to go.
                Log(CONNECTION,
                    "Station link lost in a rooted mesh: re-detecting the "
                    "mesh channel on this scan\n");
                this->stationScan.redetectOnNextScan();
              }
              this->stationScan.task.forceNextIteration();
            }
          }
        });
  }
 
  void handleStationDisconnectComplete() {
    if (_pendingStationReconnect) {
      _pendingStationReconnect = false;
      this->stationScan.yieldConnectToAP();
      // Re-enable scanning if it was disabled
      this->stationScan.task.enableIfNot();
    }
  }
 
  void tcpServerInit() {
    using namespace logger;
    Log(GENERAL, "tcpServerInit():\n");
    // A listener that exists and listens is kept. It is bound to every
    // address, so the AP a re-initialised node brings up is served by it,
    // and re-creating it is not merely needless: the connections the old
    // one accepted share its local port, and lwIP refuses to bind a new
    // listener to a port any of them still holds — for the two minutes
    // they sit in TIME_WAIT after stop() closes them. A node promoted to
    // bridge on the rig logged "bind error: -8" on every attempt for
    // exactly that long, reset every peer that came to join it, and only
    // then had a bridge's listener. AsyncTCP keeps its pcb private, so
    // SO_REUSEADDR cannot be set from here; not re-binding is the fix.
    if (_tcpListener != nullptr) {
      if (_tcpListener->status() == TCP_STATE_LISTEN) {
        Log(CONNECTION,
            "tcpServerInit(): listener on port %d already listening, kept\n",
            _meshPort);
        return;
      }
      delete _tcpListener;
      _tcpListener = nullptr;
    }
    _tcpListener = new AsyncServer(_meshPort);
    painlessmesh::tcp::initServer<Connection, painlessmesh::Mesh<Connection>>(
        (*_tcpListener), (*this));
    Log(STARTUP, "AP tcp server established on port %d\n", _meshPort);
    // The listener's state, at the level the rig keeps: a node promoted to
    // bridge re-creates its listener, and one such node reset every
    // connection to its AP for its whole time as bridge while its log said
    // nothing. LISTEN is 1 on both cores; anything else is the finding.
    Log(CONNECTION, "tcpServerInit(): listener on port %d, state %u\n",
        _meshPort, (unsigned)_tcpListener->status());
    return;
  }
 
  bool tcpListening() {
    return _tcpListener != nullptr && _tcpListener->status() == TCP_STATE_LISTEN;
  }
 
  static constexpr uint8_t TCP_STATE_LISTEN = 1;
 
  void tcpConnect() {
    using namespace logger;
    Log(GENERAL, "tcpConnect():\n");
    if (stationScan.manual && stationScan.port == 0)
      return;  // We have been configured not to connect to the mesh
 
    if (WiFi.status() == WL_CONNECTED && WiFi.localIP()) {
      // Determine target IP and port for connection
      IPAddress targetIP =
          stationScan.manualIP ? stationScan.manualIP : WiFi.gatewayIP();
      uint16_t targetPort = stationScan.port;
 
      Log(CONNECTION, "tcpConnect(): Connecting to %s:%d\n",
          targetIP.toString().c_str(), targetPort);
 
      // Add a small stabilization delay before attempting TCP connection
      // This helps prevent error -14 (ERR_CONN) by allowing the network stack
      // and TCP server to be fully ready. The delay is added via task scheduler
      // to avoid blocking the event loop.
      // The delay is read at schedule time, so calling setTcpRetryConfig()
      // while a connect is already pending affects the next attempt, not the
      // in-flight one.
      this->addTask(
          this->getTcpRetryConfig().stabilizationDelayMs, TASK_ONCE,
          [this, targetIP, targetPort]() {
            // Verify WiFi is still connected after the delay
            if (WiFi.status() != WL_CONNECTED || !WiFi.localIP()) {
              Log(CONNECTION,
                  "tcpConnect(): WiFi disconnected during stabilization "
                  "delay\n");
              return;
            }
 
            Log(CONNECTION,
                "tcpConnect(): Starting TCP connection after stabilization\n");
            AsyncClient* pConn = new AsyncClient();
            // Use wifi::Mesh type to enable blocklist functionality
            // This allows tcp::connect to call blockNodeAfterTCPFailure on retry exhaustion
            painlessmesh::tcp::connect<Connection, wifi::Mesh>(
                (*pConn), targetIP, targetPort, (*this));
          });
    } else {
      Log(ERROR, "tcpConnect(): err Something unexpected in tcpConnect()\n");
    }
  }
 
  void blockNodeAfterTCPFailure(IPAddress ip, uint32_t blockDurationMs = painlessmesh::tcp::TCP_FAILURE_BLOCK_DURATION_MS) {
    using namespace logger;
    uint32_t nodeId = painlessmesh::tcp::decodeNodeIdFromIP(ip);
    
    if (nodeId == 0) {
      Log(CONNECTION, "blockNodeAfterTCPFailure(): Invalid mesh IP %s, cannot block\n",
          ip.toString().c_str());
      return;
    }
    
    Log(CONNECTION, "blockNodeAfterTCPFailure(): Blocking node %u (IP: %s) for %u ms\n",
        nodeId, ip.toString().c_str(), blockDurationMs);
    
    stationScan.blockNodeAfterTCPFailure(nodeId, blockDurationMs);
  }
 
  bool setHostname(const char* hostname) {
#ifdef ESP8266
    return WiFi.hostname(hostname);
#elif defined(ESP32)
    if (strlen(hostname) > 32) {
      return false;
    }
    return WiFi.setHostname(hostname);
#endif  // ESP8266
  }
 
  IPAddress getStationIP() { return WiFi.localIP(); }
  IPAddress getAPIP() { return _apIp; }
 
  void enableBridgeFailover(bool enabled) { bridgeFailoverEnabled = enabled; }
 
  void setRouterCredentials(TSTRING ssid, TSTRING password) {
    routerSSID = ssid;
    routerPassword = password;
    routerCredentialsConfigured = true;
  }
 
  void setElectionTimeout(uint32_t timeoutMs) { electionTimeoutMs = timeoutMs; }
 
  void setMinimumBridgeRSSI(int8_t minRSSI) {
    if (minRSSI < -100) minRSSI = -100;
    if (minRSSI > -30) minRSSI = -30;
    minimumBridgeRSSI = minRSSI;
  }
 
  void setElectionStartupDelay(uint32_t delayMs) {
    if (delayMs < 10000) delayMs = 10000;  // Minimum 10 seconds
    electionStartupDelayMs = delayMs;
  }
 
  void setElectionRandomDelay(uint32_t minMs, uint32_t maxMs) {
    if (minMs < 100) minMs = 100;             // Minimum 100ms
    if (maxMs < minMs) maxMs = minMs + 1000;  // Ensure max > min
    electionRandomDelayMinMs = minMs;
    electionRandomDelayMaxMs = maxMs;
  }
 
  void onBridgeRoleChanged(
      std::function<void(bool isBridge, const TSTRING& reason)> callback) {
    bridgeRoleChangedCallback = callback;
  }
 
  void onBridgeCoordination(
      std::function<void(const plugin::BridgeCoordinationPackage&, uint32_t)>
          callback) {
    using namespace logger;
    bridgeCoordinationCallback = callback;
 
    // Non-bridge nodes don't run initBridgeCoordination(), so register
    // a Type 613 handler here so they can still receive coordination traffic.
    if (!this->isBridge()) {
      this->callbackList.onPackage(
          613,
          [this](protocol::Variant& variant, std::shared_ptr<Connection>,
                 uint32_t) {
            JsonDocument doc;
            TSTRING str;
            variant.printTo(str);
            deserializeJson(doc, str);
            JsonObject obj = doc.as<JsonObject>();
 
            if (obj["priority"].is<unsigned int>()) {
              uint32_t fromNode = obj["from"];
              plugin::BridgeCoordinationPackage pkg(obj);
 
              if (this->bridgeCoordinationCallback) {
                this->bridgeCoordinationCallback(pkg, fromNode);
              }
 
              // Change detection for non-bridge nodes
              if (this->bridgeCoordinationChangedCallback) {
                auto it = this->lastBridgeCoordinationState.find(fromNode);
                if (it == this->lastBridgeCoordinationState.end()) {
                  this->lastBridgeCoordinationState[fromNode] = {
                      pkg.priority, pkg.role, pkg.load, (uint32_t)millis()};
                  this->bridgeCoordinationChangedCallback(pkg, fromNode,
                                                          "new");
                } else {
                  auto& prev = it->second;
                  bool changed = (prev.priority != pkg.priority ||
                                  prev.role != pkg.role ||
                                  prev.load != pkg.load);
                  prev.priority = pkg.priority;
                  prev.role = pkg.role;
                  prev.load = pkg.load;
                  prev.lastSeen = (uint32_t)millis();
                  if (changed) {
                    this->bridgeCoordinationChangedCallback(pkg, fromNode,
                                                            "updated");
                  }
                }
              }
            }
            return false;
          });
      Log(GENERAL,
          "onBridgeCoordination(): Registered Type 613 handler for non-bridge "
          "node\n");
    }
  }
 
  void onBridgeCoordinationChanged(
      std::function<void(const plugin::BridgeCoordinationPackage&, uint32_t,
                         TSTRING)>
          callback) {
    using namespace logger;
    bridgeCoordinationChangedCallback = callback;
 
    // Start periodic lost-detection task (every 30 seconds, check for
    // bridges that haven't sent a coordination message in 60 seconds)
    bridgeLostDetectionTask = this->addTask(
        30000, TASK_FOREVER, [this]() {
          uint32_t now = (uint32_t)millis();
          for (auto it = this->lastBridgeCoordinationState.begin();
               it != this->lastBridgeCoordinationState.end();) {
            if ((now - it->second.lastSeen) > 60000) {
              uint32_t lostNode = it->first;
              // Create a package with last known state for the callback
              plugin::BridgeCoordinationPackage pkg;
              pkg.from = lostNode;
              pkg.priority = it->second.priority;
              pkg.role = it->second.role;
              pkg.load = it->second.load;
              it = this->lastBridgeCoordinationState.erase(it);
              if (this->bridgeCoordinationChangedCallback) {
                this->bridgeCoordinationChangedCallback(pkg, lostNode, "lost");
              }
            } else {
              ++it;
            }
          }
        });
 
    Log(GENERAL,
        "onBridgeCoordinationChanged(): Lost detection task started "
        "(interval: 30s, timeout: 60s)\n");
  }
 
  void enableMultiBridge(bool enabled) {
    multiBridgeEnabled = enabled;
    if (enabled) {
      Log(logger::GENERAL,
          "enableMultiBridge(): Multi-bridge coordination enabled\n");
    }
  }
 
  void setBridgeSelectionStrategy(BridgeSelectionStrategy strategy) {
    bridgeSelectionStrategy = strategy;
    Log(logger::GENERAL, "setBridgeSelectionStrategy(): Strategy set to %d\n",
        (int)strategy);
  }
 
  void setMaxBridges(uint8_t maxBridges) {
    if (maxBridges < 1) maxBridges = 1;
    if (maxBridges > 5) maxBridges = 5;
    maxConcurrentBridges = maxBridges;
    Log(logger::GENERAL, "setMaxBridges(): Max concurrent bridges set to %d\n",
        maxBridges);
  }
 
  std::vector<uint32_t> getActiveBridges() {
    std::vector<uint32_t> activeBridges;
    auto bridges = this->getBridges();
 
    for (const auto& bridge : bridges) {
      if (bridge.internetConnected && bridge.isHealthy()) {
        activeBridges.push_back(bridge.nodeId);
      }
    }
 
    return activeBridges;
  }
 
  bool hasInternetConnection() {
    // First check if THIS node is a bridge with Internet
    if (this->isBridge()) {
      // Check Internet connectivity: WiFi connected AND valid IP address
      bool hasInternet = (WiFi.status() == WL_CONNECTED) &&
                         (WiFi.localIP() != IPAddress(0, 0, 0, 0));
      if (hasInternet) {
        return true;
      }
    }
 
    // Then check other bridges in the mesh (call parent implementation)
    return painlessmesh::Mesh<Connection>::hasInternetConnection();
  }
 
  uint32_t getRecommendedBridge() {
    auto activeBridges = getActiveBridges();
 
    if (activeBridges.empty()) {
      return 0;
    }
 
    // Single bridge - return it
    if (activeBridges.size() == 1) {
      return activeBridges[0];
    }
 
    // Multi-bridge mode: apply selection strategy
    switch (bridgeSelectionStrategy) {
      case ROUND_ROBIN: {
        // Simple round-robin: cycle through bridges
        lastSelectedBridgeIndex =
            (lastSelectedBridgeIndex + 1) % activeBridges.size();
        return activeBridges[lastSelectedBridgeIndex];
      }
 
      case BEST_SIGNAL: {
        // Find bridge with best RSSI
        uint32_t bestBridge = 0;
        int8_t bestRSSI = -127;
 
        for (const auto& bridge : this->getBridges()) {
          if (bridge.internetConnected && bridge.isHealthy() &&
              bridge.routerRSSI > bestRSSI) {
            bestRSSI = bridge.routerRSSI;
            bestBridge = bridge.nodeId;
          }
        }
        return bestBridge;
      }
 
      case PRIORITY_BASED:
      default: {
        // Use highest priority bridge (stored in bridgePriorities map)
        uint32_t bestBridge = 0;
        uint8_t highestPriority = 0;
 
        for (uint32_t bridgeId : activeBridges) {
          uint8_t priority = bridgePriorities[bridgeId];
          if (priority > highestPriority) {
            highestPriority = priority;
            bestBridge = bridgeId;
          }
        }
 
        // If no priority info, use first active bridge
        return bestBridge ? bestBridge : activeBridges[0];
      }
    }
  }
 
  bool isMultiBridgeEnabled() const { return multiBridgeEnabled; }
 
  // The bridge monitor's check, one tick of the 30 s task: with no
  // healthy bridge known, an election is scheduled. Also run when a
  // bridge announces that it is stepping down, as soon as the startup
  // period allows.
  void checkForBridge() {
    using namespace logger;
    // Only a failover candidate checks: one with failover enabled and the
    // router's credentials. Every other node scheduled an election it
    // could not join, every 30 s, when this guard went missing.
    if (!bridgeFailoverEnabled || !routerCredentialsConfigured) {
      return;
    }
 
    // Don't check if we're already a bridge
    if (this->isBridge()) {
      return;
    }
 
    // Skip check during startup period to allow initial bridge discovery
    if (millis() < electionStartupDelayMs) {
      return;
    }
 
    // IMPORTANT: Don't trigger election if we're disconnected from the mesh
    // When isolated, we can't receive bridge status broadcasts, so lack of
    // healthy bridge could simply mean WE are disconnected, not that the
    // bridge is unavailable. Wait until mesh connectivity is restored before
    // considering an election.
    if (!this->hasActiveMeshConnections()) {
      Log(CONNECTION,
          "Bridge monitor: Skipping - no active mesh connections\n");
      return;
    }
 
    // Check if there are any healthy bridges
    bool hasHealthyBridge = false;
    for (const auto& bridge : this->getBridges()) {
      if (bridge.isHealthy(bridgeTimeoutMs) && bridge.internetConnected) {
        hasHealthyBridge = true;
        break;
      }
    }
 
    // If no healthy bridge exists, trigger an election
    if (!hasHealthyBridge) {
      Log(CONNECTION,
          "Bridge monitor: No healthy bridge detected, triggering "
          "election\n");
      // Random delay to prevent simultaneous elections when multiple nodes
      // start together
      uint32_t randomDelay =
          random(electionRandomDelayMinMs, electionRandomDelayMaxMs);
      Log(CONNECTION, "Bridge monitor: Scheduling election in %u ms\n",
          randomDelay);
      this->addTask(randomDelay, TASK_ONCE,
                    [this]() { this->startBridgeElection(); });
    }
  }
 
  // Schedule checkForBridge() once, after the startup period if it is
  // still running, plus a second for the news to settle.
  void checkForBridgeSoon() {
    if (bridgeCheckPending) return;
    uint32_t wait = millis() < electionStartupDelayMs
                        ? electionStartupDelayMs - millis()
                        : 0;
    bridgeCheckPending = true;
    this->addTask(wait + 1000, TASK_ONCE, [this]() {
      bridgeCheckPending = false;
      this->checkForBridge();
    });
  }
 
  void stop() {
    // A bridge stepping down says so before its connections close, so the
    // candidates hold an election now rather than when its last status
    // ages out. The short wait lets the broadcast leave the buffers.
    if (this->isBridge() && bridgeStatusBroadcastEnabled) {
      sendBridgeStatus(true);
      delay(200);
    }
    // remove all WiFi events
#ifdef ESP32
    WiFi.removeEvent(eventScanDoneHandler);
    WiFi.removeEvent(eventSTAStartHandler);
    WiFi.removeEvent(eventSTADisconnectedHandler);
    WiFi.removeEvent(eventSTAGotIPHandler);
#elif defined(ESP8266)
    eventSTAConnectedHandler = WiFiEventHandler();
    eventSTADisconnectedHandler = WiFiEventHandler();
    eventSTAGotIPHandler = WiFiEventHandler();
 
    stationScan.asyncTask.setCallback(NULL);
    mScheduler->deleteTask(stationScan.asyncTask);
#endif  // ESP32
    // Stop scanning task
    stationScan.task.setCallback(NULL);
    mScheduler->deleteTask(stationScan.task);
    painlessmesh::Mesh<Connection>::stop();
 
    // Shutdown wifi hardware
    if (WiFi.status() != WL_DISCONNECTED) WiFi.disconnect();
 
    // The TCP listener stays. A node that stops to re-initialise in place
    // — a promotion to bridge, a return to a regular node — needs a
    // listener again at once, and a new one cannot bind while the
    // connections this one accepted are still in TIME_WAIT on the same
    // port (see tcpServerInit()). The connections themselves are closed
    // above; a client accepted in the gap before init() is closed by it.
  }
 
 protected:
  friend class ::StationScan;
  // init() sets all of these; the defaults are init()'s own, so a node
  // that is asked about its AP before init() answers something true
  // rather than whatever the stack held.
  TSTRING _meshSSID;
  TSTRING _meshPassword;
  uint8_t _meshChannel = 1;
  uint8_t _meshHidden = 0;
  uint8_t _meshMaxConn = MAX_CONN;
  uint16_t _meshPort = 5555;
 
  IPAddress _apIp;
  StationScan stationScan;
 
  void init(Scheduler* scheduler, uint32_t id) {
    painlessmesh::Mesh<Connection>::init(scheduler, id);
  }
 
  void init(uint32_t id) { painlessmesh::Mesh<Connection>::init(id); }
 
  void apInit(uint32_t nodeId) {
    using namespace logger;
    _apIp = IPAddress(10, (nodeId & 0xFF00) >> 8, (nodeId & 0xFF), 1);
    IPAddress netmask(255, 255, 255, 0);
 
    WiFi.softAPConfig(_apIp, _apIp, netmask);
 
#ifdef ESP32
    // ESP32: Explicitly enable AP mode to ensure DHCP server starts properly
    // This is particularly important after channel changes or AP restarts
    WiFi.enableAP(true);
#endif
 
    WiFi.softAP(_meshSSID.c_str(), _meshPassword.c_str(), _meshChannel,
                _meshHidden, _meshMaxConn);
 
    Log(STARTUP, "apInit(): AP configured - SSID: %s, Channel: %d, IP: %s\n",
        _meshSSID.c_str(), _meshChannel, _apIp.toString().c_str());
    Log(STARTUP, "apInit(): AP active - Max connections: %d\n", _meshMaxConn);
  }
 
  void initBridgeStatusBroadcast() {
    using namespace logger;
 
    if (!this->isBridge() || !this->bridgeStatusBroadcastEnabled) {
      return;
    }
 
    Log(STARTUP,
        "initBridgeStatusBroadcast(): Setting up bridge status broadcast\n");
 
    // CRITICAL FIX: Schedule tasks with a small delay to avoid crashes when
    // called immediately after stop()/init cycle. The delay allows the scheduler
    // and internal task structures to stabilize before adding new tasks.
    // This fixes the "Load access fault" Guru Meditation error that occurred
    // when promoting to bridge role.
    const uint32_t INIT_DELAY_MS = 100;
 
    // Register ourselves as a bridge in the knownBridges list
    // This ensures the bridge knows about itself and reports correct status
    this->addTask(INIT_DELAY_MS, TASK_ONCE, [this]() {
      // Check Internet connectivity: WiFi connected AND valid IP address
      bool hasInternet = (WiFi.status() == WL_CONNECTED) &&
                         (WiFi.localIP() != IPAddress(0, 0, 0, 0));
 
      this->updateBridgeStatus(this->nodeId,    // bridgeNodeId
                               hasInternet,     // internetConnected
                               WiFi.RSSI(),     // routerRSSI
                               WiFi.channel(),  // routerChannel
                               millis(),        // uptime
                               WiFi.gatewayIP().toString(),  // gatewayIP
                               this->getNodeTime()           // timestamp
      );
 
      Log(STARTUP,
          "initBridgeStatusBroadcast(): Registered self as bridge (nodeId: "
          "%u)\n",
          this->nodeId);
    });
 
    // Create periodic task to broadcast bridge status
    // Schedule with delay to avoid crashes during stop/init cycle
    this->addTask(INIT_DELAY_MS, TASK_ONCE, [this]() {
      bridgeStatusTask = this->addTask(this->bridgeStatusIntervalMs, TASK_FOREVER,
                                       [this]() { this->sendBridgeStatus(); });
    });
 
    // Send immediate broadcast so nodes can discover this bridge right away
    // This ensures bridge is discoverable before the first periodic broadcast
    // Use slightly larger delay to allow bridge status task to be set up first
    this->addTask(INIT_DELAY_MS + 50, TASK_ONCE, [this]() {
      Log(STARTUP, "Sending initial bridge status broadcast\n");
      this->sendBridgeStatus();
    });
 
    // Also send bridge status when new nodes connect so they can discover the
    // bridge immediately Send directly to the new node to ensure delivery,
    // independent of time sync Using changedConnectionCallbacks instead of
    // newConnectionCallbacks ensures routing is ready
    this->changedConnectionCallbacks.push_back([this](uint32_t nodeId) {
      Log(CONNECTION,
          "Node %u connection changed, sending bridge status directly\n",
          nodeId);
 
      // The direct send below reaches the neighbour whose connection
      // changed. A node that joined behind that neighbour is why it changed,
      // and it learns of this bridge only from the next periodic broadcast,
      // up to thirty seconds on: on the rig the node the discovery fixture
      // sends from joined a child of the bridge at 185 s and heard the
      // bridge at 214 s, after the fixture's window. So a change also
      // brings the broadcast forward, at most once every five seconds.
      if (millis() - _lastBridgeStatusBroadcast >= 5000) {
        this->addTask(1000, TASK_ONCE, [this]() {
          if (millis() - _lastBridgeStatusBroadcast >= 5000) {
            Log(CONNECTION,
                "Topology changed; broadcasting bridge status now rather "
                "than at the next interval\n");
            this->sendBridgeStatus();
          }
        });
      }
 
      // Small delay to ensure connection is fully stable, then send directly to
      // the new node This avoids issues with time sync blocking broadcast
      // messages
      this->addTask(500, TASK_ONCE, [this, nodeId]() {
        // Check if the connection is still valid - the node may have
        // disconnected during the 500ms delay (e.g., due to timeout or network
        // issues) This prevents attempting to send messages to dropped
        // connections findRoute returns nullptr if node is not in the routing
        // table
        auto conn = router::findRoute<Connection>((*this), nodeId);
        if (!conn || !conn->connected()) {
          Log(CONNECTION,
              "Bridge status send cancelled: Node %u no longer connected\n",
              nodeId);
          return;
        }
 
        // Create bridge status message
        JsonDocument doc;
        JsonObject obj = doc.to<JsonObject>();
 
        obj["type"] = protocol::BRIDGE_STATUS;
        obj["from"] = this->nodeId;
        obj["routing"] = 1;  // SINGLE routing (direct to node)
        obj["dest"] = nodeId;
        obj["timestamp"] = this->getNodeTime();
 
        bool hasInternet = (WiFi.status() == WL_CONNECTED) &&
                           (WiFi.localIP() != IPAddress(0, 0, 0, 0));
        obj["internetConnected"] = hasInternet;
        obj["routerRSSI"] = WiFi.RSSI();
        obj["routerChannel"] = WiFi.channel();
        obj["uptime"] = millis();
        obj["gatewayIP"] = WiFi.gatewayIP().toString();
        obj["message_type"] = protocol::BRIDGE_STATUS;
 
        String msg;
        serializeJson(doc, msg);
 
        Log(CONNECTION,
            "Sending bridge status directly to node %u (Internet: %s)\n",
            nodeId, hasInternet ? "YES" : "NO");
 
        // Send directly to the connection with high priority
        // This ensures the message is sent immediately rather than queued
        // The JSON message format is the same as what router::send() produces
        // (Variant serializes to the same JSON format we built manually)
        conn->addMessage(msg, true);
      });
    });
 
    Log(STARTUP, "Bridge status broadcast enabled (interval: %d ms)\n",
        this->bridgeStatusIntervalMs);
  }
 
  void initBridgeCoordination() {
    using namespace logger;
 
    if (!this->isBridge() || !multiBridgeEnabled) {
      return;
    }
 
    Log(STARTUP,
        "initBridgeCoordination(): Setting up multi-bridge coordination\n");
 
    // Register our own priority in the bridgePriorities map
    // This ensures getRecommendedBridge() with PRIORITY_BASED strategy works
    // correctly
    bridgePriorities[this->nodeId] = bridgePriority;
    Log(STARTUP,
        "initBridgeCoordination(): Registered self priority (nodeId: %u, "
        "priority: %d)\n",
        this->nodeId, bridgePriority);
 
    // Register handler for incoming coordination messages (Type 613)
    this->callbackList.onPackage(
        613,  // BRIDGE_COORDINATION type
        [this](protocol::Variant& variant, std::shared_ptr<Connection>,
               uint32_t) {
          JsonDocument doc;
          TSTRING str;
          variant.printTo(str);
          deserializeJson(doc, str);
          JsonObject obj = doc.as<JsonObject>();
 
          if (obj["priority"].is<unsigned int>()) {
            uint32_t fromNode = obj["from"];
            uint8_t priority = obj["priority"];
            TSTRING role = obj["role"].as<TSTRING>();
            uint8_t load = obj["load"] | 0;
 
            // Store bridge priority for selection decisions
            bridgePriorities[fromNode] = priority;
 
            // Update peer bridges list
            if (obj["peerBridges"].is<JsonArray>()) {
              JsonArray peers = obj["peerBridges"];
              for (JsonVariant peer : peers) {
                uint32_t peerId = peer.as<uint32_t>();
                if (peerId != this->nodeId &&
                    std::find(knownBridgePeers.begin(), knownBridgePeers.end(),
                              peerId) == knownBridgePeers.end()) {
                  if (knownBridgePeers.size() >= 32) {
                    knownBridgePeers.erase(knownBridgePeers.begin());
                  }
                  knownBridgePeers.push_back(peerId);
                }
              }
            }
 
            Log(CONNECTION,
                "Bridge coordination from %u: priority=%d, role=%s, "
                "load=%d%%\n",
                fromNode, priority, role.c_str(), load);
 
            // Invoke bridge coordination callback if set
            if (this->bridgeCoordinationCallback) {
              plugin::BridgeCoordinationPackage pkg(obj);
              this->bridgeCoordinationCallback(pkg, fromNode);
            }
 
            // Change detection and bridgeCoordinationChangedCallback
            if (this->bridgeCoordinationChangedCallback) {
              plugin::BridgeCoordinationPackage pkg(obj);
              auto it = this->lastBridgeCoordinationState.find(fromNode);
              if (it == this->lastBridgeCoordinationState.end()) {
                this->lastBridgeCoordinationState[fromNode] = {
                    priority, role, load, (uint32_t)millis()};
                this->bridgeCoordinationChangedCallback(pkg, fromNode, "new");
              } else {
                auto& prev = it->second;
                bool changed = (prev.priority != priority ||
                                prev.role != role ||
                                prev.load != load);
                prev.priority = priority;
                prev.role = role;
                prev.load = load;
                prev.lastSeen = (uint32_t)millis();
                if (changed) {
                  this->bridgeCoordinationChangedCallback(pkg, fromNode,
                                                          "updated");
                }
              }
            }
          }
          return false;  // Don't consume the package
        });
 
    // Create periodic task to send coordination messages
    bridgeCoordinationTask = this->addTask(
        30000,  // 30 seconds interval
        TASK_FOREVER, [this]() { this->sendBridgeCoordination(); });
 
    Log(STARTUP, "Bridge coordination enabled (priority: %d, role: %s)\n",
        bridgePriority, bridgeRole.c_str());
  }
 
  void sendBridgeCoordination() {
    using namespace logger;
 
    if (!this->isBridge() || !multiBridgeEnabled) {
      return;
    }
 
    // Calculate current load (simplified: based on node count)
    uint8_t currentLoad = 0;
    auto nodeCount = this->getNodeList(false).size();
    if (nodeCount > 0) {
      currentLoad = (nodeCount * 100) / MAX_CONN;
      if (currentLoad > 100) currentLoad = 100;
    }
 
    // Create coordination message
    JsonDocument doc;
    JsonObject obj = doc.to<JsonObject>();
 
    obj["type"] = 613;  // BRIDGE_COORDINATION
    obj["from"] = this->nodeId;
    obj["routing"] = 2;  // BROADCAST
    obj["priority"] = bridgePriority;
    obj["role"] = bridgeRole;
    obj["load"] = currentLoad;
    obj["timestamp"] = this->getNodeTime();
    obj["message_type"] = 613;
 
    // Add peer bridges list
    JsonArray peers = obj["peerBridges"].to<JsonArray>();
    for (uint32_t peerId : knownBridgePeers) {
      peers.add(peerId);
    }
 
    String msg;
    serializeJson(doc, msg);
 
    // Update our own priority in bridgePriorities map
    // This ensures priority-based selection always has current data
    bridgePriorities[this->nodeId] = bridgePriority;
 
    this->sendBroadcast(msg);
 
    Log(CONNECTION,
        "Bridge coordination sent: priority=%d, role=%s, load=%d%%\n",
        bridgePriority, bridgeRole.c_str(), currentLoad);
  }
 
  int8_t scanRouterSignalStrength(TSTRING routerSSID,
                                  uint8_t* routerChannel = nullptr) {
    using namespace logger;
    Log(CONNECTION, "scanRouterSignalStrength(): Scanning for %s...\n",
        routerSSID.c_str());
 
    int n = WiFi.scanNetworks(false, false);
    if (n == WIFI_SCAN_RUNNING) {
      // The station task's asynchronous scan is in flight; a synchronous
      // scan cannot start until it ends, and -2 is not "no networks". A
      // failover backup read it as the router being out of sight — twice,
      // thirty seconds apart — and never stood for election while the
      // primary was gone. Wait the scan out, bounded, then look again.
      Log(CONNECTION,
          "scanRouterSignalStrength(): a scan is already running, waiting "
          "for it\n");
      uint32_t waitedUntil = millis() + 8000;
#ifdef ESP32
      // Not WiFi.scanComplete(): on this core it gives a scan twenty
      // dwell times to finish and then declares it failed — 2.4 s for the
      // 120 ms all-channel re-detection, which takes six in AP+STA mode
      // as the radio keeps returning to serve the AP. Asked here at three
      // seconds, it dropped the scanning flag, the scan below started on
      // top of the one in flight, and both came back with nothing: the
      // backup read "router not found" and the station "mesh not found on
      // any channel", and lost the sighting it needed to follow the mesh.
      // The scanning bit is the flag the driver clears when the scan
      // really ends.
      while ((WiFiGenericClass::getStatusBits() & WIFI_SCANNING_BIT) &&
             (int32_t)(waitedUntil - millis()) > 0) {
        delay(50);
      }
      // The scan-done event hands the station its results next; let it
      // read them before this scan deletes them.
      delay(300);
#else
      while (WiFi.scanComplete() == WIFI_SCAN_RUNNING &&
             (int32_t)(waitedUntil - millis()) > 0) {
        delay(50);
      }
#endif
      n = WiFi.scanNetworks(false, false);
    }
    Log(CONNECTION, "scanRouterSignalStrength(): Found %d networks\n", n);
 
    for (int i = 0; i < n; i++) {
      if (WiFi.SSID(i) == routerSSID) {
        int8_t rssi = WiFi.RSSI(i);
        uint8_t channel = WiFi.channel(i);
        if (routerChannel != nullptr) *routerChannel = channel;
        Log(CONNECTION,
            "scanRouterSignalStrength(): Found %s with RSSI %d dBm on "
            "channel %u\n",
            routerSSID.c_str(), rssi, channel);
        return rssi;
      }
    }
 
    Log(CONNECTION, "scanRouterSignalStrength(): Router %s not found\n",
        routerSSID.c_str());
    return 0;  // Router not found
  }
 
  void startBridgeElection() {
    using namespace logger;
 
    if (!bridgeFailoverEnabled) {
      Log(CONNECTION, "startBridgeElection(): Failover disabled\n");
      return;
    }
 
    if (!routerCredentialsConfigured) {
      Log(CONNECTION,
          "startBridgeElection(): No router credentials, cannot participate\n");
      return;
    }
 
    if (electionState != ELECTION_IDLE) {
      Log(CONNECTION, "startBridgeElection(): Election already in progress\n");
      return;
    }
 
    // Prevent rapid role changes — but look again when the hold is over.
    // A candidate that stood down a moment ago, or that only just booted,
    // returned here silently and waited for the next 30 s tick to find
    // out that there was still no bridge.
    if (millis() - lastRoleChangeTime < 60000) {
      uint32_t wait = 60000 - (millis() - lastRoleChangeTime);
      Log(CONNECTION,
          "startBridgeElection(): Too soon after last role change, "
          "checking again in %u ms\n",
          wait);
      if (!bridgeCheckPending) {
        bridgeCheckPending = true;
        this->addTask(wait, TASK_ONCE, [this]() {
          bridgeCheckPending = false;
          this->checkForBridge();
        });
      }
      return;
    }
 
    // CRITICAL: Check if mesh channel re-synchronization is needed first
    // If we haven't found any mesh nodes and are approaching the re-sync
    // threshold, prioritize finding the mesh over becoming a bridge. This
    // prevents the scenario where a node tries to become a bridge when it
    // should be re-syncing to find the mesh on a different channel (e.g., after
    // another node became bridge and switched channels to match the router).
    uint16_t emptyScans = stationScan.getConsecutiveEmptyScans();
    if (emptyScans >= 3 && WiFi.status() != WL_CONNECTED) {
      Log(CONNECTION,
          "startBridgeElection(): Mesh connectivity lost (%d empty scans), "
          "deferring election to allow channel re-sync\n",
          emptyScans);
 
      // Schedule a retry after channel re-sync has had a chance to run
      // The channel re-sync threshold is StationScan::EMPTY_SCAN_THRESHOLD
      // scans (2, ~30 s). Fast scan interval is 0.5 * SCAN_INTERVAL = 15
      // seconds Wait for re-sync to complete plus a buffer
      uint32_t retryDelay =
          (StationScan::EMPTY_SCAN_THRESHOLD - emptyScans + 2) * 15000;
      Log(CONNECTION,
          "startBridgeElection(): Will retry election in %u seconds if still "
          "needed\n",
          retryDelay / 1000);
      return;
    }
 
    Log(CONNECTION, "=== Bridge Election Started ===\n");
    electionState = ELECTION_SCANNING;
 
    // Scan for router to get RSSI
    uint8_t routerChannel = 0;
    int8_t routerRSSI =
        scanRouterSignalStrength(routerSSID, &routerChannel);
 
    if (routerRSSI == 0) {
      Log(CONNECTION,
          "startBridgeElection(): Router not visible, cannot participate\n");
      electionState = ELECTION_IDLE;
      return;
    }
 
    Log(CONNECTION, "startBridgeElection(): My router RSSI: %d dBm\n",
        routerRSSI);
 
    // Clear previous candidates
    electionCandidates.clear();
 
    // Add self as candidate
    BridgeCandidate selfCandidate;
    selfCandidate.nodeId = this->nodeId;
    selfCandidate.routerRSSI = routerRSSI;
    selfCandidate.routerChannel = routerChannel;
    selfCandidate.uptime = millis();
    selfCandidate.freeMemory = ESP.getFreeHeap();
    electionCandidates.push_back(selfCandidate);
 
    // Broadcast candidacy using JSON directly (avoiding dependency on alteriom
    // package)
    JsonDocument doc;
    JsonObject obj = doc.to<JsonObject>();
    obj["type"] = protocol::BRIDGE_ELECTION;
    obj["from"] = this->nodeId;
    obj["routing"] = 2;  // BROADCAST
    obj["routerRSSI"] = routerRSSI;
    obj["routerChannel"] = routerChannel;
    obj["uptime"] = millis();
    obj["freeMemory"] = ESP.getFreeHeap();
    obj["timestamp"] = this->getNodeTime();
    obj["routerSSID"] = routerSSID;
    obj["message_type"] = protocol::BRIDGE_ELECTION;
 
    String msg;
    serializeJson(doc, msg);
 
    // Send election message using raw broadcast to preserve type
    // BRIDGE_ELECTION
    protocol::Variant variant(msg);
    router::broadcast<Connection>(variant, (*this), 0);
 
    Log(CONNECTION, "startBridgeElection(): Candidacy broadcast sent\n");
 
    // Set election timeout
    electionDeadline = millis() + electionTimeoutMs;
    electionState = ELECTION_COLLECTING;
 
    // Schedule election evaluation
    this->addTask(electionTimeoutMs + 100, TASK_ONCE,
                  [this]() { this->evaluateElection(); });
  }
 
  void evaluateElection() {
    using namespace logger;
 
    if (electionState != ELECTION_COLLECTING) {
      Log(CONNECTION, "evaluateElection(): Not in collecting state\n");
      return;
    }
 
    Log(CONNECTION, "=== Evaluating Election ===\n");
    Log(CONNECTION, "evaluateElection(): %d candidates\n",
        electionCandidates.size());
 
    // Find best candidate
    BridgeCandidate* winner = nullptr;
    int8_t bestRSSI = -127;  // Worst possible RSSI
 
    for (auto& candidate : electionCandidates) {
      Log(CONNECTION,
          "evaluateElection(): Candidate %u: RSSI=%d, uptime=%u, mem=%u\n",
          candidate.nodeId, candidate.routerRSSI, candidate.uptime,
          candidate.freeMemory);
 
      if (candidate.routerRSSI > bestRSSI) {
        bestRSSI = candidate.routerRSSI;
        winner = &candidate;
      } else if (candidate.routerRSSI == bestRSSI && winner != nullptr) {
        // Tiebreaker 1: Higher uptime
        if (candidate.uptime > winner->uptime) {
          winner = &candidate;
        } else if (candidate.uptime == winner->uptime) {
          // Tiebreaker 2: More free memory
          if (candidate.freeMemory > winner->freeMemory) {
            winner = &candidate;
          } else if (candidate.freeMemory == winner->freeMemory) {
            // Tiebreaker 3: Lower node ID (deterministic)
            if (candidate.nodeId < winner->nodeId) {
              winner = &candidate;
            }
          }
        }
      }
    }
 
    if (winner == nullptr) {
      Log(ERROR, "evaluateElection(): No winner found!\n");
      electionState = ELECTION_IDLE;
      return;
    }
 
    // Validate RSSI threshold for single-candidate elections
    // When only one candidate exists, it indicates the node is isolated from
    // the mesh. In this case, require minimum signal quality to prevent poor
    // connections. When multiple candidates exist, the mesh is connected and
    // best RSSI wins.
    if (electionCandidates.size() == 1 &&
        winner->routerRSSI < minimumBridgeRSSI) {
      Log(CONNECTION, "=== Election Failed: Insufficient Signal Quality ===\n");
      Log(CONNECTION,
          "  Single candidate with RSSI %d dBm (minimum required: %d dBm)\n",
          winner->routerRSSI, minimumBridgeRSSI);
      Log(CONNECTION, "  Node is isolated from mesh with poor router signal\n");
      Log(CONNECTION, "  Rejecting election to prevent unreliable bridge\n");
      Log(CONNECTION,
          "  Recommendation: Move closer to router or wait for mesh "
          "connection\n");
 
      electionState = ELECTION_IDLE;
      electionCandidates.clear();
 
      // Notify via callback that election failed
      if (bridgeRoleChangedCallback) {
        bridgeRoleChangedCallback(
            false, "Insufficient signal quality for isolated bridge");
      }
      return;
    }
 
    Log(CONNECTION, "=== Election Winner: Node %u ===\n", winner->nodeId);
    Log(CONNECTION, "  Router RSSI: %d dBm\n", winner->routerRSSI);
    Log(CONNECTION, "  Uptime: %u ms\n", winner->uptime);
    Log(CONNECTION, "  Free Memory: %u bytes\n", winner->freeMemory);
 
    // Record election in diagnostics history
    if (this->diagnosticsEnabled) {
      ElectionRecord record;
      record.timestamp = millis();
      record.winnerNodeId = winner->nodeId;
      record.winnerRSSI = winner->routerRSSI;
      record.candidateCount = electionCandidates.size();
      record.reason = "Bridge failure detected";
 
      this->electionHistory.push_back(record);
 
      // Keep history limited to MAX_ELECTION_HISTORY
      if (this->electionHistory.size() > this->MAX_ELECTION_HISTORY) {
        this->electionHistory.erase(this->electionHistory.begin());
      }
 
      Log(CONNECTION, "evaluateElection(): Election recorded in history\n");
    }
 
    if (winner->nodeId == this->nodeId) {
      Log(CONNECTION, "[TARGET] I WON! Promoting to bridge...\n");
      promoteToBridge(winner->routerChannel);
    } else {
      Log(CONNECTION, "Winner is node %u, remaining as regular node\n",
          winner->nodeId);
    }
 
    electionState = ELECTION_IDLE;
    electionCandidates.clear();
  }
 
  void promoteToBridge(uint8_t routerChannel) {
    using namespace logger;
 
    Log(STARTUP, "=== Becoming Bridge Node ===\n");
    Log(STARTUP, "Scheduling bridge promotion (async to avoid task corruption)\n");
 
    // Store previous bridge (if any)
    // SAFETY: Use getPrimaryGateway() which returns the nodeId value directly
    // instead of getPrimaryBridge() which returns a pointer to a vector element.
    // This avoids crashes from dangling pointers that can occur if the 
    // knownBridges vector is modified between pointer retrieval and use.
    uint32_t previousBridgeId = this->getPrimaryGateway();
 
    // IMPORTANT: Send takeover announcement BEFORE switching channels
    // This ensures other nodes on the current channel receive the announcement
    Log(STARTUP,
        "Sending takeover announcement on current channel before "
        "switching...\n");
    JsonDocument doc;
    JsonObject obj = doc.to<JsonObject>();
    obj["type"] = protocol::BRIDGE_TAKEOVER;
    obj["from"] = this->nodeId;
    obj["routing"] = 2;  // BROADCAST
    obj["previousBridge"] = previousBridgeId;
    obj["reason"] = "Election winner - best router signal";
    obj["routerRSSI"] = 0;  // Not yet connected to router
    obj["routerChannel"] = routerChannel;
    obj["timestamp"] = this->getNodeTime();
    obj["message_type"] = protocol::BRIDGE_TAKEOVER;
 
    String msg;
    serializeJson(doc, msg);
 
    // Send takeover message using raw broadcast to preserve type
    // BRIDGE_TAKEOVER
    protocol::Variant variant(msg);
    router::broadcast<Connection>(variant, (*this), 0);
 
    // Give time for announcement to propagate before channel switch
    // Allow event loop processing during hardware settling
    for (int i = 0; i < 100; i++) { delay(10); yield(); }
    Log(STARTUP, "[OK] Takeover announcement sent on channel %d\n", _meshChannel);
 
    // Save current mesh configuration to restore if bridge init fails.
    // The copies below are captured by value into the deferred lambda so the
    // stop() call inside it cannot clear/mutate these members before the
    // reinit reads them. (The Mesh object itself outlives the lambda; this
    // protects against member mutation, not object lifetime.)
    // TODO(#373 follow-up): if the mesh owns its scheduler
    // (!isExternalScheduler), stop() deletes mScheduler and savedScheduler
    // dangles before initAsBridge() uses it. Pre-existing limitation —
    // bridge promotion requires a user-supplied scheduler.
    uint8_t savedChannel = _meshChannel;
    TSTRING savedMeshSSID = _meshSSID;
    TSTRING savedMeshPassword = _meshPassword;
    TSTRING savedRouterSSID = routerSSID;
    TSTRING savedRouterPassword = routerPassword;
    Scheduler *savedScheduler = mScheduler;
    auto savedBridgeRoleChangedCallback = bridgeRoleChangedCallback;
 
    // CRITICAL FIX: Schedule the stop/reinit work to run after current task completes
    // This prevents use-after-free crash when stop() clears taskList while
    // evaluateElection() task is still executing
    // Use minimal delay to allow current task to complete first
    this->addTask(ASYNC_PROMOTION_DELAY_MS, TASK_ONCE,
                  [this, savedChannel, savedMeshSSID, savedMeshPassword,
                   savedRouterSSID, savedRouterPassword, savedScheduler,
                   savedBridgeRoleChangedCallback]() {
      using namespace logger;
      
      Log(STARTUP, "Executing bridge promotion (stop/reinit cycle)\n");
      
      // Now reconfigure as bridge (this will switch to router's channel)
      this->stop();
      // Allow event loop processing during hardware settling
      for (int i = 0; i < 100; i++) { delay(10); yield(); }
 
      // initAsBridge always returns true: bridge mesh functionality is active
      // regardless of router connection status (router connection is opportunistic)
      this->initAsBridge(savedMeshSSID, savedMeshPassword, savedRouterSSID,
                         savedRouterPassword, savedScheduler, _meshPort);
 
      lastRoleChangeTime = millis();
 
      Log(STARTUP, "[OK] Bridge promotion complete on channel %d\n", _meshChannel);
 
      // Notify via callback
      if (savedBridgeRoleChangedCallback) {
        static const TSTRING reason = "Election winner - best router signal";
        savedBridgeRoleChangedCallback(true, reason);
      }
 
      // Note: The initial takeover announcement was already sent earlier
      // before the channel switch. The follow-up announcement that was previously
      // scheduled here has been removed to avoid potential crashes from scheduling
      // tasks immediately after stop()/reinit cycle.
      //
      // The bridge status broadcast system (initialized by initAsBridge via
      // initBridgeStatusBroadcast) will continue to inform nodes about the new
      // bridge through periodic broadcasts. Nodes that switched channels will
      // discover the new bridge through these status broadcasts.
      Log(STARTUP,
          "Bridge takeover complete. Status broadcasts will announce bridge to "
          "network.\n");
    });
  }
 
  bool attemptIsolatedBridgePromotion() {
    using namespace logger;
 
    Log(CONNECTION, "=== Isolated Bridge Promotion Attempt ===\n");
    Log(CONNECTION, "Attempt %d of %d\n", _isolatedBridgeRetryAttempts + 1,
        MAX_ISOLATED_BRIDGE_RETRY_ATTEMPTS);
 
    // First, scan for router to check if it's visible
    int8_t routerRSSI = scanRouterSignalStrength(routerSSID);
 
    if (routerRSSI == 0) {
      Log(CONNECTION,
          "attemptIsolatedBridgePromotion(): Router %s not visible\n",
          routerSSID.c_str());
      return false;  // Don't count as an attempt - router not visible
    }
 
    // Check minimum RSSI threshold for isolated promotion
    if (routerRSSI < minimumBridgeRSSI) {
      Log(CONNECTION,
          "attemptIsolatedBridgePromotion(): Router RSSI %d dBm below "
          "threshold %d dBm\n",
          routerRSSI, minimumBridgeRSSI);
      return false;  // Don't count as an attempt - signal too weak
    }
 
    Log(CONNECTION,
        "attemptIsolatedBridgePromotion(): Router visible with RSSI %d dBm\n",
        routerRSSI);
    Log(CONNECTION,
        "Attempting direct bridge promotion (bypassing election)\n");
    Log(CONNECTION,
        "Scheduling stop/reinit (async to avoid task corruption)\n");
 
    // Save current mesh configuration. Captured by value into the deferred
    // lambda so stop() cannot clear/mutate these members before the reinit
    // reads them (see the matching comment in promoteToBridge(); same
    // TODO(#373 follow-up) about savedScheduler and internal schedulers
    // applies here).
    uint8_t savedChannel = _meshChannel;
    TSTRING savedMeshSSID = _meshSSID;
    TSTRING savedMeshPassword = _meshPassword;
    TSTRING savedRouterSSID = routerSSID;
    TSTRING savedRouterPassword = routerPassword;
    Scheduler *savedScheduler = mScheduler;
    auto savedBridgeRoleChangedCallback = bridgeRoleChangedCallback;
 
    // CRITICAL FIX: Schedule the stop/reinit work to run after current task completes
    // This prevents use-after-free crash when stop() clears taskList while
    // the retry task is still executing
    // Use minimal delay to allow current task to complete first
    this->addTask(ASYNC_PROMOTION_DELAY_MS, TASK_ONCE,
                  [this, savedChannel, savedMeshSSID, savedMeshPassword,
                   savedRouterSSID, savedRouterPassword, savedScheduler,
                   savedBridgeRoleChangedCallback]() {
      using namespace logger;
      
      Log(CONNECTION, "Executing isolated bridge promotion (stop/reinit cycle)\n");
      
      // Stop current mesh operations
      this->stop();
      // Allow event loop processing during hardware settling
      for (int i = 0; i < 100; i++) { delay(10); yield(); }
 
      // initAsBridge always returns true: bridge mesh functionality is active
      // regardless of router connection status (router connection is opportunistic)
      this->initAsBridge(savedMeshSSID, savedMeshPassword, savedRouterSSID,
                         savedRouterPassword, savedScheduler, _meshPort);
 
      // Reset retry counter
      _isolatedBridgeRetryAttempts = 0;
      lastRoleChangeTime = millis();
 
      Log(STARTUP, "[OK] Isolated bridge promotion complete on channel %d\n",
          _meshChannel);
 
      // Notify via callback
      if (savedBridgeRoleChangedCallback) {
        static const TSTRING reason = "Isolated node promoted to bridge";
        savedBridgeRoleChangedCallback(true, reason);
      }
 
      // Note: Bridge status announcement will be sent automatically by
      // initBridgeStatusBroadcast() which is called by initAsBridge().
      // The immediate broadcast is scheduled in that function, so we don't
      // need to schedule another one here. This avoids potential crashes from
      // scheduling tasks immediately after stop()/reinit cycle.
      // The initBridgeStatusBroadcast() also sets up periodic broadcasts.
      Log(STARTUP,
          "Bridge status announcement will be sent by bridge status broadcast "
          "system\n");
    });
 
    return true;  // Count as an attempt - we scheduled the promotion
  }
 
  void handleBridgeElection(uint32_t fromNode, int8_t routerRSSI,
                            uint8_t routerChannel, uint32_t uptime,
                            uint32_t freeMemory) {
    using namespace logger;
 
    if (electionState != ELECTION_COLLECTING) {
      Log(CONNECTION,
          "handleBridgeElection(): Not collecting candidates, ignoring\n");
      return;
    }
 
    // Check if candidate already exists
    for (auto& candidate : electionCandidates) {
      if (candidate.nodeId == fromNode) {
        Log(CONNECTION,
            "handleBridgeElection(): Duplicate candidate from %u, ignoring\n",
            fromNode);
        return;
      }
    }
 
    BridgeCandidate candidate;
    candidate.nodeId = fromNode;
    candidate.routerRSSI = routerRSSI;
    candidate.routerChannel = routerChannel;
    candidate.uptime = uptime;
    candidate.freeMemory = freeMemory;
 
    electionCandidates.push_back(candidate);
 
    Log(CONNECTION,
        "handleBridgeElection(): Added candidate %u (RSSI: %d dBm)\n", fromNode,
        routerRSSI);
  }
 
  void sendBridgeStatus(bool leaving = false) {
    using namespace logger;
 
    if (!this->bridgeStatusBroadcastEnabled) {
      return;
    }
 
    // A bridge that nobody can reach is no bridge. On the rig a node
    // promoted in place reset every TCP connection to its AP for its whole
    // time as bridge — its listener, re-created by the promotion's
    // stop/re-init, was not listening, and nothing looked. This task runs
    // every thirty seconds on a bridge: if the listener is not in LISTEN
    // (1 on both cores) it is re-created, and the log says so.
    if (_tcpListener != nullptr && _tcpListener->status() != TCP_STATE_LISTEN) {
      Log(ERROR,
          "sendBridgeStatus(): TCP listener on port %d is in state %u, not "
          "LISTEN; re-creating it\n",
          _meshPort, (unsigned)_tcpListener->status());
      delete _tcpListener;
      _tcpListener = nullptr;
      tcpServerInit();
    }
 
    // Create bridge status package
    // We need to include the package header here since we're in wifi namespace
    // The package will be sent as a JSON string
    JsonDocument doc;
    JsonObject obj = doc.to<JsonObject>();
 
    obj["type"] = protocol::BRIDGE_STATUS;
    obj["from"] = this->nodeId;
    obj["routing"] = 2;  // BROADCAST routing
    obj["timestamp"] = this->getNodeTime();
 
    // Check Internet connectivity: WiFi connected AND valid IP address
    // We check for valid local IP instead of gateway IP because:
    // 1. Gateway IP might not be immediately available after connection
    // 2. Some networks (mobile hotspots) may not provide gateway IP via DHCP
    // 3. Having a valid local IP + being connected is sufficient for internet
    // access
    bool hasInternet = !leaving && (WiFi.status() == WL_CONNECTED) &&
                       (WiFi.localIP() != IPAddress(0, 0, 0, 0));
    obj["internetConnected"] = hasInternet;
    // A bridge stepping down says so. Every candidate would otherwise hold
    // it healthy until its last status aged out, a minute and more, before
    // holding an election — on the rig, past the failover contract.
    if (leaving) obj["leaving"] = true;
 
    int8_t rssi = WiFi.RSSI();
    uint8_t channel = WiFi.channel();
    uint32_t uptime = millis();
    TSTRING gatewayIP = WiFi.gatewayIP().toString();
 
    obj["routerRSSI"] = rssi;
    obj["routerChannel"] = channel;
    obj["uptime"] = uptime;
    obj["gatewayIP"] = gatewayIP;
    obj["message_type"] = protocol::BRIDGE_STATUS;
 
    String msg;
    serializeJson(doc, msg);
 
    Log(GENERAL, "sendBridgeStatus(): Broadcasting status (Internet: %s)%s\n",
        hasInternet ? "Connected" : "Disconnected",
        leaving ? " — stepping down" : "");
    Log(GENERAL,
        "sendBridgeStatus(): WiFi status=%d, localIP=%s, gatewayIP=%s\n",
        WiFi.status(), WiFi.localIP().toString().c_str(),
        WiFi.gatewayIP().toString().c_str());
 
    // Update our own bridge status in knownBridges list
    // This ensures the bridge reports itself correctly when queried
    this->updateBridgeStatus(this->nodeId, hasInternet, rssi, channel, uptime,
                             gatewayIP, this->getNodeTime());
 
    // Send bridge status using raw broadcast to preserve type BRIDGE_STATUS
    // Using sendBroadcast(msg) would wrap it in type 8 (BROADCAST) and hide
    // type BRIDGE_STATUS
    protocol::Variant variant(msg);
    router::broadcast<Connection>(variant, (*this), 0);
    _lastBridgeStatusBroadcast = millis();
  }
 
  bool hasActualInternetAccess() {
    using namespace logger;
 
    // Cache result to avoid blocking DNS/HTTP on every call
    static uint32_t lastCheckTime = 0;
    static bool lastResult = false;
    uint32_t now = millis();
    if (lastCheckTime > 0 && (now - lastCheckTime) < GATEWAY_CONNECTIVITY_CACHE_MS) {
      return lastResult;
    }
 
    // First check WiFi connection
    if (WiFi.status() != WL_CONNECTED) {
      lastCheckTime = millis();
      lastResult = false;
      return false;
    }
 
    // Check if we have a valid local IP
    if (WiFi.localIP() == IPAddress(0, 0, 0, 0)) {
      lastCheckTime = millis();
      lastResult = false;
      return false;
    }
 
    // Try to resolve a well-known DNS name
    // Using Google's servers as they have high availability globally
    IPAddress result;
 
#if defined(ESP8266)
    // ESP8266's hostByName() has a timeout overload, so the resolver cannot
    // stall the cooperative scheduler past GATEWAY_DNS_TIMEOUT_MS — that term
    // is part of gatewayBlockingBudgetMs() and covered by its static_assert
    // (issue #416).
    int dnsResult =
        WiFi.hostByName("www.google.com", result, GATEWAY_DNS_TIMEOUT_MS);
 
    // Check if DNS resolution succeeded
    if (dnsResult != 1) {
      Log(COMMUNICATION, "hasActualInternetAccess(): DNS resolution failed (code=%d)\n", dnsResult);
      lastCheckTime = millis();
      lastResult = false;
      return false;
    }
 
    // Additional validation: Check if resolved IP is valid
    // Some ESP8266 versions may return success but set IP to 255.255.255.255 on error
    if (result == IPAddress(0, 0, 0, 0) || result == IPAddress(255, 255, 255, 255)) {
      TSTRING resultStr = result.toString();
      Log(COMMUNICATION, "hasActualInternetAccess(): Invalid DNS result IP: %s\n", resultStr.c_str());
      lastCheckTime = millis();
      lastResult = false;
      return false;
    }
#elif defined(ESP32)
    // ESP32's hostByName() has no timeout parameter in the cores this library
    // targets, so a standalone DNS probe would be an unbounded stall on the
    // cooperative scheduler whenever DNS is slow or blackholed — the exact
    // failure mode of issues #318/#332, recurring once per
    // GATEWAY_CONNECTIVITY_CACHE_MS. The probe is therefore skipped on ESP32
    // (issue #416): actual reachability is established by the captive-portal
    // probe that runs right after this check on the same path — an HTTP
    // round trip bounded by GATEWAY_CAPTIVE_PORTAL_TIMEOUT_MS that fails on
    // a router without Internet just as the DNS probe would.
    (void)result;
    lastCheckTime = millis();
    lastResult = true;
    return true;
#else
    // Other platforms: assume internet is available if WiFi connected
    // (no reliable way to test without platform-specific APIs)
    lastCheckTime = millis();
    lastResult = true;
    return true;
#endif
 
    TSTRING resultStr = result.toString();
    Log(COMMUNICATION, "hasActualInternetAccess(): Internet connectivity verified (resolved to %s)\n",
        resultStr.c_str());
    lastCheckTime = millis();
    lastResult = true;
    return true;
  }
 
  bool detectCaptivePortal() {
    using namespace logger;
    
#if defined(ESP32) || defined(ESP8266)
    // Cache the verdict, exactly as hasActualInternetAccess() does. This probe
    // is a full HTTP round trip to an external host; running it per message
    // put that round trip in front of every single mesh->Internet send, on the
    // cooperative scheduler, where it stacks with the request's own timeout.
    static uint32_t lastCheckTime = 0;
    static bool lastResult = true;
    uint32_t now = millis();
    if (lastCheckTime > 0 && (now - lastCheckTime) < GATEWAY_CONNECTIVITY_CACHE_MS) {
      return lastResult;
    }
 
    // Record the attempt up front so that every early return below is cached
    // too -- otherwise a failing probe would be retried on every message.
    lastCheckTime = millis();
    lastResult = false;
 
    HTTPClient http;
    http.setTimeout(GATEWAY_CAPTIVE_PORTAL_TIMEOUT_MS);
    
    WiFiClient client;
    
    // Use Apple's captive portal detection endpoint
    // This is a well-maintained, reliable endpoint used by iOS devices
    const char* testUrl = "http://captive.apple.com/hotspot-detect.html";
    
    Log(COMMUNICATION, "detectCaptivePortal(): Testing %s\n", testUrl);
    
#ifdef ESP8266
    if (!http.begin(client, testUrl)) {
      Log(COMMUNICATION, "detectCaptivePortal(): Failed to begin HTTP client - treating as potential network restriction\n");
      return false;  // Conservative approach: treat initialization failure as potential captive portal or network restriction
    }
#else
    // ESP32
    if (!http.begin(testUrl)) {
      Log(COMMUNICATION, "detectCaptivePortal(): Failed to begin HTTP client - treating as potential network restriction\n");
      return false;
    }
#endif
    
    int httpCode = http.GET();
    
    if (httpCode != 200) {
      // Any response other than HTTP 200 indicates captive portal or network issue
      Log(COMMUNICATION, "detectCaptivePortal(): Unexpected HTTP code %d (expected 200)\n", httpCode);
      http.end();
      return false;
    }
    
    // Check response content
    String response = http.getString();
    http.end();
    
    // Verify the response contains "Success" - this is Apple's standard response
    // Full response: "<HTML><HEAD><TITLE>Success</TITLE></HEAD><BODY>Success</BODY></HTML>"
    // We check for presence of "Success" to be robust against minor format variations
    if (response.indexOf("Success") == -1) {
      Log(COMMUNICATION, "detectCaptivePortal(): Response doesn't contain 'Success', likely captive portal\n");
      return false;
    }
    
    Log(COMMUNICATION, "detectCaptivePortal(): No captive portal detected\n");
    lastResult = true;
    return true;
    
#else
    // Non-ESP platforms: can't reliably test, assume no captive portal
    return true;
#endif
  }
 
  gateway::NegativeDnsCache negativeDns;
 
#if defined(ESP32) || defined(ESP8266)
  static TSTRING readResponseExcerpt(HTTPClient& http) {
    const int size = http.getSize();
    if (size >= 0 &&
        static_cast<size_t>(size) <=
            gateway::GATEWAY_RESPONSE_HEAD_BYTES + gateway::GATEWAY_RESPONSE_TAIL_BYTES) {
      return http.getString();
    }
    gateway::ResponseExcerpt excerpt;
    WiFiClient* stream = http.getStreamPtr();
    if (stream == nullptr) return excerpt.text();
    const bool chunked =
        size < 0 && gateway::transferEncodingIsChunked(http.header("Transfer-Encoding"));
    gateway::ChunkedBodyDecoder decoder(excerpt);
    const uint32_t deadline =
        millis() + gateway::GATEWAY_RESPONSE_HEAD_TIMEOUT_MS;
    bool more = true;
    while (more && static_cast<int32_t>(deadline - millis()) > 0) {
      int available = stream->available();
      if (available <= 0) {
        if (!stream->connected()) break;
        delay(1);
        continue;
      }
      while (more && available-- > 0) {
        const int c = stream->read();
        if (c < 0) break;
        more = chunked ? decoder.add(static_cast<char>(c))
                       : excerpt.add(static_cast<char>(c));
      }
    }
    return excerpt.text();
  }
#endif
 
  // sendGatewayAck() is portable and lives in painlessmesh::Mesh
  // (mesh.hpp): every node needs it, not only a gateway, to answer a
  // request it cannot serve.
 
  void initGatewayInternetHandler() {
    using namespace logger;
    Log(STARTUP,
        "initGatewayInternetHandler(): Registering GATEWAY_DATA handler\n");
 
    this->callbackList.onPackage(
        protocol::GATEWAY_DATA, [this](protocol::Variant& variant,
                                       std::shared_ptr<Connection> ingress,
                                       uint32_t) {
          auto pkg = variant.to<gateway::GatewayDataPackage>();
 
          Log(COMMUNICATION,
              "Gateway received Internet request: msgId=%u dest=%s\n",
              pkg.messageId, pkg.destination.c_str());
 
          // Every exit path below goes through finish(), which re-arms the
          // mesh watchdog on all peers before the ack is routed.
          //
          // Everything from here on can block: the connectivity probes are
          // network round trips and the request itself runs to
          // GATEWAY_HTTP_TIMEOUT_MS. Nothing on the cooperative scheduler runs
          // during that, but wall-clock time keeps passing, so any peer whose
          // NODE_TIMEOUT deadline fell inside the stall is overdue the instant
          // the scheduler resumes and gets closed despite never having gone
          // missing (issues #318, #332).
          //
          // The previous mitigation disabled timeOutTask on the requesting
          // connection only. That left every other peer exposed, and it acted
          // before the stall rather than after it, which is the half that
          // cannot work: the deadline is wall-clock, so pushing it out ahead of
          // a stall longer than the window changes nothing.
          //
          // Compensation is by the *measured* stall (issue #417): exit paths
          // that never blocked measure ~0 ms and grant nothing, so a peer
          // that genuinely stopped answering NODE_SYNC still gets reaped even
          // under continuous gateway traffic from other peers.
          const auto blockingStartedMs = millis();
          // `retryable` is the gateway's word to the origin node on whether
          // the identical request may be sent again: 0 whenever it may have
          // reached the server, so a retry cannot deliver it twice.
          auto finish = [this, &pkg, ingress, blockingStartedMs](
                            bool ok, uint16_t code, const TSTRING& err,
                            int8_t retryable, const TSTRING& response = TSTRING(),
                            uint32_t retryAfterMs = 0) {
            const auto stalledMs = millis() - blockingStartedMs;
            auto refreshed = gateway::refreshPeerWatchdogs(*this, stalledMs);
            if (refreshed > 0) {
              Log(COMMUNICATION,
                  "Gateway postponed the mesh watchdog on %u peer(s) by %lu ms "
                  "after a blocking Internet request\n",
                  static_cast<unsigned>(refreshed),
                  static_cast<unsigned long>(stalledMs));
            }
            this->sendGatewayAck(pkg, ok, code, err, ingress, response, retryable,
                                 retryAfterMs);
          };
 
          // Check Internet connectivity
          // First check WiFi status for quick fail
          if (WiFi.status() != WL_CONNECTED) {
            finish(false, 0, "Gateway WiFi not connected", 0);
            return true;  // Consume package - we handled it (with error)
          }
          
          // Then check actual internet access (DNS resolution)
          // This detects when WiFi is connected but router has no internet
          if (!hasActualInternetAccess()) {
            finish(false, 0, "Router has no internet access - check WAN connection", 0);
            return true;  // Consume package - we handled it (with error)
          }
          
          // Finally, check for captive portal interference
          // This detects when DNS works but HTTP requests are intercepted
          if (!detectCaptivePortal()) {
            finish(false, 0, "Captive portal detected - requires web authentication. Check router/WiFi settings", 0);
            return true;  // Consume package - we handled it (with error)
          }
 
#if defined(ESP32) || defined(ESP8266)
#ifdef ESP32
          // A destination whose name failed to resolve is refused for
          // GATEWAY_DNS_NEGATIVE_TTL_MS without another lookup (issue #453).
          // HTTPClient reports a failed lookup as "connection refused" after
          // the resolver's own patience -- on ESP32 not boundable by this
          // library -- and it did so on every attempt: the origin node's
          // retries and, since #451, the bridge's own sends each paid it, and
          // the scheduler stalled long enough for relayed requests to time
          // out on their origin nodes. Resolving here, once, names the real
          // failure and caps the stall to one lookup per TTL per host.
          // ESP32 only: the ESP8266 core bounds HTTPClient's own lookup by the
          // HTTP timeout, and a second bounded wait would not fit the
          // blocking budget.
          const TSTRING host = gateway::hostFromUrl(pkg.destination);
          if (host.length() > 0 && !gateway::looksLikeIpLiteral(host)) {
            uint32_t failedAgoMs = 0;
            if (negativeDns.isFailing(host, millis(), &failedAgoMs)) {
              char dnsBuf[160];
              snprintf(dnsBuf, sizeof(dnsBuf),
                       "DNS lookup for %s failed %lus ago; not retried for "
                       "another %lus",
                       host.c_str(),
                       static_cast<unsigned long>(failedAgoMs / 1000),
                       static_cast<unsigned long>(
                           (gateway::GATEWAY_DNS_NEGATIVE_TTL_MS - failedAgoMs) /
                           1000));
              Log(ERROR, "%s\n", dnsBuf);
              finish(false, 0, TSTRING(dnsBuf), 0);
              return true;
            }
            IPAddress resolved;
            if (WiFi.hostByName(host.c_str(), resolved) != 1) {
              negativeDns.remember(host, millis());
              char dnsBuf[160];
              snprintf(dnsBuf, sizeof(dnsBuf), "DNS lookup failed for %s",
                       host.c_str());
              Log(ERROR, "%s\n", dnsBuf);
              finish(false, 0, TSTRING(dnsBuf), 0);
              return true;
            }
          }
#endif  // ESP32
 
          // Make HTTP/HTTPS request
          HTTPClient http;
          http.setTimeout(GATEWAY_HTTP_TIMEOUT_MS);
 
          bool success = false;
          // HTTPClient returns an int: a positive value is an HTTP status
          // code, a negative one is its own transport error (HTTPC_ERROR_*,
          // -1 for a refused connection, -11 for a read timeout, ...). This
          // was a uint16_t, which wrapped -1 to 65535 -- a value that passes
          // `httpCode > 0`, so every transport failure was reported to the
          // origin node as "HTTP 65535" (issue #446), the errorToString()
          // branch below was unreachable, and handleGatewayAck() classified a
          // transient network failure as a non-retryable HTTP status.
          int httpCode = 0;
          TSTRING error = "";
 
#ifdef ESP8266
          // ESP8266: Declare clients at function scope to ensure
          // they survive until after the HTTP request completes
          WiFiClient client;
          WiFiClientSecure secureClient;
#endif
 
          if (pkg.destination.startsWith("https://")) {
#ifdef ESP32
            // ESP32: no trust anchor is configured, so the certificate is not
            // validated against anything this library supplies. See the
            // security notes on initGatewayInternetHandler() and SECURITY.md.
            http.begin(pkg.destination.c_str());
#elif defined(ESP8266)
            // ESP8266: Use insecure mode to reduce memory overhead
            // WARNING: This disables SSL certificate validation
            secureClient.setInsecure();
            http.begin(secureClient, pkg.destination.c_str());
#endif
          } else {
#ifdef ESP32
            http.begin(pkg.destination.c_str());
#elif defined(ESP8266)
            // ESP8266: begin() requires a client parameter
            http.begin(client, pkg.destination.c_str());
#endif
          }
 
          // The same id on every attempt at this call. A service that
          // honours Idempotency-Key treats a retry as the request it already
          // has; anything recording requests can count the copies.
          const TSTRING requestId =
              gateway::requestIdFor(pkg.originNode, pkg.messageId, pkg.requestNonce);
          http.addHeader("X-Request-Id", requestId.c_str());
          http.addHeader("Idempotency-Key", requestId.c_str());
          // Not const: both cores declare collectHeaders(const char* keys[], ...).
          const char* collected[] = {"Retry-After", "Transfer-Encoding"};
          http.collectHeaders(collected, 2);
 
          // Make request (GET if no payload, POST if payload)
          if (pkg.payload.length() > 0) {
            http.addHeader("Content-Type", pkg.contentType.c_str());
            httpCode = http.POST(pkg.payload.c_str());
          } else {
            httpCode = http.GET();
          }
 
          // HTTP semantics only: 200/201/202/204 succeed, anything else fails,
          // and a retry is allowed only when it cannot deliver the request
          // twice (see gateway::classifyHttpResult). Whether a service's reply
          // means what the application wanted is the application's decision,
          // so the start of the body goes back on success as well as failure.
          //
          // 3xx redirects are not automatically followed.
          //
          // The classification lives in painlessmesh::gateway so the desktop
          // test suite can exercise it; this file is ESP-only and never
          // compiled by the Catch2 build.
          TSTRING responseHead;
          if (httpCode > 0) {
            responseHead =
                readResponseExcerpt(http);
          }
          const auto outcome =
              gateway::classifyHttpResult(httpCode, responseHead);
          success = outcome.success;
          const TSTRING responseSummary =
              httpCode > 0 ? gateway::summarizeResponseBody(responseHead) : TSTRING();
          uint32_t retryAfterMs = 0;
          if (outcome.retryable && httpCode > 0) {
            retryAfterMs = gateway::parseRetryAfterMs(http.header("Retry-After"));
          }
 
          if (!outcome.transportError) {
            char errorBuf[320];
            const char* reason = outcome.reason.c_str();
            const char* sep = outcome.reason.length() > 0 ? ": " : "";
            if (success) {
              Log(COMMUNICATION, "HTTP request completed: code=%d\n", httpCode);
            } else if (outcome.unverifiedStatus) {
              // A 2xx outside 200/201/202/204: the server answered, but not
              // with a status this library can call a delivery. Never
              // retried. Logged at ERROR, where a sketch on the default
              // levels sees what the service said.
              snprintf(errorBuf, sizeof(errorBuf),
                       "HTTP %d: not a delivery the gateway can confirm%s%s",
                       httpCode, sep, reason);
              error = TSTRING(errorBuf);
              Log(ERROR, "HTTP response unverified: %s\n", errorBuf);
            } else if (outcome.retryable) {
              // 429 or 503: the server says it did not take the request.
              snprintf(errorBuf, sizeof(errorBuf), "HTTP %d%s%s", httpCode, sep,
                       reason);
              error = TSTRING(errorBuf);
              Log(COMMUNICATION, "HTTP %d: the server asked to retry (after %lu ms)\n",
                  httpCode, static_cast<unsigned long>(retryAfterMs));
            } else {
              snprintf(errorBuf, sizeof(errorBuf), "HTTP %d%s%s", httpCode, sep,
                       reason);
              error = TSTRING(errorBuf);
              Log(ERROR, "HTTP request failed: %s\n", errorBuf);
            }
          } else {
            // Below HTTP. When the request may already be at the server -- a
            // read timeout, a connection lost after sending -- it is not
            // retried, and the error says why, so an application that
            // resends does so knowing it may duplicate.
            error = http.errorToString(httpCode);
            if (!outcome.retryable) {
              error += " (the request may have reached the server; not retried)";
            }
            Log(ERROR, "HTTP request failed: %s\n", error.c_str());
          }
 
          http.end();
 
          // Send acknowledgment back, with the verdict on retrying and the
          // start of whatever the server said.
          finish(success, outcome.ackStatus, error, outcome.retryable ? 1 : 0,
                 responseSummary, retryAfterMs);
#else
        // Non-ESP platform - send error
        finish(false, 0, "HTTP client not available on this platform", 0);
#endif
 
          return true;  // Consume package - we have processed it and sent
                        // acknowledgment
        });
  }
 
  void probeUplinkAfterAssociation() {
    if (!this->isInternetHealthCheckEnabled() || !stationScan.manual) return;
    this->addTask([this]() { this->checkInternetNow(); });
  }
 
  void eventHandleInit() {
    using namespace logger;
    // Where the station scan learns the channel the mesh is rooted on.
    // It used to look at its own scan's end, which a node connected to a
    // rooted mesh reaches once a minute: the node the failover test sends
    // from joined the bridge, the bridge left 24 s later, and no scan had
    // run in between — so it had no home to keep and followed a partition
    // off the router's channel. Topology changes are the moment to look.
    // Only "ever rooted" comes from the tree: the tree can carry a root that
    // is gone. On the rig a node's cached tree still showed the bridge as
    // its root for the seconds after the bridge had moved to its router's
    // channel, a topology change fired in that window, and the node
    // recorded the channel it was left on as home — then sat there alone,
    // seeing the mesh's four nodes on the router's channel and "staying".
    // Home is learnt from the bridge itself, below: its status message
    // carries the channel it is on, and a message just received is live.
    auto noteRoot = [this](uint32_t) {
      if (layout::isRooted(this->asNodeTree())) this->stationScan.noteEverRooted();
    };
    this->newConnectionCallbacks.push_back(noteRoot);
    this->changedConnectionCallbacks.push_back(noteRoot);
    this->callbackList.onPackage(
        protocol::BRIDGE_STATUS,
        [this](protocol::Variant& variant, std::shared_ptr<Connection>, uint32_t) {
          JsonDocument doc;
          TSTRING str;
          variant.printTo(str);
          if (deserializeJson(doc, str)) return false;
          JsonObject obj = doc.as<JsonObject>();
          if (obj["leaving"] | false) {
            // The bridge is stepping down; the generic handler forgets it.
            // Look for another now, not at the monitor's next tick.
            this->checkForBridgeSoon();
            return false;
          }
          uint8_t routerChannel = obj["routerChannel"] | 0;
          if (gateway::isValidMeshChannel(routerChannel)) {
            this->stationScan.noteRooted(routerChannel);
          }
          return false;  // the generic handler records the bridge
        });
#ifdef ESP32
    eventScanDoneHandler = WiFi.onEvent(
        [this](WiFiEvent_t event, WiFiEventInfo_t info) {
          if (this->semaphoreTake()) {
            Log(CONNECTION,
                "eventScanDoneHandler: ARDUINO_EVENT_WIFI_SCAN_DONE\n");
            // Not scanComplete() here. This callback runs on the core's
            // network-event task, under the lock that task dispatches
            // with, and scanComplete() can end in followBridgeChannel(),
            // which restarts the AP. On core 3.x that waits for events
            // only this task can deliver: on the rig every esp32-c5 and
            // esp32-c6 that followed the bridge's channel went silent for
            // the rest of the run, and stop() then blocked in
            // removeEvent() on the same lock. The result is consumed by
            // the station task instead, from update().
            this->stationScan.scanDone();
            this->semaphoreGive();
          }
        },
#if ESP_ARDUINO_VERSION_MAJOR >= 2
        WiFiEvent_t::ARDUINO_EVENT_WIFI_SCAN_DONE);
#else
        WiFiEvent_t::SYSTEM_EVENT_SCAN_DONE);
#endif
 
    eventSTAStartHandler = WiFi.onEvent(
        [this](WiFiEvent_t event, WiFiEventInfo_t info) {
          if (this->semaphoreTake()) {
            Log(CONNECTION,
                "eventSTAStartHandler: ARDUINO_EVENT_WIFI_STA_START\n");
            this->semaphoreGive();
          }
        },
#if ESP_ARDUINO_VERSION_MAJOR >= 2
        WiFiEvent_t::ARDUINO_EVENT_WIFI_STA_START);
#else
        WiFiEvent_t::SYSTEM_EVENT_STA_START);
#endif
 
    eventSTADisconnectedHandler = WiFi.onEvent(
        [this](WiFiEvent_t event, WiFiEventInfo_t info) {
          if (this->semaphoreTake()) {
            Log(CONNECTION,
                "eventSTADisconnectedHandler: "
                "ARDUINO_EVENT_WIFI_STA_DISCONNECTED\n");
            this->stationScan.stationAttemptOver();
            this->droppedConnectionCallbacks.execute(0, true);
            this->stationScan.stationDown();
            // Handle station disconnect completion after callbacks
            this->handleStationDisconnectComplete();
            this->semaphoreGive();
          }
        },
#if ESP_ARDUINO_VERSION_MAJOR >= 2
        WiFiEvent_t::ARDUINO_EVENT_WIFI_STA_DISCONNECTED);
#else
        WiFiEvent_t::SYSTEM_EVENT_STA_DISCONNECTED);
#endif
 
    eventSTAGotIPHandler = WiFi.onEvent(
        [this](WiFiEvent_t event, WiFiEventInfo_t info) {
          if (this->semaphoreTake()) {
            Log(CONNECTION,
                "eventSTAGotIPHandler: ARDUINO_EVENT_WIFI_STA_GOT_IP\n");
            this->stationScan.stationAttemptOver();
            this->stationScan.stationUp();
            this->tcpConnect();  // Connect to TCP port
            this->probeUplinkAfterAssociation();
            this->semaphoreGive();
          }
        },
#if ESP_ARDUINO_VERSION_MAJOR >= 2
        WiFiEvent_t::ARDUINO_EVENT_WIFI_STA_GOT_IP);
#else
        WiFiEvent_t::SYSTEM_EVENT_STA_GOT_IP);
#endif
 
#elif defined(ESP8266)
    eventSTAConnectedHandler = WiFi.onStationModeConnected(
        [&](const WiFiEventStationModeConnected& event) {
          // Log(CONNECTION, "Event: Station Mode Connected to \"%s\"\n",
          // event.ssid.c_str());
          Log(CONNECTION, "Event: Station Mode Connected\n");
        });
 
    eventSTADisconnectedHandler = WiFi.onStationModeDisconnected(
        [&](const WiFiEventStationModeDisconnected& event) {
          Log(CONNECTION, "Event: Station Mode Disconnected\n");
          this->stationScan.stationAttemptOver();
          this->droppedConnectionCallbacks.execute(0, true);
          this->stationScan.stationDown();
          // Handle station disconnect completion after callbacks
          this->handleStationDisconnectComplete();
        });
 
    eventSTAGotIPHandler =
        WiFi.onStationModeGotIP([&](const WiFiEventStationModeGotIP& event) {
          Log(CONNECTION,
              "Event: Station Mode Got IP (IP: %s  Mask: %s  Gateway: %s)\n",
              event.ip.toString().c_str(), event.mask.toString().c_str(),
              event.gw.toString().c_str());
          this->stationScan.stationAttemptOver();
          this->stationScan.stationUp();
          this->tcpConnect();  // Connect to TCP port
          this->probeUplinkAfterAssociation();
        });
#endif  // ESP32
    return;
  }
 
#ifdef ESP32
  // Event ids the core hands back from onEvent(); stop() removes all four.
  // 0 is never issued (the core's ids start at 1 and 0 means "no
  // callback"), so removeEvent(0) is a no-op on a node stopped before
  // init() rather than a walk of the core's callback list for garbage.
  WiFiEventId_t eventScanDoneHandler = 0;
  WiFiEventId_t eventSTAStartHandler = 0;
  WiFiEventId_t eventSTADisconnectedHandler = 0;
  WiFiEventId_t eventSTAGotIPHandler = 0;
#elif defined(ESP8266)
  WiFiEventHandler eventSTAConnectedHandler;
  WiFiEventHandler eventSTADisconnectedHandler;
  WiFiEventHandler eventSTAGotIPHandler;
#endif  // ESP8266
  // Null until tcpServerInit() creates it. Every reader checks for null
  // first, and one of them (tcpServerInit() itself, since 2.1.0) runs before
  // anything has assigned it -- on an uninitialised pointer that check
  // passed on garbage and the delete that followed crashed the node before
  // it served a single connection (#466).
  AsyncServer* _tcpListener = nullptr;
  std::shared_ptr<Task> bridgeStatusTask;
  // millis() of the last status broadcast, periodic or brought forward by a
  // topology change; the latter is held to one every five seconds.
  uint32_t _lastBridgeStatusBroadcast = 0;
 
  // Station disconnect handling state
  bool _pendingStationReconnect = false;
 
  // Bridge failover state and configuration
  enum ElectionState { ELECTION_IDLE, ELECTION_SCANNING, ELECTION_COLLECTING };
 
  struct BridgeCandidate {
    uint32_t nodeId = 0;
    int8_t routerRSSI = 0;
    uint8_t routerChannel = 0;
    uint32_t uptime = 0;
    uint32_t freeMemory = 0;
  };
 
  bool bridgeFailoverEnabled = true;
  bool routerCredentialsConfigured = false;
  TSTRING routerSSID = "";
  TSTRING routerPassword = "";
  uint32_t electionTimeoutMs = 5000;  // Default 5 seconds
  int8_t minimumBridgeRSSI =
      -80;  // Default -80 dBm minimum for isolated elections
  uint32_t electionStartupDelayMs =
      60000;  // Default 60 seconds before first election check
  uint32_t electionRandomDelayMinMs =
      1000;  // Default min 1 second random delay
  uint32_t electionRandomDelayMaxMs =
      3000;  // Default max 3 seconds random delay
  uint32_t lastRoleChangeTime = 0;
  // A checkForBridge() is already scheduled (a bridge stepping down, or
  // the role-change hold); one at a time is enough.
  bool bridgeCheckPending = false;
  ElectionState electionState = ELECTION_IDLE;
  uint32_t electionDeadline = 0;
  std::vector<BridgeCandidate> electionCandidates;
  std::function<void(bool isBridge, const TSTRING& reason)> bridgeRoleChangedCallback;
 
  // Isolated bridge retry state and configuration
  uint8_t _isolatedBridgeRetryAttempts = 0;
  uint32_t _isolatedBridgeRetryResetTime =
      0;  // Time when retry counter can be reset
  bool _isolatedRetryPending =
      false;  // Flag to skip empty scan check after failed promotion
  static const uint8_t MAX_ISOLATED_BRIDGE_RETRY_ATTEMPTS =
      5;  // Max retry attempts before waiting
  static const uint32_t isolatedBridgeRetryIntervalMs =
      60000;  // Retry every 60 seconds
  static const uint32_t isolatedBridgeRetryResetIntervalMs =
      300000;  // Reset counter after 5 minutes
  static const uint16_t ISOLATED_BRIDGE_RETRY_SCAN_THRESHOLD =
      6;  // Require 6 empty scans before retrying
  static const uint32_t ASYNC_PROMOTION_DELAY_MS =
      10;  // Delay for async bridge promotion to allow current task to complete
 
  // Multi-bridge coordination state and configuration
 protected:
  bool multiBridgeEnabled = false;
  BridgeSelectionStrategy bridgeSelectionStrategy = PRIORITY_BASED;
  uint8_t maxConcurrentBridges = 2;
  uint8_t bridgePriority = 5;        // Default medium priority
  TSTRING bridgeRole = "secondary";  // Default role
  std::shared_ptr<Task> bridgeCoordinationTask;
  std::map<uint32_t, uint8_t> bridgePriorities;  // nodeId -> priority mapping
  std::vector<uint32_t> knownBridgePeers;        // List of peer bridge node IDs
  size_t lastSelectedBridgeIndex = 0;   // For round-robin selection
 
  // Bridge coordination monitoring callbacks and state
  // Constructed by name, not as an aggregate: with default member
  // initializers this is not an aggregate under gnu++11, which the ESP32
  // Arduino 2.x core still builds with, and `= {priority, role, load,
  // millis()}` below needs a constructor to land on there.
  struct BridgeCoordinationState {
    uint8_t priority = 0;
    TSTRING role;
    uint8_t load = 0;
    uint32_t lastSeen = 0;
    BridgeCoordinationState() {}
    BridgeCoordinationState(uint8_t priority_, const TSTRING& role_,
                            uint8_t load_, uint32_t lastSeen_)
        : priority(priority_), role(role_), load(load_), lastSeen(lastSeen_) {}
  };
  std::map<uint32_t, BridgeCoordinationState> lastBridgeCoordinationState;
  std::function<void(const plugin::BridgeCoordinationPackage&, uint32_t)> bridgeCoordinationCallback;
  std::function<void(const plugin::BridgeCoordinationPackage&, uint32_t, TSTRING)> bridgeCoordinationChangedCallback;
  std::shared_ptr<Task> bridgeLostDetectionTask;
 
  // Shared gateway mode state and configuration
  bool _sharedGatewayMode = false;
  gateway::SharedGatewayConfig _sharedGatewayConfig;
  std::shared_ptr<Task> _sharedGatewayMonitorTask;
  uint32_t _lastRouterReconnectAttempt = 0;
  uint8_t _routerReconnectAttempts = 0;
  static const uint8_t MAX_ROUTER_RECONNECT_ATTEMPTS = 10;
  static const uint32_t ROUTER_RECONNECT_BASE_INTERVAL =
      5000;  // 5 seconds base interval
  static const uint32_t ROUTER_RECONNECT_MAX_INTERVAL =
      300000;  // 5 minutes max interval
  static const int ROUTER_CONNECTION_TIMEOUT_SECONDS =
      30;  // Router connection timeout
  static const uint8_t MIN_WIFI_CHANNEL = 1;
  static const uint8_t MAX_WIFI_CHANNEL =
      14;  // Support channels 1-14 for regions that allow it
 
  void initSharedGatewayMonitoring() {
    using namespace logger;
 
    if (!_sharedGatewayMode) {
      return;
    }
 
    Log(STARTUP,
        "initSharedGatewayMonitoring(): Setting up router connection "
        "monitoring\n");
 
    // Add callback for router disconnection in shared gateway mode
    this->droppedConnectionCallbacks.push_back(
        [this](uint32_t nodeId, bool station) {
          if (station && _sharedGatewayMode) {
            Log(CONNECTION,
                "Router disconnected in shared gateway mode, scheduling "
                "reconnection\n");
            scheduleRouterReconnect();
          }
        });
 
    // Create periodic monitoring task
    _sharedGatewayMonitorTask =
        this->addTask(_sharedGatewayConfig.internetCheckInterval, TASK_FOREVER,
                      [this]() { monitorRouterConnection(); });
 
    Log(STARTUP, "Router connection monitoring enabled (interval: %u ms)\n",
        _sharedGatewayConfig.internetCheckInterval);
  }
 
  void monitorRouterConnection() {
    using namespace logger;
 
    if (!_sharedGatewayMode) {
      return;
    }
 
    bool isConnected = (WiFi.status() == WL_CONNECTED) &&
                       (WiFi.localIP() != IPAddress(0, 0, 0, 0));
 
    if (!isConnected) {
      Log(CONNECTION,
          "monitorRouterConnection(): Router connection lost, triggering "
          "reconnect\n");
      scheduleRouterReconnect();
    } else {
      // Connection is healthy, reset reconnect attempts
      _routerReconnectAttempts = 0;
 
      // Log periodic status
      Log(GENERAL,
          "monitorRouterConnection(): Router connected (RSSI: %d dBm, IP: "
          "%s)\n",
          WiFi.RSSI(), WiFi.localIP().toString().c_str());
    }
  }
 
  void scheduleRouterReconnect() {
    using namespace logger;
 
    if (!_sharedGatewayMode) {
      return;
    }
 
    // Don't schedule if already connected
    if (WiFi.status() == WL_CONNECTED) {
      return;
    }
 
    // Limit reconnection attempts
    if (_routerReconnectAttempts >= MAX_ROUTER_RECONNECT_ATTEMPTS) {
      Log(ERROR,
          "scheduleRouterReconnect(): Max reconnection attempts reached (%d)\n",
          MAX_ROUTER_RECONNECT_ATTEMPTS);
      Log(ERROR,
          "Router reconnection suspended. Manual intervention may be "
          "required.\n");
      return;
    }
 
    // Calculate delay with exponential backoff, preventing overflow
    // Limit shift amount to prevent overflow (5000 * 2^6 = 320000 is safe)
    uint8_t shiftAmount =
        (_routerReconnectAttempts > 6) ? 6 : _routerReconnectAttempts;
    uint32_t delay = ROUTER_RECONNECT_BASE_INTERVAL * (1UL << shiftAmount);
    if (delay > ROUTER_RECONNECT_MAX_INTERVAL)
      delay = ROUTER_RECONNECT_MAX_INTERVAL;
 
    // Don't reconnect too frequently
    uint32_t now = millis();
    if (now - _lastRouterReconnectAttempt < delay) {
      return;
    }
 
    _routerReconnectAttempts++;
    _lastRouterReconnectAttempt = now;
 
    Log(CONNECTION,
        "scheduleRouterReconnect(): Attempting reconnection (attempt %d/%d, "
        "delay %u ms)\n",
        _routerReconnectAttempts, MAX_ROUTER_RECONNECT_ATTEMPTS, delay);
 
    // Schedule reconnection
    this->addTask(delay, TASK_ONCE, [this]() { attemptRouterReconnect(); });
  }
 
  void attemptRouterReconnect() {
    using namespace logger;
 
    if (!_sharedGatewayMode) {
      return;
    }
 
    // Check if already connected
    if (WiFi.status() == WL_CONNECTED) {
      Log(CONNECTION,
          "attemptRouterReconnect(): Already connected to router\n");
      _routerReconnectAttempts = 0;
      return;
    }
 
    Log(CONNECTION, "attemptRouterReconnect(): Reconnecting to router %s...\n",
        _sharedGatewayConfig.routerSSID.c_str());
 
    // Use stationManual to reconnect (port 0 means no TCP mesh connection to
    // router)
    stationManual(_sharedGatewayConfig.routerSSID,
                  _sharedGatewayConfig.routerPassword, 0);
  }
};
}  // namespace wifi
};  // namespace painlessmesh
 
#endif
 
#endif