wifi_component_libretiny.cpp

Go to the documentation of this file.

#include "wifi_component.h"
 
#ifdef USE_WIFI
#ifdef USE_LIBRETINY
 
#include <cinttypes>
#include <utility>
#include <algorithm>
#include "lwip/ip_addr.h"
#include "lwip/err.h"
#include "lwip/dns.h"
 
#ifdef USE_BK72XX
extern "C" {
// BDK 3.0.78 (required for BK7238) redeclares wifi_event_sta_disconnected_t,
// which LibreTiny's Arduino WiFi API already defines. ESPHome doesn't use the
// BDK version, so rename it across this include to avoid the collision.
#define wifi_event_sta_disconnected_t bdk_wifi_event_sta_disconnected_t
#include <wlan_ui_pub.h>
#undef wifi_event_sta_disconnected_t
}
#endif
 
#ifdef USE_RTL87XX
extern "C" {
#include <wifi_conf.h>
#include <wifi_structures.h>
}
#endif
 
#ifdef USE_LN882X
#include <WiFiPrivate.h>
#undef DATA  // clashes with setup_priority::DATA
// LibreTiny 1.13's LN882H reconnect() gives the SDK a NULL bssid; pass on the requested one. Remove once it passes
// info.bssid. Safe without a BSSID: begin() frees sta.bssid (resetNetworkInfo), so it stays NULL.
// NOLINTBEGIN(bugprone-reserved-identifier,cert-dcl37-c,cert-dcl51-cpp,readability-identifier-naming)
// Names are mandated by the --wrap linker mechanism.
extern "C" int __real_wifi_sta_connect(wifi_sta_connect_t *connect, wifi_scan_cfg_t *scan_cfg);
extern "C" int __wrap_wifi_sta_connect(wifi_sta_connect_t *connect, wifi_scan_cfg_t *scan_cfg) {
  if (connect->bssid == nullptr)
    connect->bssid = static_cast<WiFiData *>(WiFi.data)->sta.bssid;
  return __real_wifi_sta_connect(connect, scan_cfg);
}
// NOLINTEND(bugprone-reserved-identifier,cert-dcl37-c,cert-dcl51-cpp,readability-identifier-naming)
#endif
 
#include "esphome/core/application.h"
#include "esphome/core/hal.h"
#include "esphome/core/helpers.h"
#include "esphome/core/log.h"
#include "esphome/core/util.h"
 
