Skip to content
Get started

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 entry
wifi:
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 secrets
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password

TIP

For WiFi security recommendations including min_auth_mode configuration, see the Security Best Practices guide.

  • 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 true if the network does not broadcast its SSID. Only for the single-network shorthand and requires ssid to be set; with networks, set hidden on the network entry instead. Defaults to false. 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 to 90s. With ap_mode: always_on or wisp, it is instead the wait before a failed start is tried again, and 0s is rejected.

    • ap_mode (Optional, string): One of fallback, always_on or wisp. Defaults to fallback, which starts the access point only when no connection to the WiFi router can be made. always_on keeps the access point up at all times, see Always-On Access Point. wisp also passes the traffic of its clients on to the internet, see WISP Mode. always_on and wisp are 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 to 15min. 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: true
    storage: rtc
    • enabled (Optional, boolean): Whether fast connect is active. Defaults to true when 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 rtc on ESP8266 and flash on ESP32, matching each platform’s previous behavior. rtc is available on ESP32 (except the C2 and C61 variants, which have no RTC memory), ESP8266 and the Beken BK7231T, BK7231N and BK7238; elsewhere only flash is available and rtc is rejected. These Beken chips have no RTC memory: there rtc keeps the details in flash and forgets them after a power cut, so it does not avoid flash wear.

    NOTE

    While fast_connect skips the initial scan, if the connection attempt fails, ESPHome will still perform a scan to find available networks. For hidden networks, set hidden: 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 esp32 with 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: rtc
    max_age: 12h
    • enabled (Optional, boolean): Whether the lease cache is active. Defaults to true when 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: flash must 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_ip always 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_age to bound this window, or a manual_ip if the address must never be stale.

  • min_auth_mode (Optional, string): Only on esp32 and esp8266. 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 WPA2 on ESP32 and ESP8266.

    Security Warning: Setting min_auth_mode: WPA allows 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 default WPA2 setting 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 are AUTO (use both 2.4 GHz and 5 GHz), 2.4GHZ (2.4 GHz only), and 5GHZ (5 GHz only). If not specified, it defaults to AUTO.

  • phy_mode (Optional, string): Only on esp8266. Pins the radio to a specific 802.11 PHY mode. Possible values are AUTO, 11B, 11G, and 11N. Defaults to AUTO, 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 with phy_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_btm or enable_rrm is enabled. See Post-Connect Roaming. Set to false with ap_mode: always_on, see Always-On Access Point. Defaults to true.

  • 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 timeout after an attempt that did not finish. Defaults to 1min.
  • 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 uri of type const char *. Requires dpp.

  • 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.

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.

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 (ssid or networks), 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 (no networks, 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.

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: wisp

Without 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: wisp

With 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 (ssid or networks), Ethernet or a modem.
  • Without dns_servers or captive_portal, the access point starts only once the upstream connection is up and its DNS servers are known. A network or an Ethernet connection with manual_ip must then set dns1.
  • 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: y in the esp32 sdkconfig_options.
  • If the node is close to the router, a lower output_power (for example 8.5dB) and pinning bssid on the network can improve speed noticeably.
  • The number of clients is limited by the ESP32 access point (five at the same time).

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.

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 entry
wifi:
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().

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.

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.0

After 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.

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: none

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.

wifi:
ssid: MyHomeNetwork
password: VerySafePassword
min_auth_mode: WPA2 # Reject WPA-only networks

Example: 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 provides basic roaming for stationary devices that don’t move but may benefit from switching to a better access point after initial connection.

Without post-connect roaming, devices can get stuck on a suboptimal AP permanently in three common scenarios:

  1. 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.

  2. 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.

  3. 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.

  • 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)

Post-connect roaming is enabled by default. To disable it:

wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
post_connect_roaming: false

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 Management

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.

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 entry
wifi:
networks:
- ssid: FirstNetworkToConnectTo
password: VerySafePassword
- ssid: SecondNetworkToConnectTo
password: VerySafePassword
# Other options
# ...
  • 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: true if 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.

A hidden network does not broadcast its SSID, so ESPHome tries to connect to it directly before scanning.

wifi:
ssid: MyHiddenNetwork
password: VerySafePassword
hidden: true

With multiple networks, set hidden on the network entry instead:

wifi:
networks:
- ssid: MyHiddenNetwork
password: VerySafePassword
hidden: true

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 configuration
wifi:
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.pem
  • 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 certificate for EAP-TLS authentication. Optionally encrypted with password.

  • ttls_phase_2 (Optional, string): The Phase 2 Authentication Method for EAP-TTLS. Can be pap, eap, mschap, mschapv2 or chap, defaults to mschapv2.

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"

This trigger is activated when a WiFi connection is established or dropped.

wifi:
# ...
on_connect:
- switch.turn_on: switch1
on_disconnect:
- switch.turn_off: switch1

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!

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.

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!"
  • 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 to true.

  • 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.

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.

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().

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().

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().