This component is responsible for managing the ESP WiFi interface. More...

#include <wifi_component.h>

Inheritance diagram for esphome::wifi::WiFiComponent:

Public Member Functions
	WiFiComponent ()
	Construct a WiFiComponent.

void	set_sta (const WiFiAP &ap)

WiFiAP	get_sta () const

void	init_sta (size_t count)

void	add_sta (const WiFiAP &ap)

void	clear_sta ()

void	set_ap (const WiFiAP &ap)
	Setup an Access Point that should be created if no connection to a station can be made.

WiFiAP	get_ap ()

void	set_ap_timeout (uint32_t ap_timeout)

void	enable ()

void	disable ()

bool	is_disabled ()

void	start_scanning ()

void	check_scanning_finished ()

void	start_connecting (const WiFiAP &ap)

void	start_connecting (const WiFiAP &ap, bool)

void	check_connecting_finished ()

void	retry_connect ()

bool	can_proceed () override

void	set_reboot_timeout (uint32_t reboot_timeout)

bool	is_connected ()

void	set_power_save_mode (WiFiPowerSaveMode power_save)

void	set_min_auth_mode (WifiMinAuthMode min_auth_mode)

void	set_output_power (float output_power)

void	set_passive_scan (bool passive)

void	save_wifi_sta (const std::string &ssid, const std::string &password)

void	setup () override
	Setup WiFi interface.

void	start ()

void	dump_config () override

void	restart_adapter ()

float	get_setup_priority () const override
	WIFI setup_priority.

float	get_loop_priority () const override

void	loop () override
	Reconnect WiFi if required.

bool	has_sta () const

bool	has_ap () const

bool	is_ap_active () const

void	set_btm (bool btm)

void	set_rrm (bool rrm)

network::IPAddress	get_dns_address (int num)

network::IPAddresses	get_ip_addresses ()

const char *	get_use_address () const

void	set_use_address (const char *use_address)

const wifi_scan_vector_t< WiFiScanResult > &	get_scan_result () const

network::IPAddress	wifi_soft_ap_ip ()

bool	has_sta_priority (const bssid_t &bssid)

int8_t	get_sta_priority (const bssid_t bssid)

void	set_sta_priority (const bssid_t bssid, int8_t priority)

network::IPAddresses	wifi_sta_ip_addresses ()

std::string	wifi_ssid ()

const char *	wifi_ssid_to (std::span< char, SSID_BUFFER_SIZE > buffer)
	Write SSID to buffer without heap allocation.

bssid_t	wifi_bssid ()

int8_t	wifi_rssi ()

void	set_enable_on_boot (bool enable_on_boot)

void	set_keep_scan_results (bool keep_scan_results)

Trigger *	get_connect_trigger () const

Trigger *	get_disconnect_trigger () const

int32_t	get_wifi_channel ()

void	add_ip_state_listener (WiFiIPStateListener *listener)
	Add a listener for IP state changes.

void	add_scan_results_listener (WiFiScanResultsListener *listener)
	Add a listener for WiFi scan results.

void	add_connect_state_listener (WiFiConnectStateListener *listener)
	Add a listener for WiFi connection state changes.

void	add_power_save_listener (WiFiPowerSaveListener *listener)
	Add a listener for WiFi power save mode changes.

bool	request_high_performance ()
	Request high-performance mode (no power saving) for improved WiFi latency.

bool	release_high_performance ()
	Release a high-performance mode request.

Public Member Functions inherited from esphome::Component
float	get_actual_setup_priority () const

void	set_setup_priority (float priority)

void	call ()

virtual void	on_shutdown ()

virtual void	on_safe_shutdown ()

virtual bool	teardown ()
	Called during teardown to allow component to gracefully finish operations.

virtual void	on_powerdown ()
	Called after teardown is complete to power down hardware.

uint8_t	get_component_state () const

void	reset_to_construction_state ()
	Reset this component back to the construction state to allow setup to run again.

bool	is_in_loop_state () const
	Check if this component has completed setup and is in the loop state.

bool	is_idle () const
	Check if this component is idle.

virtual void	mark_failed ()
	Mark this component as failed.

	ESPDEPRECATED ("Use mark_failed(LOG_STR(\"static string literal\")) instead. Do NOT use .c_str() from temporary " "strings. Will stop working in 2026.6.0", "2025.12.0") void mark_failed(const char *message)

void	mark_failed (const LogString *message)

void	disable_loop ()
	Disable this component's loop.

void	enable_loop ()
	Enable this component's loop.

void	enable_loop_soon_any_context ()
	Thread and ISR-safe version of enable_loop() that can be called from any context.

bool	is_failed () const

bool	is_ready () const

bool	status_has_warning () const

bool	status_has_error () const

void	status_set_warning (const char *message=nullptr)

void	status_set_warning (const LogString *message)

void	status_set_error ()

	ESPDEPRECATED ("Use status_set_error(LOG_STR(\"static string literal\")) instead. Do NOT use .c_str() from temporary " "strings. Will stop working in 2026.6.0", "2025.12.0") void status_set_error(const char *message)

void	status_set_error (const LogString *message)

void	status_clear_warning ()

void	status_clear_error ()

void	status_momentary_warning (const char *name, uint32_t length=5000)
	Set warning status flag and automatically clear it after a timeout.

void	status_momentary_error (const char *name, uint32_t length=5000)
	Set error status flag and automatically clear it after a timeout.

bool	has_overridden_loop () const

void	set_component_source (const LogString *source)
	Set where this component was loaded from for some debug messages.

const LogString *	get_component_log_str () const
	Get the integration where this component was declared as a LogString for logging.

bool	should_warn_of_blocking (uint32_t blocking_time)

Protected Member Functions
void	setup_ap_config_ ()

void	print_connect_params_ ()

WiFiAP	build_params_for_current_phase_ ()

WiFiRetryPhase	determine_next_phase_ ()
	Determine next retry phase based on current state and failure conditions.

bool	transition_to_phase_ (WiFiRetryPhase new_phase)
	Transition to a new retry phase with logging Returns true if a scan was started (caller should wait), false otherwise.

bool	needs_scan_results_ () const
	Check if we need valid scan results for the current phase but don't have any Returns true if the phase requires scan results but they're missing or don't match.

bool	went_through_explicit_hidden_phase_ () const
	Check if we went through EXPLICIT_HIDDEN phase (first network is marked hidden) Used in RETRY_HIDDEN to determine whether to skip explicitly hidden networks.

