From fbe7739a86a28020a6a9e394a4e6f6caa6bad6fd Mon Sep 17 00:00:00 2001 From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com> Date: Wed, 27 May 2026 07:32:33 -0500 Subject: [PATCH] Fix broken Starter Kit nav links and clean up OPNsense mDNS page (#873) - first-steps: correct ../ depth on five md-button links and drop the .md from the using-secrets URL - connect-to-home-assistant: fix Back button depth and link the UniFi mDNS guide from Troubleshooting - opnsense mDNS page: replace mangled bold intro with a !!! tip admonition matching the UniFi page - homey opnsense copy: convert to a snippet wrapper so it inherits the main page --- .../opnsense-mdns-auto-discover-issue.md | 24 +------------------ .../ESPHome-Starter-Kit/setup/first-steps.md | 8 +++---- .../tutorials/connect-to-home-assistant.md | 4 ++-- .../opnsense-mdns-auto-discover-issue.md | 4 +++- 4 files changed, 10 insertions(+), 30 deletions(-) diff --git a/docs/homey/products/general/troubleshooting/opnsense-mdns-auto-discover-issue.md b/docs/homey/products/general/troubleshooting/opnsense-mdns-auto-discover-issue.md index f4562153ba..2c76f67665 100755 --- a/docs/homey/products/general/troubleshooting/opnsense-mdns-auto-discover-issue.md +++ b/docs/homey/products/general/troubleshooting/opnsense-mdns-auto-discover-issue.md @@ -1,23 +1 @@ ---- -title: OPNsense mDNS Auto Discover Issue -description: Tutorial to help fix the OPNsense mDNS Auto Discover Issue ---- -# OPNsense mDNS Auto Discover Issue - -**If mDNS is unchecked then Home Assistant and ESPHome will not auto discover new devices. Also, if you have different networks that Home Assistant and ESPHome devices are on, then you will need mDNS on both networks and firewall rules between them.** - -Install the mDNS Repeater - -1\. Click System -> Click Firmware -> Click Plugins -> Search for "mdns" -> Click the “+” symbol to install os-mdns-repeater. - -![](/assets/opnsense-mdns-guide-pic-1.png) - -2\. Confirm that the installation was successful. - -![](/assets/opnsense-mdns-guide-pic-2.png) - -3\. Refresh the page and then go to Services -> mDNS Repeater (if it isn't there after refreshing your screen, verify the plugin install was successful.)-> Check off "enable" -> select your networks containing Home Assistant / ESPHome IoT devices -> click save. - -![](/assets/opnsense-mdns-guide-pic-3.png) - -Now the Home Assistant/ESPHome auto-discover issue should be fixed! \ No newline at end of file +--8<-- "products/general/troubleshooting/opnsense-mdns-auto-discover-issue.md:5:" diff --git a/docs/products/ESPHome-Starter-Kit/setup/first-steps.md b/docs/products/ESPHome-Starter-Kit/setup/first-steps.md index d92495d263..6a49297d64 100755 --- a/docs/products/ESPHome-Starter-Kit/setup/first-steps.md +++ b/docs/products/ESPHome-Starter-Kit/setup/first-steps.md @@ -16,7 +16,7 @@ ESPHome Device Builder is the software that gives you a user interface for writi Think of it like telling the starter kit about what devices it has connected and how to use them! - Learn more about ESPHome + Learn more about ESPHome Pick the platform you'll be running ESPHome Device Builder on: @@ -114,7 +114,7 @@ Fill in your Wi-Fi network name (SSID) and Wi-Fi password then click Save creden !!! tip "Secrets Folder" - One popular option is to store your encryption keys here. That way, you can share your full YAML with other users without needing to edit and hide your encryption key. See our using secrets wiki for step by step directions! + One popular option is to store your encryption keys here. That way, you can share your full YAML with other users without needing to edit and hide your encryption key. See our using secrets wiki for step by step directions! ![](../../../assets/esphome-builder-enter-wifi-credentials.gif) @@ -188,7 +188,7 @@ Before we continue, confirm that you installed the ESPHome Device Builder, confi It's a great way to see what's happening under the hood. - Learn about Core Components + Learn about Core Components ### Test your LED @@ -202,4 +202,4 @@ Example of the light changing colors below! ![](../../../assets/esphome-starter-kit-onboard-rgb-led-light-up.webp) - Back - Start Here Add More Modules Connect to Home Assistant \ No newline at end of file + Back - Start Here Add More Modules Connect to Home Assistant \ No newline at end of file diff --git a/docs/products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md b/docs/products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md index fd33ee6e41..1e5aaff714 100644 --- a/docs/products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md +++ b/docs/products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md @@ -36,7 +36,7 @@ Toggle the **Onboard RGB LED** light entity and confirm the LED responds on the #### The device never appears under Discovered * Confirm Home Assistant is on the same Wi-Fi network as the device. -* Some routers and VLAN setups block mDNS broadcasts across subnets. Add the integration manually using the device's IP address. Look the IP up on your router's client list or in the **Device Information** section of the ESPHome Device Builder info panel. +* Some routers and VLAN setups block mDNS broadcasts across subnets. If you run UniFi, turning on mDNS in your network settings usually fixes this. See the [UniFi mDNS guide](../../general/troubleshooting/ubiquiti-unifi-mdns-auto-discover-issue.md). Otherwise, add the integration manually using the device's IP address. Look the IP up on your router's client list or in the **Device Information** section of the ESPHome Device Builder info panel. * The device's web page should still load at the hostname or IP. If it does not, the device is not reachable from your computer yet and Home Assistant will not find it either. #### The encryption key is rejected @@ -47,4 +47,4 @@ Open `secrets.yaml` in Device Builder, copy the `api_encryption_key` value, and Want to understand what just happened under the hood? Read [the Home Assistant integration](../learning-the-basics/how-esphome-talks-to-home-assistant.md). - Back - First Steps + Back - First Steps diff --git a/docs/products/general/troubleshooting/opnsense-mdns-auto-discover-issue.md b/docs/products/general/troubleshooting/opnsense-mdns-auto-discover-issue.md index afcf0beb22..92c91c1e18 100755 --- a/docs/products/general/troubleshooting/opnsense-mdns-auto-discover-issue.md +++ b/docs/products/general/troubleshooting/opnsense-mdns-auto-discover-issue.md @@ -4,7 +4,9 @@ description: Tutorial to help fix the OPNsense mDNS Auto Discover Issue --- # OPNsense mDNS Auto Discover Issue -\*\*If mDNS is unchecked then Home Assistant and ESPHome will not auto discover new devices. Also, if you have different networks that Home Assistant and ESPHome devices are on, then you will need mDNS on both networks and firewall rules between them. +!!! tip "If mDNS is unchecked then Home Assistant and ESPHome will not auto discover new devices" + + If you have different networks that Home Assistant and ESPHome devices are on, then you will need mDNS working across both networks and firewall rules allowing access between them. Below is a guide for installing the mDNS Repeater plugin on OPNsense to fix this issue. Install the mDNS Repeater