Guide: Bluetooth Proxy to Home Assistant using ESPHome

In previous post I briefly looked into SwitchBot Bluetooth ecosystem and promised to write a post about setting up a Bluetooth Proxy using ESP32 and ESPHome. In this post I’m going through the process of installing ESPHome and flashing Bluetooth Proxy into an ESP32 device and connecting BLE device to Home Assistant through it.

ESP32, ESPHome and Bluetooth Proxy

ESP32, ESPHome and Bluetooth Proxy? A little introduction to get used to these terms..

ESP32 is a MCU with integrated WiFi and Bluetooth (successor of popular ESP8266). ESP32 a very powerful and has low power consumption. In theory, it can be battery operated if put on a deep sleep, but with casual use cases a permanent power connection is required. ESP32 software can be developed with easy to learn Arduino, but is not excluded to only that.

ESPHome is a platform developed for ESP32/ESP8266 and is mainly used for Smart Home devices. ESPHome has tons of ready made configurations, libraries and examples. In 2021 Nabu Casa (Home Assistant developer company) acquired ESPHome and integrated the whole ESPHome system more deep into the Home Assistant Core. These days ESPHome can be installed directly from Home Assistant Add-On store and configured from Home Assistant UI!

Bluetooth Proxy is a gateway software that listens for ‘all’ Bluetooth traffic and forwards them to the Home Assistant instance. Basically BLE to WiFi gateway.

Required Hardware

In this project we are going to need few items:

• ESP32 development board
  • ESP32 development board has an ESP32 chip (Bluetooth and Wifi already integrated) plus an USB interface for powering up flashing.
• 5v USB Power supply providing at least 0.5 amps (an old cellphone charger will do fine)
• Micro USB cable
• Optional: Plastic enclosure to fit the ESP32 devkit (or 3D printer)

Note: I’ve tested this with two different development boards, ESP32 Wroom devkit v1 and ESP32 Wroom devkit v2, but for some odd reason the devkit v2 did not work properly with flashing esp-idf type of framework. You can find the exact device I’ve used from Amazon store. Most probably other ESP32 dev kits works as well, but I’ve not tested them my self, so can’t say 100% sure that others works the same.

Installing ESPHome into Home Assistant

ESPHome is now days hosted within the Official Home Assistant Add-On Store and can be installed to the Home Assistant without any problems. Just head over to Home Assistant Settings -> Add-On Store -> Select ESPHome and press the install.

Once installed I’d suggest to set on the Watchdog switch in order for ESPHome to restart it if crashing at anytime for any reason. Also press ‘start’ button to start the ESPHome container in your environment.

Now the ESPHome service should be fully running and can be opened from “Open Web UI” -button bottom of the ESPHome Add-on page.

Flashing Bluetooth Proxy

Now it’s time to get really things started and setup the proper configurations for the ESP32! Open ESPHome UI from ESPHome Add-on page and connect the ESP32 device to your PC using a micro USB cable.

Create a new config

First initial configuration is needed to be created. Let’s start by pressing the plus-button in the bottom right corner and let’s name the device as “Bluetooth Proxy“. Next select a Generic ESP32 as a device (unless you have some other specific ESP32 dev board that is in the list).

Generated encryption key should be now shown, but you can safely ignore it. It will be automatically added to the configuration once finished. So just press “Skip” button and we continue editing in the edit view.

After finished and initial config is created, open the newly created configuration by pressing “edit” from the Bluetooth Proxy device at ESPHome WEB UI.

Now we need to add the Bluetooth Proxy support for our configuration. Fill in the missing parts of the configuration from the code below (esp32_ble_tracker and bluetooth_proxy -blocks). Also remember to change the framework type to esp-idf! This is important, since the bluetooth proxy performance is quite poor on default Arduino framework. Don’t copy the below configuration totally, since the encryption key and other password should be unique to your device and environment. I’ve altered those values in my configuration shown here.

esphome:
  name: bluetooth-proxy
  friendly_name: Bluetooth Proxy

esp32:
  board: esp32dev
  framework:
    type: esp-idf

# Enable logging
logger:

# Enable Home Assistant API
api:
  encryption:
    key: "REMOVED"

ota:
  password: "REMOVED"

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  # Enable fallback hotspot in case wifi connection fails
  ap:
    ssid: "Bluetooth-Proxy Fallback Hotspot"
    password: "REMOVED"

esp32_ble_tracker:
  scan_parameters:
    interval: 1100ms
    window: 1100ms
    active: true

bluetooth_proxy:
  active: true

Flashing the device

Once modifications are in place, we just need to flash it on the ESP32 device. For this, Google Chrome or Microsoft Edge browser is required. So using Google Chrome press the “install” button in the current view and select the corresponding com port the device is connected to using USB cable. Port name should be something like: ‘CP2102 USB to UART Bridge Controller (Com 4)‘

After this step the programming should begin processing and will take couple of minutes until completed.

After the first time flashing the device, it can be re-flashed wirelessly. In fact, Home Assistant will notify if ESPHome is updated and will ask you to update the device (wirelessly) when a new ESPHome update is pushed out.

Once done, move to the next step.

Adding the proxy to Home Assistant

After installation, when ESP32 has properly started up, a notification of a new device should appear in the Home Assistant notification center. Clicking this notification will take you to the Home Assistant devices & integrations -view and will kindly ask you to configure the Bluetooth Proxy device. So click it, add an area you are planning to place the device and you’re all done! The proxy is now ready for use!

Discovering Bluetooth devices

You can now disconnect the device from PC and connect it to the power supply using a micro USB cable.

Proxy should now start and automatically discover all nearby supported Bluetooth devices in range. All of those devices will be notified in the same Home Assistant notification area and clicking those notifications will take you to the Home Assistant devices & integrations page once again.. and again kindly ask you to configure the bluetooth devices.

In my case, the SwitchBot Meter Plus was discovered as should and configuration was to just add the device area. Once that was done the device started sending values for the Home Assistant immediately!

Creating an enclosure (optional)

It’s not a good practice to install electrical devices exposed to dust, so it’s nice to have an enclosure for the device. If you have a 3D Printer available, I’d suggest to find a 3D model for the ESP32 case (depending on your dev board) from e.g. Thingiverse. As said earlier, I’m using a Wroom32 devkit v1 and found this specific case to fit for my needs. That enclosure does require a bit glue to close the lid tight, but otherwise it’s a perfect fit.

If you don’t have a 3D printer available, you can use any plastic case. Just add some hot glue to the bottom of the enclosure and glue the ESP32 device on it so it won’t move inside accidentally. Also create a hole for the USB power cable.

The end

Everything is now ready and the proxy device should be passing ‘all’ bluetooth device data directly to your Home Assistant instance. I’ve been using this for about week now and I’ve had zero connection drops and everything has been working as great as expected. It’s very easy now to expand Bluetooth range by just placing more of these proxy devices in the house!

---