请选择 进入手机版 | 继续访问电脑版

『瀚思彼岸』» 智能家居技术论坛

 找回密码
 立即注册
查看: 2390|回复: 16

[经验分享] 写ZHA quirk配置文件把控客肖邦开关接入HA

[复制链接]

1

主题

13

帖子

114

积分

注册会员

Rank: 2

积分
114
金钱
101
HASS币
0
发表于 2022-8-15 23:38:21 | 显示全部楼层 |阅读模式
本帖最后由 onespark123 于 2022-8-16 10:43 编辑

我是在ZHA里面配置的,我的网关用的是Sonoff的USB Dongle Plus,HA是跑在群晖NAS的虚拟机里的,映射了一个usb端口给HA(ZHA能自动识别Sonoff这个网关,所以插上重启就能自动发现配置好了,挺方便)

——————————————
配置方法
1. 确保ZHA打开后,在configuration.yaml里面加入下面的配置
zha:
  enable_quirks: true
  custom_quirks_path: /config/zha_quirks
   a. enable_quirks设置为true,让zha接受自定义的quirk脚本文件,把非标准配置的zigbee设备转化为标准zcl库里的交互方式,quirk应该类似于zigbee2MQTT里面自己加新设备时写的那种配置文件
    b. custom_quirks_path表示的是你自定义quirk脚本的存放位置根目录


2. 接下来把我附件里的zha_quirks.zip解压后把目录放到HA的config目录下,重启HA之后再尝试在ZHA里面添加肖邦单键或双键开关试试(开关要进入配对模式,黄灯慢闪才是在配对中)


——————————————
代码解释


代码里面有一个konke目录,里面的chopin_double_switch.py和chopin_single_switch.py是我照着原本这个目录其他文件写的,用来给肖邦双键和单键开关的配置文件。

代码来源于HA的官方文档里给过一个开源仓zigpy/zha_device_handlers,里面有个目录zhaquirks是社区写的一些quirks脚本配置文件。其中有一个konke的目录,但设备没有国内的肖邦、灵悦等等这些产品。我是照着已有的控客的quirks自己反复调试代码之后摸出来的肖邦开关的映射逻辑。

因为我家只有控客的肖邦单键和双键,所以只写了两个配置文件,如果有其他的控客设备可以往下尝试自行配对然后摸索写出类似的配置文件

——————————————
非ZHA官方支持的控客设备怎么接入

- 一、理解ZHA -
在HA官网对ZHA的描述里可以看到它支持几类主流设备类型,比如常见的开关、灯、按键、门锁、传感器、环境感应、窗帘、温控设备、风扇等等,基本是ZCL标准里面的,可以自行翻看一下ZHA官方介绍文档
ZHA supported devices.PNG

ZHA子模块是依赖zigpy/zigpy开源库实现的ZCL设备逻辑,正常情况下按照ZCL(Zigbee Cluster Library - Zigbee联盟发布的Zigbee协议智能设备的类型和细节定义标准)标准实现的设备都是可以用ZHA加入HA并且正常使用的,不过各大厂商多多少少都会按自己的方式改写一些逻辑,跟标准里不一样,直接配对加入HA的话会有一些适配问题。所以才会有quirks这种配置文件,把各个非标准实现的zigbee设备的逻辑翻译成ZHA能理解的标准ZCL设备逻辑,这样就能愉快玩耍了。


- 二、理解quirks配置文件 -
上面提到的开源仓zigpy/zha_device_handlers,zhaquirks目录就有社区针对各个厂商设备写的quirks配置文件,里面小米、aqara、涂鸦的设备一大堆。这个仓库首页Readme写了一些基础知识,我是看了他的描述才大概理解了zigbee协议标准,以及quirk怎么玩的。

简单来说,quirk配置文件主要有两个重要部分,一个是signature,一个是replacement。signature表示了识别这个设备所必要的信息,具体有哪些在下面截图后有说;replacement则是表示这个设备在ZHA要怎么表现,相当于一个翻译器。另外有的配置文件里面最后还会接device_automation_triggers部分,这个主要是方便事件上报的时候,在HA里能够捕捉并在日志里打印自定义事件,方便自动化里面识别。


- 三、开始调试 -

