教程：让你的不智能蓝牙灯接入 HomeKit 智能家居
引言#如果你有一个蓝牙灯，并且它能够被以下几个手机应用控制：
LampSmart ProLamp Smart Pro - Soft Lighting / Smart LightingFanLamp ProZhi JiaZhi GuangApplianceSmartVmax smartZhi Mei Deng Kong那么恭喜你，你可以跟随本篇教程，一步一步将它接入 HomeKit 智能家居。
来实现通过 iPhone 家庭应用控制以及 Siri 语音控制。
对于实现后的效果，可以看我另一篇博文：折腾：HomeKit 接入蓝牙吸顶灯
非常感谢 https://github.com/NicoIIT/ha-ble-adv/，本篇教程实际是从零接入该项目。
开始之前#在开始之前，需要一点点基础的计算机知识，确保满足以下条件：
熟悉 Home Assistant 概念和一些基本操作，可以阅读官方文档快速熟悉；能够使用 Terminal 命令行工具；已安装 Docker 并且可用；有一个 GitHub 帐号；关键：一块 ESP32 开发板；主要用于蓝牙通信，如果没有的话，可以网购一块，25 元左右的价格；（未来会研究如何直接使用系统自带的蓝牙）；教程方式#本教程以 MacOS 为例。如果你使用 Linux 或 Windows，部分操作可能需要稍作调整。
教程的每个步骤会说明：要做什么、怎么做、以及验证结果。请确保完成验证后再进行下一步。遇到问题时，可以参考自查攻略（部分步骤有）或联系我。
如何实现#对于实现不感兴趣的，可以跳转到下一部分
组件列表#Home Assistant (HA)Home Assistant Community Store (HACS)ha-ble-adv缩写是 Home Assistant Bluetooth Low Energy Advertise翻译为 Home Assistant 蓝牙低功耗广播ESP Homeesphome-ble-adv-proxyESP32组件交互#核心是使用 ha-ble-adv 通过蓝牙与设备交互，控制开关和亮度通过 Home Assistant 提供的 HomeKit Bridge 连接到 iPhone 家庭应用，来实现控制要让 Home Assistant 成功使用上 ha-ble-adv 需要具备以下条件：通过 HACS 安装组件 ha-ble-adv通过 ESP Home 在 ESP32 上面安装 esphome-ble-adv-proxy 以供 ha-ble-adv 发送和接收蓝牙信息以下是整体架构图
话不多说，让我们开始吧。基于上面的实现，为了教程的连贯性，让我们从 ESP32 开始。
首先创建一个目录存放本次用到的所有组件。
$ mkdir Home-Assistant
$ cd Home-Assistant
第一部分： ESP Home #安装 ESP Home#要做什么#使用 Docker 安装 ESP Home。
当然，可以访问 官方文档 获取更多安装方式。
怎么做#使用以下 Docker compose 文件# Home-Assistant/docker-compose.yml
services:
esphome:
container_name: esphome
image: ghcr.io/esphome/esphome
volumes:
- ./esphome/config:/config
- /etc/localtime:/etc/localtime:ro
restart: always
privileged: true
network_mode: host
启动运行$ docker compose up -d
结果验证#在浏览器访问 http://localhost:6052 能够进入 ESP Home 后台。
遇到问题请参考 官方文档。
连接 ESP32#要做什么#添加 ESP32 到 ESP Home 进行管理，用于后续安装组件。
怎么做#将你的 ESP32 设备通过有线连接到 MacOS在 ESP Home 后台添加设备，设置一个名字，比如 esp32-ble-adv-proxy选择 ESP32 连接的串口输入 Wi-Fi 信息（SSID & Password）重要：确保连接 2.4G Wi-Fi开始安装，选择 Plug into this computer等待 2 分钟以上，安装完毕结果验证#安装完成后会有提示关闭提示后可以在后台看到刚才添加的设备是在线状态（ONLINE）点击 LOGS 可以查看到相关日志遇到问题#无法安装？等待大于 2 分钟以上，检查安装过程中页面上面文案是否有变化安装后设备不在线？检查 Wi-Fi 信息是否正确检查是否连接的是 2.4G Wi-Fi安装 esphome-ble-adv-proxy#要做什么#在 ESP Home 后台为刚连接的 ESP32 设备安装社区组件 esphome-ble_adv_proxy。
当然，可以访问 esphome-ble_adv_proxy 获取详细安装说明。
怎么做#在 ESP Home 后台对设备 esp32-ble-adv-proxy 点击 Edit编辑如下信息(...)
esp32:
board: esp32dev # Or your specific board model
framework:
type: esp-idf # Recommended for BLE stability
# Enable ESP32 Bluetooth Low Energy Tracker
esp32_ble_tracker:
scan_parameters:
# Active scanning can discover more devices but uses more power
active: true
# Enable standard Home Assistant Bluetooth Proxy
bluetooth_proxy:
active: true
# Define the external component source for ble_adv_proxy
external_components:
- source: github://NicoIIT/esphome-ble_adv_proxy
# Enable the ble_adv_proxy component
ble_adv_proxy:
# No specific configuration needed here unless specified by component docs
(...)
点击保存（Save），点击安装（Install），选择无线安装（Wireless）等待 2 分钟以上，安装完毕结果验证#选择无线安装以后，可以实时查看安装进度安装完成后，点击新出现的 VISIT 按钮，会跳转到调试页面，观察页面是否有数据产生注意：当前页面地址 http://esp32-ble-adv-proxy.local遇到问题？可以根据安装日志提示寻找相关解决方案。
至此，ESP32 部分准备完成，让我们回到主线 Home Assistant。
第二部分： Home Assistant#安装 Home Assistant#要做什么#通过 python 直接在 MacOS 主机上面安装 Home Assistant Core。
注意：本教程对于在 Docker 内运行的 Home Assistant 无法成功，详见下面 Q&A
当然，可以访问 官方文档 获取更多安装说明。
怎么做#初始化 python 环境$ python3 -m venv .
$ source ./bin/activate
安装 homeassistant Core$ pip3 install homeassistant==2025.4.4
创建一个配置目录$ mkdir config
启动hass --config config
结果验证#在浏览器访问 http://localhost:8123 能够进入 Home Assistant 后台创建帐号，完成首次登录流程遇到问题请参考 官方文档。
接入 ESP32#要做什么#在 Home Assistant 后台添加上面 ESP32 集成。
怎么做#如果之前的步骤一切顺利的话，在 Home Assistant 完成安装后，会自发现 ESP32 设备，点击添加即可。
如果没有自发现，我们仍然可以手动添加：
在 Settings > Devices & Services 点击 ADD INTEGRATION 搜索 ESP Home 进行添加输入上面的地址 esp32-ble-adv-proxy.local点击添加回到 ESP Home 复制 esp32-ble-adv-proxy API Key 完成集成结果验证#在 Home Assistant Devices & Services 页面显示添加成功的 ESP32 设备和蓝牙遇到问题#手动添加失败？检查 http://esp32-ble-adv-proxy.local 是否可以访问检查 ESP Home 是否运行找不到 API Key在 ESP Home 设备卡片，点击 ··· 按钮，点击 Show API Key更多帮助可以查看 官方文档安装 Home Assistant Community Store#要做什么#在 Home Assistant 后台安装 HACS 集成
当然，可以访问 官方文档 获取更多安装说明。
怎么做#确保 wget 是可用的在命令行执行安装命令$ wget -O - https://get.hacs.xyz | bash -
重启 Home Assistant在 Settings > Devices & Services 点击 ADD INTEGRATION 搜索 HACS 进行添加根据指引完成 GitHub 帐号授权安装完成结果验证#在 Home Assistant 后台导航菜单可以看到 HACS遇到问题？请参考 官方文档 完成配置
安装 ha-ble-adv#要做什么#通过 HACS 安装自定义仓库 ha-ble-adv
怎么做#进入 Home Assistant，进入 HACS点击 ··· 右上角 > Custom respositories根据指引安装 https://github.com/NicoIIT/ha-ble-adv结果验证#安装成功在 Settings > Devices & Services 点击 ADD INTEGRATION 能够搜索到 BLE ADV遇到问题？请参考 官方文档 安装自定义仓库指引
添加 蓝牙灯 设备#要做什么#添加 ha-ble-adv 蓝牙灯设备集成
怎么做#在 Settings > Devices & Services 点击 ADD INTEGRATION 搜索 BLE ADV 进行添加根据指引进行添加，推荐选择 Duplicate Paired Phone App Config结果验证#添加成功在 Overview 可以通过 Home Assistant 直接控制蓝牙灯遇到问题#无法打开安装指引？需要手动加载 ble-adv 组件打开 config/configurations.yml 进行编辑，在最后一行添加# config/configurations.yml
...
ble_adv:
重启 Home Assistant， 重新添加无法接收到蓝牙信息？请确保前面 ESP32 在 EPS Home 是在线状态可以通过访问 http://esp32-ble-adv-proxy.local 来检查其他问题？可以参考 FAQ 来排查接入 HomeKit Bridge#截止上一步，我们实现了通过 Home Assistant 控制蓝牙来控制蓝牙灯。
接下来，我们进入最后一步，接入 HomeKit Bridge 来接入家庭应用。
要做什么#通过 HomeKit Bridge 接入家庭应用。
当然，可以访问 官方文档 获取更多安装说明。
怎么做#在 Settings > Devices & Services 点击 ADD INTEGRATION 搜索 Apple 点击后添加 HomeKit Bridge这里无需额外配置，直接点击下一步即可完成添加后，打开左下角 NotificationiPhone 打开家庭应用，扫描二维码添加设备扫描成功后会弹窗 未认证配件，点击 仍要添加 完成配置结果验证#蓝牙灯控制出现在 iPhone 家庭应用可以通过 家庭应用 / Siri 控制 灯 开关和灯光遇到问题#在最后一步遇到的问题会多一些，以下是我遇到的问题，排查思路和解决方案。
扫码后无法添加，提示 找不到设备？
主要是网络问题引起，请依次检查：
排查一：排查本机 mDNS 是否正常工作：
【操作步骤】
在命令行执行以下命令$ dns-sd -B _hap._tcp local
【结果验证】
如果返回以下信息，说明本机 mDNS 没问题，注意右边 Instance Name 含有 HASS Bridge
Timestamp A/R Flags if Domain Service Type Instance Name
0:29:39.244 Add 3 10 local. _hap._tcp. HASS Bridge xxxxxx
【解决方式一】
打开 Debug 日志，打开 config/configurations.yml 进行编辑，在最后一行添加logger:
default: warning
logs:
homeassistant.components.homekit: debug
pyhap: debug
重启 Home Assistant重新扫码添加设备到家庭应用观察是否有异常日志根据日志报错搜索相关解决方案【解决方式二】
若使用 Docker 启动 Home Assistant，改为直接安装 Home Assistant 到本机。排查二：排查手机 mDNS 是否正常工作：
【操作步骤】
在 Apple Store 搜索 Discovery - DNS-SD Browser安装后打开，检查 local 域【结果验证】
检查是否存在 _hap._tcp点击查看，是否存在 HASS Bridge xxxxxx如果存在，说明手机 mDNS 通信在同一个网络下没问题【解决方式一】
检查手机和运行 Home Assistant 的 MacOS 是否在同一个网络下【解决方式二】
检查 MacOS 防火墙配置，是否有禁止端口：HomeKit Bridge 21063mDNS 5353【解决方式三】
检查路由器配置，是否禁用 mDNS其他问题？
以下是我在排查问题中找到的一些有用的文章，希望能对你有启发：
Offcial: HomeKit TroubleshootingCommunity: HomeKit Bridge on Home Assistant in DockerCommunity: Use HomeKit Component inside DockerReddit: Troubleshooting HomeKit What Tools to Use and HowGitHub issue: Homekit not working with dockerGitHub gist: Home Assistant Docker on MacOSEnjoy！#太好了，大功告成！开始享用家庭应用控制蓝牙灯吧。
总结#本教程详细介绍了如何将特定的蓝牙灯（如 LampSmart Pro 控制的灯）通过一系列开源工具接入 Apple HomeKit 智能家居系统。我们从准备 ESP32 开发板开始，利用 ESPHome 安装了 esphome-ble-adv-proxy 以实现蓝牙通信代理。接着，我们在 MacOS 上安装了 Home Assistant Core，并集成了 ESP32 设备。通过 HACS，我们安装了关键的 ha-ble-adv 自定义组件，用于发现和控制蓝牙灯。最后，利用 Home Assistant 内置的 HomeKit Bridge 功能，成功将蓝牙灯设备桥接至 iPhone 的家庭应用，实现了通过家庭 App 和 Siri 进行控制。教程中也涵盖了各个步骤可能遇到的问题及其排查方法，特别是 HomeKit 连接时常见的 mDNS 网络问题。遵循本教程，你可以将原本“不智能”的蓝牙设备融入现代智能家居生态。
答疑 #Q1 是否可以使用 Docker 运行 Home Assistant#可以，但我没有成功，可以参考
GitHub gist: Home Assistant Docker on MacOS。Community: HomeKit Bridge on Home Assistant in Docker使用 Docker 会有什么问题？
我遇到的问题是 HomeKit 死活连不上，排查后发现是主机的 mDNS 网络无法探查到 Docker 内部 HomeKit Bridge 网络。就算使用 network_mode=host 也不行，我就放弃折腾 Docker，改为安装到本机。Q2 是否可以不用 ESP32， 使用 MacOS 自带的蓝牙功能#目前不行，有 2 个原因：
使用 Docker 运行，无法在 Docker 内使用主机的蓝牙功能，最简单的方式是使用 ESP32 代理一下目前 MacOS 自带的蓝牙功能无法满足 ble-adv 功能，可以参考 作者回复Q3 本机运行 Home Assistant 脚本#后台运行脚本，创建一个文件 run.sh
#!/bin/bash
source bin/activate
nohup hass --config config > hass.log 2>&1 &
echo "Home Assistant started on: http://localhost:8123"
添加执行权限
$ chmod +x run.sh
启动 Home Assistant
$ ./run.sh
查看日志
tail -f hass.log
停止 Home Assistant
$ pkill -f "hass --config config"
引用#Home Assistant (HA)Home Assistant Community Store (HACS)ha-ble-advESP Homeesphome-ble-adv-proxyESP Home 官方文档 - 安装ESP Home 官方文档 - 安装问题ESP Home 官方文档 - Home Assistant 集成Home Assistant 官方文档 - MacOS 安装Home Assistant 官方文档 - HomeKit 集成Home Assistant 官方文档 - HomeKit TroubleshootingHACS 官方文档 - 首页HACS 官方文档 - 配置HACS 官方文档 - 自定义仓库ha-ble-adv FAQCommunity: HomeKit Bridge on Home Assistant in DockerCommunity: Use HomeKit Component inside DockerReddit: Troubleshooting HomeKit What Tools to Use and HowGitHub issue: Homekit not working with dockerGitHub gist: Home Assistant Docker on MacOSESP Home 后台 http://localhost:6052Home Assistant 后台 http://localhost:8123
