wifi roam

esphome/components/wifi/__init__.py

@@ -64,6 +64,7 @@ _LOGGER = logging.getLogger(__name__)
 NO_WIFI_VARIANTS = [const.VARIANT_ESP32H2, const.VARIANT_ESP32P4]
 CONF_SAVE = "save"
 CONF_MIN_AUTH_MODE = "min_auth_mode"
+CONF_POST_CONNECT_ROAMING = "post_connect_roaming"
 
 # Maximum number of WiFi networks that can be configured
 # Limited to 127 because selected_sta_index_ is int8_t in C++
@@ -349,6 +350,7 @@ CONFIG_SCHEMA = cv.All(
             ),
             cv.Optional(CONF_PASSIVE_SCAN, default=False): cv.boolean,
             cv.Optional(CONF_ENABLE_ON_BOOT, default=True): cv.boolean,
+            cv.Optional(CONF_POST_CONNECT_ROAMING, default=True): cv.boolean,
             cv.Optional(CONF_ON_CONNECT): automation.validate_automation(single=True),
             cv.Optional(CONF_ON_DISCONNECT): automation.validate_automation(
                 single=True
@@ -491,6 +493,15 @@ async def to_code(config):
     if not config[CONF_ENABLE_ON_BOOT]:
         cg.add(var.set_enable_on_boot(False))
 
+    # post_connect_roaming defaults to true in C++ - disable if user disabled it
+    # or if 802.11k/v is enabled (driver handles roaming natively)
+    if (
+        not config[CONF_POST_CONNECT_ROAMING]
+        or config.get(CONF_ENABLE_BTM)
+        or config.get(CONF_ENABLE_RRM)
+    ):
+        cg.add(var.set_post_connect_roaming(False))
+
     if CORE.is_esp8266:
         cg.add_library("ESP8266WiFi", None)
     elif CORE.is_rp2040:

esphome/components/wifi/wifi_component.cpp

@@ -489,7 +489,7 @@ void WiFiComponent::loop() {
         // Skip cooldown if new credentials were provided while connecting
         if (this->skip_cooldown_next_cycle_) {
           this->skip_cooldown_next_cycle_ = false;
-          this->check_connecting_finished();
+          this->check_connecting_finished(now);
           break;
         }
         // Use longer cooldown when captive portal/improv is active to avoid disrupting user config
@@ -500,7 +500,7 @@ void WiFiComponent::loop() {
           // a failure, or something tried to connect over and over
           // so we entered cooldown. In both cases we call
           // check_connecting_finished to continue the state machine.
-          this->check_connecting_finished();
+          this->check_connecting_finished(now);
         }
         break;
       }
@@ -511,7 +511,7 @@ void WiFiComponent::loop() {
       }
       case WIFI_COMPONENT_STATE_STA_CONNECTING: {
         this->status_set_warning(LOG_STR("associating to network"));
-        this->check_connecting_finished();
+        this->check_connecting_finished(now);
         break;
       }
 
@@ -525,6 +525,10 @@ void WiFiComponent::loop() {
         } else {
           this->status_clear_warning();
           this->last_connected_ = now;
+
+          // Post-connect roaming: check for better AP
+          this->check_roaming_(now);
+          this->process_roaming_scan_(now);
         }
         break;
       }