1. 直接配对非标准zigbee设备
虽然这些设备没有完全按照标准实现,但他们整体框架基本还是遵从Zigbee协议,包括设备协商通信等逻辑是不变的。所以即使没有对应的配置文件,直接在ZHA里添加配对一些非标准zigbee设备是能够协商配对成功的,我家的肖邦开关最开始就是这么加入ZHA的。这是我能调试控客开关的基础,如果打开配对模式的设备没法在ZHA里找到的话,下面的方法可能就不适用了

(不过直接协商完的控客开关会表现异常,不管是HA里控制还是实际开关控制,按下打开键之后开关会马上自动关掉。所以才需要写quirks配置文件去改正逻辑)

协商完成的设备可以在HA配置 -> 设备里找到,点开设备信息三个点里面的Zigbee设备签名,能找到下面的设备制造商和型号
zigbee签名位置.png

控客双键开关的zigbee签名.png

上面的签名文件有三项需要留意:
a. "endpoints"里面的那一堆
b. 设备制造商(manufacturer)
c. 型号(model)

这三项是ZHA识别这个设备的关键,相当于这个设备的身份证,新写的针对本设备的quirk配置文件的signature部分必须要准确指定上面三项内容(具体可以打开一个quirk配置文件的代码看看)

2. 写自己的quirk配置文件
如果要新写quirk配置文件,可以先把signature填对,确保ZHA能够按照这个配置文件去识别你的设备。replacement部分可以先照抄signature的部分(除了MODELS_INFO,这部分在replacement里面不需要)

以控客肖邦开关为例,如果代码里的quirks配置脚本识别成功,在设备信息下面的Quirk能看到调用的是konke.chopin_single_switch或者chopin_double_switch里面的类,也就是配置文件里改写的内容。如果没找到说明应该这个配置文件不适用于你的设备,型号什么的匹配不上ch,oinhopin_double_switch_double_switchchdopin_double_switch
生效quirk信息.png

3. 开始调试
接下来就是痛苦(或快乐?)的调试阶段了,在HA的configuration.yaml配置文件里面加入以下内容可以修改各模块的日志打印级别,在HA的配置->系统->日志里面可以对相关模块进行debug日志打印
logger:
  default: critical
  logs:
    zigpy: debug
    zhaquirks: debug
把default改为了critical级别是为了减少不相关模块的日志打印

在设备操作的时候,会打印一些重要的调试日志,包括解析zigbee通信消息,对设备进行处理,上报事件等等日志。我的能力有限,基本是通过正常可操作的zigbee设备的调试日志进行对比以及读Zigpy源码,才找出控客开关有哪里处理不一样的。这个调试花了我两三周的时间,基本都是在读代码,猜逻辑。如果对HA的代码很熟悉的话这个过程应该很快~


zha_quirks.zip

14.35 KB, 下载次数: 61

评分

参与人数 4金钱 +34 收起 理由
zjxoye + 2 我是纯小白,但是精装房已经装好控客了,我.
sorrypqa + 8 膜拜大神!
samhsba + 8 感谢楼主分享!
dscao + 16 感谢楼主分享!研究代码有同感!.

查看全部评分

回复

使用道具 举报

35

主题

364

帖子

2193

积分

金牌会员

Rank: 6Rank: 6

积分
2193
金钱
1829
HASS币
10
发表于 2022-8-16 08:14:29 | 显示全部楼层
本帖最后由 lexcao 于 2022-8-16 08:17 编辑

赞!学习了!
我这样理解对不对:无法通过ZHA Toolkit正常调用功能的zigbee硬件,就要用这个方式来配置?
回复

使用道具 举报

0

主题

557

帖子

2143

积分

金牌会员

Rank: 6Rank: 6

积分
2143
金钱
1586
HASS币
0
发表于 2022-8-16 08:47:31 | 显示全部楼层
我也试试zha
回复

使用道具 举报

1

主题

13

帖子

114

积分

注册会员

Rank: 2

积分
114
金钱
101
HASS币
0
 楼主| 发表于 2022-8-16 10:52:22 | 显示全部楼层
lexcao 发表于 2022-8-16 08:14
赞!学习了!
我这样理解对不对:无法通过ZHA Toolkit正常调用功能的zigbee硬件,就要用这个方式来配置? ...