int8_t	find_first_non_hidden_index_ () const
	Find the index of the first non-hidden network Returns where EXPLICIT_HIDDEN phase would have stopped, or -1 if all networks are hidden.

bool	ssid_was_seen_in_scan_ (const std::string &ssid) const
	Check if an SSID was seen in the most recent scan results Used to skip hidden mode for SSIDs we know are visible.

int8_t	find_next_hidden_sta_ (int8_t start_index)
	Find next SSID that wasn't in scan results (might be hidden) Returns index of next potentially hidden SSID, or -1 if none found.

void	log_and_adjust_priority_for_failed_connect_ ()
	Log failed connection and decrease BSSID priority to avoid repeated attempts.

void	clear_priorities_if_all_min_ ()
	Clear BSSID priority tracking if all priorities are at minimum (saves memory)

void	advance_to_next_target_or_increment_retry_ ()
	Advance to next target (AP/SSID) within current phase, or increment retry counter Called when staying in the same phase after a failed connection attempt.

void	start_initial_connection_ ()
	Start initial connection - either scan or connect directly to hidden networks.

const WiFiAP *	get_selected_sta_ () const

void	reset_selected_ap_to_first_if_invalid_ ()

bool	all_networks_hidden_ () const

void	connect_soon_ ()

void	wifi_loop_ ()

bool	wifi_mode_ (optional< bool > sta, optional< bool > ap)

bool	wifi_sta_pre_setup_ ()

bool	wifi_apply_output_power_ (float output_power)

bool	wifi_apply_power_save_ ()

bool	wifi_sta_ip_config_ (const optional< ManualIP > &manual_ip)

bool	wifi_apply_hostname_ ()

bool	wifi_sta_connect_ (const WiFiAP &ap)

void	wifi_pre_setup_ ()

WiFiSTAConnectStatus	wifi_sta_connect_status_ ()

bool	wifi_scan_start_ (bool passive)

bool	wifi_ap_ip_config_ (const optional< ManualIP > &manual_ip)

bool	wifi_start_ap_ (const WiFiAP &ap)

bool	wifi_disconnect_ ()

network::IPAddress	wifi_subnet_mask_ ()

network::IPAddress	wifi_gateway_ip_ ()

network::IPAddress	wifi_dns_ip_ (int num)

bool	is_captive_portal_active_ ()

bool	is_esp32_improv_active_ ()

bool	load_fast_connect_settings_ (WiFiAP &params)

void	save_fast_connect_settings_ ()

void	wifi_scan_done_callback_ (void *arg, STATUS status)

void	wifi_event_callback_ (arduino_event_id_t event, arduino_event_info_t info)

void	wifi_scan_done_callback_ ()

void	wifi_process_event_ (IDFWiFiEvent *data)

void	wifi_scan_result (void env, const cyw43_ev_scan_result_t result)

void	wifi_event_callback_ (arduino_event_id_t event, arduino_event_info_t info)

void	wifi_scan_done_callback_ ()

Protected Member Functions inherited from esphome::Component
virtual void	call_loop ()

virtual void	call_setup ()

virtual void	call_dump_config ()

void	set_component_state_ (uint8_t state)
	Helper to set component state (clears state bits and sets new state)

void	set_interval (const std::string &name, uint32_t interval, std::function< void()> &&f)
	Set an interval function with a unique name.

void	set_interval (const char *name, uint32_t interval, std::function< void()> &&f)
	Set an interval function with a const char* name.

void	set_interval (uint32_t interval, std::function< void()> &&f)

bool	cancel_interval (const std::string &name)
	Cancel an interval function.

bool	cancel_interval (const char *name)

void	set_retry (const std::string &name, uint32_t initial_wait_time, uint8_t max_attempts, std::function< RetryResult(uint8_t)> &&f, float backoff_increase_factor=1.0f)
	Set an retry function with a unique name.

void	set_retry (const char *name, uint32_t initial_wait_time, uint8_t max_attempts, std::function< RetryResult(uint8_t)> &&f, float backoff_increase_factor=1.0f)

void	set_retry (uint32_t initial_wait_time, uint8_t max_attempts, std::function< RetryResult(uint8_t)> &&f, float backoff_increase_factor=1.0f)

bool	cancel_retry (const std::string &name)
	Cancel a retry function.

bool	cancel_retry (const char *name)

void	set_timeout (const std::string &name, uint32_t timeout, std::function< void()> &&f)
	Set a timeout function with a unique name.

void	set_timeout (const char *name, uint32_t timeout, std::function< void()> &&f)
	Set a timeout function with a const char* name.

void	set_timeout (uint32_t timeout, std::function< void()> &&f)

bool	cancel_timeout (const std::string &name)
	Cancel a timeout function.

bool	cancel_timeout (const char *name)

void	defer (const std::string &name, std::function< void()> &&f)
	Defer a callback to the next loop() call.

void	defer (const char *name, std::function< void()> &&f)
	Defer a callback to the next loop() call with a const char* name.

void	defer (std::function< void()> &&f)
	Defer a callback to the next loop() call.

bool	cancel_defer (const std::string &name)
	Cancel a defer callback using the specified name, name must not be empty.

Static Protected Member Functions
static void	wifi_event_callback (System_Event_t *event)

static void	s_wifi_scan_done_callback (void *arg, STATUS status)

static int	s_wifi_scan_result (void env, const cyw43_ev_scan_result_t result)

Protected Attributes
FixedVector< WiFiAP >	sta_

std::vector< WiFiSTAPriority >	sta_priorities_

wifi_scan_vector_t< WiFiScanResult >	scan_result_

WiFiAP	ap_

float	output_power_ {NAN}

std::vector< WiFiIPStateListener * >	ip_state_listeners_

std::vector< WiFiScanResultsListener * >	scan_results_listeners_

std::vector< WiFiConnectStateListener * >	connect_state_listeners_

std::vector< WiFiPowerSaveListener * >	power_save_listeners_

ESPPreferenceObject	pref_

ESPPreferenceObject	fast_connect_pref_

uint32_t	action_started_

uint32_t	last_connected_ {0}

uint32_t	reboot_timeout_ {}

uint32_t	ap_timeout_ {}

WiFiComponentState	state_ {WIFI_COMPONENT_STATE_OFF}

