ESPHome 蓝牙网关完整指南三步把 BLE 设备接入 Home Assistant【免费下载链接】esphomeESPHome is a system to control your ESP32, ESP8266, BK72xx, RP2040 by simple yet powerful configuration files and control them remotely through Home Automation systems.项目地址: https://gitcode.com/GitHub_Trending/es/esphome墙上的小米温湿度计只发 BLE 广播进不了 Wi-Fi传统做法是另购网关或靠手机转发延迟高还依赖手机在线。用 ESPHome 的bluetooth_proxy组件一块 ESP32 就能直接扫描、连接这些 BLE 设备再由 Home Assistant 通过ESPHome API拉取数据。本文给出最小可运行配置并讲清扫描窗口、连接槽位这些调优参数。01 适用场景与价值 先界定一下它解决什么问题避免买错硬件BLE 传感器无法直连网络温湿度、门窗、电池供电的设备大多只有 BLE。本网关部署后Home Assistant 里的 ESPHome 集成会自动发现它们如xiaomi_lywsd02mmc组件可直接按 MAC 解析数据替代手机做蓝牙中转或专用硬件网关。集中式 BLE 代理多台 ESP32 网关共用一个接入点客户端按需选择网关比每台设备各配一个网关省成本。主动与被动两种模式被动模式只转发广播包适合广播型传感器主动模式active: true默认开启可建立 GATT 连接做读写适合门锁、开关这类需要交互的设备见 esphome/components/bluetooth_proxy/init.py。明确了边界下面用最短路径把它跑起来。02 三步跑通最小示例 只需 ESP32 开发板 供电环境上安装 ESPHomepip install esphome然后按写配置 → 编译 → 刷写三步走。代码1ble-gateway.yaml最小配置esphome: name: ble-gateway esp32: board: esp32dev framework: type: esp-idf wifi: ssid: YOUR_WIFI_SSID password: YOUR_WIFI_PASSWORD api: encryption: key: YOUR_ENCRYPTION_KEY # 用 esphome encryption key 生成 bluetooth_proxy: active: true # 开启主动连接被动模式改为 false connection_slots: 3 # 默认 3范围 1~9 logger:关键参数api是硬依赖组件加载时自动检查DEPENDENCIES [api]见 bluetooth_proxy/__init__.py L59connection_slots上限 9镜像自esp32_ble.IDF_MAX_CONNECTIONS见 esp32_ble/__init__.py L278。代码2编译与刷写esphome config ble-gateway.yaml # 先校验配置 esphome compile ble-gateway.yaml # 编译固件 esphome upload ble-gateway.yaml # USB 刷写之后可用 OTA验证结果刷写后在 Home Assistant 里添加 ESPHome 集成并填入加密密钥集成页面会出现 BLE 设备列表看到墙上的传感器 MAC 地址最小链路即跑通。配置能跑通只是第一步值得再看下数据到底怎么流转。03 原理拆解 图1数据流向与协议转换时序三个核心机制点到为止广播批处理广播包不是一条一推而是攒成批次发送批大小固定为 16源码在 bluetooth_proxy/__init__.py L404-L408。按每包约 80 字节算一批约 1.3KB接近 Wi-Fi MTU 上限把高频广播的流量压缩了近一个数量级。连接槽位池connection_slots决定能同时维持几条 GATT 连接槽位被占满时新的连接请求会被拒绝而不是踢掉旧连接。服务缓存cache_services默认true在 ESP32 上开启CONFIG_BT_GATTC_CACHE_NVS_FLASHbluetooth_proxy/__init__.py L383-L384首次连接完成服务发现后把结果存进 NVS之后重连省去重新发现。04 进阶配置与调优 ️跑通后最容易卡住你的是扫描参数和连接数。按参数 作用 推荐值整理scan_parameters.window扫描窗口BLE 每个扫描周期内实际监听射频的时间。与 Wi-Fi 共用射频时窗口超过600ms会触发编译期警告MAX_RECOMMENDED_WIFI_SCAN_WINDOW见 esp32_ble_tracker/__init__.py L151部分路由器下 Wi-Fi 会掉包断连。推荐值≤600ms代码注释给出的示例是interval: 320ms, window: 300ms。若使用 ESP-IDF ≥5.5.5 且开着 Wi-Fi 共存仲裁未显式设置时窗口会自动抬升到等于intervalesp32_ble_tracker/__init__.py L180-L199此时想降低占空比就显式写小窗口。scan_parameters.interval扫描间隔一个扫描周期的长度默认 320msESP-IDF 参考值见 esp32_ble_tracker/__init__.py L262-L264。间隔越小发现越快但对射频占用越大一般保持默认即可。connection_slots默认 3上限 9。每多占一个槽BLE 协议栈内存开销上升且该额度是全局的——同一固件里ble_client等其他客户端还要分槽总数别顶满 9。建议按同时需要主动连接的设备数 1给余量。cache_services仅 ESP32 支持其他平台会明确报错默认开启即可对重连频繁的设备收益最明显。代码3针对广播传感器收紧扫描参数esp32_ble_tracker: scan_parameters: interval: 320ms window: 300ms # Wi-Fi 同射频场景下建议不超过 600ms sensor: - platform: xiaomi_lywsd02mmc mac_address: A4:C1:38:XX:XX:XX temperature: name: Living Room Temperature05 踩坑实录 代码4表高频问题对照现象原因解决方法网关上线后 Wi-Fi 频繁掉线扫描窗口过长常见抄自旧教程的 1100ms占满共用射频window降到 300ms 左右编译时会打印警告提示阈值主动连接某设备一直失败但广播能收到连接槽被占满请求被拒绝调大connection_slots或排查其他客户端占用的槽位配置校验报错 Active connections are not supported非 ESP32 平台如仅广播型 hub上写了active: true相关选项该平台只能active: false只转发广播RP2 等非 ESP32 平台报cache_services无效服务缓存依赖 Bluedroid NVS仅 ESP32 有移除该项重连变慢属预期Home Assistant 看不到 BLE 设备只配了bluetooth_proxy没配api或集成密钥不匹配确认api存在且encryption.key与集成中一致问题清完上生产前再过一遍下面的清单。06 生产化清单 ✅加密必开api.encryption.key与ota的password是最低门槛密钥用esphome encryption key生成不要写弱口令。供电稳定BLE 射频突发电流不小5V 供电不稳会表现为 Wi-Fi/BLE 交替掉线优先用正规 5V/2A 适配器。日志分级日常保持INFO排查 BLE 问题再临时把esp32_ble、bluetooth_proxy相关标签调高别长期开 DEBUG。OTA 通道保留ota默认 esphome 平台作为刷机后无线更新的兜底避免每次改配置都要插 USB。槽位预算留余量connection_slots合计不要贴近 9 的上限给后续新增ble_client设备留空间。一句话收束一块 ESP32 bluetooth_proxy就是 Home Assistant 的 BLE 前哨参数调优的核心是扫描窗口和连接槽位两件事。延伸阅读可看仓库的 README.md 与 THREAT_MODEL.md有问题可到项目仓库提 issue 讨论。觉得有用可以点赞收藏关注获取更多 ESPHome 教程。【免费下载链接】esphomeESPHome is a system to control your ESP32, ESP8266, BK72xx, RP2040 by simple yet powerful configuration files and control them remotely through Home Automation systems.项目地址: https://gitcode.com/GitHub_Trending/es/esphome创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ESPHome 蓝牙网关完整指南：三步把 BLE 设备接入 Home Assistant
ESPHome 蓝牙网关完整指南三步把 BLE 设备接入 Home Assistant【免费下载链接】esphomeESPHome is a system to control your ESP32, ESP8266, BK72xx, RP2040 by simple yet powerful configuration files and control them remotely through Home Automation systems.项目地址: https://gitcode.com/GitHub_Trending/es/esphome墙上的小米温湿度计只发 BLE 广播进不了 Wi-Fi传统做法是另购网关或靠手机转发延迟高还依赖手机在线。用 ESPHome 的bluetooth_proxy组件一块 ESP32 就能直接扫描、连接这些 BLE 设备再由 Home Assistant 通过ESPHome API拉取数据。本文给出最小可运行配置并讲清扫描窗口、连接槽位这些调优参数。01 适用场景与价值 先界定一下它解决什么问题避免买错硬件BLE 传感器无法直连网络温湿度、门窗、电池供电的设备大多只有 BLE。本网关部署后Home Assistant 里的 ESPHome 集成会自动发现它们如xiaomi_lywsd02mmc组件可直接按 MAC 解析数据替代手机做蓝牙中转或专用硬件网关。集中式 BLE 代理多台 ESP32 网关共用一个接入点客户端按需选择网关比每台设备各配一个网关省成本。主动与被动两种模式被动模式只转发广播包适合广播型传感器主动模式active: true默认开启可建立 GATT 连接做读写适合门锁、开关这类需要交互的设备见 esphome/components/bluetooth_proxy/init.py。明确了边界下面用最短路径把它跑起来。02 三步跑通最小示例 只需 ESP32 开发板 供电环境上安装 ESPHomepip install esphome然后按写配置 → 编译 → 刷写三步走。代码1ble-gateway.yaml最小配置esphome: name: ble-gateway esp32: board: esp32dev framework: type: esp-idf wifi: ssid: YOUR_WIFI_SSID password: YOUR_WIFI_PASSWORD api: encryption: key: YOUR_ENCRYPTION_KEY # 用 esphome encryption key 生成 bluetooth_proxy: active: true # 开启主动连接被动模式改为 false connection_slots: 3 # 默认 3范围 1~9 logger:关键参数api是硬依赖组件加载时自动检查DEPENDENCIES [api]见 bluetooth_proxy/__init__.py L59connection_slots上限 9镜像自esp32_ble.IDF_MAX_CONNECTIONS见 esp32_ble/__init__.py L278。代码2编译与刷写esphome config ble-gateway.yaml # 先校验配置 esphome compile ble-gateway.yaml # 编译固件 esphome upload ble-gateway.yaml # USB 刷写之后可用 OTA验证结果刷写后在 Home Assistant 里添加 ESPHome 集成并填入加密密钥集成页面会出现 BLE 设备列表看到墙上的传感器 MAC 地址最小链路即跑通。配置能跑通只是第一步值得再看下数据到底怎么流转。03 原理拆解 图1数据流向与协议转换时序三个核心机制点到为止广播批处理广播包不是一条一推而是攒成批次发送批大小固定为 16源码在 bluetooth_proxy/__init__.py L404-L408。按每包约 80 字节算一批约 1.3KB接近 Wi-Fi MTU 上限把高频广播的流量压缩了近一个数量级。连接槽位池connection_slots决定能同时维持几条 GATT 连接槽位被占满时新的连接请求会被拒绝而不是踢掉旧连接。服务缓存cache_services默认true在 ESP32 上开启CONFIG_BT_GATTC_CACHE_NVS_FLASHbluetooth_proxy/__init__.py L383-L384首次连接完成服务发现后把结果存进 NVS之后重连省去重新发现。04 进阶配置与调优 ️跑通后最容易卡住你的是扫描参数和连接数。按参数 作用 推荐值整理scan_parameters.window扫描窗口BLE 每个扫描周期内实际监听射频的时间。与 Wi-Fi 共用射频时窗口超过600ms会触发编译期警告MAX_RECOMMENDED_WIFI_SCAN_WINDOW见 esp32_ble_tracker/__init__.py L151部分路由器下 Wi-Fi 会掉包断连。推荐值≤600ms代码注释给出的示例是interval: 320ms, window: 300ms。若使用 ESP-IDF ≥5.5.5 且开着 Wi-Fi 共存仲裁未显式设置时窗口会自动抬升到等于intervalesp32_ble_tracker/__init__.py L180-L199此时想降低占空比就显式写小窗口。scan_parameters.interval扫描间隔一个扫描周期的长度默认 320msESP-IDF 参考值见 esp32_ble_tracker/__init__.py L262-L264。间隔越小发现越快但对射频占用越大一般保持默认即可。connection_slots默认 3上限 9。每多占一个槽BLE 协议栈内存开销上升且该额度是全局的——同一固件里ble_client等其他客户端还要分槽总数别顶满 9。建议按同时需要主动连接的设备数 1给余量。cache_services仅 ESP32 支持其他平台会明确报错默认开启即可对重连频繁的设备收益最明显。代码3针对广播传感器收紧扫描参数esp32_ble_tracker: scan_parameters: interval: 320ms window: 300ms # Wi-Fi 同射频场景下建议不超过 600ms sensor: - platform: xiaomi_lywsd02mmc mac_address: A4:C1:38:XX:XX:XX temperature: name: Living Room Temperature05 踩坑实录 代码4表高频问题对照现象原因解决方法网关上线后 Wi-Fi 频繁掉线扫描窗口过长常见抄自旧教程的 1100ms占满共用射频window降到 300ms 左右编译时会打印警告提示阈值主动连接某设备一直失败但广播能收到连接槽被占满请求被拒绝调大connection_slots或排查其他客户端占用的槽位配置校验报错 Active connections are not supported非 ESP32 平台如仅广播型 hub上写了active: true相关选项该平台只能active: false只转发广播RP2 等非 ESP32 平台报cache_services无效服务缓存依赖 Bluedroid NVS仅 ESP32 有移除该项重连变慢属预期Home Assistant 看不到 BLE 设备只配了bluetooth_proxy没配api或集成密钥不匹配确认api存在且encryption.key与集成中一致问题清完上生产前再过一遍下面的清单。06 生产化清单 ✅加密必开api.encryption.key与ota的password是最低门槛密钥用esphome encryption key生成不要写弱口令。供电稳定BLE 射频突发电流不小5V 供电不稳会表现为 Wi-Fi/BLE 交替掉线优先用正规 5V/2A 适配器。日志分级日常保持INFO排查 BLE 问题再临时把esp32_ble、bluetooth_proxy相关标签调高别长期开 DEBUG。OTA 通道保留ota默认 esphome 平台作为刷机后无线更新的兜底避免每次改配置都要插 USB。槽位预算留余量connection_slots合计不要贴近 9 的上限给后续新增ble_client设备留空间。一句话收束一块 ESP32 bluetooth_proxy就是 Home Assistant 的 BLE 前哨参数调优的核心是扫描窗口和连接槽位两件事。延伸阅读可看仓库的 README.md 与 THREAT_MODEL.md有问题可到项目仓库提 issue 讨论。觉得有用可以点赞收藏关注获取更多 ESPHome 教程。【免费下载链接】esphomeESPHome is a system to control your ESP32, ESP8266, BK72xx, RP2040 by simple yet powerful configuration files and control them remotely through Home Automation systems.项目地址: https://gitcode.com/GitHub_Trending/es/esphome创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考