2018-05-13 11:37:02 +02:00
WiFi Component
==============
2018-11-14 22:12:27 +01:00
.. seo ::
2019-02-16 23:25:23 +01:00
:description: Instructions for setting up the WiFi configuration for your ESP node in ESPHome.
2018-11-19 18:32:16 +01:00
:image: network-wifi.png
2018-11-14 22:12:27 +01:00
:keywords: WiFi, WLAN, ESP8266, ESP32
2019-02-16 23:25:23 +01:00
This core ESPHome component sets up WiFi connections to access points
for you. It needs to be in your configuration or otherwise ESPHome
2018-05-13 11:37:02 +02:00
will fail in the config validation stage.
It’ s recommended to provide a static IP for your node, as it can
dramatically improve connection times.
2018-11-19 18:32:16 +01:00
.. code-block :: yaml
2018-05-13 11:37:02 +02:00
# Example configuration entry
wifi:
ssid: MyHomeNetwork
password: VerySafePassword
# Optional manual IP
manual_ip:
static_ip: 10.0.0.42
gateway: 10.0.0.1
subnet: 255.255.255.0
Configuration variables:
2018-08-24 22:44:01 +02:00
------------------------
2018-05-13 11:37:02 +02:00
2018-06-01 18:10:00 +02:00
- **ssid** (*Optional* , string): The name (or `service set
identifier <https://www.lifewire.com/definition-of-service-set-identifier-816547>`__)
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.
2019-01-06 18:56:14 +01:00
- **networks** (*Optional* ): Configure multiple WiFi networks to connect to, the best one
that is reachable will be connected to. See :ref: `wifi-networks` .
2018-06-01 18:10:00 +02:00
- **manual_ip** (*Optional* ): Manually configure the static IP of the node.
2018-05-13 11:37:02 +02:00
2021-02-20 22:02:46 +01:00
- **static_ip** (**Required** , IPv4 address): The static IP of your node.
2021-02-07 17:35:39 +01:00
- **gateway** (**Required** , IPv4 address): The gateway of the local network.
- **subnet** (**Required** , IPv4 address): The subnet of the local network.
2018-06-01 18:10:00 +02:00
- **dns1** (*Optional* , IPv4 address): The main DNS server to use.
- **dns2** (*Optional* , IPv4 address): The backup DNS server to use.
2018-05-13 11:37:02 +02:00
2019-02-16 23:25:23 +01:00
- **use_address** (*Optional* , string): Manually override what address to use to connect
2020-05-10 21:27:59 +02:00
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.
2019-06-19 11:42:30 +02:00
2018-06-01 18:10:00 +02:00
- **ap** (*Optional* ): Enable an access point mode on the node.
2018-05-13 11:37:02 +02:00
2021-02-07 17:35:39 +01:00
- **ssid** (**Required** , string): The name of the access point to create.
- **password** (*Optional* , string): The password for the access point. Leave empty for
2018-06-01 18:10:00 +02:00
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.
2019-07-28 12:41:15 +02:00
- **ap_timeout** (*Optional* , :ref: `time <config-time>` ): The time after which to enable the
configured fallback hotspot. Defaults to `` 1min `` .
2018-05-13 11:37:02 +02:00
2018-06-01 18:10:00 +02:00
- **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 `` .
2018-06-13 22:38:49 +02:00
- **reboot_timeout** (*Optional* , :ref: `time <config-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
2019-07-28 12:41:15 +02:00
seems to have issues with WiFi where a full reboot is required to get the interface back working. Defaults to `` 15min `` .
- **power_save_mode** (*Optional* , string): The power save mode for the WiFi interface.
2018-10-07 16:51:47 +02:00
See :ref: `wifi-power_save_mode`
2020-07-24 15:39:59 +02:00
2020-04-27 17:47:11 +02:00
- **output_power** (*Optional* , string): The amount of TX power for the WiFi interface from 10dB to 20.5dB. Default for ESP8266 is 20dB, 20.5dB might cause unexpected restarts.
2019-01-13 16:20:22 +01:00
- **fast_connect** (*Optional* , boolean): If enabled, directly connects to WiFi network without doing a full scan
first. This is required for hidden networks and can significantly improve connection times. Defaults to `` off `` .
2019-02-16 23:25:23 +01:00
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.
2018-06-01 18:10:00 +02:00
- **id** (*Optional* , :ref: `config-id` ): Manually specify the ID used for code generation.
2018-05-13 11:37:02 +02:00
Access Point Mode
2018-08-24 22:44:01 +02:00
-----------------
2018-05-13 11:37:02 +02:00
2019-02-16 23:25:23 +01:00
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
2018-05-13 11:37:02 +02:00
can connect to. Additionally, you can specify both a "normal" station mode and AP mode at the
2019-02-16 23:25:23 +01:00
same time. This will cause ESPHome to only enable the access point when no connection
2020-05-10 21:27:59 +02:00
to the WiFi router can be made.
2018-06-01 18:10:00 +02:00
2020-12-21 01:55:44 +01:00
.. code-block :: yaml
wifi:
ap:
ssid: "Livingroom Fallback Hotspot"
password: "W1PBGyrokfLz"
2018-10-07 10:04:14 +02:00
.. _wifi-manual_ip:
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.
2018-11-19 18:32:16 +01:00
.. code-block :: yaml
2018-10-07 10:04:14 +02:00
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.
2018-11-04 22:19:14 +01:00
Additionally, this can help with :doc: `Over-The-Air updates <ota>` if for example the
2018-10-07 10:04:14 +02:00
home 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.
2019-06-19 11:42:30 +02:00
.. note ::
See also :ref: `esphome-changing_node_name` .
2018-10-07 16:51:47 +02:00
.. _wifi-power_save_mode:
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.
2019-07-28 12:41:15 +02:00
- `` NONE `` (least power saving, Default for ESP8266)
- `` LIGHT `` (Default for ESP32)
2018-10-07 16:51:47 +02:00
- `` HIGH `` (most power saving)
2018-11-19 18:32:16 +01:00
.. code-block :: yaml
2018-10-07 16:51:47 +02:00
wifi:
# ...
power_save_mode: none
2019-01-06 18:56:14 +01:00
.. _wifi-networks:
Connecting to Multiple Networks
-------------------------------
2019-02-16 23:25:23 +01:00
Starting with version 1.10.0, 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.
2019-01-06 18:56:14 +01:00
To enable this mode, remove the `` ssid `` and `` password `` options from your wifi configuration
and move everything under the `` networks `` key:
.. code-block :: yaml
# Example configuration entry
wifi:
networks:
- ssid: FirstNetworkToConnectTo
password: VerySafePassword
- ssid: SecondNetworkToConnectTo
password: VerySafePassword
# Other options
# ...
Configuration variables:
2019-02-16 23:25:23 +01:00
- **ssid** (*Optional* , string): The SSID or WiFi network name.
- **password** (*Optional* , string): The password to use for authentication. Leave empty for no password.
2020-07-24 15:39:59 +02:00
- **eap** (*Optional* ): See :ref: `eap` .
2019-02-16 23:25:23 +01:00
- **channel** (*Optional* , int): The channel of the network (1-14). If given, only connects to networks
2019-01-06 18:56:14 +01:00
that are on this channel.
2019-02-16 23:25:23 +01:00
- **bssid** (*Optional* , string): Optionally define a BSSID (MAC-Address) of the network to connect to.
2019-01-06 18:56:14 +01:00
This can be used to further restrict which networks to connect to.
2019-02-16 23:25:23 +01:00
- **hidden** (*Optional* , boolean): Whether this network is hidden. Defaults to false.
If you add this option you also have to specify ssid.
2019-11-01 18:28:26 +01:00
- **priority** (*Optional* , float): The priority of this network. After each time, the network with
the highest priority is chosen. If the connection fails, the priority is decreased by one.
Defaults to `` 0 `` .
2019-01-06 18:56:14 +01:00
2020-07-24 15:39:59 +02:00
.. _eap:
Enterprise Authentication
-------------------------
2020-11-01 08:40:25 +01:00
WPA2_EAP Enterprise Authentication is supported on ESP32s and ESP8266s.
2020-07-24 15:39:59 +02:00
In order to configure this feature you must use the :ref: `wifi-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.
.. code-block :: yaml
# Example EAP configuration
wifi:
networks:
- ssid: EAP-TTLS_EnterpriseNetwork
eap:
username: bob
password: VerySafePassword
- ssid: EAP-TLS_EnterpriseNetwork
eap:
2020-12-21 01:55:44 +01:00
identity: bob
2020-07-24 15:39:59 +02:00
certificate_authority: ca_cert.pem
certificate: cert.pem
key: key.pem
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 `` certificate `` for EAP-TLS authentication.
Optionally encrypted with `` password `` .
2019-05-15 11:49:05 +02:00
.. _wifi-connected_condition:
2019-05-12 22:44:59 +02:00
`` wifi.connected `` Condition
----------------------------
This :ref: `Condition <config-condition>` checks if the WiFi client is currently connected to a station.
.. code-block :: yaml
on_...:
if:
condition:
wifi.connected:
then:
- logger.log: WiFi is connected!
2018-06-01 18:10:00 +02:00
See Also
--------
2019-07-28 12:41:15 +02:00
- :doc: `captive_portal`
2019-05-12 22:44:59 +02:00
- :apiref: `wifi/wifi_component.h`
2019-02-07 13:54:45 +01:00
- :ghedit: `Edit`