WiFiPowerSaveMode	power_save_ {WIFI_POWER_SAVE_NONE}

WifiMinAuthMode	min_auth_mode_ {WIFI_MIN_AUTH_MODE_WPA2}

WiFiRetryPhase	retry_phase_ {WiFiRetryPhase::INITIAL_CONNECT}

uint8_t	num_retried_ {0}

int8_t	selected_sta_index_ {-1}

uint8_t	num_ipv6_addresses_ {0}

bool	has_ap_ {false}

bool	handled_connected_state_ {false}

bool	error_from_callback_ {false}

bool	scan_done_ {false}

bool	ap_setup_ {false}

bool	ap_started_ {false}

bool	passive_scan_ {false}

bool	has_saved_wifi_settings_ {false}

bool	btm_ {false}

bool	rrm_ {false}

bool	enable_on_boot_ {true}

bool	got_ipv4_address_ {false}

bool	keep_scan_results_ {false}

bool	did_scan_this_cycle_ {false}

bool	skip_cooldown_next_cycle_ {false}

WiFiPowerSaveMode	configured_power_save_ {WIFI_POWER_SAVE_NONE}

bool	is_high_performance_mode_ {false}

SemaphoreHandle_t	high_performance_semaphore_ {nullptr}

Trigger *	connect_trigger_ {new Trigger<>()}

Trigger *	disconnect_trigger_ {new Trigger<>()}

Protected Attributes inherited from esphome::Component
const LogString *	component_source_ {nullptr}

uint16_t	warn_if_blocking_over_ {WARN_IF_BLOCKING_OVER_MS}
	Warn if blocked for this many ms (max 65.5s)

uint8_t	component_state_ {0x00}
	State of this component - each bit has a purpose: Bits 0-2: Component state (0x00=CONSTRUCTION, 0x01=SETUP, 0x02=LOOP, 0x03=FAILED, 0x04=LOOP_DONE) Bit 3: STATUS_LED_WARNING Bit 4: STATUS_LED_ERROR Bits 5-7: Unused - reserved for future expansion.

volatile bool	pending_enable_loop_ {false}
	ISR-safe flag for enable_loop_soon_any_context.

Detailed Description

This component is responsible for managing the ESP WiFi interface.

Definition at line 296 of file wifi_component.h.

Constructor & Destructor Documentation

◆ WiFiComponent()

esphome::wifi::WiFiComponent::WiFiComponent ( )

Construct a WiFiComponent.

Definition at line 596 of file wifi_component.cpp.

Member Function Documentation

◆ add_connect_state_listener()

void esphome::wifi::WiFiComponent::add_connect_state_listener ( WiFiConnectStateListener * listener )

inline

Add a listener for WiFi connection state changes.

Listener receives: SSID, BSSID

Definition at line 441 of file wifi_component.h.

◆ add_ip_state_listener()

void esphome::wifi::WiFiComponent::add_ip_state_listener ( WiFiIPStateListener * listener )

inline

Add a listener for IP state changes.

Listener receives: IP addresses, DNS address 1, DNS address 2

Definition at line 433 of file wifi_component.h.

◆ add_power_save_listener()

void esphome::wifi::WiFiComponent::add_power_save_listener ( WiFiPowerSaveListener * listener )

inline

Add a listener for WiFi power save mode changes.

Listener receives: WiFiPowerSaveMode

Definition at line 447 of file wifi_component.h.

◆ add_scan_results_listener()

void esphome::wifi::WiFiComponent::add_scan_results_listener ( WiFiScanResultsListener * listener )

inline

Add a listener for WiFi scan results.

Definition at line 435 of file wifi_component.h.

◆ add_sta()

void esphome::wifi::WiFiComponent::add_sta ( const WiFiAP & ap )

Definition at line 683 of file wifi_component.cpp.

◆ advance_to_next_target_or_increment_retry_()

void esphome::wifi::WiFiComponent::advance_to_next_target_or_increment_retry_ ( )

protected

Advance to next target (AP/SSID) within current phase, or increment retry counter Called when staying in the same phase after a failed connection attempt.

Handle target advancement or retry counter increment when staying in the same phase This function is called when a connection attempt fails and determine_next_phase_() indicates we should stay in the current phase.

It decides whether to:

Advance to the next target (AP in fast_connect, SSID in hidden mode)
Or increment the retry counter to try the same target again

Phase-specific behavior:

FAST_CONNECT_CYCLING_APS: Always advance to next AP (no retries per AP)
RETRY_HIDDEN: Advance to next SSID after exhausting retries on current SSID
Other phases: Increment retry counter (will retry same target)

Definition at line 1577 of file wifi_component.cpp.

◆ all_networks_hidden_()

bool esphome::wifi::WiFiComponent::all_networks_hidden_ ( ) const

inlineprotected

Definition at line 532 of file wifi_component.h.

◆ build_params_for_current_phase_()

WiFiAP esphome::wifi::WiFiComponent::build_params_for_current_phase_ ( )

protected

Definition at line 693 of file wifi_component.cpp.

◆ can_proceed()

bool esphome::wifi::WiFiComponent::can_proceed ( )

overridevirtual

Reimplemented from esphome::Component.

Definition at line 1668 of file wifi_component.cpp.

◆ check_connecting_finished()

void esphome::wifi::WiFiComponent::check_connecting_finished ( )

Definition at line 1166 of file wifi_component.cpp.

◆ check_scanning_finished()

void esphome::wifi::WiFiComponent::check_scanning_finished ( )

Definition at line 1066 of file wifi_component.cpp.

◆ clear_priorities_if_all_min_()

void esphome::wifi::WiFiComponent::clear_priorities_if_all_min_ ( )

protected

Clear BSSID priority tracking if all priorities are at minimum (saves memory)

Clear BSSID priority tracking if all priorities are at minimum (saves memory) At minimum priority, all BSSIDs are equally bad, so priority tracking is useless Called after successful connection or after failed connection attempts.

Definition at line 1475 of file wifi_component.cpp.

◆ clear_sta()

void esphome::wifi::WiFiComponent::clear_sta ( )

inline

Definition at line 306 of file wifi_component.h.

◆ connect_soon_()

void esphome::wifi::WiFiComponent::connect_soon_ ( )

protected

Definition at line 757 of file wifi_component.cpp.

◆ determine_next_phase_()

WiFiRetryPhase esphome::wifi::WiFiComponent::determine_next_phase_ ( )

