ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
esphome::wifi Namespace Reference

Data Structures

class  CompactString
 20-byte string: 18 chars inline + null, heap for longer. More...
 
struct  EAPAuth
 
class  ExpectedDisconnect
 
struct  ManualIP
 Struct for setting static IPs in WiFiComponent. More...
 
struct  SavedWifiFastConnectSettings
 
struct  SavedWifiLeaseSettings
 
struct  SavedWifiSettings
 
class  ScanResultsLock
 Guards WiFiComponent::scan_result_. More...
 
class  WiFiAP
 
class  WiFiComponent
 This component is responsible for managing the ESP WiFi interface. More...
 
class  WiFiConfigureAction
 
class  WiFiConnectStateListener
 Listener interface for WiFi connection state changes. More...
 
class  WiFiIPStateListener
 Listener interface for WiFi IP state changes. More...
 
class  WiFiPowerSaveListener
 Listener interface for WiFi power save mode changes. More...
 
class  WiFiScanResult
 
class  WiFiScanResultsListener
 Listener interface for WiFi scan results. More...
 
struct  WiFiSTAPriority
 

Typedefs

using bssid_t = std::array<uint8_t, 6>
 
template<typename T >
using wifi_scan_vector_t = std::vector<T>
 
using esphome_wifi_event_id_t = arduino_event_id_t
 
using esphome_wifi_event_info_t = arduino_event_info_t
 

Enumerations

enum class  ExpectedLeave : uint8_t { EXPECTED_LEAVE_NONE , EXPECTED_LEAVE_AP , EXPECTED_LEAVE_ATTEMPT }
 Which expected leave a disconnect matched. More...
 
enum  WiFiComponentState : uint8_t {
  WIFI_COMPONENT_STATE_OFF = 0 , WIFI_COMPONENT_STATE_DISABLED , WIFI_COMPONENT_STATE_COOLDOWN , WIFI_COMPONENT_STATE_STA_SCANNING ,
  WIFI_COMPONENT_STATE_STA_CONNECTING , WIFI_COMPONENT_STATE_STA_CONNECTED , WIFI_COMPONENT_STATE_AP
}
 
enum class  WiFiSTAConnectStatus : int {
  IDLE , CONNECTING , CONNECTED , ERROR_NETWORK_NOT_FOUND ,
  ERROR_CONNECT_FAILED
}
 
enum class  WiFiRetryPhase : uint8_t {
  INITIAL_CONNECT , FAST_CONNECT_CYCLING_APS , EXPLICIT_HIDDEN , SCAN_CONNECTING ,
  RETRY_HIDDEN , RESTARTING_ADAPTER
}
 Tracks the current retry strategy/phase for WiFi connection attempts. More...
 
enum class  RoamingState : uint8_t { IDLE , SCANNING , CONNECTING , RECONNECTING }
 Tracks post-connect roaming state machine. More...
 
enum class  RetryHiddenMode : uint8_t { SCAN_BASED , BLIND_RETRY }
 Controls how RETRY_HIDDEN phase selects networks to try. More...
 
enum  WiFiPowerSaveMode : uint8_t { WIFI_POWER_SAVE_NONE = 0 , WIFI_POWER_SAVE_LIGHT , WIFI_POWER_SAVE_HIGH }
 
enum  WifiMinAuthMode : uint8_t { WIFI_MIN_AUTH_MODE_WPA = 0 , WIFI_MIN_AUTH_MODE_WPA2 , WIFI_MIN_AUTH_MODE_WPA3 }
 
enum  WiFi8266PhyMode : uint8_t { WIFI_8266_PHY_MODE_AUTO = 0 , WIFI_8266_PHY_MODE_11B = 1 , WIFI_8266_PHY_MODE_11G = 2 , WIFI_8266_PHY_MODE_11N = 3 }
 
enum class  ESP8266WiFiSTAState : uint8_t {
  IDLE , CONNECTING , ASSOCIATED , CONNECTED ,
  ERROR_NOT_FOUND , ERROR_FAILED
}
 
