Bluetooth Proxy (ESPHome)

The Bluetooth Proxy integration is not a traditional type of integration that adds specific products or services. Instead, it allows Home Assistant to recognize Bluetooth devices that are out of range of the hardware on which Home Assistant is running.

Bluetooth Proxy Support in Home Assistant

Home Assistant has gradually introduced support for Bluetooth, expanding its integration capabilities:

• Version 2022.08 introduced support for internal Bluetooth and USB dongles.
• Version 2022.09 enabled passive data reading from ESP32 devices using ESPHome Proxy.
• Version 2022.10 added the ability to actively control devices through an active Bluetooth proxy.

Role of Bluetooth Proxy

A Bluetooth proxy is useful in situations where:

1. Home Assistant is not close enough to the Bluetooth device.
2. We want to extend Bluetooth coverage throughout the house.

ESPHome acts as a bridge between Bluetooth and WiFi/Ethernet, allowing connection to remote devices.

Recommended Hardware

I have had great success with basic ESP32 devices, which can be purchased for a very low cost. They include both WiFi (2.4GHz only) and Bluetooth and are directly supported by ESPHome for Proxy.

ESP32-WROOM

Basic ESP32 in many variants

409 Kč

Alza.cz

87 Kč

Aliexpress

Creating a Bluetooth Proxy Using ESP32 and ESPHome

The procedure differs depending on the current situation:

1. If we are already running ESPHome on some ESP32 compatible device.
2. If we do not yet have ESPHome installed or want to set up ESPHome on another device.

Adding to an Existing ESP32 with ESPHome

We will assume that we already have the ESPHome add-on installed in Home Assistant and can edit the configuration of the ESP32 device.

The situation will be simple, as we only need to add two lines:

# Example configuration to activate Bluetooth Proxy
bluetooth_proxy:
  active: true

and upload the updated version to the ESP32.

The first line adds support for Bluetooth Proxy, and the second line specifies whether we want only a passive or active version. The default value is a passive proxy only.

Creating a New ESP32 Device with ESPHome

When using a new ESP32 device, it is not even necessary to have the ESPHome Addon installed in Home Assistant, and everything can be done through the web interface.

Simply connect the ESP32 device to the computer via USB, open the web interface in the Chrome browser, and after successfully uploading the firmware to the ESP32, Home Assistant will automatically find and install it as an integration when connected to the correct WiFi network.

Adding Bluetooth Devices to Home Assistant via ESPHome Proxy

If we already have an ESP32 with ESPHome Proxy running and have added it to Home Assistant, devices with the discovered flag should start appearing after a while.

info

Four letters/numbers in the device name correspond to the last four characters of the device's MAC address.

If the device does not appear as discovered for some reason, it is still possible to add it using the Add Integration button, where we manually search for the integration. For example, for Bluetooth devices from Xiaomi, we can use the integration named Xiaomi BLE.

The specific steps during the addition may vary depending on the manufacturer and device, but it should not usually be complicated.

We will look at Xiaomi devices, which are among the most widespread – at least for me – and specifically show two scenarios:

1. Adding a device without a pairing code
2. Adding a device with a pairing code

Device Without a Pairing Code

These are usually older devices that do not yet use data encryption, making their addition simpler. On the other hand, anyone within range can add them.

An example of such a device is the Xiaomi Mijia LYWSDCGQ thermometer, which, however, seems to be almost impossible to find nowadays.

After adding it to Home Assistant, we can see both the Temperature and Humidity as well as the status of the AA battery.

Device with a Pairing Code – Xiaomi

Newer Xiaomi devices, on the other hand, require a token for pairing – in the official Xiaomi Home app, you are spared this, but internally this token is generated and used.

As in the previous case, the device will first appear in the Discovered state, and if you do not yet know the pairing token, I recommend not adding it yet – we will look at how to obtain it below.

An example of such a device is the Xiaomi Mijia LYWSD03MMC thermometer.

Xiaomi Mijia Bluetooth Thermometer

Bluetooth thermometer and hygrometer from Xiaomi LYWSD03MMC

154 Kč

Aliexpress

Obtaining the Existing Pairing Code

The first option is to obtain the existing pairing code, which is stored on the Xiaomi Cloud. To do this, we will need to download the Token Extractor application from the web and prepare the login name and password for the Xiaomi Cloud (the same as used in the Xiaomi Home app on the mobile).

