feat: implement WiFi AP roaming support and add these metrics to device health reporting

Author: chvvkumar

ESP32-P4-Allsky-Display.ino

@@ -1823,7 +1823,10 @@ void loop() {
     }
 
     // Process background retry tasks (handles network, MQTT, and image download failures)
-    taskRetryHandler.process();
+    // Skip during OTA to free network bandwidth and reduce PSRAM contention
+    if (!webConfig.isOTAInProgress()) {
+        taskRetryHandler.process();
+    }
     systemMonitor.forceResetWatchdog();
 
     // Handle web server first for maximum responsiveness
@@ -1889,8 +1892,8 @@ void loop() {
             if (webHandleTime > 5000) {
                 Serial.printf("WARNING: Web client handling took %lu ms\n", webHandleTime);
             }
-        } else {
-            // Try to start web server if not running
+        } else if (!webConfig.isOTAInProgress()) {
+            // Try to start web server if not running (skip during OTA)
             Serial.println("DEBUG: Web server not running, attempting to restart...");
             systemMonitor.forceResetWatchdog();  // Reset before webConfig.begin
             if (webConfig.begin(8080)) {
@@ -1904,19 +1907,20 @@ void loop() {
     }
 
     // Update MQTT manager (connect to MQTT after WiFi is established) with protection
-    if (wifiManager.isConnected()) {
+    // Skip during OTA to free network bandwidth
+    if (wifiManager.isConnected() && !webConfig.isOTAInProgress()) {
         unsigned long mqttStartTime = millis();
         mqttManager.update();
-        
+
         // Check if MQTT update took too long
         if (millis() - mqttStartTime > 2000) {
             Serial.printf("WARNING: MQTT update took %lu ms\n", millis() - mqttStartTime);
         }
         systemMonitor.forceResetWatchdog();
     }
-    
-    // Handle WebSocket events
-    if (wifiManager.isConnected() && webConfig.isRunning()) {
+
+    // Handle WebSocket events — skip during OTA to free network bandwidth
+    if (wifiManager.isConnected() && webConfig.isRunning() && !webConfig.isOTAInProgress()) {
         webConfig.loopWebSocket();
     }
 
@@ -2016,8 +2020,9 @@ void loop() {
     }
 
     // Only auto-cycle if in automatic mode, not paused, and multiple images available
+    // Skip during OTA — no point cycling images while firmware is being written
     int imageUpdateMode = cachedImageUpdateMode;
-    if (imageUpdateMode == 0 && cyclingEnabled && imageSourceCount > 1 && !imageProcessing && !singleImageRefreshMode && !cyclingPausedForEditing) {
+    if (imageUpdateMode == 0 && cyclingEnabled && imageSourceCount > 1 && !imageProcessing && !singleImageRefreshMode && !cyclingPausedForEditing && !webConfig.isOTAInProgress()) {
         // Use per-image duration instead of global cycle interval (from cached NVS value)
         unsigned long currentImageDuration = cachedImageDuration * 1000;  // Convert seconds to milliseconds
         if (currentTime - lastCycleTime >= currentImageDuration || lastCycleTime == 0) {

build_info.h

@@ -9,8 +9,8 @@
 #define BUILD_TIME __TIME__
 
 // Git information (updated by compile script)
-#define GIT_COMMIT_HASH "3c63259"
-#define GIT_COMMIT_FULL "3c632593726059ee497de5aeb289ceb69c05c406"
+#define GIT_COMMIT_HASH "3f64c2d"
+#define GIT_COMMIT_FULL "3f64c2d636ef43cfc0102beac1db150c38ce586a"
 #define GIT_BRANCH "snd"
 
 #endif // BUILD_INFO_H

config.h

@@ -58,6 +58,10 @@ extern const char* WIFI_PASSWORD;
 #define WIFI_MAX_WAIT_TIME 12000         // 12 seconds maximum wait time
 #define WIFI_RETRY_DELAY 400             // Delay between connection attempts
 
+// WiFi AP roaming (mesh network support)
+#define WIFI_ROAM_CHECK_INTERVAL  60000  // ms between roam scans (60 seconds)
+#define WIFI_ROAM_RSSI_THRESHOLD  8      // minimum dB improvement to trigger AP switch
+
 // =============================================================================
 // MQTT CONFIGURATION
 // =============================================================================

device_health.cpp

@@ -15,6 +15,9 @@ DeviceHealthAnalyzer deviceHealth;
 unsigned long DeviceHealthAnalyzer::networkDisconnectCount = 0;
 unsigned long DeviceHealthAnalyzer::mqttReconnectCount = 0;
 unsigned long DeviceHealthAnalyzer::watchdogResetCount = 0;
+unsigned long DeviceHealthAnalyzer::roamCount = 0;
+unsigned long DeviceHealthAnalyzer::roamScanCount = 0;
+unsigned long DeviceHealthAnalyzer::lastRoamTime = 0;
 
 DeviceHealthAnalyzer::DeviceHealthAnalyzer() {
 }
@@ -104,7 +107,11 @@ NetworkHealth DeviceHealthAnalyzer::analyzeNetwork() {
     health.rssi = WiFi.RSSI();
     health.uptime = millis();
     health.disconnectCount = networkDisconnectCount;
-    
+    health.bssid = WiFi.BSSIDstr();
+    health.roamCount = roamCount;
+    health.roamScanCount = roamScanCount;
+    health.lastRoamTime = lastRoamTime;
+
     if (!health.connected) {
         health.status = HEALTH_FAILING;
         health.message = "Critical: WiFi disconnected";
@@ -365,7 +372,9 @@ void DeviceHealthAnalyzer::printReport(const DeviceHealthReport& report) {
     LOG_INFO_F("  Connected: %s | RSSI: %d dBm | Disconnects: %lu\n",
                report.network.connected ? "Yes" : "No",
                report.network.rssi, report.network.disconnectCount);
-    
+    LOG_INFO_F("  BSSID: %s | Roams: %lu | Roam Scans: %lu\n",
+               report.network.bssid.c_str(), report.network.roamCount, report.network.roamScanCount);
+
     // MQTT
     LOG_INFO_F("[MQTT] %s - %s\n", healthStatusToString(report.mqtt.status), report.mqtt.message.c_str());
     LOG_INFO_F("  Connected: %s | Reconnects: %lu\n",
@@ -429,9 +438,13 @@ String DeviceHealthAnalyzer::getReportJSON(const DeviceHealthReport& report) {
     json += "\"message\":\"" + escapeJsonString(report.network.message) + "\",";
     json += "\"connected\":" + String(report.network.connected ? "true" : "false") + ",";
     json += "\"rssi\":" + String(report.network.rssi) + ",";
-    json += "\"disconnect_count\":" + String(report.network.disconnectCount);
+    json += "\"disconnect_count\":" + String(report.network.disconnectCount) + ",";
+    json += "\"bssid\":\"" + escapeJsonString(report.network.bssid) + "\",";
+    json += "\"roam_count\":" + String(report.network.roamCount) + ",";
+    json += "\"roam_scan_count\":" + String(report.network.roamScanCount) + ",";
+    json += "\"last_roam_time_ms\":" + String(report.network.lastRoamTime);
     json += "},";
-    
+
     // MQTT health
     json += "\"mqtt\":{";
     json += "\"status\":\"" + String(healthStatusToString(report.mqtt.status)) + "\",";
@@ -488,6 +501,16 @@ void DeviceHealthAnalyzer::recordWatchdogReset() {
     LOG_DEBUG_F("[HealthTracker] Watchdog reset count: %lu\n", watchdogResetCount);
 }
 
+void DeviceHealthAnalyzer::recordRoam() {
+    roamCount++;
+    lastRoamTime = millis();
+    LOG_DEBUG_F("[HealthTracker] Roam count: %lu\n", roamCount);
+}
+
+void DeviceHealthAnalyzer::recordRoamScan() {
+    roamScanCount++;
+}
+
 bool DeviceHealthAnalyzer::isMemoryHealthy() {
     MemoryHealth health = analyzeMemory();
     return health.status <= HEALTH_GOOD;

device_health.h

@@ -32,6 +32,10 @@ struct NetworkHealth {
     int rssi;
     unsigned long uptime;
     unsigned long disconnectCount;
+    String bssid;
+    unsigned long roamCount;
+    unsigned long roamScanCount;
+    unsigned long lastRoamTime;
     HealthStatus status;
     String message;
 };
@@ -88,7 +92,10 @@ class DeviceHealthAnalyzer {
     static unsigned long networkDisconnectCount;
     static unsigned long mqttReconnectCount;
     static unsigned long watchdogResetCount;
-    
+    static unsigned long roamCount;
+    static unsigned long roamScanCount;
+    static unsigned long lastRoamTime;
+
     // Analysis methods
     MemoryHealth analyzeMemory();
     NetworkHealth analyzeNetwork();
@@ -118,7 +125,9 @@ class DeviceHealthAnalyzer {
     static void recordNetworkDisconnect();
     static void recordMQTTReconnect();
     static void recordWatchdogReset();
-    
+    static void recordRoam();
+    static void recordRoamScan();
+
     // Quick health checks
     bool isMemoryHealthy();
     bool isSystemHealthy();

network_manager.cpp

@@ -30,8 +30,14 @@ WiFiManager::WiFiManager() :
     ntpRetries(0),
     debugPrintFunc(nullptr),
     debugPrintfFunc(nullptr),
-    firstImageLoaded(false)
+    firstImageLoaded(false),
+    roamScanPending(false),
+    roamInProgress(false),
+    lastRoamScanTime(0),
+    roamStartTime(0),
+    roamTargetChannel(0)
 {
+    memset(roamTargetBSSID, 0, sizeof(roamTargetBSSID));
 }
 
 bool WiFiManager::begin() {
@@ -166,11 +172,135 @@ void WiFiManager::setDebugFunctions(void (*debugPrint)(const char*, uint16_t),
     }
 }
 
+void WiFiManager::checkForBetterAP() {
+    unsigned long now = millis();
+
+    // --- State: Roam in progress (polling reconnection to target AP) ---
+    if (roamInProgress) {
+        if (WiFi.status() == WL_CONNECTED) {
+            // Roam succeeded
+            roamInProgress = false;
+            wifiConnected = true;
+            LOG_INFO_F("[WiFi] Roam successful - connected to %s (RSSI: %d dBm, ch: %d) in %lu ms\n",
+                       WiFi.BSSIDstr().c_str(), WiFi.RSSI(), WiFi.channel(),
+                       now - roamStartTime);
+            DeviceHealthAnalyzer::recordRoam();
+            syncNTPTime();
+        } else if (now - roamStartTime > WIFI_MAX_WAIT_TIME) {
+            // Roam timed out — fall back to normal reconnection
+            LOG_WARNING_F("[WiFi] Roam failed (timeout after %lu ms) - falling back to auto-connect\n",
+                          now - roamStartTime);
+            roamInProgress = false;
+            wifiConnected = false;
+            WiFi.disconnect();
+            // Next update() cycle will call connectToWiFi() without BSSID lock
+        } else if (WiFi.status() == WL_CONNECT_FAILED || WiFi.status() == WL_NO_SSID_AVAIL) {
+            LOG_WARNING_F("[WiFi] Roam failed (status: %d) - falling back to auto-connect\n",
+                          WiFi.status());
+            roamInProgress = false;
+            wifiConnected = false;
+            WiFi.disconnect();
+        }
+        return;
+    }
+
+    // Don't start roam logic if not connected or if NTP sync is in progress
+    if (!isConnected() || ntpSyncInProgress) {
+        return;
+    }
+
+    // --- State: Scan pending (poll for async scan completion) ---
+    if (roamScanPending) {
+        int scanResult = WiFi.scanComplete();
+
+        if (scanResult == WIFI_SCAN_RUNNING) {
+            return;  // Still scanning
+        }
+
+        roamScanPending = false;
+
+        if (scanResult == WIFI_SCAN_FAILED || scanResult < 0) {
+            LOG_WARNING("[WiFi] Roam scan failed");
+            WiFi.scanDelete();
+            return;
+        }
+
+        // Get current connection info for comparison
+        int currentRSSI = WiFi.RSSI();
+        String currentBSSID = WiFi.BSSIDstr();
+        String currentSSID = String(WIFI_SSID);
+
+        // Find the strongest AP with the same SSID but different BSSID
+        int bestIndex = -1;
+        int bestRSSI = currentRSSI;
+
+        for (int i = 0; i < scanResult; i++) {
+            String scanSSID = WiFi.SSID(i);
+            String scanBSSID = WiFi.BSSIDstr(i);
+            int scanRSSI = WiFi.RSSI(i);
+
+            if (scanSSID == currentSSID && scanBSSID != currentBSSID) {
+                if (scanRSSI > bestRSSI + WIFI_ROAM_RSSI_THRESHOLD) {
+                    bestRSSI = scanRSSI;
+                    bestIndex = i;
+                }
+            }
+        }
+
+        if (bestIndex >= 0) {
+            // Found a significantly stronger AP — initiate roam
+            LOG_INFO_F("[WiFi] Roaming from %s (%d dBm) to %s (%d dBm, ch: %d)\n",
+                       currentBSSID.c_str(), currentRSSI,
+                       WiFi.BSSIDstr(bestIndex).c_str(), bestRSSI, WiFi.channel(bestIndex));
+
+            // Save target BSSID and channel before scanDelete clears them
+            memcpy(roamTargetBSSID, WiFi.BSSID(bestIndex), 6);
+            roamTargetChannel = WiFi.channel(bestIndex);
+
+            WiFi.scanDelete();
+
+            // Disconnect and reconnect to the stronger AP
+            WiFi.disconnect();
+            roamInProgress = true;
+            roamStartTime = now;
+            WiFi.begin(WIFI_SSID, WIFI_PASSWORD, roamTargetChannel, roamTargetBSSID);
+        } else {
+            LOG_DEBUG_F("[WiFi] Roam scan: no better AP found (current: %s, %d dBm, %d candidates)\n",
+                        currentBSSID.c_str(), currentRSSI, scanResult);
+            WiFi.scanDelete();
+        }
+
+        return;
+    }
+
+    // --- State: Idle (check if it's time to start a new roam scan) ---
+    if (now - lastRoamScanTime >= WIFI_ROAM_CHECK_INTERVAL) {
+        // Don't start a scan if one is already running (e.g., web API scan)
+        if (WiFi.scanComplete() == WIFI_SCAN_RUNNING) {
+            return;
+        }
+
+        lastRoamScanTime = now;
+        roamScanPending = true;
+        DeviceHealthAnalyzer::recordRoamScan();
+        WiFi.scanNetworks(true, false);  // async=true, show_hidden=false
+        LOG_DEBUG("[WiFi] Roam scan started (async)");
+    }
+}
+
 void WiFiManager::update() {
+    // During a roam, skip checkConnection/connectToWiFi to prevent interference
+    if (roamInProgress) {
+        checkForBetterAP();  // Poll roam connection status
+        return;
+    }
+
     checkConnection();
 
-    // Attempt reconnection if disconnected (non-blocking)
-    if (!isConnected()) {
+    if (isConnected()) {
+        checkForBetterAP();  // Scan for better APs / evaluate results
+    } else {
+        // Attempt reconnection if disconnected (non-blocking)
         connectToWiFi();
     }
 

network_manager.h

@@ -19,6 +19,14 @@ class WiFiManager {
     static constexpr unsigned long RECONNECT_BACKOFF_MIN = 2000;
     static constexpr unsigned long RECONNECT_BACKOFF_MAX = 60000;
 
+    // AP roaming state (mesh WiFi support)
+    bool roamScanPending;
+    bool roamInProgress;
+    unsigned long lastRoamScanTime;
+    unsigned long roamStartTime;
+    uint8_t roamTargetBSSID[6];
+    int roamTargetChannel;
+
     // Non-blocking NTP state
     bool ntpSyncInProgress;
     unsigned long ntpSyncStartTime;
@@ -29,6 +37,7 @@ class WiFiManager {
     // Debug display function pointer
     void (*debugPrintFunc)(const char* message, uint16_t color);
     void (*debugPrintfFunc)(uint16_t color, const char* format, ...);
+    void checkForBetterAP();
     bool firstImageLoaded;
 
 public:

web_config_api.cpp

@@ -949,6 +949,7 @@ void WebConfig::handleGetAllInfo() {
         json += "\"dns\":\"" + WiFi.dnsIP().toString() + "\",";
         json += "\"mac\":\"" + WiFi.macAddress() + "\",";
         json += "\"rssi\":" + String(WiFi.RSSI()) + ",";
+        json += "\"bssid\":\"" + WiFi.BSSIDstr() + "\",";
         json += "\"hostname\":\"" + String(WiFi.getHostname()) + "\"";
     } else {
         json += "\"ssid\":null,";
@@ -957,6 +958,7 @@ void WebConfig::handleGetAllInfo() {
         json += "\"dns\":null,";
         json += "\"mac\":\"" + WiFi.macAddress() + "\",";
         json += "\"rssi\":0,";
+        json += "\"bssid\":null,";
         json += "\"hostname\":null";
     }
     json += "},";