WiFi Component
This core ESPHome component sets up WiFi connections to access points for you. You need to have a network configuration (such as WiFi or Ethernet) or ESPHome will fail in the config validation stage.
On ESP32 family devices, WiFi may be configured alongside Ethernet in the same
configuration; this requires a network: priority: list naming both interfaces — see
Multi-Interface Support on the Network
component. Using more than one network interface is not supported on other platforms.
An access point alone can run next to Ethernet or a Modem without a
priority: list; with ap_mode: wisp the devices that join it reach the network through the Ethernet or cellular
connection, see WISP Mode.
It’s recommended to provide a static IP for your node, as it can dramatically improve connection times.
# Example configuration entrywifi: ssid: MyHomeNetwork password: VerySafePassword
# Optional manual IP manual_ip: static_ip: 192.168.0.123 gateway: 192.168.0.1 subnet: 255.255.255.0# It is highly recommended to use secretswifi: ssid: !secret wifi_ssid password: !secret wifi_passwordTIP
For WiFi security recommendations including min_auth_mode configuration, see the Security Best Practices guide.
Configuration variables
Section titled “Configuration variables”-
ssid (Optional, string): The name (or service set identifier) of the WiFi access point your device should connect to.
-
password (Optional, string): The password (or PSK) for your WiFi network. Leave empty for no password.
-
hidden (Optional, boolean): Set to
trueif the network does not broadcast its SSID. Only for the single-network shorthand and requiresssidto be set; withnetworks, sethiddenon the network entry instead. Defaults tofalse. See Connecting to a Hidden Network. -
networks (Optional): Configure multiple WiFi networks to connect to, the best one that is reachable will be connected to. See Connecting to Multiple Networks.
-
manual_ip (Optional): Manually configure the static IP of the node.
- static_ip (Required, IPv4 address): The static IP of your node.
- gateway (Required, IPv4 address): The gateway of the local network.
- subnet (Required, IPv4 address): The subnet of the local network.
- dns1 (Optional, IPv4 address): The main DNS server to use.
- dns2 (Optional, IPv4 address): The backup DNS server to use.
-
use_address (Optional, string): Manually override what address to use to connect to the ESP. Defaults to auto-generated value. Example, if you have changed your static IP and want to flash OTA to the previously configured IP address.
-
ap (Optional): Enable an access point mode on the node.
-
ssid (Optional, string): The name of the access point to create. Leave empty to use the device name.
-
password (Optional, string): The password for the access point. Leave empty for no password.
-
channel (Optional, int): The channel the AP should operate on from 1 to 14. Defaults to 1.
-
manual_ip (Optional): Manually set the IP options for the AP. Same options as manual_ip for station mode.
-
ap_timeout (Optional, Time): The time after which to enable the configured fallback hotspot. Can be disabled by setting this to
0s, which requires manually starting the AP by other means (eg: from a button press). Defaults to90s. Withap_mode: always_onorwisp, it is instead the wait before a failed start is tried again, and0sis rejected. -
ap_mode (Optional, string): One of
fallback,always_onorwisp. Defaults tofallback, which starts the access point only when no connection to the WiFi router can be made.always_onkeeps the access point up at all times, see Always-On Access Point.wispalso passes the traffic of its clients on to the internet, see WISP Mode.always_onandwispare ESP32 only. -
dns_servers (Optional, list of IPv4 addresses): The DNS servers handed out to clients of the access point. Only valid with
ap_mode: wisp. Accepts one server, or two with ESP-IDF 6.0 or newer. If not set, the DNS servers of the upstream connection are passed on to the clients.
-
-
domain (Optional, string): Set the domain of the node hostname used for uploading. For example, if it’s set to
.local, all uploads will be sent to<HOSTNAME>.local. Defaults to.local. -
reboot_timeout (Optional, Time): The amount of time to wait before rebooting when no WiFi connection exists. Can be disabled by setting this to
0s, but note that the low level IP stack currently seems to have issues with WiFi where a full reboot is required to get the interface back working. Defaults to15min. The device does not reboot while a client (for example a phone) is connected to its fallback access point, or when no networks are configured. RTL87xx and LN882x boards cannot detect connected clients, so on those boards the device does not reboot while the fallback access point is up. -
power_save_mode (Optional, string): The power save mode for the WiFi interface. See Power Save Mode
-
output_power (Optional, string): The amount of TX power for the WiFi interface from 8.5dB to 20.5dB. Default for ESP8266 is 20dB, 20.5dB might cause unexpected restarts.
-
fast_connect (Optional, boolean): If enabled, directly connects to WiFi network without doing a full scan first. This can significantly improve connection times (thus reducing power consumption). Defaults to
off. The downside is that this option connects to the first network the ESP sees, even if that network is very far away and better ones are available. If multiple networks are configured, the last successfully connected one is tested first. In case it fails, all networks are then tested one after the other in their declared order, starting with the first one in the list.Instead of a boolean, this option also accepts a settings block:
wifi:# ...fast_connect:enabled: truestorage: rtc-
enabled (Optional, boolean): Whether fast connect is active. Defaults to
truewhen the block form is used. -
storage (Optional, string): Where to persist the connection details (BSSID and channel) that fast connect saves after each successful connection. One of:
flash: survives power loss but wears flash a little on each save.rtc: stored in RTC memory, which survives software reboots and deep sleep but not power loss, and avoids flash wear. A good fit for battery-powered devices that wake from deep sleep frequently.
Defaults to
rtcon ESP8266 andflashon ESP32, matching each platform’s previous behavior.rtcis available on ESP32 (except the C2 and C61 variants, which have no RTC memory), ESP8266 and the Beken BK7231T, BK7231N and BK7238; elsewhere onlyflashis available andrtcis rejected. These Beken chips have no RTC memory: therertckeeps the details in flash and forgets them after a power cut, so it does not avoid flash wear.
NOTE
While
fast_connectskips the initial scan, if the connection attempt fails, ESPHome will still perform a scan to find available networks. For hidden networks, sethidden: true(see Connecting to a Hidden Network) to ensure the device always connects without scanning. Be aware that marking networks as hidden prevents ESPHome from finding the best access point to connect to, so the device may not connect to the AP with the best signal strength. -
-
lease_cache (Optional): Only on
esp32with the ESP-IDF framework. Remembers the DHCP lease the device is assigned and, on the next boot, re-applies it as a static IP without running DHCP while it is still valid. This skips the DHCP handshake, so the network is usable in milliseconds. It is most useful for battery-powered devices that wake from deep sleep frequently. Disabled by default. Accepts a boolean, or a settings block:wifi:# ...lease_cache:storage: rtcmax_age: 12h-
enabled (Optional, boolean): Whether the lease cache is active. Defaults to
truewhen the block form is used. -
storage (Optional, string): Where to persist the cached lease. One of:
rtc: stored in RTC memory, which survives software reboots and deep sleep but not power loss, and avoids flash wear. This is the default where RTC memory is available.flash: survives power loss, but wears flash, so it must be selected explicitly. The lease is written again whenever its details change. After a power cycle the device cannot age the stored lease (see the note below), so it runs DHCP and writes the lease once more before the cache is useful again.
The ESP32-C2 and C61 variants have no RTC memory, so
storage: flashmust be set to use the cache on them. Without it, the configuration is rejected. -
max_age (Optional, Time): Do not re-use a cached lease older than this, regardless of the lease length the DHCP server granted. By default there is no extra limit, and a cached lease is re-used until its renewal deadline.
NOTE
A cached lease is only re-applied after a deep-sleep wake or a software reboot, where the device can measure how much time has passed; after a power cycle it cannot, so it falls back to a normal DHCP request. A user-configured
manual_ipalways takes precedence and disables the cache.If the device is still awake when a cached lease reaches its renewal deadline (about half the lease by default), it requests a new address over DHCP. This drops the address for a moment, so open connections such as the native API or MQTT may drop and reconnect.
WARNING
A cached lease is re-applied without checking that the address is still free. If the network behind the SSID changes — the router is replaced or moved to a different subnet, or the DHCP server forgets the lease and reassigns the address — the cached address may be wrong or clash with another device. An awake device recovers at the lease’s renewal deadline (about half the lease by default) by falling back to DHCP; a deep-sleep device only re-checks on each wake, so it can keep applying a stale address until the lease ages past that deadline. Use
max_ageto bound this window, or amanual_ipif the address must never be stale. -
-
min_auth_mode (Optional, string): Only on
esp32andesp8266. Sets the minimum WiFi authentication mode that the device will accept when connecting to access points. This controls the weakest encryption your device will allow. Possible values are:WPA- Allows WPA, WPA2, and WPA3 networks (least secure, uses TKIP encryption with known vulnerabilities)WPA2- Allows WPA2 and WPA3 networks (recommended, uses AES encryption)WPA3- Only allows WPA3 networks (most secure, ESP32 only)
Defaults to
WPA2on ESP32 and ESP8266.Security Warning: Setting
min_auth_mode: WPAallows connection to networks using deprecated WPA/TKIP encryption, which has known security vulnerabilities. Only use this setting for legacy routers that cannot be upgraded to WPA2 or WPA3. If your router supports WPA2 or newer, use the defaultWPA2setting for better security. -
passive_scan (Optional, boolean): If enabled, then the device will perform WiFi scans in a passive fashion. Defaults to
false. -
enable_btm (Optional, bool): Only on
esp32. Enable 802.11v BSS Transition Management support. -
enable_rrm (Optional, bool): Only on
esp32. Enable 802.11k Radio Resource Management support. -
band_mode (Optional, string): Only on
esp32-c5. Controls which WiFi frequency band the device uses. Possible values areAUTO(use both 2.4 GHz and 5 GHz),2.4GHZ(2.4 GHz only), and5GHZ(5 GHz only). If not specified, it defaults toAUTO. -
phy_mode (Optional, string): Only on
esp8266. Pins the radio to a specific 802.11 PHY mode. Possible values areAUTO,11B,11G, and11N. Defaults toAUTO, which leaves the SDK at its default behavior. There is a known compatibility issue with some routers when ESP8266 devices use 802.11n; you can work around it by limiting the ESP to 802.11g withphy_mode: 11G. -
post_connect_roaming (Optional, bool): Enable basic post-connect roaming for stationary devices. After connecting to a non-hidden network, the device will periodically check for better access points with the same SSID and switch if one is found with significantly better signal (+10 dB). This helps devices recover from scenarios where they connect to a suboptimal AP (e.g., after an AP reboot or site power loss). Automatically disabled if
enable_btmorenable_rrmis enabled. See Post-Connect Roaming. Set tofalsewithap_mode: always_on, see Always-On Access Point. Defaults totrue. -
dpp (Optional): Let a phone provision the network with Wi-Fi Easy Connect. ESP32 only. See Wi-Fi Easy Connect.
- channels (Optional, list of int): The channels the device listens on for a configurator. Defaults to
[6]. - device_info (Optional, string): Free text carried in the URI, such as a serial number, that some configurators show. It cannot contain spaces.
- private_key (Optional, string): The bootstrapping private key, 32 bytes written as 64 hexadecimal characters. A new key is generated on every boot when it is left out, so the URI, and with it the QR code, changes with each boot.
- timeout (Optional, Time): How long the configured or saved networks
are tried before the device listens for a configurator. The device then listens during each pause between
connection attempts. Without any network it listens from boot, and listens again at most once per
timeoutafter an attempt that did not finish. Defaults to1min.
- channels (Optional, list of int): The channels the device listens on for a configurator. Defaults to
-
on_ap_start (Optional, Automation): An action to be performed when the access point starts. Requires
ap:to be configured. -
on_ap_stop (Optional, Automation): An action to be performed when the access point stops. Requires
ap:to be configured. -
on_connect (Optional, Automation): An action to be performed when a connection is established.
-
on_disconnect (Optional, Automation): An action to be performed when the connection is dropped.
-
on_dpp_uri (Optional, Automation): An action to be performed when the Wi-Fi Easy Connect URI is ready, available as
uriof typeconst char *. Requiresdpp. -
enable_on_boot (Optional, boolean): If enabled, the WiFi interface will be enabled on boot. Defaults to
true. -
use_psram (Optional, boolean): For ESP32 only, requests that the WiFi libraries try to allocate memory from PSRAM. Defaults to
false. Requires PSRAM to be configured. -
id (Optional, ID): Manually specify the ID used for code generation.
Access Point Mode
Section titled “Access Point Mode”ESPHome has an optional “Access Point Mode”. If you include ap:
in your wifi configuration, ESPHome will automatically set up an access point that you
can connect to. Additionally, you can specify both a “normal” station mode and AP mode at the
same time. By default, this will cause ESPHome to only enable the access point when no connection
to the WiFi router can be made, also after a connection that was established and then lost. The exception is a device
whose provisioning window has closed: that shuts the access point down until the next
restart. On ESP32, the access point can stay up at all times instead, see
Always-On Access Point and WISP Mode.
wifi: ap: ssid: "Livingroom Fallback Hotspot" password: "W1PBGyrokfLz"You can also create a simple ap config which will set up the access point to have the
devices name as the ssid with no password.
wifi: ap: {}
# or if you still want the ap to have a password
wifi: ap: password: "W1PBGyrokfLz"For a device that only ever uses its access point, add web_server:
to control it from a phone without any internet connection.
Always-On Access Point
Section titled “Always-On Access Point”With ap_mode: always_on, an ESP32 starts its access point at boot and keeps it up at all times, also while it is
connected to the router. Devices that join the access point can reach the node, but not the router or the internet; use
WISP Mode for that.
wifi: ssid: !secret wifi_ssid password: !secret wifi_password post_connect_roaming: false ap: ssid: "Livingroom Hotspot" password: "W1PBGyrokfLz" ap_mode: always_on
captive_portal:Notes:
- Requires an ESP32 and an upstream connection: a WiFi network (
ssidornetworks), Ethernet or a Modem. - Set
post_connect_roaming: false, because a roaming scan would take the access point down. This is only optional when no WiFi network can be added at run time (nonetworks, DPP, captive portal or Improv). - With Captive Portal (or the captive mode of the web server), the portal is shown only while the node is not connected to the router: 10 seconds after the connection is lost, or at once when there are no WiFi networks. Once the provisioning window has closed, the portal is not shown again.
- The ESP32 has one radio, so the access point always uses the channel of the router. When that channel changes, clients of the access point can be briefly disconnected.
WISP Mode
Section titled “WISP Mode”With ap_mode: wisp an ESP32 runs an access point whose clients get an address from the node and have their
traffic routed (NAT) through an upstream connection: the router it joins as a station, which makes the node a
WiFi repeater, Ethernet or a cellular Modem.
wifi: networks: - ssid: "Router SSID" password: "Router password" ap: ssid: "Repeater" password: "W1PBGyrokfLz" ap_mode: wispWithout networks, the upstream is Ethernet or a Modem instead of the
router: with Ethernet or the modem configured as described on its page, only the access point is added. Unless
dns_servers or captive_portal is set, it starts once the Ethernet or cellular connection has an address and DNS
servers, and the clients are routed through it.
wifi: ap: ssid: "Bridge" password: "W1PBGyrokfLz" ap_mode: wispWith a modem, all the clients’ traffic goes through the serial link to the modem, so set a high baud_rate on the
modem if it supports one (for example 3686400). Even then, the link is much slower than Ethernet or WiFi, so this
access point is meant for other ESPHome nodes that send little data, for example over MQTT, rather than for phones or
laptops used to browse the web or for other heavy use.
Notes:
- Requires an ESP32, a password for the access point, and an upstream connection: a WiFi network (
ssidornetworks), Ethernet or a modem. - Without
dns_serversorcaptive_portal, the access point starts only once the upstream connection is up and its DNS servers are known. A network or an Ethernet connection withmanual_ipmust then setdns1. - WISP mode enlarges the Wi-Fi driver buffers and enables frame aggregation, the Wi-Fi half of
high performance networking; the TCP settings stay at their
defaults since the forwarded traffic never uses the node’s own connections. Keeping the lwIP fast paths in IRAM
raises throughput further at the cost of about 10 KB of IRAM: set
CONFIG_LWIP_IRAM_OPTIMIZATION: yin the esp32sdkconfig_options. - If the node is close to the router, a lower
output_power(for example8.5dB) and pinningbssidon the network can improve speed noticeably. - The number of clients is limited by the ESP32 access point (five at the same time).
WISP Mode with a Captive Portal
Section titled “WISP Mode with a Captive Portal”Add captive_portal: to let clients of the access point enter new router credentials, for example after the
router password changed:
wifi: networks: - ssid: "Router SSID" password: "Router password" ap: ssid: "Repeater" password: "W1PBGyrokfLz" ap_mode: wisp
captive_portal:The access point then starts without waiting for the upstream connection, and the portal is shown while the router
connection is down, as with an always-on access point. dns_servers cannot be combined
with captive_portal in WISP mode.
While the portal is shown, or while the upstream connection has no DNS servers, clients use the node as their DNS server so that they reach the portal. When this changes, clients are briefly disconnected to pick up the new DNS server.
Wi-Fi Easy Connect
Section titled “Wi-Fi Easy Connect”On the ESP32, dpp lets a phone provision the network with Wi-Fi Easy Connect, the Device Provisioning Protocol: the
device publishes a bootstrapping URI, which is shown as a QR code, and a configurator such as the Android Wi-Fi
settings scans it and sends the credentials. The device saves them and connects, and keeps using them on later boots
like credentials entered on the captive portal. The device listens for a configurator right away when it has no
network, neither configured nor saved, and otherwise once those networks have failed for timeout.
# Example configuration entrywifi: dpp: channels: [1, 6, 11] on_dpp_uri: - lambda: id(my_qr_code).set_value(uri);The QR Code display component renders the URI from on_dpp_uri once a lambda passes it to
set_value().
User Entered Credentials
Section titled “User Entered Credentials”Some components such as Captive Portal, Improv Serial, Improv via BLE and Wi-Fi Easy Connect enable the user to send and save Wi-Fi credentials to the device. Beginning in 2022.11.0, as long as no credentials are set in the config file, and firmware is uploaded without erasing the flash (via OTA), the device will keep the saved credentials.
Manual IPs
Section titled “Manual IPs”If you’re having problems with your node not connecting to WiFi or the connection process taking a long time, it can be a good idea to assign a static IP address to the ESP. This way, the ESP doesn’t need to go through the slow DHCP process.
You can do so with the manual_ip: option in the WiFi configuration.
wifi: # ... manual_ip: # Set this to the IP of the ESP static_ip: 10.0.0.42 # Set this to the IP address of the router. Often ends with .1 gateway: 10.0.0.1 # The subnet of the network. 255.255.255.0 works for most home networks. subnet: 255.255.255.0After putting a manual IP in your configuration, the ESP will no longer need to negotiate a dynamic IP address with the router, thus improving the time until connection.
Additionally, this can help with Ota if for example the
network doesn’t allow for .local addresses. When a manual IP is in your configuration,
the OTA process will automatically choose that as the target for the upload.
NOTE
See also Changing ESPHome Node Name.
Power Save Mode
Section titled “Power Save Mode”The WiFi interface of all ESPs offer three power save modes to reduce the amount of power spent on WiFi. While some options can reduce the power usage of the ESP, they generally also decrease the reliability of the WiFi connection, with frequent disconnections from the router in the highest power saving mode.
NONE(least power saving, Default for ESP8266, BK72xx, RTL87xx and LN882x)LIGHT(Default for ESP32 and RP2040)HIGH(most power saving)
wifi: # ... power_save_mode: noneWiFi Authentication Mode
Section titled “WiFi Authentication Mode”The min_auth_mode option allows you to control the minimum WiFi security standard your device will accept.
This is useful for ensuring your device only connects to secure networks, or for maintaining compatibility with
legacy routers that only support older encryption standards.
Example: Maximum Security (WPA2 or newer)
Section titled “Example: Maximum Security (WPA2 or newer)”wifi: ssid: MyHomeNetwork password: VerySafePassword min_auth_mode: WPA2 # Reject WPA-only networksExample: Legacy Router Support (WPA allowed)
Section titled “Example: Legacy Router Support (WPA allowed)”wifi: ssid: OldRouter password: VerySafePassword min_auth_mode: WPA # Allow connection to WPA-only routers (less secure)Example: Modern Security (WPA3 only, ESP32 only)
Section titled “Example: Modern Security (WPA3 only, ESP32 only)”wifi: ssid: ModernRouter password: VerySafePassword min_auth_mode: WPA3 # Only connect to WPA3 networks (most secure)Post-Connect Roaming
Section titled “Post-Connect Roaming”Post-connect roaming provides basic roaming for stationary devices that don’t move but may benefit from switching to a better access point after initial connection.
Why This Feature Exists
Section titled “Why This Feature Exists”Without post-connect roaming, devices can get stuck on a suboptimal AP permanently in three common scenarios:
-
AP reboot: When an access point reboots (firmware update or other reason), the device connects to another AP with worse signal. Without roaming, it stays on the worse AP permanently, never returning to the original better AP even after it comes back online.
-
Full site power loss: When power is restored after an outage, the device connects to whichever AP recovers first, which may be the worst option (e.g., the furthest one). Without roaming, it remains on this suboptimal AP permanently, even after better APs come online.
-
Out-of-box provisioning: When WiFi credentials are provisioned via captive portal, Improv, or other methods, the device connects without using ESPHome’s normal RSSI-based AP selection. Without roaming, the device stays on that initial AP forever even if a better one is available.
In all three cases, the only fix without post-connect roaming is to manually reboot the device or wait for another disconnection event.
How It Works
Section titled “How It Works”- After connecting to a non-hidden network, checks up to 3 times (every 5 minutes)
- Scans are skipped when signal is already excellent (> -49 dBm), but still count toward the limit
- Each scan may trigger a roam if an AP with the same SSID is found with +10 dB better signal
- After 3 checks, stops checking (device has converged to best available AP)
- A non-roaming disconnect (e.g., AP goes down) resets the counter for a fresh start
- Clears all BSSID priority penalties after successful connection (forgives past failures)
Configuration
Section titled “Configuration”Post-connect roaming is enabled by default. To disable it:
wifi: ssid: !secret wifi_ssid password: !secret wifi_password post_connect_roaming: false802.11k/v Native Roaming
Section titled “802.11k/v Native Roaming”On ESP32, post-connect roaming is automatically disabled when enable_btm
or enable_rrm is configured, as these provide native 802.11k/v roaming
support:
wifi: ssid: !secret wifi_ssid password: !secret wifi_password enable_btm: true # 802.11v BSS Transition Management enable_rrm: true # 802.11k Radio Resource ManagementLimitations
Section titled “Limitations”Post-connect roaming provides basic roaming support and does not provide seamless handoff:
- TCP connections (including API) will briefly disconnect during the AP switch. Reconnection is typically fast but not transparent to clients.
For seamless 802.11k/v/r roaming, use ESP32 and configure enable_btm and
enable_rrm.
To trigger a roaming check immediately instead of waiting for the periodic check, use the
wifi.roam action.
Connecting to Multiple Networks
Section titled “Connecting to Multiple Networks”You can give ESPHome a number of WiFi networks to connect to. ESPHome will then attempt to connect to the one with the highest signal strength.
To enable this mode, remove the ssid and password options from your wifi configuration
and move everything under the networks key:
# Example configuration entrywifi: networks: - ssid: FirstNetworkToConnectTo password: VerySafePassword - ssid: SecondNetworkToConnectTo password: VerySafePassword # Other options # ...Configuration variables
Section titled “Configuration variables”-
ssid (Optional, string): The SSID or WiFi network name.
-
password (Optional, string): The password to use for authentication. Leave empty for no password.
-
manual_ip (Optional): Manually configure the static IP of the node when using this network. Note that when using different static IP addresses on each network, it is required to set
use_address, as ESPHome cannot infer to which network the node is connected.- static_ip (Required, IPv4 address): The static IP of your node.
- gateway (Required, IPv4 address): The gateway of the local network.
- subnet (Required, IPv4 address): The subnet of the local network.
- dns1 (Optional, IPv4 address): The main DNS server to use.
- dns2 (Optional, IPv4 address): The backup DNS server to use.
-
eap (Optional): See Enterprise Authentication.
-
channel (Optional, int): The channel of the network (1-14). If given, only connects to networks that are on this channel.
-
bssid (Optional, string): The connection’s BSSID (MAC address). BSSIDs must consist of six two-digit hexadecimal values separated by colon characters (“
:”). All letters must be in upper case. -
hidden (Optional, boolean): Whether this network is hidden. Defaults to false. If you add this option you also have to specify ssid.
TIP
Set
hidden: trueif your network does not broadcast its SSID. This ensures the device attempts to connect using hidden network mode without first scanning for visible networks. Note that when connecting to a hidden network, ESPHome cannot determine which access point has the best signal strength, potentially resulting in connections to APs with weaker signals when multiple APs share the same SSID. -
priority (Optional, int): The priority of this network (range: -128 to 127). The network with the highest priority is chosen. After each connection failure, the priority is decreased by one. If all tracked BSSIDs have identical priorities, they are automatically reset to 0 to start fresh. Defaults to
0.
Connecting to a Hidden Network
Section titled “Connecting to a Hidden Network”A hidden network does not broadcast its SSID, so ESPHome tries to connect to it directly before scanning.
wifi: ssid: MyHiddenNetwork password: VerySafePassword hidden: trueWith multiple networks, set hidden on the network entry instead:
wifi: networks: - ssid: MyHiddenNetwork password: VerySafePassword hidden: trueEnterprise Authentication
Section titled “Enterprise Authentication”WPA2_EAP Enterprise Authentication is supported on ESP32s and ESP8266s. In order to configure this feature you must use the Connecting to Multiple Networks style configuration. The ESP32 is known to work with PEAP, EAP-TTLS, and the certificate based EAP-TLS. These are advanced settings and you will usually need to consult your enterprise network administrator.
# Example EAP configurationwifi: networks: - ssid: EAP-TTLS_EnterpriseNetwork eap: username: bob password: VerySafePassword ttls_phase_2: mschapv2 - ssid: EAP-TLS_EnterpriseNetwork eap: identity: bob certificate_authority: ca_cert.pem certificate: cert.pem key: key.pemConfiguration variables
Section titled “Configuration variables”-
identity (Optional, string): The outer identity to pass to the EAP authentication server. This is required for EAP-TLS.
-
username (Optional, string): The username to present to the authenticating server.
-
password (Optional, string): The password to present to the authentication server. For EAP-TLS this password may be set to decrypt to private key instead.
-
certificate_authority (Optional, string): Path to a PEM encoded certificate to use when validating the authentication server.
-
certificate (Optional, string): Path to a PEM encoded certificate to use for EAP-TLS authentication.
-
key (Optional, string): Path to a PEM encoded private key matching
certificatefor EAP-TLS authentication. Optionally encrypted withpassword. -
ttls_phase_2 (Optional, string): The Phase 2 Authentication Method for EAP-TTLS. Can be
pap,eap,mschap,mschapv2orchap, defaults tomschapv2.
on_ap_start / on_ap_stop Trigger
Section titled “on_ap_start / on_ap_stop Trigger”These triggers run once when the access point has been set up successfully, and once when it stops. They
require ap: to be configured. An access point that fails to start does not fire on_ap_start.
wifi: # ... ap: password: !secret ap_password on_ap_start: - logger.log: "Access point started" on_ap_stop: - logger.log: "Access point stopped"on_connect / on_disconnect Trigger
Section titled “on_connect / on_disconnect Trigger”This trigger is activated when a WiFi connection is established or dropped.
wifi: # ... on_connect: - switch.turn_on: switch1 on_disconnect: - switch.turn_off: switch1Actions
Section titled “Actions”wifi.disable Action
Section titled “wifi.disable Action”This action turns off the WiFi interface on demand.
on_...: then: - wifi.disable:NOTE
Be mindful of the reboot timeouts set for both the API component and the WiFi component if you disable WiFi. If WiFi remains off for longer than the duration of either timeout, the device will reboot!
wifi.enable Action
Section titled “wifi.enable Action”This action turns on the WiFi interface on demand.
on_...: then: - wifi.enable:NOTE
The configuration option enable_on_boot can be set to false if you do not want wifi to be enabled on boot.
wifi.configure Action
Section titled “wifi.configure Action”This action connects to an SSID and password, optionally saving it in persistent memory so that the next time the WiFi interface is enabled, it will connect to the stored access point.
on_...: then: - wifi.configure: ssid: "MyHomeNetwork" password: "VerySafePassword" save: true timeout: 30000ms on_connect: - logger.log: "Connected to WiFi!" on_error: - logger.log: "Failed to connect to WiFi!"Configuration variables
Section titled “Configuration variables”-
ssid (Required, string, templatable): The name of the WiFi access point.
-
password (Required, string, templatable): The password of the WiFi access point. Leave empty for no password.
-
save (Optional, boolean, templatable): If set to
true, the SSID and password will be saved in persistent memory. Defaults totrue. -
timeout (Optional, Time, templatable): The time to wait for the connection to be established. Defaults to 30 seconds.
-
on_connect (Optional, Automation): An action to be performed when a connection is established.
-
on_error (Optional, Automation): An action to be performed when the connection fails.
wifi.roam Action
Section titled “wifi.roam Action”This action asks the WiFi component to check right away for a better access point on the current network, as described in Post-Connect Roaming. It skips the usual 5-minute wait between checks, but still only roams if a meaningfully stronger access point is actually found.
on_...: then: - wifi.roam:The action is ignored if the device is not currently connected, or if a roaming check is already in progress.
Conditions
Section titled “Conditions”wifi.connected Condition
Section titled “wifi.connected Condition”This Condition checks if the WiFi client is currently connected to a station.
on_...: if: condition: wifi.connected: then: - logger.log: WiFi is connected!The lambda equivalent for this is id(wifi_id).is_connected().
wifi.enabled Condition
Section titled “wifi.enabled Condition”This Condition checks if WiFi is currently enabled or not.
on_...: - if: condition: wifi.enabled then: - wifi.disable: else: - wifi.enable:The lambda equivalent for this is !id(wifi_id).is_disabled().
wifi.ap_active Condition
Section titled “wifi.ap_active Condition”This Condition checks if WiFi AP is currently active or not.
on_...: - if: condition: wifi.ap_active then: - logger.log: WiFi AP is active!The lambda equivalent for this is id(wifi_id).is_ap_active().