ApolloAutomation · bharvey88 · Jul 1, 2026 · Jul 1, 2026 · Jul 1, 2026
diff --git a/docs/_snippets/bluetooth-proxy/method1-air-1.md b/docs/_snippets/bluetooth-proxy/method1-air-1.md
@@ -1,7 +1,5 @@
 --8<-- "_snippets/bluetooth-proxy/method1-steps.md"
 
-5\. Copy the code inside the codeblock below.
-
 --8<-- "_snippets/bluetooth-proxy/air-1.md"
 
 --8<-- "_snippets/bluetooth-proxy/method1-finish.md"
diff --git a/docs/_snippets/bluetooth-proxy/method1-finish.md b/docs/_snippets/bluetooth-proxy/method1-finish.md
@@ -1,17 +1,11 @@
-6\. Paste the code as shown below directly below the yaml you just edited above. Make sure the spaces look the same and there are no red lines under any of the code.
+![](/assets/esphome-device-builder-add-ble-proxy-method-1-edit-yaml.gif)
 
-![](/assets/bluetooth-proxy-tutorial-9.png)
+5\. Click **Save** then **Install** in the bottom right. Click **On the network** when prompted.
 
-7\. Click save then Install in the top right.
+![](/assets/esphome-device-builder-add-ble-proxy-save-install.gif)
 
-![](/assets/bluetooth-proxy-tutorial-11.png)
+6\. When you see the purple lines the device has booted successfully and the logs will show the **Bluetooth Proxy** section. Click **Stop** in the bottom right and you're finished!
 
-8\. Click "Wirelessly" and let it finish compiling then installing.
+![](/assets/ble-proxy-install-completed.png)
 
-![](/assets/bluetooth-proxy-tutorial-6.png)
-
-9\. When you see this "OTA Successful" it has finished and you can click "Close" in the bottom right.
-
-![](/assets/bluetooth-proxy-tutorial-7.png)
-
-10\. You are finished and your Apollo device is now acting as a Bluetooth Proxy!
+--8<-- "_snippets/bluetooth-proxy/verify.md"
diff --git a/docs/_snippets/bluetooth-proxy/method1-msr-1.md b/docs/_snippets/bluetooth-proxy/method1-msr-1.md
@@ -1,7 +1,5 @@
 --8<-- "_snippets/bluetooth-proxy/method1-steps.md"
 
-5\. Copy the code inside the codeblock below.
-
 --8<-- "_snippets/bluetooth-proxy/msr-1.md"
 
 --8<-- "_snippets/bluetooth-proxy/method1-finish.md"
diff --git a/docs/_snippets/bluetooth-proxy/method1-msr-2.md b/docs/_snippets/bluetooth-proxy/method1-msr-2.md
@@ -1,7 +1,5 @@
 --8<-- "_snippets/bluetooth-proxy/method1-steps.md"
 
-5\. Copy the code inside the codeblock below.
-
 --8<-- "_snippets/bluetooth-proxy/msr-2.md"
 
 --8<-- "_snippets/bluetooth-proxy/method1-finish.md"
diff --git a/docs/_snippets/bluetooth-proxy/method1-mtr-1.md b/docs/_snippets/bluetooth-proxy/method1-mtr-1.md
@@ -1,7 +1,5 @@
 --8<-- "_snippets/bluetooth-proxy/method1-steps.md"
 
-5\. Copy the code inside the codeblock below.
-
 --8<-- "_snippets/bluetooth-proxy/mtr-1.md"
 
 --8<-- "_snippets/bluetooth-proxy/method1-finish.md"
diff --git a/docs/_snippets/bluetooth-proxy/method1-plt-1.md b/docs/_snippets/bluetooth-proxy/method1-plt-1.md
@@ -1,7 +1,5 @@
 --8<-- "_snippets/bluetooth-proxy/method1-steps.md"
 
-5\. Copy the code inside the codeblock below.
-
 --8<-- "_snippets/bluetooth-proxy/plt-1.md"
 
 --8<-- "_snippets/bluetooth-proxy/method1-finish.md"
diff --git a/docs/_snippets/bluetooth-proxy/method1-plt-1b.md b/docs/_snippets/bluetooth-proxy/method1-plt-1b.md
@@ -1,7 +1,5 @@
 --8<-- "_snippets/bluetooth-proxy/method1-steps.md"
 
-5\. Copy the code inside the codeblock below.
-
 --8<-- "_snippets/bluetooth-proxy/plt-1b.md"
 
 --8<-- "_snippets/bluetooth-proxy/method1-finish.md"