protected

Determine next retry phase based on current state and failure conditions.

Determine the next retry phase based on current state and failure conditions This function examines the current retry phase, number of retries, and failure reasons to decide what phase to move to next.

It does not modify any state - it only returns the recommended next phase.

Returns: The next WiFiRetryPhase to transition to (may be same as current phase if should retry)

Definition at line 1268 of file wifi_component.cpp.

◆ disable()

void esphome::wifi::WiFiComponent::disable ( )

Definition at line 952 of file wifi_component.cpp.

◆ dump_config()

void esphome::wifi::WiFiComponent::dump_config ( )

overridevirtual

Reimplemented from esphome::Component.

Definition at line 1158 of file wifi_component.cpp.

◆ enable()

void esphome::wifi::WiFiComponent::enable ( )

Definition at line 942 of file wifi_component.cpp.

◆ find_first_non_hidden_index_()

int8_t esphome::wifi::WiFiComponent::find_first_non_hidden_index_ ( ) const

protected

Find the index of the first non-hidden network Returns where EXPLICIT_HIDDEN phase would have stopped, or -1 if all networks are hidden.

Definition at line 174 of file wifi_component.cpp.

◆ find_next_hidden_sta_()

int8_t esphome::wifi::WiFiComponent::find_next_hidden_sta_ ( int8_t start_index )

protected

Find next SSID that wasn't in scan results (might be hidden) Returns index of next potentially hidden SSID, or -1 if none found.

Parameters

start_index Start searching from index after this (-1 to start from beginning)

Definition at line 280 of file wifi_component.cpp.

◆ get_ap()

WiFiAP esphome::wifi::WiFiComponent::get_ap ( )

inline

Definition at line 320 of file wifi_component.h.

◆ get_connect_trigger()

Trigger * esphome::wifi::WiFiComponent::get_connect_trigger ( ) const

inline

Definition at line 424 of file wifi_component.h.

◆ get_disconnect_trigger()

Trigger * esphome::wifi::WiFiComponent::get_disconnect_trigger ( ) const

inline

Definition at line 425 of file wifi_component.h.

◆ get_dns_address()

network::IPAddress esphome::wifi::WiFiComponent::get_dns_address ( int num )

Definition at line 616 of file wifi_component.cpp.

◆ get_ip_addresses()

network::IPAddresses esphome::wifi::WiFiComponent::get_ip_addresses ( )

Definition at line 605 of file wifi_component.cpp.

◆ get_loop_priority()

float esphome::wifi::WiFiComponent::get_loop_priority ( ) const

overridevirtual

Reimplemented from esphome::Component.

Definition at line 678 of file wifi_component.cpp.

◆ get_scan_result()

const wifi_scan_vector_t< WiFiScanResult > & esphome::wifi::WiFiComponent::get_scan_result ( ) const

inline

Definition at line 381 of file wifi_component.h.

◆ get_selected_sta_()

const WiFiAP * esphome::wifi::WiFiComponent::get_selected_sta_ ( ) const

inlineprotected

Definition at line 519 of file wifi_component.h.

◆ get_setup_priority()

float esphome::wifi::WiFiComponent::get_setup_priority ( ) const

overridevirtual

WIFI setup_priority.

Reimplemented from esphome::Component.

Definition at line 344 of file wifi_component.cpp.

◆ get_sta()

WiFiAP esphome::wifi::WiFiComponent::get_sta ( ) const

Definition at line 736 of file wifi_component.cpp.

◆ get_sta_priority()

int8_t esphome::wifi::WiFiComponent::get_sta_priority ( const bssid_t bssid )

inline

Definition at line 392 of file wifi_component.h.

◆ get_use_address()

const char * esphome::wifi::WiFiComponent::get_use_address ( ) const

Definition at line 623 of file wifi_component.cpp.

◆ get_wifi_channel()

int32_t esphome::wifi::WiFiComponent::get_wifi_channel ( )

Definition at line 935 of file wifi_component_esp8266.cpp.

◆ has_ap()

bool esphome::wifi::WiFiComponent::has_ap ( ) const

Definition at line 598 of file wifi_component.cpp.

◆ has_sta()

bool esphome::wifi::WiFiComponent::has_sta ( ) const

Definition at line 600 of file wifi_component.cpp.

◆ has_sta_priority()

bool esphome::wifi::WiFiComponent::has_sta_priority ( const bssid_t & bssid )

inline

Definition at line 385 of file wifi_component.h.

◆ init_sta()

void esphome::wifi::WiFiComponent::init_sta ( size_t count )

Definition at line 682 of file wifi_component.cpp.

◆ is_ap_active()

bool esphome::wifi::WiFiComponent::is_ap_active ( ) const

Definition at line 599 of file wifi_component.cpp.

◆ is_captive_portal_active_()

bool esphome::wifi::WiFiComponent::is_captive_portal_active_ ( )

protected

Definition at line 1690 of file wifi_component.cpp.

◆ is_connected()

bool esphome::wifi::WiFiComponent::is_connected ( )

Definition at line 1677 of file wifi_component.cpp.

◆ is_disabled()

bool esphome::wifi::WiFiComponent::is_disabled ( )

Definition at line 962 of file wifi_component.cpp.

◆ is_esp32_improv_active_()

bool esphome::wifi::WiFiComponent::is_esp32_improv_active_ ( )

protected

Definition at line 1697 of file wifi_component.cpp.

◆ load_fast_connect_settings_()

bool esphome::wifi::WiFiComponent::load_fast_connect_settings_ ( WiFiAP & params )

protected

Definition at line 1738 of file wifi_component.cpp.

◆ log_and_adjust_priority_for_failed_connect_()

void esphome::wifi::WiFiComponent::log_and_adjust_priority_for_failed_connect_ ( )

protected

Log failed connection and decrease BSSID priority to avoid repeated attempts.

Log failed connection attempt and decrease BSSID priority to avoid repeated failures This function identifies which BSSID was attempted (from scan results or config), decreases its priority by 1.0 to discourage future attempts, and logs the change.

The priority degradation system ensures that failed BSSIDs are automatically sorted lower in subsequent scans, naturally cycling through different APs without explicit BSSID tracking within a scan cycle.

Priority sources:

SCAN_CONNECTING phase: Uses BSSID from scan_result_[0] (best match after sorting)
Other phases: Uses BSSID from config if explicitly specified by user or fast_connect

