xiaomi_ble组件：米家系蓝牙门锁接入HA的最佳方式，适配之路

XCray

大约两年前，HA加入了用于小米各种蓝牙设备的xiaomi_ble组件，之后越来越好用，支持的设备也越来越多。本贴只说门锁。

依托于本论坛，大家齐心协力，先后摸索出几条把蓝牙门锁接入HA的道路：
0. 间接法，利用闲置的插座灯等设备映射。
1. 蓝牙网关TTL数据，最终接近于产品级品质，但TTL输出并不是那么及时。
2. esp32+ESPHome打造的蓝牙网关，直接解密蓝牙消息，真正实现了本地化。但esp32不使用以太网的话蓝牙性能难免受限。
3. 多模网关+非常棒的xg3插件。我没有多模网关（主要是因为不支持我用的榉树门锁），没有实际经验。

上述1我深度参与过很多、2是我主导完成的，当然也挪用了网上大神们的开源代码和知识。其中2也是我使用时间最长、几年间最满意的方式。

但是，随着xiaomi_ble组件的到来，一个更完美更好的方法也出现了！只需要HA主机具备蓝牙，轻松实现全时扫描、代码维护最轻松、涉及硬件最少......

因为我的门锁是比较早期的产品，固件缺乏必要的更新（据说厂家已经倒闭了），小米也逐渐抛弃了对这款产品的支持（多模网关就不支持）。
毫不意外地，xiaomi_ble组件也不支持。

于是，闲来无事，开始琢磨如何修改代码使之支持我这款门锁。。。

首先：为啥对这款锁连发现都不发现呢？
device_trigger.py中有各设备型号的枚举，显然这个型号不在其中。
尝试增加一行：

"JSMSxxx": TRIGGER_MODEL_DATA[LOCK_FINGERPRINT],

复制代码

广播里有pid，pid到型号还有一个查询转换动作，在requirements引入的三方组件xiaomi-ble（这个和HA自己的xiaomi_ble不是一个东西）里，/usr/local/lib/python3.12/site-packages/xiaomi_ble，其中有个devices.py，增加：

    0x0197: DeviceEntry(
        name="Door Lock",
        model="JSMSxxx",
    ),

复制代码

附：对于绝大部分未在支持列表里的米系门锁来说，只修改这两个地方就足够了，欢迎测试（pid换成你自己的）。

修改容器内文件后重启HA，发现了，但没来得及输入beacon_key，后来就不再提示，只出现了一个默认禁用的信号强度实体。

回顾之前的积累，这款门锁会不断地发送两种广播报文：

a：“Service Data”(0x16)含有Mi Service(UUID：0xFE95)，MAC地址就在这个报文里。这种报文未加密、长度固定12字节，内容中只有一个字节的序号约6分钟变一次，其余固定不变  这条报文根据官方文档里MiBeacon的说明可以完美解读；

b：“Manufacturer Specific Data”(0xFF)含有小米公司识别码(ID：0x038F)，这类消息是加密的，又分为两种：
   b.1：待机状态下，长度固定为16，这是锁属性/状态报告，早期大概十来秒发一次，后来小米偷偷修改了，改成了差不多6分钟一次；
- 在开锁或发生其他事件时，门锁会发出长度不同的“Manufacturer Specific Data”广播报文：
   b.2：比如开锁时，长度为25，对应小米文档里的“锁事件”。显然，这个是很重要的；

（米家门锁只有Service Data一种报文）
这类消息包含Object，即各种事件之类的有用信息。

显然，HA可以发现它就是因为它会发送那条没啥用处的Service Data广播。而绝大多数米家系门锁，也根据小米的新的规范，只发送Service Data广播。所以，我只能自己撸代码

在三方组件xiaomi-ble的/usr/local/lib/python3.12/site-packages/xiaomi_ble/perser.py文件第1542行增加：

        for uuid, data in service_info.manufacturer_data.items():