是的,理论上只要写对配置文件就能把所有支持类型的zigbee硬件调试成ZHA能正常使用的样子
回复

使用道具 举报

1

主题

13

帖子

114

积分

注册会员

Rank: 2

积分
114
金钱
101
HASS币
0
 楼主| 发表于 2022-8-16 10:53:32 | 显示全部楼层

个人感觉ZHA配置比较简单,而且相关源码都是Python,对我来说理解起来比较快,可以试试~
回复

使用道具 举报

35

主题

364

帖子

2193

积分

金牌会员

Rank: 6Rank: 6

积分
2193
金钱
1829
HASS币
10
发表于 2022-8-16 11:37:56 | 显示全部楼层
一些tuya的zigbee硬件(比如中央空调网关)无法通过ZHA使用。通过这个就能实现ZHA的直接使用啦
回复

使用道具 举报

196

主题

534

帖子

3761

积分

论坛元老

Rank: 8Rank: 8

积分
3761
金钱
3227
HASS币
0
发表于 2022-8-16 11:39:09 | 显示全部楼层
本帖最后由 newspaper 于 2022-8-16 11:41 编辑

楼主您好,我有同一品牌同一型号的产品,但生产批次不同,用的芯片不同。
橙色灯的可以在zigbee2mqtt认出型号可以工作,按您的方法在zha里也可以工作。
但蓝色指示灯的在zigbee2mqtt认不出型号不能工作,在zha里也认不出型号,也不能工作,修改能里?可以让它在zha里工作呢?

3.png 1.png 2.png
回复

使用道具 举报

1

主题

13

帖子

114

积分

注册会员

Rank: 2

积分
114
金钱
101
HASS币
0
 楼主| 发表于 2022-8-16 12:19:29 | 显示全部楼层
newspaper 发表于 2022-8-16 11:39
楼主您好,我有同一品牌同一型号的产品,但生产批次不同,用的芯片不同。
橙色灯的可以在zigbee2mqtt认出型 ...

这个情况我也没碰到过,如果按截图日志里协商过程找不到Node Descriptor的话就有点难办了,这第一步的协商都没通过,可能改quirk也没用

看Zigbee2MQTT里面控客设备的描述说控客的设备只支持15、20、25的Zigbee信道,不确定是不是信道不一致导致协商的问题,初始通信就失败了。按照ZHA官方文档里的描述的话改一下configuration.yaml可以修改zigbee的信道,不过文档说这么改了可能会让网络重置,已加入的设备会失效,所以请谨慎操作。我能力有限,不知道你这种问题要怎么解决




回复

使用道具 举报

196

主题

534

帖子

3761

积分

论坛元老

Rank: 8Rank: 8

积分
3761
金钱
3227
HASS币
0
发表于 2022-8-16 12:22:49 | 显示全部楼层
onespark123 发表于 2022-8-16 12:19
这个情况我也没碰到过,如果按截图日志里协商过程找不到Node Descriptor的话就有点难办了,这第一步的协 ...

zigbee2mqtt 默认是11通道,不改成15的话。配对时都发现不到设备,改成15后,可以发现设备但认不出型号。 ZHA默认的就是15通道。也是只能发现设备,但同样认不出型号。
修改哪里,能认出型号呀?
回复

使用道具 举报

1

主题

13

帖子

114

积分

注册会员

Rank: 2

积分
114
金钱
101
HASS币
0
 楼主| 发表于 2022-8-16 12:27:07 来自手机 | 显示全部楼层
newspaper 发表于 2022-8-16 12:22
zigbee2mqtt 默认是11通道,不改成15的话。配对时都发现不到设备,改成15后,可以发现设备但认不出型号。 ...

哦我想起像绿米魔方之类的设备加入ZHA的时候,在配对时需要不停地周期按配对键,大概1秒一次。你看看配对时按开关的配对或者按键会不会蹦出新的日志呢
回复

使用道具 举报

您需要登录后才可以回帖 登录 | 立即注册

本版积分规则

Archiver|手机版|小黑屋|Hassbian

GMT+8, 2024-3-29 05:01 , Processed in 0.062056 second(s), 35 queries .

Powered by Discuz! X3.4

Copyright © 2001-2021, Tencent Cloud.

快速回复 返回顶部 返回列表