Home Assistant, ESPhome, creating a Bluetooth proxy

My Home Assistant(HA) server setup virtualized with Linux KVM 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".

Since using HA ESPHome is the way to get a BTP !

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.

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