If no BSSID is available (SSID-only connection), priority adjustment is skipped.

IMPORTANT: Priority is only decreased on the LAST attempt for a BSSID in SCAN_CONNECTING phase. This prevents false positives from transient WiFi stack state issues after scanning. Single failures don't necessarily mean the AP is bad - two genuine failures provide higher confidence before degrading priority and skipping the BSSID in future scans.

Definition at line 1518 of file wifi_component.cpp.

◆ loop()

void esphome::wifi::WiFiComponent::loop ( )

overridevirtual

Reconnect WiFi if required.

Reimplemented from esphome::Component.

Definition at line 472 of file wifi_component.cpp.

◆ needs_scan_results_()

bool esphome::wifi::WiFiComponent::needs_scan_results_ ( ) const

protected

Check if we need valid scan results for the current phase but don't have any Returns true if the phase requires scan results but they're missing or don't match.

Definition at line 253 of file wifi_component.cpp.

◆ print_connect_params_()

void esphome::wifi::WiFiComponent::print_connect_params_ ( )

protected

Definition at line 891 of file wifi_component.cpp.

◆ release_high_performance()

bool esphome::wifi::WiFiComponent::release_high_performance ( )

Release a high-performance mode request.

Should be called when a component no longer needs maximum WiFi latency. When all requests are released (semaphore count reaches zero), WiFi power saving is restored to the YAML-configured mode.

Note: Only supported on ESP32.

Returns: true if release was successful (or already in high-performance config), false if operation failed (semaphore error)

Definition at line 1721 of file wifi_component.cpp.

◆ request_high_performance()

bool esphome::wifi::WiFiComponent::request_high_performance ( )

Request high-performance mode (no power saving) for improved WiFi latency.

Components that need maximum WiFi performance (e.g., audio streaming, large data transfers) can call this method to temporarily disable WiFi power saving. Multiple components can request high performance simultaneously using a counting semaphore.

Power saving will be restored to the YAML-configured mode when all components have called release_high_performance().

Note: Only supported on ESP32.

Returns: true if request was satisfied (high-performance mode active or already configured), false if operation failed (semaphore error)

Definition at line 1706 of file wifi_component.cpp.

◆ reset_selected_ap_to_first_if_invalid_()

void esphome::wifi::WiFiComponent::reset_selected_ap_to_first_if_invalid_ ( )

inlineprotected

Definition at line 526 of file wifi_component.h.

◆ restart_adapter()

void esphome::wifi::WiFiComponent::restart_adapter ( )

Definition at line 466 of file wifi_component.cpp.

◆ retry_connect()

void esphome::wifi::WiFiComponent::retry_connect ( )

Definition at line 1634 of file wifi_component.cpp.

◆ s_wifi_scan_done_callback()

void esphome::wifi::WiFiComponent::s_wifi_scan_done_callback	(	void *	arg,
		STATUS	status )

staticprotected

Definition at line 741 of file wifi_component_esp8266.cpp.

◆ s_wifi_scan_result()

int esphome::wifi::WiFiComponent::s_wifi_scan_result	(	void *	env,
		const cyw43_ev_scan_result_t *	result )

staticprotected

Definition at line 134 of file wifi_component_pico_w.cpp.

◆ save_fast_connect_settings_()

void esphome::wifi::WiFiComponent::save_fast_connect_settings_ ( )

protected

Definition at line 1769 of file wifi_component.cpp.

◆ save_wifi_sta()

void esphome::wifi::WiFiComponent::save_wifi_sta	(	const std::string &	ssid,
		const std::string &	password )

Definition at line 740 of file wifi_component.cpp.

◆ set_ap()

void esphome::wifi::WiFiComponent::set_ap ( const WiFiAP & ap )

Setup an Access Point that should be created if no connection to a station can be made.

This can also be used without set_sta(). Then the AP will always be active.

If both STA and AP are defined, then both will be enabled at startup, but if a connection to a station can be made, the AP will be turned off again.

Definition at line 672 of file wifi_component.cpp.

◆ set_ap_timeout()

void esphome::wifi::WiFiComponent::set_ap_timeout ( uint32_t ap_timeout )

inline

Definition at line 321 of file wifi_component.h.

◆ set_btm()

void esphome::wifi::WiFiComponent::set_btm ( bool btm )

Definition at line 602 of file wifi_component.cpp.

◆ set_enable_on_boot()

void esphome::wifi::WiFiComponent::set_enable_on_boot ( bool enable_on_boot )

inline

Definition at line 421 of file wifi_component.h.

◆ set_keep_scan_results()

void esphome::wifi::WiFiComponent::set_keep_scan_results ( bool keep_scan_results )

inline

Definition at line 422 of file wifi_component.h.

◆ set_min_auth_mode()

void esphome::wifi::WiFiComponent::set_min_auth_mode ( WifiMinAuthMode min_auth_mode )

inline

Definition at line 346 of file wifi_component.h.

◆ set_output_power()

void esphome::wifi::WiFiComponent::set_output_power ( float output_power )

inline

Definition at line 347 of file wifi_component.h.

◆ set_passive_scan()

void esphome::wifi::WiFiComponent::set_passive_scan ( bool passive )

Definition at line 1688 of file wifi_component.cpp.

◆ set_power_save_mode()

void esphome::wifi::WiFiComponent::set_power_save_mode ( WiFiPowerSaveMode power_save )

Definition at line 1681 of file wifi_component.cpp.

◆ set_reboot_timeout()

void esphome::wifi::WiFiComponent::set_reboot_timeout ( uint32_t reboot_timeout )

Definition at line 1676 of file wifi_component.cpp.

◆ set_rrm()

void esphome::wifi::WiFiComponent::set_rrm ( bool rrm )

Definition at line 603 of file wifi_component.cpp.

◆ set_sta()

void esphome::wifi::WiFiComponent::set_sta ( const WiFiAP & ap )

Definition at line 684 of file wifi_component.cpp.

◆ set_sta_priority()

void esphome::wifi::WiFiComponent::set_sta_priority	(	const bssid_t	bssid,
		int8_t	priority )

inline

Definition at line 399 of file wifi_component.h.

◆ set_use_address()

void esphome::wifi::WiFiComponent::set_use_address ( const char * use_address )

Definition at line 624 of file wifi_component.cpp.

◆ setup()