enum class  LTWiFiSTAState : uint8_t {
  IDLE , CONNECTING , CONNECTED , ERROR_NOT_FOUND ,
  ERROR_FAILED
}
 

Functions

template<typename Results , typename Entry >
bool should_show_scan_entry (const Results &results, const Entry &scan, bool &with_auth)
 
 ESPHOME_LOG_TAG (TAG, "wifi")
 
void __attribute__ ((flatten)) WiFiComponent
 
const LogString * get_signal_bars (int8_t rssi)
 
 __attribute__ ((noinline)) static void log_scan_result(const WiFiScanResult &res)
 
 ESPHOME_LOG_TAG (TAG, "wifi_esp8266")
 
struct netif * eagle_lwip_getif (int netif_index)
 
void netif_set_addr (struct netif *netif, const ip4_addr_t *ip, const ip4_addr_t *netmask, const ip4_addr_t *gw)
 
void netif_set_down (struct netif *netif)
 
 PROGMEM_STRING_TABLE (AuthModeStrings, "OPEN", "WEP", "WPA PSK", "WPA2 PSK", "WPA/WPA2 PSK", "UNKNOWN")
 
const LogString * get_auth_mode_str (uint8_t mode)
 
 PROGMEM_STRING_TABLE (OpModeStrings, "OFF", "STA", "AP", "AP+STA", "UNKNOWN")
 
const LogString * get_op_mode_str (uint8_t mode)
 
const LogString * get_disconnect_reason_str (uint8_t reason)
 
 ESPHOME_LOG_TAG (TAG, "wifi_lt")
 
 PROGMEM_STRING_TABLE (JoinErrorStrings, "none", "network not found", "connect failed", "handshake failed (wrong password?)", "4-way handshake timeout", "DHCP failed", "auth failed", "assoc failed", "deauthenticated", "unknown")
 
 ESPHOME_LOG_TAG (TAG, "wifi_pico_w")
 

Variables

WiFiComponent * global_wifi_component
 
struct esphome::wifi::SavedWifiSettings PACKED
 
const uint8_t MANUAL_IP_TABLE[] PROGMEM
 Every configured manual IP, generated by codegen (components/wifi/__init__.py) and kept in flash.
 

Typedef Documentation

◆ bssid_t

using esphome::wifi::bssid_t = std::array<uint8_t, 6>

Definition at line 215 of file wifi_component.h.

◆ esphome_wifi_event_id_t

using esphome::wifi::esphome_wifi_event_id_t = arduino_event_id_t

Definition at line 411 of file wifi_component_libretiny.cpp.

◆ esphome_wifi_event_info_t

using esphome::wifi::esphome_wifi_event_info_t = arduino_event_info_t

Definition at line 412 of file wifi_component_libretiny.cpp.

◆ wifi_scan_vector_t

template<typename T >
using esphome::wifi::wifi_scan_vector_t = std::vector<T>

Definition at line 223 of file wifi_component.h.

Enumeration Type Documentation

◆ ESP8266WiFiSTAState

enum class esphome::wifi::ESP8266WiFiSTAState : uint8_t
strong
Enumerator
IDLE 
CONNECTING 
ASSOCIATED 
CONNECTED 
ERROR_NOT_FOUND 
ERROR_FAILED 

Definition at line 45 of file wifi_component_esp8266.cpp.

◆ ExpectedLeave

enum class esphome::wifi::ExpectedLeave : uint8_t
strong

Which expected leave a disconnect matched.

Enumerator
EXPECTED_LEAVE_NONE 
EXPECTED_LEAVE_AP 
EXPECTED_LEAVE_ATTEMPT 

An attempt that never associated, so no BSSID.

Definition at line 9 of file expected_disconnect.h.

◆ LTWiFiSTAState

