Home Assistant DIY, ESPhome, creating a Bluetooth proxy

My Home Assistant(HA) server setup is virtualized with Linux KVM and I needed a solution handling Bluetooth since the used Mac Mini just had a PCI connected one.

HA recommends to use a Bluetooth proxy(BTP) quote "since Linux kernel updates have previously broken Bluetooth functionality and Bluetooth driver support Linux generally falls behind other operating systems for newer adapters. A Bluetooth proxy is particularly interesting to users who virtualize their instance, where the USB pass-through may cause additional problems".

So using ESPHome I will set up a BTP in this post !

Hardware

For this project I'm using Waveshare - ESP32-C3-Zero 

Installing

My preferred install method is described in this post and the actual code is found below. If you are using a "plain" ESP32 here is a ready made project and here some additional info. Some sample files are found here.

This setup will activate the two buttons, reset and safe mode, on the board.

Connecting the device to HA

In "Settings => Devices & services => Add integration => ESPHome" fill in the IP adres and submit.

As said in other posts I'm using RuuviTag and it directly appeared as a discovered integration !

Add-ons

And as usual you got some ideas to improve the setup.....

LED

The RGB light is a WS2812, and can be controlled with the ESP32 RMT LED Strip component which works with both the ESP-IDF and Arduino frameworks. Inspiration link

Implemented LED functions

• Red when connected to power and booting up
• Green when connected to WiFi
• Blue, flash, when BT advertisement is detected but not more than every 10 second

Reboot functions

There is a built in Hardware Watchdog but I also added a reboot timeout for both the WiFi connection and the HA server connection. 

Additional entities

I also added a button, so you can turn off the LED, and 2 sensors, uptime and WiFi signal strength.

Wrap up

Code for the additional functions are found here.

Code

esphome:
  name: bt-proxy
  friendly_name: Bluetooth Proxy
  min_version: 2025.8.0
  name_add_mac_suffix: true
esp32:
  variant: esp32c3
  framework:
    type: esp-idf
    sdkconfig_options:
      CONFIG_BT_BLE_42_FEATURES_SUPPORTED: y
      CONFIG_BT_BLE_50_FEATURES_SUPPORTED: n
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
api:
logger:
ota:
  - platform: esphome
    id: ota_esphome
esp32_ble_tracker:
  scan_parameters:
    # We currently use the defaults to ensure Bluetooth
    # can co-exist with WiFi In the future we may be able to
    # enable the built-in coexistence logic in ESP-IDF
    active: true
bluetooth_proxy:
  active: true
button:
  - platform: safe_mode
    id: button_safe_mode
    name: Safe Mode Boot
  - platform: factory_reset
    id: factory_reset_btn
    name: Factory reset