void esphome::wifi::WiFiComponent::setup ( )

overridevirtual

Setup WiFi interface.

Reimplemented from esphome::Component.

Definition at line 346 of file wifi_component.cpp.

◆ setup_ap_config_()

void esphome::wifi::WiFiComponent::setup_ap_config_ ( )

protected

Definition at line 627 of file wifi_component.cpp.

◆ ssid_was_seen_in_scan_()

bool esphome::wifi::WiFiComponent::ssid_was_seen_in_scan_ ( const std::string & ssid ) const

protected

Check if an SSID was seen in the most recent scan results Used to skip hidden mode for SSIDs we know are visible.

Definition at line 262 of file wifi_component.cpp.

◆ start()

void esphome::wifi::WiFiComponent::start ( )

Definition at line 371 of file wifi_component.cpp.

◆ start_connecting() [1/2]

void esphome::wifi::WiFiComponent::start_connecting ( const WiFiAP & ap )

Definition at line 765 of file wifi_component.cpp.

◆ start_connecting() [2/2]

void esphome::wifi::WiFiComponent::start_connecting	(	const WiFiAP &	ap,
		bool	)

inline

Definition at line 331 of file wifi_component.h.

◆ start_initial_connection_()

void esphome::wifi::WiFiComponent::start_initial_connection_ ( )

protected

Start initial connection - either scan or connect directly to hidden networks.

Definition at line 310 of file wifi_component.cpp.

◆ start_scanning()

void esphome::wifi::WiFiComponent::start_scanning ( )

Definition at line 964 of file wifi_component.cpp.

◆ transition_to_phase_()

bool esphome::wifi::WiFiComponent::transition_to_phase_ ( WiFiRetryPhase new_phase )

protected

Transition to a new retry phase with logging Returns true if a scan was started (caller should wait), false otherwise.

Transition from current retry phase to a new phase with logging and phase-specific setup This function handles the actual state change, including:

Logging the phase transition
Resetting the retry counter
Performing phase-specific initialization (e.g., advancing AP index, starting scans)

Parameters

new_phase The phase we're transitioning TO

Returns: true if connection attempt should be skipped (scan started or no networks to try) false if caller can proceed with connection attempt

Definition at line 1380 of file wifi_component.cpp.

◆ went_through_explicit_hidden_phase_()

bool esphome::wifi::WiFiComponent::went_through_explicit_hidden_phase_ ( ) const

protected

Check if we went through EXPLICIT_HIDDEN phase (first network is marked hidden) Used in RETRY_HIDDEN to determine whether to skip explicitly hidden networks.

Definition at line 168 of file wifi_component.cpp.

◆ wifi_ap_ip_config_()

bool esphome::wifi::WiFiComponent::wifi_ap_ip_config_ ( const optional< ManualIP > & manual_ip )

protected

Definition at line 777 of file wifi_component_esp8266.cpp.

◆ wifi_apply_hostname_()

bool esphome::wifi::WiFiComponent::wifi_apply_hostname_ ( )

protected

Definition at line 211 of file wifi_component_esp8266.cpp.

◆ wifi_apply_output_power_()

bool esphome::wifi::WiFiComponent::wifi_apply_output_power_ ( float output_power )

protected

Definition at line 641 of file wifi_component_esp8266.cpp.

◆ wifi_apply_power_save_()

bool esphome::wifi::WiFiComponent::wifi_apply_power_save_ ( )

protected

Definition at line 92 of file wifi_component_esp8266.cpp.

◆ wifi_bssid()

bssid_t esphome::wifi::WiFiComponent::wifi_bssid ( )

Definition at line 907 of file wifi_component_esp8266.cpp.

◆ wifi_disconnect_()

bool esphome::wifi::WiFiComponent::wifi_disconnect_ ( )

protected

Definition at line 729 of file wifi_component_esp8266.cpp.

◆ wifi_dns_ip_()

network::IPAddress esphome::wifi::WiFiComponent::wifi_dns_ip_ ( int num )

protected

Definition at line 938 of file wifi_component_esp8266.cpp.

◆ wifi_event_callback()

void esphome::wifi::WiFiComponent::wifi_event_callback ( System_Event_t * event )

staticprotected

Definition at line 517 of file wifi_component_esp8266.cpp.

◆ wifi_event_callback_() [1/2]

void esphome::wifi::WiFiComponent::wifi_event_callback_	(	arduino_event_id_t	event,
		arduino_event_info_t	info )

protected

Definition at line 274 of file wifi_component_libretiny.cpp.

◆ wifi_event_callback_() [2/2]

void esphome::wifi::WiFiComponent::wifi_event_callback_	(	arduino_event_id_t	event,
		arduino_event_info_t	info )

protected

◆ wifi_gateway_ip_()

network::IPAddress esphome::wifi::WiFiComponent::wifi_gateway_ip_ ( )

protected

Definition at line 937 of file wifi_component_esp8266.cpp.

◆ wifi_loop_()

void esphome::wifi::WiFiComponent::wifi_loop_ ( )

protected

Definition at line 939 of file wifi_component_esp8266.cpp.

◆ wifi_mode_()

bool esphome::wifi::WiFiComponent::wifi_mode_	(	optional< bool >	sta,
		optional< bool >	ap )

protected

Definition at line 51 of file wifi_component_esp8266.cpp.

◆ wifi_pre_setup_()

void esphome::wifi::WiFiComponent::wifi_pre_setup_ ( )

protected

Definition at line 664 of file wifi_component_esp8266.cpp.

◆ wifi_process_event_()

void esphome::wifi::WiFiComponent::wifi_process_event_ ( IDFWiFiEvent * data )

protected

Definition at line 712 of file wifi_component_esp_idf.cpp.

◆ wifi_rssi()

int8_t esphome::wifi::WiFiComponent::wifi_rssi ( )

Definition at line 928 of file wifi_component_esp8266.cpp.

◆ wifi_scan_done_callback_() [1/3]

void esphome::wifi::WiFiComponent::wifi_scan_done_callback_ ( )

protected

Definition at line 473 of file wifi_component_libretiny.cpp.

◆ wifi_scan_done_callback_() [2/3]

void esphome::wifi::WiFiComponent::wifi_scan_done_callback_ ( )

protected

◆ wifi_scan_done_callback_() [3/3]

void esphome::wifi::WiFiComponent::wifi_scan_done_callback_	(	void *	arg,
		STATUS	status )