enum class esphome::wifi::LTWiFiSTAState : uint8_t
strong
Enumerator
IDLE 
CONNECTING 
CONNECTED 
ERROR_NOT_FOUND 
ERROR_FAILED 

Definition at line 116 of file wifi_component_libretiny.cpp.

◆ RetryHiddenMode

enum class esphome::wifi::RetryHiddenMode : uint8_t
strong

Controls how RETRY_HIDDEN phase selects networks to try.

Enumerator
SCAN_BASED 

Normal mode: scan completed, only try networks NOT visible in scan results (truly hidden networks that need probe requests)

BLIND_RETRY 

Blind retry mode: scanning disabled (captive portal/improv active), try ALL configured networks sequentially without consulting scan results.

Definition at line 173 of file wifi_component.h.

◆ RoamingState

enum class esphome::wifi::RoamingState : uint8_t
strong

Tracks post-connect roaming state machine.

Enumerator
IDLE 

Not roaming, waiting for next check interval.

SCANNING 

Scanning for better AP.

CONNECTING 

Attempting to connect to better AP found in scan.

RECONNECTING 

Roam connection failed, reconnecting to any available AP.

Definition at line 161 of file wifi_component.h.

◆ WiFi8266PhyMode

Enumerator
WIFI_8266_PHY_MODE_AUTO 
WIFI_8266_PHY_MODE_11B 
WIFI_8266_PHY_MODE_11G 
WIFI_8266_PHY_MODE_11N 

Definition at line 401 of file wifi_component.h.

◆ WiFiComponentState

Enumerator
WIFI_COMPONENT_STATE_OFF 

Nothing has been initialized yet.

Internal AP, if configured, is disabled at this point.

WIFI_COMPONENT_STATE_DISABLED 

WiFi is disabled.

WIFI_COMPONENT_STATE_COOLDOWN 

WiFi is in cooldown mode because something went wrong, scanning will begin after a short period of time.

WIFI_COMPONENT_STATE_STA_SCANNING 

WiFi is in STA-only mode and currently scanning for APs.

WIFI_COMPONENT_STATE_STA_CONNECTING 

WiFi is in STA(+AP) mode and currently connecting to an AP.

WIFI_COMPONENT_STATE_STA_CONNECTED 

WiFi is in STA(+AP) mode and successfully connected.

WIFI_COMPONENT_STATE_AP 

WiFi is in AP-only mode and internal AP is already enabled.

Definition at line 117 of file wifi_component.h.

◆ WifiMinAuthMode

Enumerator
WIFI_MIN_AUTH_MODE_WPA 
WIFI_MIN_AUTH_MODE_WPA2 
WIFI_MIN_AUTH_MODE_WPA3 

Definition at line 392 of file wifi_component.h.

◆ WiFiPowerSaveMode

Enumerator
WIFI_POWER_SAVE_NONE 
WIFI_POWER_SAVE_LIGHT 
WIFI_POWER_SAVE_HIGH 

Definition at line 386 of file wifi_component.h.

◆ WiFiRetryPhase

enum class esphome::wifi::WiFiRetryPhase : uint8_t
strong

Tracks the current retry strategy/phase for WiFi connection attempts.

Enumerator
INITIAL_CONNECT 

Initial connection attempt (varies based on fast_connect setting)

FAST_CONNECT_CYCLING_APS 

Fast connect mode: cycling through configured APs (config-only, no scan)

EXPLICIT_HIDDEN 

Explicitly hidden networks (user marked as hidden, try before scanning)

SCAN_CONNECTING 

Scan-based: connecting to best AP from scan results.

RETRY_HIDDEN 

Retry networks not found in scan (might be hidden)

RESTARTING_ADAPTER 

Restarting WiFi adapter to clear stuck state.

Definition at line 143 of file wifi_component.h.

◆ WiFiSTAConnectStatus

enum class esphome::wifi::WiFiSTAConnectStatus : int
strong
Enumerator
IDLE 
CONNECTING 
CONNECTED 
ERROR_NETWORK_NOT_FOUND 
ERROR_CONNECT_FAILED 