复制代码

增加对manufacturer data广播的处理，后续代码照搬原有的。

具体事件/属性报告的处理上，门事件（7）、电量报告（0x100a）无需任何修改。锁属性（0x100e）需要略作修改：

    device.update_sensor(
        key=ExtendedSensorDeviceClass.SCORE,
        name="Lock Attribute",
        device_class=ExtendedSensorDeviceClass.SCORE,
        native_value=xobj[0],
        native_unit_of_measurement=None,
    )

复制代码

修改量最大的是门事件，榉树使用的是已经废弃的0x0005，而现在通用的是0x000B。参考现有代码，简化、修改（好在榉树实现的功能比较少比较简单）。

完工。

实测很完美（只是功能完美，性能很差，每次都比esp32还慢，不知为什么），鉴于本论坛内没有人使用同款锁，具体代码我就不贴了。

使用其他xiaomi_ble组件暂不支持的米家系门锁的朋友们，可以参考这个思路，经过比我这更简单的修改，即可实现接入HA。

qiaofei828

我用的小米全自动，可以用HOMEKIT集成接入本地接入HA，但它老是丢信息，不知道怎么回事，可能是蓝牙信号差

PerryLayne

感谢大佬分享，可惜对于我们这些没有相关知识基础的人来说，等同于天书。哎

想折腾一下试试。可视我连目录都没找到。尴尬。。。进行不下去

ghostist

这帖子为啥没刷到  今天还是我搜你ID找老帖子才发现的

我用的blemonitor   xiaomible这个当时改了也接入了，但是门锁信息很少
两个都不支持我的型号，不过好在协议是一样的  改PID就行了

seazer

大佬你好，我是来自于广东海洋大学的一名研究生，最近想在学校搞一套小型的基于米家生态的自动水肥一体化系统，在这里用到了米家的花花草草检测仪，但是到现在许多插件包括小米 BLE、miflora等都已经停止服务了，我想用这个传感器去连接HAss去实时传参，从而实现实时监控去配合下一步的供水开关启动等功能，请问能抽出宝贵时间为我指点一下吗？如果有需求我可以为您提供两台检测仪作为配置样本。

XCray

seazer 发表于 2024-7-22 23:23
大佬你好，我是来自于广东海洋大学的一名研究生，最近想在学校搞一套小型的基于米家生态的自动水肥一体化系 ...

ha内置的xiaomi_ble组件没有停止呀，而且也很好用

seazer

XCray 发表于 2024-7-23 12:10
ha内置的xiaomi_ble组件没有停止呀，而且也很好用

大佬，我是学农的，零基础，应该从你的 哪篇文章看？

XCray

seazer 发表于 2024-7-23 19:14
大佬，我是学农的，零基础，应该从你的 哪篇文章看？

完全从头说起的话不现实也没必要。
我那个置顶的科普贴可以先看看，先把ha的安装部署弄好，主机要有蓝牙。
然后添加xiaomi_ble组件、阅读该组件的官方文档、配置传感器。
最后就是自动化的设计和调试。

jerryxue

大佬，我用的就是和你同款的榉树门锁啊，当年你写了蓝牙网关TTL数据那篇帖子的时候我就买了相关的板子和连接线，不过后来搞了一半没成功又放弃了，这一次打算重新再来一遍，可以贴个代码吗？我好抄作业

XCray

jerryxue 发表于 2024-7-26 10:43
大佬，我用的就是和你同款的榉树门锁啊，当年你写了蓝牙网关TTL数据那篇帖子的时候我就买了相关的板子和连 ...

蓝牙网关TTL方案已经被更好的方案取代了，就是esp32刷esphome，也是我到现在依然在用的。

这个帖子更多的是尝试，实际用下来虽然功能没问题，但性能较差，每次收到消息都比esp32慢，不知道为啥。所以我也就没再继续深入。

推荐esp32+esphome方案。