protected

Definition at line 745 of file wifi_component_esp8266.cpp.

◆ wifi_scan_result()

void esphome::wifi::WiFiComponent::wifi_scan_result	(	void *	env,
		const cyw43_ev_scan_result_t *	result )

protected

Definition at line 139 of file wifi_component_pico_w.cpp.

◆ wifi_scan_start_()

bool esphome::wifi::WiFiComponent::wifi_scan_start_ ( bool passive )

protected

Definition at line 689 of file wifi_component_esp8266.cpp.

◆ wifi_soft_ap_ip()

network::IPAddress esphome::wifi::WiFiComponent::wifi_soft_ap_ip ( )

Definition at line 900 of file wifi_component_esp8266.cpp.

◆ wifi_ssid()

std::string esphome::wifi::WiFiComponent::wifi_ssid ( )

Definition at line 915 of file wifi_component_esp8266.cpp.

◆ wifi_ssid_to()

const char * esphome::wifi::WiFiComponent::wifi_ssid_to ( std::span< char, SSID_BUFFER_SIZE > buffer )

Write SSID to buffer without heap allocation.

Returns pointer to buffer, or empty string if not connected.

Definition at line 916 of file wifi_component_esp8266.cpp.

◆ wifi_sta_connect_()

bool esphome::wifi::WiFiComponent::wifi_sta_connect_ ( const WiFiAP & ap )

protected

Definition at line 240 of file wifi_component_esp8266.cpp.

◆ wifi_sta_connect_status_()

WiFiSTAConnectStatus esphome::wifi::WiFiComponent::wifi_sta_connect_status_ ( )

protected

Definition at line 671 of file wifi_component_esp8266.cpp.

◆ wifi_sta_ip_addresses()

network::IPAddresses esphome::wifi::WiFiComponent::wifi_sta_ip_addresses ( )

Definition at line 201 of file wifi_component_esp8266.cpp.

◆ wifi_sta_ip_config_()

bool esphome::wifi::WiFiComponent::wifi_sta_ip_config_ ( const optional< ManualIP > & manual_ip )

protected

Definition at line 130 of file wifi_component_esp8266.cpp.

◆ wifi_sta_pre_setup_()

bool esphome::wifi::WiFiComponent::wifi_sta_pre_setup_ ( )

protected

Definition at line 646 of file wifi_component_esp8266.cpp.

◆ wifi_start_ap_()

bool esphome::wifi::WiFiComponent::wifi_start_ap_ ( const WiFiAP & ap )

protected

Definition at line 847 of file wifi_component_esp8266.cpp.

◆ wifi_subnet_mask_()

network::IPAddress esphome::wifi::WiFiComponent::wifi_subnet_mask_ ( )

protected

Definition at line 936 of file wifi_component_esp8266.cpp.

Field Documentation

◆ action_started_

uint32_t esphome::wifi::WiFiComponent::action_started_

protected

Definition at line 618 of file wifi_component.h.

◆ ap_

WiFiAP esphome::wifi::WiFiComponent::ap_

protected

Definition at line 603 of file wifi_component.h.

◆ ap_setup_

bool esphome::wifi::WiFiComponent::ap_setup_ {false}

protected

Definition at line 645 of file wifi_component.h.

◆ ap_started_

bool esphome::wifi::WiFiComponent::ap_started_ {false}

protected

Definition at line 646 of file wifi_component.h.

◆ ap_timeout_

uint32_t esphome::wifi::WiFiComponent::ap_timeout_ {}

protected

Definition at line 622 of file wifi_component.h.

◆ btm_

bool esphome::wifi::WiFiComponent::btm_ {false}

protected

Definition at line 650 of file wifi_component.h.

◆ configured_power_save_

WiFiPowerSaveMode esphome::wifi::WiFiComponent::configured_power_save_ {WIFI_POWER_SAVE_NONE}

protected

Definition at line 659 of file wifi_component.h.

◆ connect_state_listeners_

std::vector<WiFiConnectStateListener *> esphome::wifi::WiFiComponent::connect_state_listeners_

protected

Definition at line 609 of file wifi_component.h.

◆ connect_trigger_

Trigger* esphome::wifi::WiFiComponent::connect_trigger_ {new Trigger<>()}

protected

Definition at line 666 of file wifi_component.h.

◆ did_scan_this_cycle_

bool esphome::wifi::WiFiComponent::did_scan_this_cycle_ {false}

protected

Definition at line 656 of file wifi_component.h.

◆ disconnect_trigger_

Trigger* esphome::wifi::WiFiComponent::disconnect_trigger_ {new Trigger<>()}

protected

Definition at line 667 of file wifi_component.h.

◆ enable_on_boot_

bool esphome::wifi::WiFiComponent::enable_on_boot_ {true}

protected

Definition at line 653 of file wifi_component.h.

◆ error_from_callback_

bool esphome::wifi::WiFiComponent::error_from_callback_ {false}

protected

Definition at line 643 of file wifi_component.h.

◆ fast_connect_pref_

ESPPreferenceObject esphome::wifi::WiFiComponent::fast_connect_pref_

protected

Definition at line 614 of file wifi_component.h.

◆ got_ipv4_address_

bool esphome::wifi::WiFiComponent::got_ipv4_address_ {false}

protected

Definition at line 654 of file wifi_component.h.

◆ handled_connected_state_

bool esphome::wifi::WiFiComponent::handled_connected_state_ {false}

protected

Definition at line 642 of file wifi_component.h.

◆ has_ap_

bool esphome::wifi::WiFiComponent::has_ap_ {false}

protected

Definition at line 641 of file wifi_component.h.

◆ has_saved_wifi_settings_

bool esphome::wifi::WiFiComponent::has_saved_wifi_settings_ {false}

protected

Definition at line 648 of file wifi_component.h.

◆ high_performance_semaphore_

SemaphoreHandle_t esphome::wifi::WiFiComponent::high_performance_semaphore_ {nullptr}

protected

Definition at line 662 of file wifi_component.h.

◆ ip_state_listeners_

std::vector<WiFiIPStateListener *> esphome::wifi::WiFiComponent::ip_state_listeners_

protected

Definition at line 607 of file wifi_component.h.

◆ is_high_performance_mode_

bool esphome::wifi::WiFiComponent::is_high_performance_mode_ {false}

protected

Definition at line 660 of file wifi_component.h.