Definition at line 134 of file wifi_component.h.

Function Documentation

◆ __attribute__() [1/2]

void esphome::wifi::__attribute__ ( (flatten) )

Definition at line 549 of file wifi_component.cpp.

◆ __attribute__() [2/2]

esphome::wifi::__attribute__ ( (noinline) ) const &

Definition at line 1663 of file wifi_component.cpp.

◆ eagle_lwip_getif()

struct netif * esphome::wifi::eagle_lwip_getif ( int netif_index)

◆ ESPHOME_LOG_TAG() [1/4]

esphome::wifi::ESPHOME_LOG_TAG ( TAG ,
"wifi"  )

◆ ESPHOME_LOG_TAG() [2/4]

esphome::wifi::ESPHOME_LOG_TAG ( TAG ,
"wifi_esp8266"  )

◆ ESPHOME_LOG_TAG() [3/4]

esphome::wifi::ESPHOME_LOG_TAG ( TAG ,
"wifi_lt"  )

◆ ESPHOME_LOG_TAG() [4/4]

esphome::wifi::ESPHOME_LOG_TAG ( TAG ,
"wifi_pico_w"  )

◆ get_auth_mode_str()

const char * esphome::wifi::get_auth_mode_str ( uint8_t mode)

Definition at line 429 of file wifi_component_esp8266.cpp.

◆ get_disconnect_reason_str()

const char * esphome::wifi::get_disconnect_reason_str ( uint8_t reason)

Definition at line 443 of file wifi_component_esp8266.cpp.

◆ get_op_mode_str()

const char * esphome::wifi::get_op_mode_str ( uint8_t mode)

Definition at line 438 of file wifi_component_esp8266.cpp.

◆ get_signal_bars()

const LogString * esphome::wifi::get_signal_bars ( int8_t rssi)

Definition at line 1410 of file wifi_component.cpp.

◆ netif_set_addr()

void esphome::wifi::netif_set_addr ( struct netif * netif,
const ip4_addr_t * ip,
const ip4_addr_t * netmask,
const ip4_addr_t * gw )

◆ netif_set_down()

void esphome::wifi::netif_set_down ( struct netif * netif)

◆ PROGMEM_STRING_TABLE() [1/3]

esphome::wifi::PROGMEM_STRING_TABLE ( AuthModeStrings ,
"OPEN" ,
"WEP" ,
"WPA PSK" ,
"WPA2 PSK" ,
"WPA/WPA2 PSK" ,
"UNKNOWN"  )

◆ PROGMEM_STRING_TABLE() [2/3]

esphome::wifi::PROGMEM_STRING_TABLE ( JoinErrorStrings ,
"none" ,
"network not found" ,
"connect failed" ,
"handshake failed (wrong password?)" ,
"4-way handshake timeout" ,
"DHCP failed" ,
"auth failed" ,
"assoc failed" ,
"deauthenticated" ,
"unknown"  )

◆ PROGMEM_STRING_TABLE() [3/3]

esphome::wifi::PROGMEM_STRING_TABLE ( OpModeStrings ,
"OFF" ,
"STA" ,
"AP" ,
"AP+STA" ,
"UNKNOWN"  )

◆ should_show_scan_entry()

template<typename Results , typename Entry >
bool esphome::wifi::should_show_scan_entry ( const Results & results,
const Entry & scan,
bool & with_auth )

Definition at line 11 of file scan_list.h.

Variable Documentation

◆ global_wifi_component

WiFiComponent * esphome::wifi::global_wifi_component

Definition at line 2898 of file wifi_component.cpp.

◆ PACKED

struct esphome::wifi::SavedWifiLeaseSettings esphome::wifi::PACKED

◆ PROGMEM

const uint8_t MANUAL_IP_TABLE [] esphome::wifi::PROGMEM
extern

Every configured manual IP, generated by codegen (components/wifi/__init__.py) and kept in flash.