写ZHA quirk配置文件把控客肖邦开关接入HA

onespark123

我是在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子模块是依赖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设备签名，能找到下面的设备制造商和型号




上面的签名文件有三项需要留意：
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


3. 开始调试
接下来就是痛苦（或快乐？）的调试阶段了，在HA的configuration.yaml配置文件里面加入以下内容可以修改各模块的日志打印级别，在HA的配置->系统->日志里面可以对相关模块进行debug日志打印

logger:
  default: critical
  logs:
    zigpy: debug
    zhaquirks: debug

复制代码

把default改为了critical级别是为了减少不相关模块的日志打印

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

lexcao

赞！学习了！
我这样理解对不对：无法通过ZHA Toolkit正常调用功能的zigbee硬件，就要用这个方式来配置？

Ari

我也试试zha

onespark123

lexcao 发表于 2022-8-16 08:14
赞！学习了！
我这样理解对不对：无法通过ZHA Toolkit正常调用功能的zigbee硬件，就要用这个方式来配置？ ...

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

onespark123

Ari 发表于 2022-8-16 08:47
我也试试zha

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

lexcao

一些tuya的zigbee硬件（比如中央空调网关）无法通过ZHA使用。通过这个就能实现ZHA的直接使用啦

newspaper

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

onespark123

newspaper 发表于 2022-8-16 11:39
楼主您好，我有同一品牌同一型号的产品，但生产批次不同，用的芯片不同。
橙色灯的可以在zigbee2mqtt认出型 ...

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

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

newspaper

onespark123 发表于 2022-8-16 12:19
这个情况我也没碰到过，如果按截图日志里协商过程找不到Node Descriptor的话就有点难办了，这第一步的协 ...

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

onespark123

newspaper 发表于 2022-8-16 12:22
zigbee2mqtt 默认是11通道，不改成15的话。配对时都发现不到设备，改成15后，可以发现设备但认不出型号。 ...

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