Skip to content

[wifi] Clarify fast_connect behavior and add hidden network documentation #5682

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 28, 2025
Merged

[wifi] Clarify fast_connect behavior and add hidden network documentation #5682

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
afe8450
[wifi] Clarify fast_connect behavior and add hidden network documenta…
bdraco Nov 26, 2025
d642ab9
Update content/components/wifi.md
bdraco Nov 26, 2025
0e99fa9
Merge branch 'current' into wifi_hidden_docs
bdraco Nov 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 24 additions & 2 deletions content/components/wifi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,13 +97,19 @@ wifi:
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 is required for hidden networks and can significantly improve connection times (thus reducing power
consumption). Defaults to `off`.
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.

> [!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, use `hidden: true` on the network configuration (see
> [Connecting to Multiple Networks](#wifi-networks)) 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.

- **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:
Expand Down Expand Up @@ -300,11 +306,27 @@ wifi:
- **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`.

### Example: Connecting to a Hidden Network

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

{{< anchor "eap" >}}

## Enterprise Authentication
Expand Down