The installation is ideally done from the command line:

wget https://github.com/PiotrMachowski/Xiaomi-cloud-tokens-extractor/releases/latest/download/token_extractor.zip
unzip token_extractor.zip
cd token_extractor

and we will also need to install the Python packages. I recommend doing this in a separate Python Environment, which you can then delete:

python3.11 -m venv venv
source ./venv/bin/activate
pip install -r ./requirements.txt

We run the application with the command python token_extractor.py, and after entering the login details, we will also need to enter the server. This should correspond to the region setting in the Xiaomi Home app – in our region, we will probably have it set to Czechia, and then the server name is de (i.e., Germany).

The login to the Xiaomi cloud will take place, and we should get a list of all devices, including pairing codes – here they are labeled as tokens.

Server (one of: cn, de, us, ru, tw, sg, in, i2) Leave empty to check all available:
de

Logging in...
Logged in.

Devices found for server "de":

---------

   ---------
   NAME:     Thermometer #1
   ID:       blt.4.1b8ih56mcgc00
   BLE KEY:  758679a38a4d356bc7aa926f40af2434
   MAC:      A4:C1:38:91:A4:DE
   IP:       45.129.32.131
   TOKEN:    07c5d233c078fb0b7d0be498
   MODEL:    miaomiaoce.sensor_ht.t2
   ---------
   NAME:     Thermometer #2
   ID:       blt.4.1ghihju9cgk00
   BLE KEY:  2bab4851cc3adb58a87dcaca374d5dba
   MAC:      A4:C1:38:92:2A:45
   TOKEN:    82ae1f02e05a3f4dbf6509ee
   MODEL:    miaomiaoce.sensor_ht.t2
   ---------
...

Press ENTER to finish

Warning for Xiaomi Mijia LYWSDCGQ Thermometer

According to my findings, it seems that the Xiaomi Mijia LYWSDCGQ thermometer can no longer be used via ESPHome Proxy in the case of firmware 2.x. If you haven't done so yet, do not perform the update through the app.

You can probably tell if you have version 2 during the pairing code retrieval, where version 2 also includes an IP address.

Generating a New Pairing Code

If we do not want to use the application to obtain the code for any reason, the second option, which is not general, is to use the website to generate a new code in the case of the Xiaomi thermometer. This is done by connecting via Do Activation and then copying the Mi Bind Key.

info

The disadvantage of this solution is that the device's token will be changed, i.e., we will no longer be able to connect to the device via the Xiaomi Home app – the tokens will not match.

Adding the Device to Home Assistant

Now we can click the Set Up button to add it. If we now look at the new device, we will find that it does not contain any entities. This is because the transmission of values is encrypted, and we still need to set the pairing code.

We wait a little longer, and the device should reappear at the top of the device list in the Attention Required state.

If we now click on Reconfigure, we will receive a dialog where we can enter the pairing key we obtained using one of the methods above.

With that, we are done, and the entities will gradually start to appear.

Device with a Pairing Code – QINGPING

Apparently, not all integrations require knowing the pairing code, so, for example, the QINGPING alarm clock, which appears as a Xiaomi device, can be added in Home Assistant via the QINGPING integration, which does not require entering the pairing code.

However, we can still add QINGPING devices using the Xiaomi BLE integration, which will require the pairing code.

Qingping Bluetooth Alarm Clock

Bluetooth alarm clock with thermometer and hygrometer

549 Kč

Alza.cz

480 Kč

Aliexpress

Evaluation

I have been using Xiaomi Bluetooth thermometers for quite some time because they are very inexpensive and have a display. However, before the proper Bluetooth support was added directly to Home Assistant, I integrated them using ESP32 and ESPHome, where I set up individual devices directly in ESPHome.

The new method using the ESPHome Proxy integration greatly simplifies the integration of Bluetooth devices and may make it a bit more complicated to decide which device to choose – whether WiFi, Zigbee, or now Bluetooth.

Especially for sensors, the differences and comparison of advantages/disadvantages between Zigbee and Bluetooth can be very close, making the decision more difficult. The advantage of Bluetooth should generally be longer battery life and usually lower cost. The disadvantage is the need to spread the Bluetooth signal throughout the house if we do not want to cover only one room.