@@ -681,8 +685,14 @@ float WiFiComponent::get_loop_priority() const {
 
 void WiFiComponent::init_sta(size_t count) { this->sta_.init(count); }
 void WiFiComponent::add_sta(const WiFiAP &ap) { this->sta_.push_back(ap); }
+void WiFiComponent::clear_sta() {
+  // Clear roaming state - no more configured networks
+  this->clear_roaming_state_();
+  this->sta_.clear();
+  this->selected_sta_index_ = -1;
+}
 void WiFiComponent::set_sta(const WiFiAP &ap) {
-  this->clear_sta();
+  this->clear_sta();  // Also clears roaming state
   this->init_sta(1);
   this->add_sta(ap);
   this->selected_sta_index_ = 0;
@@ -1163,7 +1173,7 @@ void WiFiComponent::dump_config() {
   this->print_connect_params_();
 }
 
-void WiFiComponent::check_connecting_finished() {
+void WiFiComponent::check_connecting_finished(uint32_t now) {
   auto status = this->wifi_sta_connect_status_();
 
   if (status == WiFiSTAConnectStatus::CONNECTED) {
@@ -1209,6 +1219,9 @@ void WiFiComponent::check_connecting_finished() {
     this->state_ = WIFI_COMPONENT_STATE_STA_CONNECTED;
     this->num_retried_ = 0;
 
+    // Reset roaming timer on successful connection
+    this->roaming_last_check_ = now;
+
     // Clear priority tracking if all priorities are at minimum
     this->clear_priorities_if_all_min_();
 
@@ -1216,16 +1229,11 @@ void WiFiComponent::check_connecting_finished() {
     this->save_fast_connect_settings_();
 #endif
 
-    // Free scan results memory unless a component needs them
-    if (!this->keep_scan_results_) {
-      this->scan_result_.clear();
-      this->scan_result_.shrink_to_fit();
-    }
+    this->release_scan_results_();
 
     return;
   }
 
-  uint32_t now = millis();
   if (now - this->action_started_ > WIFI_CONNECT_TIMEOUT_MS) {
     ESP_LOGW(TAG, "Connection timeout, aborting connection attempt");
     this->wifi_disconnect_();
@@ -1632,6 +1640,11 @@ void WiFiComponent::advance_to_next_target_or_increment_retry_() {
 }
 
 void WiFiComponent::retry_connect() {
+  // Reset roaming state if this wasn't a roaming-initiated disconnect
+  if (!this->roaming_in_progress_) {
+    this->clear_roaming_state_();
+  }
+
   this->log_and_adjust_priority_for_failed_connect_();
 
   // Determine next retry phase based on current state
@@ -1874,6 +1887,113 @@ bool WiFiScanResult::get_is_hidden() const { return this->is_hidden_; }
 
 bool WiFiScanResult::operator==(const WiFiScanResult &rhs) const { return this->bssid_ == rhs.bssid_; }
 
+void WiFiComponent::clear_roaming_state_() {
+  this->roaming_attempts_ = 0;
+  this->roaming_last_check_ = 0;
+  this->roaming_scan_active_ = false;
+}
+
+void WiFiComponent::check_roaming_(uint32_t now) {
+  // Guard: feature enabled
+  if (!this->post_connect_roaming_)
+    return;
+
+  // Guard: not for hidden networks (may not appear in scan)
+  const WiFiAP *selected = this->get_selected_sta_();
+  if (selected == nullptr || selected->get_hidden())
+    return;
+
+  // Guard: attempt limit
+  if (this->roaming_attempts_ >= ROAMING_MAX_ATTEMPTS)
+    return;
+
+  // Guard: scan not already active
+  if (this->roaming_scan_active_)
+    return;
+
+  // Guard: interval check
+  if (now - this->roaming_last_check_ < ROAMING_CHECK_INTERVAL)
+    return;
+
+  this->roaming_last_check_ = now;
+  ESP_LOGD(TAG, "Roaming: scanning for better AP (current RSSI %d dBm)", this->wifi_rssi());
+  this->roaming_scan_active_ = true;
+  this->wifi_scan_start_(this->passive_scan_);
+}
+
+void WiFiComponent::process_roaming_scan_(uint32_t now) {
+  // Not our scan
+  if (!this->roaming_scan_active_)
+    return;
+
+  // Scan not done yet
+  if (!this->scan_done_)
+    return;
+
+  this->scan_done_ = false;
+  this->roaming_scan_active_ = false;
+
+  // Get current connection info
+  bssid_t current_bssid = this->wifi_bssid();
+  int8_t current_rssi = this->wifi_rssi();
+  std::string current_ssid = this->wifi_ssid();
+
+  // Find best candidate: same SSID, different BSSID
+  bssid_t best_bssid{};
+  uint8_t best_channel = 0;
+  int8_t best_rssi = WIFI_RSSI_DISCONNECTED;
+
+  for (const auto &result : this->scan_result_) {
+    // Must be same SSID as current connection
+    if (result.get_ssid() != current_ssid)
+      continue;
+
+    // Must be different BSSID
+    if (result.get_bssid() == current_bssid)
+      continue;
+
+    ESP_LOGV(TAG, "Roaming: candidate %s RSSI %d dB", result.get_ssid().c_str(), result.get_rssi());
+
+    // Track the best candidate
+    if (result.get_rssi() > best_rssi) {
+      best_rssi = result.get_rssi();
+      best_bssid = result.get_bssid();
+      best_channel = result.get_channel();
+    }
+  }
+
+  this->release_scan_results_();
+
+  // Check if best candidate meets minimum improvement threshold
+  int8_t improvement = (best_rssi == WIFI_RSSI_DISCONNECTED) ? 0 : best_rssi - current_rssi;
+  if (improvement < ROAMING_MIN_IMPROVEMENT) {
+    ESP_LOGD(TAG, "Roaming: best candidate %+d dB (need +%d dB)", improvement, ROAMING_MIN_IMPROVEMENT);
+    return;
+  }
+
+  // Found better AP - initiate roam
+  this->roaming_attempts_++;
+
+  char bssid_s[18];
+  format_mac_addr_upper(best_bssid.data(), bssid_s);
+  ESP_LOGI(TAG, "Roaming: switching to %s (%d dBm, +%d dB improvement)", bssid_s, best_rssi, best_rssi - current_rssi);
+
+  // Create roam parameters from current selected AP with target BSSID/channel
+  const WiFiAP *selected = this->get_selected_sta_();
+  if (selected == nullptr) {
+    ESP_LOGW(TAG, "Roaming: selected AP is null");
+    return;
+  }
+
+  WiFiAP roam_params = *selected;
+  roam_params.set_bssid(best_bssid);
+  roam_params.set_channel(best_channel);
+
+  // Connect directly - wifi_sta_connect_ handles disconnect internally
+  this->error_from_callback_ = false;
+  this->start_connecting(roam_params);
+}
+
 WiFiComponent *global_wifi_component;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
 
 }  // namespace esphome::wifi

esphome/components/wifi/wifi_component.h

@@ -303,10 +303,7 @@ class WiFiComponent : public Component {
   WiFiAP get_sta() const;
   void init_sta(size_t count);
   void add_sta(const WiFiAP &ap);
-  void clear_sta() {
-    this->sta_.clear();
-    this->selected_sta_index_ = -1;
-  }
+  void clear_sta();
 
 #ifdef USE_WIFI_AP
   /** Setup an Access Point that should be created if no connection to a station can be made.
@@ -330,7 +327,7 @@ class WiFiComponent : public Component {
   // Backward compatibility overload - ignores 'two' parameter
   void start_connecting(const WiFiAP &ap, bool /* two */) { this->start_connecting(ap); }
 
-  void check_connecting_finished();
+  void check_connecting_finished(uint32_t now);
 
   void retry_connect();
 
@@ -420,6 +417,7 @@ class WiFiComponent : public Component {
 
   void set_enable_on_boot(bool enable_on_boot) { this->enable_on_boot_ = enable_on_boot; }
   void set_keep_scan_results(bool keep_scan_results) { this->keep_scan_results_ = keep_scan_results; }
+  void set_post_connect_roaming(bool enabled) { this->post_connect_roaming_ = enabled; }
 
   Trigger<> *get_connect_trigger() const { return this->connect_trigger_; };
   Trigger<> *get_disconnect_trigger() const { return this->disconnect_trigger_; };
@@ -572,6 +570,19 @@ class WiFiComponent : public Component {
   void save_fast_connect_settings_();
 #endif
 
+  // Post-connect roaming methods
+  void check_roaming_(uint32_t now);
+  void process_roaming_scan_(uint32_t now);
+  void clear_roaming_state_();
+
+  /// Free scan results memory unless a component needs them
+  void release_scan_results_() {
+    if (!this->keep_scan_results_) {
+      this->scan_result_.clear();
+      this->scan_result_.shrink_to_fit();
+    }
+  }
+
 #ifdef USE_ESP8266
   static void wifi_event_callback(System_Event_t *event);
   void wifi_scan_done_callback_(void *arg, STATUS status);
@@ -614,10 +625,16 @@ class WiFiComponent : public Component {
   ESPPreferenceObject fast_connect_pref_;
 #endif
 
+  // Post-connect roaming constants
+  static constexpr uint32_t ROAMING_CHECK_INTERVAL = 90 * 1000;  // 90s for testing, 5 min for prod
+  static constexpr int8_t ROAMING_MIN_IMPROVEMENT = 10;          // dB
+  static constexpr uint8_t ROAMING_MAX_ATTEMPTS = 3;
+
   // Group all 32-bit integers together
   uint32_t action_started_;
   uint32_t last_connected_{0};
   uint32_t reboot_timeout_{};
+  uint32_t roaming_last_check_{0};
 #ifdef USE_WIFI_AP
   uint32_t ap_timeout_{};
 #endif
@@ -632,6 +649,7 @@ class WiFiComponent : public Component {
   // Used to access password, manual_ip, priority, EAP settings, and hidden flag
   // int8_t limits to 127 APs (enforced in __init__.py via MAX_WIFI_NETWORKS)
   int8_t selected_sta_index_{-1};
+  uint8_t roaming_attempts_{0};
 
 #if USE_NETWORK_IPV6
   uint8_t num_ipv6_addresses_{0};
@@ -655,6 +673,8 @@ class WiFiComponent : public Component {
   bool keep_scan_results_{false};
   bool did_scan_this_cycle_{false};
   bool skip_cooldown_next_cycle_{false};
+  bool post_connect_roaming_{true};  // Enabled by default
+  bool roaming_scan_active_{false};
 #if defined(USE_ESP32) && defined(USE_WIFI_RUNTIME_POWER_SAVE)
   WiFiPowerSaveMode configured_power_save_{WIFI_POWER_SAVE_NONE};
   bool is_high_performance_mode_{false};

tests/components/wifi/test.esp32-idf.yaml

@@ -14,6 +14,7 @@ esphome:
 wifi:
   use_psram: true
   min_auth_mode: WPA
+  post_connect_roaming: false
   manual_ip:
     static_ip: 192.168.1.100
     gateway: 192.168.1.1

tests/components/wifi/test.esp8266-ard.yaml

@@ -1,5 +1,6 @@
 wifi:
   min_auth_mode: WPA2
+  post_connect_roaming: true
 
 packages:
   - !include common.yaml