[wifi] Clarify fast_connect behavior and add hidden network documentation

[bdraco]

Description:

This PR improves the WiFi component documentation to clarify the relationship between fast_connect and hidden network options:

1. Clarifies fast_connect behavior: Updated the description to explain that while fast_connect skips the initial scan, if the connection attempt fails, ESPHome will still perform a scan to find available networks. This addresses user confusion when devices with fast_connect: true still scan after failed connection attempts.

2. Adds guidance for hidden networks: Added a note explaining that users who want to completely skip scanning (e.g., for hidden networks) should use hidden: true on the network configuration.

3. Documents signal strength limitation: Added a tip warning that marking networks as hidden prevents ESPHome from finding the best access point by signal strength, which may result in connections to APs with weaker signals when multiple APs share the same SSID.

4. Adds example: Added a concrete YAML example showing how to configure a hidden network.

Related issue (if applicable): fixes esphome/esphome#12105

Pull request in esphome with YAML changes (if applicable):

• N/A (documentation only)

Checklist:

• I am merging into next because this is new documentation that has a matching pull-request in esphome as linked above.
  or

• I am merging into current because this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.

• Link added in /components/index.rst when creating new documents for new components or cookbook.

[netlify]

✅ Deploy Preview for esphome ready!

Name	Link
🔨 Latest commit	d642ab9
🔍 Latest deploy log	https://app.netlify.com/projects/esphome/deploys/69270dd58f8460000879b945
😎 Deploy Preview	https://deploy-preview-5682--esphome.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

Pull request overview

This PR improves WiFi component documentation by clarifying the behavior of fast_connect and adding comprehensive guidance for hidden network configuration. The changes address user confusion about when scanning occurs and provide clear instructions for properly configuring hidden networks.

Key changes:

• Corrected fast_connect description to remove the misleading claim that it's required for hidden networks
• Added clarification that ESPHome still scans after failed connection attempts even with fast_connect enabled
• Documented the proper use of hidden: true for hidden networks with warnings about signal strength limitations

---

You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.

[coderabbitai]

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Walkthrough

Documentation for the WiFi component clarifies fast_connect and hidden network behavior, adds notes about fallback scan behavior when fast_connect fails, includes TIPs about signal-selection trade-offs for hidden SSIDs, and adds YAML examples showing how to configure hidden networks.

Changes

Cohort / File(s)

Summary

Documentation — WiFi hidden networks content/components/wifi.md

Removed the statement that fast_connect is required for hidden networks and changed wording to say it "can significantly improve connection times". Added a note explaining that if a fast_connect attempt fails ESPHome will still perform a scan and that hidden: true should be used for reliable behavior; noted that marking networks as hidden can influence signal-quality selection when multiple APs share an SSID. Inserted a TIP about weaker signal selection with hidden SSIDs, reorganized content, and added YAML examples demonstrating connecting to hidden networks.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Verify accuracy of the new note/TIP against actual WiFi connection behavior.
• Check YAML examples for correct syntax and typical parameter usage.
• Confirm phrasing about fast_connect and fallback scanning matches implementation.

Suggested reviewers

• kbx81

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Linked Issues check	❓ Inconclusive	The PR addresses issue #12105 by providing documentation clarifying fast_connect behavior and hidden network handling, though it is documentation-only rather than implementing code fixes for the underlying connection issues.	While documentation improves user understanding, verify whether documentation alone adequately addresses the intermittent connection failures reported in #12105 or if code fixes are also required.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and specifically describes the main changes: clarifying fast_connect behavior and adding documentation for hidden networks, which aligns with the changeset.
Description check	✅ Passed	The description is well-structured and directly related to the changeset, explaining the documentation improvements for fast_connect and hidden network configurations.
Out of Scope Changes check	✅ Passed	All changes remain within the scope of updating WiFi component documentation to clarify fast_connect and hidden network behavior; no unrelated modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch wifi_hidden_docs

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions:
   | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context.
   Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

content/components/wifi.md (1)

110-111: Consolidate signal strength phrasing for consistency.

The same limitation about connecting to weaker APs is described with two different phrasings:

• Line 111: "may not connect to the AP with the best signal strength"
• Lines 312-313: "potentially resulting in connections to APs with weaker signals"

While both convey the same idea, using a consistent phrase across both the NOTE and TIP blocks would improve clarity. Consider aligning them to use one consistent wording (ideally the clearer "may not connect to the AP with the best signal strength" as suggested in the prior review).

Apply this diff to align the phrasing in the TIP block:

- 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.
+ Note that when connecting to a hidden network, ESPHome cannot determine which access point has the best signal strength and may not connect to the AP with the best signal when multiple APs share the same SSID.

Also applies to: 309-313

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between afe8450 and d642ab9.

📒 Files selected for processing (1)

• content/components/wifi.md (2 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**

⚙️ CodeRabbit configuration file

• Do not generate or add any sequence diagrams

Files:

• content/components/wifi.md

🧠 Learnings (1)

📚 Learning: 2025-05-12T00:02:50.869Z

Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 4901
File: changelog/2025.4.0.rst:124-126
Timestamp: 2025-05-12T00:02:50.869Z
Learning: In the ESPHome changelog structure, the "All changes" section should have the `:open:` attribute to be expanded by default, but the "Dependency Changes" section should NOT have this attribute as it should remain collapsed by default.

Applied to files:

• content/components/wifi.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Build

🔇 Additional comments (2)

content/components/wifi.md (2)

99-111: Clarified fast_connect behavior and fallback scan behavior is accurate.

The removal of "required for hidden networks" is correct since hidden: true is the recommended approach. The NOTE block properly explains that fast_connect still performs a scan on connection failure and directs hidden network users to use the hidden: true configuration option.

---

320-328: Hidden network example is clear and helpful.

The YAML example properly demonstrates the configuration of a hidden network with the hidden: true flag and complements the preceding documentation well.