diff --git a/docs/assets/esphome-device-builder-add-ble-proxy-component.gif b/docs/assets/esphome-device-builder-add-ble-proxy-component.gif new file mode 100644 index 0000000000..d29f15967b Binary files /dev/null and b/docs/assets/esphome-device-builder-add-ble-proxy-component.gif differ diff --git a/docs/assets/esphome-device-builder-add-ble-proxy-save-validate-install.gif b/docs/assets/esphome-device-builder-add-ble-proxy-save-validate-install.gif new file mode 100644 index 0000000000..44a25b052e Binary files /dev/null and b/docs/assets/esphome-device-builder-add-ble-proxy-save-validate-install.gif differ diff --git a/docs/products/ESPHome-Starter-Kit/tutorials/bluetooth-proxy.md b/docs/products/ESPHome-Starter-Kit/tutorials/bluetooth-proxy.md new file mode 100644 index 0000000000..15d530cc02 --- /dev/null +++ b/docs/products/ESPHome-Starter-Kit/tutorials/bluetooth-proxy.md @@ -0,0 +1,69 @@ +--- +title: Bluetooth Proxy +description: >- + Turn your ESPHome Starter Kit into a Bluetooth proxy so Home Assistant can see + BLE devices anywhere in your home, using one line of config. +--- +# Turn Your Starter Kit into a Bluetooth Proxy + +Home Assistant can talk to Bluetooth devices directly, but only ones close to the machine it runs on. A Bluetooth proxy fixes that. Your starter kit's ESP32-C6 listens for nearby BLE devices and relays them back to Home Assistant over Wi-Fi, so a sensor two rooms away shows up as if it were sitting next to your server. Drop a few of these around the house and Home Assistant gets Bluetooth coverage everywhere. + +Adding one used to mean a block of YAML. Now it's a single line, and Device Builder can add it for you. + +!!! note "Before you start" + + Work through this first: + + * [First Steps](/products/ESPHome-Starter-Kit/setup/first-steps.md) to install ESPHome Device Builder and create your starter kit device. + + Your device also needs to be on Wi-Fi and adopted in [Home Assistant](/products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md) so the proxy has somewhere to send what it hears. + +## Add the Bluetooth proxy + +Device Builder has an **Add Component** flow that drops the proxy into your config for you, no typing required. + +1. Open your starter kit device in ESPHome Device Builder and click **Edit**. +2. Click **Add Component** in the editor toolbar. +3. Search for **Bluetooth Proxy** and select it. +4. Click **Add**. Device Builder inserts the proxy into your YAML. + +![](../../../assets/esphome-device-builder-add-ble-proxy-component.gif) + +??? note "Prefer to add it by hand? Here's the YAML" + + If you'd rather edit the config directly, open the editor and add this one line anywhere at the top level: + + ```yaml + bluetooth_proxy: + ``` + + That's it. Active connections are on by default, and `bluetooth_proxy` automatically pulls in the ESP32 BLE Tracker it needs, so you don't have to add anything else. + + You only need to add a second `esp32_ble_tracker:` line if you want to explicitly set passive scanning: + + ```yaml + esp32_ble_tracker: + scan_parameters: + active: false + ``` + +## Install the firmware + +The proxy is saved in Device Builder, but the device is still running its old firmware. Compile and install to push the change. + +1. Click **Save** in the bottom right of the editor. +2. Click **Install**, then pick **On the Network** to push the new firmware over Wi-Fi. +3. Wait for the compile and flash to finish. The device reboots once the install is done. + +![](../../../assets/esphome-device-builder-add-ble-proxy-save-validate-install.gif) + +## Verify it works + +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 Bluetooth adapters page. Your starter kit shows up in the list, confirming it's now working as a proxy. +4. Open the advertisement monitor 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" diff --git a/mkdocs.yml b/mkdocs.yml index 3085478967..e69e0fe9b3 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -540,6 +540,7 @@ nav: - Using Secrets: products/ESPHome-Starter-Kit/tutorials/using-secrets.md - Connect to Home Assistant: products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md - Light Effects: products/ESPHome-Starter-Kit/tutorials/light-effects.md + - Bluetooth Proxy: products/ESPHome-Starter-Kit/tutorials/bluetooth-proxy.md - Automations: - Button Controlled LEDs: products/ESPHome-Starter-Kit/automations/button-controlled-leds.md - Play a Tune: products/ESPHome-Starter-Kit/automations/play-a-tune.md