◆ keep_scan_results_

bool esphome::wifi::WiFiComponent::keep_scan_results_ {false}

protected

Definition at line 655 of file wifi_component.h.

◆ last_connected_

uint32_t esphome::wifi::WiFiComponent::last_connected_ {0}

protected

Definition at line 619 of file wifi_component.h.

◆ min_auth_mode_

WifiMinAuthMode esphome::wifi::WiFiComponent::min_auth_mode_ {WIFI_MIN_AUTH_MODE_WPA2}

protected

Definition at line 628 of file wifi_component.h.

◆ num_ipv6_addresses_

uint8_t esphome::wifi::WiFiComponent::num_ipv6_addresses_ {0}

protected

Definition at line 637 of file wifi_component.h.

◆ num_retried_

uint8_t esphome::wifi::WiFiComponent::num_retried_ {0}

protected

Definition at line 630 of file wifi_component.h.

◆ output_power_

float esphome::wifi::WiFiComponent::output_power_ {NAN}

protected

Definition at line 605 of file wifi_component.h.

◆ passive_scan_

bool esphome::wifi::WiFiComponent::passive_scan_ {false}

protected

Definition at line 647 of file wifi_component.h.

◆ power_save_

WiFiPowerSaveMode esphome::wifi::WiFiComponent::power_save_ {WIFI_POWER_SAVE_NONE}

protected

Definition at line 627 of file wifi_component.h.

◆ power_save_listeners_

std::vector<WiFiPowerSaveListener *> esphome::wifi::WiFiComponent::power_save_listeners_

protected

Definition at line 610 of file wifi_component.h.

◆ pref_

ESPPreferenceObject esphome::wifi::WiFiComponent::pref_

protected

Definition at line 612 of file wifi_component.h.

◆ reboot_timeout_

uint32_t esphome::wifi::WiFiComponent::reboot_timeout_ {}

protected

Definition at line 620 of file wifi_component.h.

◆ retry_phase_

WiFiRetryPhase esphome::wifi::WiFiComponent::retry_phase_ {WiFiRetryPhase::INITIAL_CONNECT}

protected

Definition at line 629 of file wifi_component.h.

◆ rrm_

bool esphome::wifi::WiFiComponent::rrm_ {false}

protected

Definition at line 651 of file wifi_component.h.

◆ scan_done_

bool esphome::wifi::WiFiComponent::scan_done_ {false}

protected

Definition at line 644 of file wifi_component.h.

◆ scan_result_

wifi_scan_vector_t<WiFiScanResult> esphome::wifi::WiFiComponent::scan_result_

protected

Definition at line 601 of file wifi_component.h.

◆ scan_results_listeners_

std::vector<WiFiScanResultsListener *> esphome::wifi::WiFiComponent::scan_results_listeners_

protected

Definition at line 608 of file wifi_component.h.

◆ selected_sta_index_

int8_t esphome::wifi::WiFiComponent::selected_sta_index_ {-1}

protected

Definition at line 634 of file wifi_component.h.

◆ skip_cooldown_next_cycle_

bool esphome::wifi::WiFiComponent::skip_cooldown_next_cycle_ {false}

protected

Definition at line 657 of file wifi_component.h.

◆ sta_

FixedVector<WiFiAP> esphome::wifi::WiFiComponent::sta_

protected

Definition at line 599 of file wifi_component.h.

◆ sta_priorities_

std::vector<WiFiSTAPriority> esphome::wifi::WiFiComponent::sta_priorities_

protected

Definition at line 600 of file wifi_component.h.

◆ state_

WiFiComponentState esphome::wifi::WiFiComponent::state_ {WIFI_COMPONENT_STATE_OFF}

protected

Definition at line 626 of file wifi_component.h.

The documentation for this class was generated from the following files:

esphome/components/wifi/wifi_component.h
esphome/components/wifi/wifi_component.cpp
esphome/components/wifi/wifi_component_esp8266.cpp
esphome/components/wifi/wifi_component_esp_idf.cpp
esphome/components/wifi/wifi_component_libretiny.cpp
esphome/components/wifi/wifi_component_pico_w.cpp

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ WiFiComponent()

Member Function Documentation

◆ add_connect_state_listener()

◆ add_ip_state_listener()

◆ add_power_save_listener()

◆ add_scan_results_listener()

◆ add_sta()

◆ advance_to_next_target_or_increment_retry_()

◆ all_networks_hidden_()

◆ build_params_for_current_phase_()

◆ can_proceed()

◆ check_connecting_finished()

◆ check_scanning_finished()

◆ clear_priorities_if_all_min_()

◆ clear_sta()

◆ connect_soon_()

◆ determine_next_phase_()

◆ disable()

◆ dump_config()

◆ enable()

◆ find_first_non_hidden_index_()

◆ find_next_hidden_sta_()

◆ get_ap()

◆ get_connect_trigger()

◆ get_disconnect_trigger()

◆ get_dns_address()

◆ get_ip_addresses()

◆ get_loop_priority()

◆ get_scan_result()

◆ get_selected_sta_()

◆ get_setup_priority()

◆ get_sta()

◆ get_sta_priority()

◆ get_use_address()

◆ get_wifi_channel()

◆ has_ap()

◆ has_sta()

◆ has_sta_priority()

◆ init_sta()

◆ is_ap_active()

◆ is_captive_portal_active_()

◆ is_connected()

◆ is_disabled()

◆ is_esp32_improv_active_()

◆ load_fast_connect_settings_()

◆ log_and_adjust_priority_for_failed_connect_()

◆ loop()

◆ needs_scan_results_()

◆ print_connect_params_()

◆ release_high_performance()

◆ request_high_performance()

◆ reset_selected_ap_to_first_if_invalid_()

◆ restart_adapter()

◆ retry_connect()

◆ s_wifi_scan_done_callback()

◆ s_wifi_scan_result()

◆ save_fast_connect_settings_()

◆ save_wifi_sta()

◆ set_ap()

◆ set_ap_timeout()

◆ set_btm()

◆ set_enable_on_boot()

◆ set_keep_scan_results()

◆ set_min_auth_mode()

◆ set_output_power()

◆ set_passive_scan()

◆ set_power_save_mode()

◆ set_reboot_timeout()

◆ set_rrm()

◆ set_sta()

◆ set_sta_priority()

◆ set_use_address()

◆ setup()

◆ setup_ap_config_()