diff --git a/docs/_snippets/bluetooth-proxy/method1-steps.md b/docs/_snippets/bluetooth-proxy/method1-steps.md
@@ -1,13 +1,13 @@
-1\. Open the Esphome Device Builder.
+1\. Open ESPHome Device Builder. The button below opens the app right in your Home Assistant.
 
-![](/assets/bluetooth-proxy-tutorial-1.png)
+<a href="http://homeassistant.local:8123/5c53de3b_esphome" target="_blank" rel="noreferrer nofollow noopener" class="md-button md-button--primary"><img src="/assets/esphome-logo.svg" /> Open ESPHome Device Builder</a>
 
-2\. If you do not have it installed, [go here](https://esphome.io/guides/getting_started_hassio.html#installing-esphome-device-compiler "Install Esphome Device Builder.") and then move on to step 3.
+2\. Don't have it installed yet? Add it from the App Store with the badge below, then move on to step 3.
 
-3\. Click "Edit" as shown below.
+[![Open your Home Assistant instance and show the dashboard of the ESPHome Device Builder app.](https://my.home-assistant.io/badges/supervisor_addon.svg)](https://my.home-assistant.io/redirect/supervisor_addon/?addon=5c53de3b_esphome&repository_url=https%3A%2F%2Fgithub.com%2Fesphome%2Fhome-assistant-addon)
 
-![](/assets/bluetooth-proxy-tutorial-2.png)
+3\. Find your device and click **Edit**.
 
-4\. Add a \# before the packages line and the line after it as shown in the image below.
+![](/assets/esphome-device-builder-edit-device.gif)
 
-![](/assets/bluetooth-proxy-tutorial-10.png)
+4\. Replace the `packages:` line and the line directly below it with the code below.
diff --git a/docs/_snippets/bluetooth-proxy/method1-temp-1.md b/docs/_snippets/bluetooth-proxy/method1-temp-1.md
@@ -1,7 +1,5 @@
 --8<-- "_snippets/bluetooth-proxy/method1-steps.md"
 
-5\. Copy the code inside the codeblock below.
-
 --8<-- "_snippets/bluetooth-proxy/temp-1.md"
 
 --8<-- "_snippets/bluetooth-proxy/method1-finish.md"
diff --git a/docs/_snippets/bluetooth-proxy/method1-temp-1b.md b/docs/_snippets/bluetooth-proxy/method1-temp-1b.md
@@ -1,7 +1,5 @@
 --8<-- "_snippets/bluetooth-proxy/method1-steps.md"
 
-5\. Copy the code inside the codeblock below.
-
 --8<-- "_snippets/bluetooth-proxy/temp-1b.md"
 
 --8<-- "_snippets/bluetooth-proxy/method1-finish.md"
diff --git a/docs/_snippets/bluetooth-proxy/method2.md b/docs/_snippets/bluetooth-proxy/method2.md
@@ -1,45 +1,27 @@
-1\. Open the Esphome Device Builder.
+The easiest way is to let ESPHome Device Builder add the component for you. You can also paste the single line by hand.
 
-![](/assets/bluetooth-proxy-tutorial-1.png)
+1\. Open ESPHome Device Builder and click **Edit** on your device. The button below opens the app right in your Home Assistant.
 
-2\. If you do not have it installed, [go here](https://esphome.io/guides/getting_started_hassio.html#installing-esphome-device-compiler "Install Esphome Device Builder.") and then move on to step 3.
+<a href="http://homeassistant.local:8123/5c53de3b_esphome" target="_blank" rel="noreferrer nofollow noopener" class="md-button md-button--primary"><img src="/assets/esphome-logo.svg" /> Open ESPHome Device Builder</a>
 
-3\. Click "Edit" as shown below.
+Don't have it installed yet? Add it from the App Store with the badge below first.
 
-![](/assets/bluetooth-proxy-tutorial-2.png)
+[![Open your Home Assistant instance and show the dashboard of the ESPHome Device Builder app.](https://my.home-assistant.io/badges/supervisor_addon.svg)](https://my.home-assistant.io/redirect/supervisor_addon/?addon=5c53de3b_esphome&repository_url=https%3A%2F%2Fgithub.com%2Fesphome%2Fhome-assistant-addon)
 
-4\. Copy the code inside the codeblock below.
+2\. Click **Add Component** in the editor toolbar, search for **Bluetooth Proxy**, and click **Add**.
 
-```yaml
-  power_save_mode: LIGHT
-```
+![](/assets/esphome-device-builder-add-ble-proxy-component.gif)
 
-5\. Paste the code as shown below - make sure the spaces look the same and there are no red lines under any of the code.<br>![](/assets/bluetooth-proxy-tutorial-5.png)
-
-6\. Copy the code inside the codeblock below.
+Device Builder drops a single line into your config:
 
 ```yaml
 bluetooth_proxy:
-  active: true
-esp32_ble_tracker:
-  scan_parameters:
-    active: false
 ```
 
-7\. Paste the code on a new line at the very bottom of the file as shown below.
-
-![](/assets/bluetooth-proxy-tutorial-7-1.png)
-
-8\. Click save then Install in the top right.
-
-![](/assets/bluetooth-proxy-tutorial-8.png)
-
-9\. Click "Wirelessly" and let it finish compiling then installing.
-
-![](/assets/bluetooth-proxy-tutorial-6.png)
+That's all it needs. Active connections are on by default, and `bluetooth_proxy` automatically pulls in the <a href="https://esphome.io/components/esp32_ble_tracker/" target="_blank" rel="noreferrer nofollow noopener">ESP32 BLE Tracker</a> it depends on, so there's nothing else to add. Prefer to type it? Paste that one line at the top level of your YAML instead of using **Add Component**.
 
-10\. When you see this "OTA Successful" it has finished and you can click "Close" in the bottom right.
+3\. Click **Save**, then **Install**, and choose **On the Network** to flash the new firmware over Wi-Fi.
 
-![](/assets/bluetooth-proxy-tutorial-7.png)
+![](/assets/esphome-device-builder-add-ble-proxy-save-validate-install.gif)
 
-11\. You are finished and your Apollo device is now acting as a Bluetooth Proxy!
+--8<-- "_snippets/bluetooth-proxy/verify.md"
diff --git a/docs/_snippets/bluetooth-proxy/verify.md b/docs/_snippets/bluetooth-proxy/verify.md
@@ -0,0 +1,3 @@
+!!! success "Verify it works"
+
+    Once the device reboots, Home Assistant picks it up as a Bluetooth proxy automatically. Open the [Bluetooth advertisement monitor](https://my.home-assistant.io/redirect/bluetooth_advertisement_monitor/) to watch nearby BLE devices roll in through it. Anything that shows up is ready to add under **Settings → Devices & Services → Bluetooth** like any other device.
diff --git a/docs/assets/ble-proxy-install-completed.png b/docs/assets/ble-proxy-install-completed.png
diff --git a/docs/assets/esphome-device-builder-add-ble-proxy-method-1-edit-yaml.gif b/docs/assets/esphome-device-builder-add-ble-proxy-method-1-edit-yaml.gif
diff --git a/docs/assets/esphome-device-builder-add-ble-proxy-save-install.gif b/docs/assets/esphome-device-builder-add-ble-proxy-save-install.gif
diff --git a/docs/assets/esphome-device-builder-edit-device.gif b/docs/assets/esphome-device-builder-edit-device.gif
diff --git a/docs/products/ESPHome-Starter-Kit/tutorials/bluetooth-proxy.md b/docs/products/ESPHome-Starter-Kit/tutorials/bluetooth-proxy.md
@@ -63,7 +63,6 @@ Once the device reboots, Home Assistant picks up the proxy on its own.
 
 1. Open your ESPHome device in Home Assistant. If you haven't adopted it yet, follow [Connect to Home Assistant](/products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md) first.
 2. Home Assistant detects the new Bluetooth proxy and offers to set it up. Accept the prompt.
-3. Open your <a href="https://my.home-assistant.io/redirect/navigate/?path=%2Fconfig%2Fbluetooth%2Fadapter-info" target="_blank" rel="noreferrer nofollow noopener">Bluetooth adapters</a> page. Your starter kit shows up in the list, confirming it's now working as a proxy.
-4. Open the <a href="https://my.home-assistant.io/redirect/navigate/?path=%2Fconfig%2Fbluetooth%2Fadvertisement-monitor" target="_blank" rel="noreferrer nofollow noopener">advertisement monitor</a> to watch the BLE devices your starter kit is picking up in real time. Anything in range shows up here, ready to add under **Settings → Devices & Services → Bluetooth** like any other device.
+3. Open the <a href="https://my.home-assistant.io/redirect/bluetooth_advertisement_monitor/" target="_blank" rel="noreferrer nofollow noopener">Bluetooth advertisement monitor</a> to watch the BLE devices your starter kit is picking up in real time. Anything in range shows up here, ready to add under **Settings → Devices & Services → Bluetooth** like any other device.
 
 --8<-- "_snippets/community-help.md"
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		!!! success "Verify it works"

		Once the device reboots, Home Assistant picks it up as a Bluetooth proxy automatically. Open the [Bluetooth advertisement monitor](https://my.home-assistant.io/redirect/bluetooth_advertisement_monitor/) to watch nearby BLE devices roll in through it. Anything that shows up is ready to add under Settings → Devices & Services → Bluetooth like any other device.