namespace esphome::wifi {
 
ESPHOME_LOG_TAG(TAG, "wifi_lt");
 
// Thread-safe event handling for LibreTiny WiFi
//
// LibreTiny's WiFi.onEvent() callback runs in the WiFi driver's thread context,
// not the main ESPHome loop. Without synchronization, modifying shared state
// (like connection status flags) from the callback causes race conditions:
// - The main loop may never see state changes (values cached in registers)
// - State changes may be visible in inconsistent order
//
// Solution: Queue events in the callback and process them in the main loop.
// This is the same approach used by ESP32 IDF's wifi_process_event_().
// All state modifications happen in the main loop context, eliminating races.
//
// On platforms with hardware atomics (RTL87xx, LN882x): LockFreeQueue (SPSC ring buffer)
// On platforms without (BK72xx): FreeRTOSQueue (xQueue wrapper with critical sections)
 
// Event structure for queued WiFi events - contains a copy of event data
// to avoid lifetime issues with the original event data from the callback
struct LTWiFiEvent {
  arduino_event_id_t event_id;
  union {
    struct {
      uint8_t ssid[33];
      uint8_t ssid_len;
      uint8_t bssid[6];
      uint8_t channel;
      uint8_t authmode;
    } sta_connected;
    struct {
      uint8_t ssid[33];
      uint8_t ssid_len;
      uint8_t bssid[6];
      uint8_t reason;
    } sta_disconnected;
    struct {
      uint8_t old_mode;
      uint8_t new_mode;
    } sta_authmode_change;
    struct {
      uint32_t status;
      uint8_t number;
      uint8_t scan_id;
    } scan_done;
    struct {
      uint8_t mac[MAC_ADDRESS_SIZE];
      int rssi;
    } ap_probe_req;
  } data;
};
 
// Connection state machine - only modified from main loop after queue processing
enum class LTWiFiSTAState : uint8_t {
  IDLE,             // Not connecting
  CONNECTING,       // Connection in progress
  CONNECTED,        // Successfully connected with IP
  ERROR_NOT_FOUND,  // AP not found (probe failed)
  ERROR_FAILED,     // Connection failed (auth, timeout, etc.)
};
 
// Count of ignored disconnect events during connection - too many indicates real failure
static uint8_t s_ignored_disconnect_count = 0;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
// Threshold for ignored disconnect events before treating as connection failure
// LibreTiny sends spurious "Association Leave" events, but more than this many
// indicates the connection is failing repeatedly. Value of 3 balances fast failure
// detection with tolerance for occasional spurious events on successful connections.
static constexpr uint8_t IGNORED_DISCONNECT_THRESHOLD = 3;
 
bool WiFiComponent::wifi_mode_(optional<bool> sta, optional<bool> ap) {
  uint8_t current_mode = WiFi.getMode();
  bool current_sta = current_mode & 0b01;
  bool current_ap = current_mode & 0b10;
  bool enable_sta = sta.value_or(current_sta);
  bool enable_ap = ap.value_or(current_ap);
  if (current_sta == enable_sta && current_ap == enable_ap)
    return true;
 
  if (enable_sta && !current_sta) {
    ESP_LOGV(TAG, "Enabling STA");
    // Fresh STA stack: skip the pre-attempt teardown again.
    this->lt_first_connect_attempt_ = true;
  } else if (!enable_sta && current_sta) {
    ESP_LOGV(TAG, "Disabling STA");
  }
  if (enable_ap && !current_ap) {
    ESP_LOGV(TAG, "Enabling AP");
  } else if (!enable_ap && current_ap) {
    ESP_LOGV(TAG, "Disabling AP");
  }
 
  uint8_t mode = 0;
  if (enable_sta)
    mode |= 0b01;
  if (enable_ap)
    mode |= 0b10;
  bool ret = WiFi.mode(static_cast<wifi_mode_t>(mode));
 
  if (!ret) {
    ESP_LOGW(TAG, "Setting mode failed");
    return false;
  }
 
  this->ap_started_ = enable_ap;
 
  return ret;
}
bool WiFiComponent::wifi_apply_output_power_(float output_power) {
  int8_t val = static_cast<int8_t>(output_power * 4);
  return WiFi.setTxPower(val);
}
bool WiFiComponent::wifi_sta_pre_setup_() {
  if (!this->wifi_mode_(true, {}))
    return false;
 
  WiFi.setAutoReconnect(false);
  delay(10);
  return true;
}
bool WiFiComponent::wifi_apply_power_save_() {
  bool success = WiFi.setSleep(this->power_save_ != WIFI_POWER_SAVE_NONE);
#ifdef USE_WIFI_POWER_SAVE_LISTENERS
  if (success) {
    for (auto *listener : this->power_save_listeners_) {
      listener->on_wifi_power_save(this->power_save_);
    }
  }
#endif
  return success;
}
bool WiFiComponent::wifi_sta_ip_config_(const optional<ManualIP> &manual_ip) {
  // enable STA
  if (!this->wifi_mode_(true, {}))
    return false;
 
  if (!manual_ip.has_value()) {
    return true;
  }
 
  WiFi.config(manual_ip->static_ip, manual_ip->gateway, manual_ip->subnet, manual_ip->dns1, manual_ip->dns2);
 
  return true;
}
 
network::IPAddresses WiFiComponent::wifi_sta_ip_addresses() {
  if (!this->has_sta())
    return {};
  network::IPAddresses addresses;
  addresses[0] = WiFi.localIP();
#if USE_NETWORK_IPV6
  int i = 1;
  auto v6_addresses = WiFi.allLocalIPv6();
  for (auto address : v6_addresses) {
    addresses[i++] = network::IPAddress(address.toString().c_str());
  }
#endif /* USE_NETWORK_IPV6 */
  return addresses;
}
 
bool WiFiComponent::wifi_apply_hostname_() {
  // setting is done in SYSTEM_EVENT_STA_START callback too
  WiFi.setHostname(App.get_name().c_str());
  return true;
}
bool WiFiComponent::wifi_sta_connect_(const WiFiAP &ap) {
  // enable STA
  if (!this->wifi_mode_(true, {}))
    return false;
 
  // Tear down any live session so begin() re-fires its events; skipped on the
  // first attempt after STA-up (nothing to tear down, and BK7231N on the older
  // Beken SDK did not come back from it). The flag is per-attempt and armed
  // only for a live session: an idle disconnect may emit no event, and a stale
  // flag would swallow this attempt's first real failure.
  this->lt_teardown_event_pending_ = false;
  if (!this->lt_first_connect_attempt_) {
    const bool was_live = WiFi.status() == WL_CONNECTED;
    if (WiFi.disconnect()) {
      this->lt_teardown_event_pending_ = was_live;
    } else {
      ESP_LOGD(TAG, "Pre-connect teardown returned false");
    }
  }
  this->lt_first_connect_attempt_ = false;
 
#ifdef USE_WIFI_MANUAL_IP
  if (!this->wifi_sta_ip_config_(ap.get_manual_ip())) {
    return false;
  }
#else
  if (!this->wifi_sta_ip_config_({})) {
    return false;
  }
#endif
 
  this->wifi_apply_hostname_();
 
  // Reset state machine and disconnect counter before connecting
  this->sta_state_ = static_cast<uint8_t>(LTWiFiSTAState::CONNECTING);
  s_ignored_disconnect_count = 0;
 
  WiFiStatus status;
  {
    // The driver blocks until the join has started, or finished on Realtek
    UnavoidableBlockingScope scope;
    status = WiFi.begin(ap.ssid_.c_str(), ap.password_.empty() ? NULL : ap.password_.c_str(),
                        ap.get_channel(),  // 0 = auto
                        ap.has_bssid() ? ap.get_bssid().data() : NULL);
  }
  if (status != WL_CONNECTED) {
    ESP_LOGW(TAG, "WiFi.begin failed: %d", status);
    // Without this reset the state machine stays at CONNECTING and each retry
    // stalls for the full connect timeout (46 s).
    this->sta_state_ = static_cast<uint8_t>(LTWiFiSTAState::ERROR_FAILED);
    return false;
  }
 
  return true;
}
const char *get_auth_mode_str(uint8_t mode) {
  switch (mode) {
    case WIFI_AUTH_OPEN:
      return "OPEN";
    case WIFI_AUTH_WEP:
      return "WEP";
    case WIFI_AUTH_WPA_PSK:
      return "WPA PSK";
    case WIFI_AUTH_WPA2_PSK:
      return "WPA2 PSK";
    case WIFI_AUTH_WPA_WPA2_PSK:
      return "WPA/WPA2 PSK";
    default:
      return "UNKNOWN";
  }
}
 
const char *get_op_mode_str(uint8_t mode) {
  switch (mode) {
    case WIFI_OFF:
      return "OFF";
    case WIFI_STA:
      return "STA";
    case WIFI_AP:
      return "AP";
    case WIFI_AP_STA:
      return "AP+STA";
    default:
      return "UNKNOWN";
  }
}
const char *get_disconnect_reason_str(uint8_t reason) {
  switch (reason) {
    case WIFI_REASON_AUTH_EXPIRE:
      return "Auth Expired";
    case WIFI_REASON_AUTH_LEAVE:
      return "Auth Leave";
    case WIFI_REASON_ASSOC_EXPIRE:
      return "Association Expired";
    case WIFI_REASON_ASSOC_TOOMANY:
      return "Too Many Associations";
    case WIFI_REASON_NOT_AUTHED:
      return "Not Authenticated";
    case WIFI_REASON_NOT_ASSOCED:
      return "Not Associated";
    case WIFI_REASON_ASSOC_LEAVE:
      return "Association Leave";
    case WIFI_REASON_ASSOC_NOT_AUTHED:
      return "Association not Authenticated";
    case WIFI_REASON_DISASSOC_PWRCAP_BAD:
      return "Disassociate Power Cap Bad";
    case WIFI_REASON_DISASSOC_SUPCHAN_BAD:
      return "Disassociate Supported Channel Bad";
    case WIFI_REASON_IE_INVALID:
      return "IE Invalid";
    case WIFI_REASON_MIC_FAILURE:
      return "Mic Failure";
    case WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT:
      return "4-Way Handshake Timeout";
    case WIFI_REASON_GROUP_KEY_UPDATE_TIMEOUT:
      return "Group Key Update Timeout";
    case WIFI_REASON_IE_IN_4WAY_DIFFERS:
      return "IE In 4-Way Handshake Differs";
    case WIFI_REASON_GROUP_CIPHER_INVALID:
      return "Group Cipher Invalid";
    case WIFI_REASON_PAIRWISE_CIPHER_INVALID:
      return "Pairwise Cipher Invalid";
    case WIFI_REASON_AKMP_INVALID:
      return "AKMP Invalid";
    case WIFI_REASON_UNSUPP_RSN_IE_VERSION:
      return "Unsupported RSN IE version";
    case WIFI_REASON_INVALID_RSN_IE_CAP:
      return "Invalid RSN IE Cap";
    case WIFI_REASON_802_1X_AUTH_FAILED:
      return "802.1x Authentication Failed";
    case WIFI_REASON_CIPHER_SUITE_REJECTED:
      return "Cipher Suite Rejected";
    case WIFI_REASON_BEACON_TIMEOUT:
      return "Beacon Timeout";
    case WIFI_REASON_NO_AP_FOUND:
      return "AP Not Found";
    case WIFI_REASON_AUTH_FAIL:
      return "Authentication Failed";
    case WIFI_REASON_ASSOC_FAIL:
      return "Association Failed";
    case WIFI_REASON_HANDSHAKE_TIMEOUT:
      return "Handshake Failed";
    case WIFI_REASON_CONNECTION_FAIL:
      return "Connection Failed";
    case WIFI_REASON_UNSPECIFIED:
    default:
      return "Unspecified";
  }
}
 
#define ESPHOME_EVENT_ID_WIFI_READY ARDUINO_EVENT_WIFI_READY
#define ESPHOME_EVENT_ID_WIFI_SCAN_DONE ARDUINO_EVENT_WIFI_SCAN_DONE
#define ESPHOME_EVENT_ID_WIFI_STA_START ARDUINO_EVENT_WIFI_STA_START
#define ESPHOME_EVENT_ID_WIFI_STA_STOP ARDUINO_EVENT_WIFI_STA_STOP
#define ESPHOME_EVENT_ID_WIFI_STA_CONNECTED ARDUINO_EVENT_WIFI_STA_CONNECTED
#define ESPHOME_EVENT_ID_WIFI_STA_DISCONNECTED ARDUINO_EVENT_WIFI_STA_DISCONNECTED
#define ESPHOME_EVENT_ID_WIFI_STA_AUTHMODE_CHANGE ARDUINO_EVENT_WIFI_STA_AUTHMODE_CHANGE
#define ESPHOME_EVENT_ID_WIFI_STA_GOT_IP ARDUINO_EVENT_WIFI_STA_GOT_IP
#define ESPHOME_EVENT_ID_WIFI_STA_GOT_IP6 ARDUINO_EVENT_WIFI_STA_GOT_IP6
#define ESPHOME_EVENT_ID_WIFI_STA_LOST_IP ARDUINO_EVENT_WIFI_STA_LOST_IP
#define ESPHOME_EVENT_ID_WIFI_AP_START ARDUINO_EVENT_WIFI_AP_START
#define ESPHOME_EVENT_ID_WIFI_AP_STOP ARDUINO_EVENT_WIFI_AP_STOP
#define ESPHOME_EVENT_ID_WIFI_AP_STACONNECTED ARDUINO_EVENT_WIFI_AP_STACONNECTED
#define ESPHOME_EVENT_ID_WIFI_AP_STADISCONNECTED ARDUINO_EVENT_WIFI_AP_STADISCONNECTED
#define ESPHOME_EVENT_ID_WIFI_AP_STAIPASSIGNED ARDUINO_EVENT_WIFI_AP_STAIPASSIGNED
#define ESPHOME_EVENT_ID_WIFI_AP_PROBEREQRECVED ARDUINO_EVENT_WIFI_AP_PROBEREQRECVED
#define ESPHOME_EVENT_ID_WIFI_AP_GOT_IP6 ARDUINO_EVENT_WIFI_AP_GOT_IP6
using esphome_wifi_event_id_t = arduino_event_id_t;
using esphome_wifi_event_info_t = arduino_event_info_t;
 
// Event callback - runs in WiFi driver thread context
// Only queues events for processing in main loop, no logging or state changes here
void WiFiComponent::wifi_event_callback_(esphome_wifi_event_id_t event, esphome_wifi_event_info_t info) {
  // Allocate on heap and fill directly to avoid extra memcpy
  auto *to_send = new LTWiFiEvent{};  // NOLINT(cppcoreguidelines-owning-memory)
  to_send->event_id = event;
 
  // Copy event-specific data
  switch (event) {
    case ESPHOME_EVENT_ID_WIFI_STA_CONNECTED: {
      auto &it = info.wifi_sta_connected;
      to_send->data.sta_connected.ssid_len = it.ssid_len;
      memcpy(to_send->data.sta_connected.ssid, it.ssid,
             std::min(static_cast<size_t>(it.ssid_len), sizeof(to_send->data.sta_connected.ssid) - 1));
      memcpy(to_send->data.sta_connected.bssid, it.bssid, 6);
      to_send->data.sta_connected.channel = it.channel;
      to_send->data.sta_connected.authmode = it.authmode;
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_STA_DISCONNECTED: {
      auto &it = info.wifi_sta_disconnected;
      to_send->data.sta_disconnected.ssid_len = it.ssid_len;
      memcpy(to_send->data.sta_disconnected.ssid, it.ssid,
             std::min(static_cast<size_t>(it.ssid_len), sizeof(to_send->data.sta_disconnected.ssid) - 1));
      memcpy(to_send->data.sta_disconnected.bssid, it.bssid, 6);
      to_send->data.sta_disconnected.reason = it.reason;
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_STA_AUTHMODE_CHANGE: {
      auto &it = info.wifi_sta_authmode_change;
      to_send->data.sta_authmode_change.old_mode = it.old_mode;
      to_send->data.sta_authmode_change.new_mode = it.new_mode;
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_SCAN_DONE: {
      auto &it = info.wifi_scan_done;
      to_send->data.scan_done.status = it.status;
      to_send->data.scan_done.number = it.number;
      to_send->data.scan_done.scan_id = it.scan_id;
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_AP_PROBEREQRECVED: {
      auto &it = info.wifi_ap_probereqrecved;
      memcpy(to_send->data.ap_probe_req.mac, it.mac, MAC_ADDRESS_SIZE);
      to_send->data.ap_probe_req.rssi = it.rssi;
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_AP_STACONNECTED: {
      auto &it = info.wifi_sta_connected;
      memcpy(to_send->data.sta_connected.bssid, it.bssid, 6);
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_AP_STADISCONNECTED: {
      auto &it = info.wifi_sta_disconnected;
      memcpy(to_send->data.sta_disconnected.bssid, it.bssid, 6);
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_READY:
    case ESPHOME_EVENT_ID_WIFI_STA_START:
    case ESPHOME_EVENT_ID_WIFI_STA_STOP:
    case ESPHOME_EVENT_ID_WIFI_STA_GOT_IP:
    case ESPHOME_EVENT_ID_WIFI_STA_GOT_IP6:
    case ESPHOME_EVENT_ID_WIFI_STA_LOST_IP:
    case ESPHOME_EVENT_ID_WIFI_AP_START:
    case ESPHOME_EVENT_ID_WIFI_AP_STOP:
    case ESPHOME_EVENT_ID_WIFI_AP_STAIPASSIGNED:
      // No additional data needed
      break;
    default:
      // Unknown event, don't queue
      delete to_send;  // NOLINT(cppcoreguidelines-owning-memory)
      return;
  }
 
  // Queue event (don't block if queue is full)
  if (!this->event_queue_.push(to_send)) {
    delete to_send;  // NOLINT(cppcoreguidelines-owning-memory)
  }
}
 
// Process a single event from the queue - runs in main loop context.
// Listener notifications must be deferred until after the state machine transitions
// (in check_connecting_finished) so that conditions like wifi.connected return
// correct values in automations.
void WiFiComponent::wifi_process_event_(LTWiFiEvent *event) {
  switch (event->event_id) {
    case ESPHOME_EVENT_ID_WIFI_READY: {
      ESP_LOGV(TAG, "Ready");
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_SCAN_DONE: {
      auto &it = event->data.scan_done;
      ESP_LOGV(TAG, "Scan done: status=%" PRIu32 " number=%u scan_id=%u", it.status, it.number, it.scan_id);
      this->wifi_scan_done_callback_();
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_STA_START: {
      ESP_LOGV(TAG, "STA start");
      WiFi.setHostname(App.get_name().c_str());
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_STA_STOP: {
      ESP_LOGV(TAG, "STA stop");
      this->sta_state_ = static_cast<uint8_t>(LTWiFiSTAState::IDLE);
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_STA_CONNECTED: {
      // Processed in queue order, so a teardown event still ahead of this
      // CONNECTED was already consumed; a leftover flag is stale.
      this->lt_teardown_event_pending_ = false;
      auto &it = event->data.sta_connected;
      char bssid_buf[MAC_ADDRESS_PRETTY_BUFFER_SIZE];
      format_mac_addr_upper(it.bssid, bssid_buf);
      ESP_LOGV(TAG, "Connected ssid='%.*s' bssid=" LOG_SECRET("%s") " channel=%u, authmode=%s", it.ssid_len,
               (const char *) it.ssid, bssid_buf, it.channel, get_auth_mode_str(it.authmode));
      // Note: We don't set CONNECTED state here yet - wait for GOT_IP
      // This matches ESP32 IDF behavior where s_sta_connected is set but
      // wifi_sta_connect_status_() also checks got_ipv4_address_
#ifdef USE_WIFI_CONNECT_STATE_LISTENERS
      // Defer listener notification until state machine reaches STA_CONNECTED
      // This ensures wifi.connected condition returns true in listener automations
      this->pending_.connect_state = true;
#endif
      // For static IP configurations, GOT_IP event may not fire, so set connected state here
#ifdef USE_WIFI_MANUAL_IP
      if (const WiFiAP *config = this->get_selected_sta_(); config && config->get_manual_ip().has_value()) {
        this->sta_state_ = static_cast<uint8_t>(LTWiFiSTAState::CONNECTED);
#ifdef USE_WIFI_IP_STATE_LISTENERS
        this->notify_ip_state_listeners_();
#endif
      }
#endif
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_STA_DISCONNECTED: {
      auto &it = event->data.sta_disconnected;
 
      // Consume the disconnect our own teardown queued, without spending an
      // ignore slot. Ungated on SSID and state: the flag is armed only for this
      // attempt's teardown of a live session.
      if (this->lt_teardown_event_pending_ && it.reason != WIFI_REASON_NO_AP_FOUND) {
        this->lt_teardown_event_pending_ = false;
        break;
      }
 
      // LibreTiny can send spurious disconnect events with empty ssid/bssid during connection.
      // These are typically "Association Leave" events that don't indicate actual failures:
      //   [W][wifi_lt]: Disconnected ssid='' bssid=00:00:00:00:00:00 reason='Association Leave'
      //   [W][wifi_lt]: Disconnected ssid='' bssid=00:00:00:00:00:00 reason='Association Leave'
      //   [V][wifi_lt]: Connected ssid='WIFI' bssid=... channel=3, authmode=WPA2 PSK
      // Without this check, the spurious events would transition state to ERROR_FAILED,
      // causing wifi_sta_connect_status_() to return an error. The main loop would then
      // call retry_connect(), aborting a connection that may succeed moments later.
      // Only ignore benign reasons - real failures like NO_AP_FOUND should still be processed.
      // However, if we get too many of these events (IGNORED_DISCONNECT_THRESHOLD), treat it
      // as a real connection failure to avoid waiting the full timeout for a failing connection.
      if (it.ssid_len == 0 && this->sta_state_ == static_cast<uint8_t>(LTWiFiSTAState::CONNECTING) &&
          it.reason != WIFI_REASON_NO_AP_FOUND) {
        s_ignored_disconnect_count++;
        if (s_ignored_disconnect_count >= IGNORED_DISCONNECT_THRESHOLD) {
          ESP_LOGW(TAG, "Too many disconnect events (%u) while connecting, treating as failure (reason=%s)",
                   s_ignored_disconnect_count, get_disconnect_reason_str(it.reason));
          this->sta_state_ = static_cast<uint8_t>(LTWiFiSTAState::ERROR_FAILED);
          WiFi.disconnect();
          this->error_from_callback_ = true;
          // Don't break - fall through to notify listeners
        } else {
          ESP_LOGV(TAG, "Ignoring disconnect event with empty ssid while connecting (reason=%s, count=%u)",
                   get_disconnect_reason_str(it.reason), s_ignored_disconnect_count);
          break;
        }
      }
 
      if (it.reason == WIFI_REASON_NO_AP_FOUND) {
        ESP_LOGW(TAG, "Disconnected ssid='%.*s' reason='Probe Request Unsuccessful'", it.ssid_len,
                 (const char *) it.ssid);
        this->sta_state_ = static_cast<uint8_t>(LTWiFiSTAState::ERROR_NOT_FOUND);
      } else {
        char bssid_s[MAC_ADDRESS_PRETTY_BUFFER_SIZE];
        format_mac_addr_upper(it.bssid, bssid_s);
        ESP_LOGW(TAG, "Disconnected ssid='%.*s' bssid=" LOG_SECRET("%s") " reason='%s'", it.ssid_len,
                 (const char *) it.ssid, bssid_s, get_disconnect_reason_str(it.reason));
        this->sta_state_ = static_cast<uint8_t>(LTWiFiSTAState::ERROR_FAILED);
      }
 
      uint8_t reason = it.reason;
      if (reason == WIFI_REASON_AUTH_EXPIRE || reason == WIFI_REASON_BEACON_TIMEOUT ||
          reason == WIFI_REASON_NO_AP_FOUND || reason == WIFI_REASON_ASSOC_FAIL ||
          reason == WIFI_REASON_HANDSHAKE_TIMEOUT) {
        WiFi.disconnect();
        this->error_from_callback_ = true;
      }
 
      // Refresh is_connected() cache; sta_state_/error_from_callback_ make it false.
      this->update_connected_state_();
#ifdef USE_WIFI_CONNECT_STATE_LISTENERS
      this->notify_disconnect_state_listeners_();
#endif
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_STA_AUTHMODE_CHANGE: {
      auto &it = event->data.sta_authmode_change;
      ESP_LOGV(TAG, "Authmode Change old=%s new=%s", get_auth_mode_str(it.old_mode), get_auth_mode_str(it.new_mode));
      // Mitigate CVE-2020-12638
      // https://lbsfilm.at/blog/wpa2-authenticationmode-downgrade-in-espressif-microprocessors
      if (it.old_mode != WIFI_AUTH_OPEN && it.new_mode == WIFI_AUTH_OPEN) {
        ESP_LOGW(TAG, "Potential Authmode downgrade detected, disconnecting");
        WiFi.disconnect();
        this->error_from_callback_ = true;
        this->sta_state_ = static_cast<uint8_t>(LTWiFiSTAState::ERROR_FAILED);
      }
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_STA_GOT_IP: {
      char ip_buf[network::IP_ADDRESS_BUFFER_SIZE], gw_buf[network::IP_ADDRESS_BUFFER_SIZE];
      ESP_LOGV(TAG, "static_ip=%s gateway=%s", network::IPAddress(WiFi.localIP()).str_to(ip_buf),
               network::IPAddress(WiFi.gatewayIP()).str_to(gw_buf));
      this->sta_state_ = static_cast<uint8_t>(LTWiFiSTAState::CONNECTED);
#ifdef USE_WIFI_IP_STATE_LISTENERS
      this->notify_ip_state_listeners_();
#endif
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_STA_GOT_IP6: {
      ESP_LOGV(TAG, "Got IPv6");
#ifdef USE_WIFI_IP_STATE_LISTENERS
      this->notify_ip_state_listeners_();
#endif
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_STA_LOST_IP: {
      ESP_LOGV(TAG, "Lost IP");
      // Don't change state to IDLE - let the disconnect event handle that
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_AP_START: {
      ESP_LOGV(TAG, "AP start");
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_AP_STOP: {
      ESP_LOGV(TAG, "AP stop");
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_AP_STACONNECTED: {
#ifdef USE_WIFI_AP
      this->ap_clients_++;
#endif
#if ESPHOME_LOG_LEVEL >= ESPHOME_LOG_LEVEL_VERBOSE
      auto &it = event->data.sta_connected;
      char mac_buf[MAC_ADDRESS_PRETTY_BUFFER_SIZE];
      format_mac_addr_upper(it.bssid, mac_buf);
      ESP_LOGV(TAG, "AP client connected MAC=%s", mac_buf);
#endif
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_AP_STADISCONNECTED: {
#ifdef USE_WIFI_AP
      if (this->ap_clients_ > 0)
        this->ap_clients_--;
#endif
#if ESPHOME_LOG_LEVEL >= ESPHOME_LOG_LEVEL_VERBOSE
      auto &it = event->data.sta_disconnected;
      char mac_buf[MAC_ADDRESS_PRETTY_BUFFER_SIZE];
      format_mac_addr_upper(it.bssid, mac_buf);
      ESP_LOGV(TAG, "AP client disconnected MAC=%s", mac_buf);
#endif
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_AP_STAIPASSIGNED: {
      ESP_LOGV(TAG, "AP client assigned IP");
      break;
    }
    case ESPHOME_EVENT_ID_WIFI_AP_PROBEREQRECVED: {
#if ESPHOME_LOG_LEVEL >= ESPHOME_LOG_LEVEL_VERY_VERBOSE
      auto &it = event->data.ap_probe_req;
      char mac_buf[MAC_ADDRESS_PRETTY_BUFFER_SIZE];
      format_mac_addr_upper(it.mac, mac_buf);
      ESP_LOGVV(TAG, "AP receive Probe Request MAC=%s RSSI=%d", mac_buf, it.rssi);
#endif
      break;
    }
    default:
      break;
  }
}
void WiFiComponent::wifi_pre_setup_() {
  WiFi.onEvent(
      [this](arduino_event_id_t event, arduino_event_info_t info) { this->wifi_event_callback_(event, info); });
  // Make sure WiFi is in clean state before anything starts
  this->wifi_mode_(false, false);
}
WiFiSTAConnectStatus WiFiComponent::wifi_sta_connect_status_() const {
  // Use state machine instead of querying WiFi.status() directly
  // State is updated in main loop from queued events, ensuring thread safety
  switch (static_cast<LTWiFiSTAState>(this->sta_state_)) {
    case LTWiFiSTAState::CONNECTED:
      return WiFiSTAConnectStatus::CONNECTED;
    case LTWiFiSTAState::ERROR_NOT_FOUND:
      return WiFiSTAConnectStatus::ERROR_NETWORK_NOT_FOUND;
    case LTWiFiSTAState::ERROR_FAILED:
      return WiFiSTAConnectStatus::ERROR_CONNECT_FAILED;
    case LTWiFiSTAState::CONNECTING:
      return WiFiSTAConnectStatus::CONNECTING;
    case LTWiFiSTAState::IDLE:
    default:
      return WiFiSTAConnectStatus::IDLE;
  }
}
bool WiFiComponent::wifi_scan_start_(bool passive) {
  // enable STA
  if (!this->wifi_mode_(true, {}))
    return false;
 
  // Reset scan_done_ before starting new scan to prevent stale flag from previous scan
  // (e.g., roaming scan completed just before unexpected disconnect)
  this->scan_done_ = false;
 
  // need to use WiFi because of WiFiScanClass allocations :(
  int16_t err = WiFi.scanNetworks(true, true, passive, 200);
  if (err != WIFI_SCAN_RUNNING) {
    ESP_LOGV(TAG, "WiFi.scanNetworks failed: %d", err);
    return false;
  }
 
  return true;
}
void WiFiComponent::wifi_scan_done_callback_() {
  int16_t num = WiFi.scanComplete();
  bool needs_full = this->needs_full_scan_results_();
  {
    // Mutate in place under the lock; blocking a portal request is fine and
    // avoids scratch buffers
    ScanResultsLock lock(this);
    this->scan_result_.clear();
    this->scan_done_ = true;
 
    if (num < 0)
      return;
 
    // Access scan results directly via WiFi.scan struct to avoid Arduino String allocations
    // WiFi.scan is public in LibreTiny for WiFiEvents & WiFiScan static handlers
    auto *scan = WiFi.scan;
 
    // First pass: count matching networks
    size_t count = 0;
    for (int i = 0; i < num; i++) {
      const char *ssid_cstr = scan->ap[i].ssid;
      if (needs_full || this->matches_configured_network_(ssid_cstr, scan->ap[i].bssid.addr)) {
        count++;
      }
    }
 
    if (!this->scan_result_.try_init(count)) {
      ESP_LOGW(TAG, "No memory for %zu scan results", count);
      WiFi.scanDelete();
      return;
    }
 
    // Second pass: store matching networks
    for (int i = 0; i < num; i++) {
      const char *ssid_cstr = scan->ap[i].ssid;
      auto &ap = scan->ap[i];
      if (needs_full || this->matches_configured_network_(ssid_cstr, ap.bssid.addr)) {
        this->scan_result_.emplace_back(bssid_t{ap.bssid.addr[0], ap.bssid.addr[1], ap.bssid.addr[2], ap.bssid.addr[3],
                                                ap.bssid.addr[4], ap.bssid.addr[5]},
                                        ssid_cstr, strlen(ssid_cstr), ap.channel, ap.rssi, ap.auth != WIFI_AUTH_OPEN,
                                        ssid_cstr[0] == '\0');
      } else {
        this->log_discarded_scan_result_(ssid_cstr, ap.bssid.addr, ap.rssi, ap.channel);
      }
    }
  }
 
  ESP_LOGV(TAG, "Scan complete: %d found, %zu stored%s", num, this->scan_result_.size(),
           needs_full ? "" : " (filtered)");
  WiFi.scanDelete();
#ifdef USE_WIFI_SCAN_RESULTS_LISTENERS
  this->notify_scan_results_listeners_();
#endif
}
 
#ifdef USE_WIFI_AP
bool WiFiComponent::wifi_ap_ip_config_(const optional<ManualIP> &manual_ip) {
  // enable AP
  if (!this->wifi_mode_({}, true))
    return false;
 
  if (manual_ip.has_value()) {
    return WiFi.softAPConfig(manual_ip->static_ip, manual_ip->gateway, manual_ip->subnet);
  } else {
    return WiFi.softAPConfig(IPAddress(192, 168, 4, 1), IPAddress(192, 168, 4, 1), IPAddress(255, 255, 255, 0));
  }
}
 
bool WiFiComponent::wifi_start_ap_(const WiFiAP &ap) {
  // enable AP
  if (!this->wifi_mode_({}, true))
    return false;
 
#ifdef USE_WIFI_MANUAL_IP
  if (!this->wifi_ap_ip_config_(ap.get_manual_ip())) {
    ESP_LOGV(TAG, "wifi_ap_ip_config_ failed");
    return false;
  }
#else
  if (!this->wifi_ap_ip_config_({})) {
    ESP_LOGV(TAG, "wifi_ap_ip_config_ failed");
    return false;
  }
#endif
 
  yield();
 
#ifdef USE_LN882X
  // LibreTiny's LN882H softAP() points ap.bssid at a static array and frees it
  // on the next call, tripping FreeRTOS's configASSERT until the watchdog
  // resets the chip. Clear it so that a second AP start frees nothing.
  static_cast<WiFiData *>(WiFi.data)->ap.bssid = nullptr;
#endif
 
  return WiFi.softAP(ap.ssid_.c_str(), ap.password_.empty() ? NULL : ap.password_.c_str(),
                     ap.has_channel() ? ap.get_channel() : 1, ap.get_hidden());
}
 
network::IPAddress WiFiComponent::wifi_soft_ap_ip() { return {WiFi.softAPIP()}; }
#endif  // USE_WIFI_AP
 
#ifdef USE_LN882X
void WiFiComponent::on_powerdown() {
  // Leave the AP so it no longer holds the association when we come back.
  if (WiFi.status() != WL_CONNECTED)  // associated, even before DHCP has finished
    return;
  ESP_LOGD(TAG, "Disconnecting before powerdown");
  wifi_sta_disconnect();  // not WiFi.disconnect(): it frees the SSID its event handlers read
  delay(100);             // NOLINT: once per reboot or deep sleep, lets the deauth go out
}
#endif
 
bool WiFiComponent::wifi_disconnect_() {
  // Reset state first so disconnect events aren't ignored
  // and wifi_sta_connect_status_() returns IDLE instead of CONNECTING
  this->sta_state_ = static_cast<uint8_t>(LTWiFiSTAState::IDLE);
  return WiFi.disconnect();
}
 
bssid_t WiFiComponent::wifi_bssid() {
  bssid_t bssid{};
  uint8_t *raw_bssid = WiFi.BSSID();
  if (raw_bssid != nullptr) {
    for (size_t i = 0; i < bssid.size(); i++)
      bssid[i] = raw_bssid[i];
  }
  return bssid;
}
const char *WiFiComponent::wifi_ssid_to(std::span<char, SSID_BUFFER_SIZE> buffer) {
#ifdef USE_BK72XX
  LinkStatusTypeDef link_status{};
  bk_wlan_get_link_status(&link_status);
  size_t len = strnlen(reinterpret_cast<const char *>(link_status.ssid), SSID_BUFFER_SIZE - 1);
  memcpy(buffer.data(), link_status.ssid, len);
#elif defined(USE_RTL87XX)
  rtw_wifi_setting_t setting{};
  wifi_get_setting("wlan0", &setting);
  size_t len = strnlen(reinterpret_cast<const char *>(setting.ssid), SSID_BUFFER_SIZE - 1);
  memcpy(buffer.data(), setting.ssid, len);
#else
  // LN882X: wifi_get_sta_conn_info() provides direct pointer access
  String ssid = WiFi.SSID();
  size_t len = std::min(static_cast<size_t>(ssid.length()), SSID_BUFFER_SIZE - 1);
  memcpy(buffer.data(), ssid.c_str(), len);
#endif
  buffer[len] = '\0';
  return buffer.data();
}
int8_t WiFiComponent::wifi_rssi() { return WiFi.status() == WL_CONNECTED ? WiFi.RSSI() : WIFI_RSSI_DISCONNECTED; }
int32_t WiFiComponent::get_wifi_channel() { return WiFi.channel(); }
network::IPAddress WiFiComponent::wifi_subnet_mask_() { return {WiFi.subnetMask()}; }
network::IPAddress WiFiComponent::wifi_gateway_ip_() { return {WiFi.gatewayIP()}; }
network::IPAddress WiFiComponent::wifi_dns_ip_(int num) { return {WiFi.dnsIP(num)}; }
bool WiFiComponent::wifi_loop_() {
  // Use pop() directly instead of empty() — avoids redundant synchronization.
  // LockFreeQueue: pop() costs 1 memw vs empty()'s 2 memw on Xtensa.
  // FreeRTOSQueue: pop() is 1 critical section vs empty() + pop() = 2.
  LTWiFiEvent *event = this->event_queue_.pop();
  if (event == nullptr)
    return false;
 
  do {
    wifi_process_event_(event);
    delete event;  // NOLINT(cppcoreguidelines-owning-memory)
  } while ((event = this->event_queue_.pop()) != nullptr);
 
  // Drops only occur when the queue is full, and only this loop drains it,
  // so if pop() returned nullptr above we can skip this check.
  uint16_t dropped = this->event_queue_.get_and_reset_dropped_count();
  if (dropped > 0) {
    // A dropped station event cannot be made up for: the BK72xx core has no station query
    ESP_LOGW(TAG, "Dropped %" PRIu16 " WiFi events due to buffer overflow", dropped);
  }
  return true;
}
 
}  // namespace esphome::wifi
#endif  // USE_LIBRETINY
#endif