实现EZSP的库
项目描述
波纹
波纹 是一个针对 zigpy 项目的 Python 3 库实现，用于添加 Zigbee 无线电支持，用于基于 Silicon Labs EM35x ("Ember") 和 EFR32 ("Mighty Gecko") 的 Zigbee 协调器设备，并使用 EZSP (EmberZNet Serial Protocol) 接口。
该项目可以作为独立库使用，然而，本项目的主要目标是向Home Assistant的内置ZHA（Zigbee家庭自动化）集成组件添加对基于EmberZNet Zigbee无线电的USB棒设备（即“Ember”和“Mighty Gecko”基于的适配器/线夹/模块）的原生支持，使带有此类硬件的Home Assistant能够原生支持直接控制兼容的Zigbee设备，例如；飞利浦HUE、GE、Ledvance、欧司朗Lightify、小米/Aqara、IKEA Tradfri、三星SmartThings，等等。
bellows库通过UART使用EZSP协议串行接口API与Zigbee网络协处理器（NCP）进行交互，使用EmberZNet PRO Zigbee协调器固件。该库目前支持Silabs旧EM35x "Ember"和他们的新EFR32 "Mighty Gecko" SoC使用ASH协议通过串行接口，使用Silabs EZSP（EmberZNet串行协议）API版本v4/v5/v6/v7/v8。
硬件要求
基于EmberZNet的Zigbee无线电使用EZSP协议（通过zigpy的bellows库）
- Tube的Zigbee网关（Silabs EFR32版本） 注意！基于ESP32的以太网桥作为预组装或DIY项目可用。
- ITEAD Sonoff ZBBridge（注意！基于WiFi的桥接器不建议用于ZHA与EZSP无线电。此外，此设备必须先刷入Tasmota固件和EmberZNet固件）
- ITead Zigbee 3.0 USB线夹（EFR32MG21）型号9888010100045 注意！由于稳定性问题，目前不推荐。
- Nortek GoControl QuickStick Combo型号HUSBZB-1（Z-Wave & Zigbee Ember 3581 USB适配器）（注意！并非必需，但建议升级EmberZNet NCP应用程序固件）
- Elelabs Zigbee USB适配器（注意！并非必需，但建议升级EmberZNet NCP应用程序固件）
- Elelabs Zigbee Raspberry Pi外壳（注意！并非必需，但建议升级EmberZNet NCP应用程序固件）
- DEFARO SprutStick Pro（也称为Defaro SprutStick ZigBee 2 Pro）
- Telegesis ETRX357USB/ETRX357USB-LRS/TRX357USB-LRS+8M（注意！此设备必须先刷入其他EmberZNet固件）
- IKEA Billy EZSP - DIY ICC-1 / ICC-A-1模块，来自IKEA TRÅDFRI设备。（注意！此设备必须先破解并刷入其他EmberZNet固件）
- Tuya TYGWZ01和重新命名的Lidl Silvercrest智能家居网关（注意！此设备必须先破解并刷入其他EmberZNet固件）
- 基于Silicon Labs Ember 3587的Bitron Video/Smabit BV AV2010/10 USB线夹（也称为Telekom Magenta线夹）
- EByte E180-Z120B SMD模块和EByte E180-Z120B-TB评估板（注意！此设备必须先破解并刷入其他EmberZNet固件）
关于Zigbee到WiFi桥接器的警告
zigpy需要一个强大的连接，在zigpy无线电库和Zigbee无线电的串行端口之间。使用诸如ITEAD Sonoff ZBBridge或通过WiFi网络的Ser2Net串行代理连接等解决方案，预期会在日志中看到NCP进入失败状态。请求APP控制器重启。这是操作的正常部分，表明通信丢失导致zigpy无线电库和Zigbee无线电之间的数据包丢失。因此，当希望使用zigpy获得稳定的Zigbee环境时，不建议通过WiFi使用串行网络代理/网桥/服务器。
固件要求
bellows要求Zigbee适配器/板/模块预先烧录/烧录与EmberZNet PRO Zigbee Stack兼容的固件，该固件使用标准Silicon Labs EZSP（EmberZNet串行协议）API通过串行接口进行ASH协议。
Silabs曾经提供两种主要的NCP映像，预构建的固件用于EM35x，一种映像支持硬件流控制，波特率为115200，另一种映像支持软件流控制，波特率为57600。
Silicon Labs不再提供预构建的固件映像，因此现在您必须使用EmberZNet PRO Zigbee协议栈软件的Simplicity Studio SDK构建和编译固件。Simplicity Studio是免费下载的，但构建和编译EmberZNet PRO Zigbee固件映像需要您有一个官方Zigbee开发套件的序列号已注册到您的Silicon Labs用户帐户。
固件升级资源
- 有关固件要求和推荐固件，请参阅Zigpy Wiki。
- Elelabs EZSP固件更新实用程序（应适用于大多数基于EFR32的Zigbee协调器，带有Silicon Labs标准引导加载程序）.
- walthowd的Docker固件更新映像，用于升级Nortek/GoControl/Linear HUSBZB-1和Telegesis ETRX357 Zigbee协调器适配器.
EmberZNet和EZSP协议版本
Silicon Labs目前没有EmberZNet SDK或EZSP协议版本更改的汇总列表。EZSP的添加、更改和删除仅列在“Zigbee EmberZNet发布说明”（EmberZNet SDK）的“新项目”部分，以及每个EmberZNet SDK发布中包含的UG100 EZSP参考指南。
最大的变化是在EZSP v4（首次添加到EmberZNet 4.7.2 SDK）和添加到EmberZNet 5.9.0 SDK的EZSP v5之间，它需要Legacy Frame ID 0xFF。从EZSP v5到EZSP v6的更改是在EmberZNet 6.0.0 SDK中进行的。从EZSP v6到EZSP v7的更改在EmberZNet 6.4.0 SDK中。EmberZNet 6.7.0 SDK添加了EZSP v8（以及Secure EZSP协议版本2）。
今天可能更重要的是要知道，EZSP v5、v6和v7（EmberZNet 6.6.x.x）使用相同的帧格式，但EmberZNet 6.7.x.x/EZSP v8引入了新的帧格式，并将命令ID字段从8位扩展到16位，并且不是向后兼容的。
项目状态
该项目处于早期阶段，因此API可能会更改。
目前实现的功能包括
- EZSP UART网关协议
- EZSP应用协议
- CLI封装基本的ZigBee网络操作（例如，扫描和建立网络）
- ZDO功能（带有CLI）
- ZCL功能（带有CLI）
- 一个具有设备状态持久性的应用框架
CLI的示例用法
$ export EZSP_DEVICE=/dev/ttyUSB1
$ bellows devices
Device:
NWK: 0x1ee4
IEEE: 00:0d:6f:00:05:7d:2d:34
Endpoints:
1: profile=0x104, device_type=None, clusters=[0, 1, 3, 32, 1026, 1280, 2821]
2: profile=0xc2df, device_type=None, clusters=[0, 1, 3, 2821]
Device:
NWK: 0x64a6
IEEE: d0:52:a8:00:e0:be:00:05
Endpoints:
1: profile=0x104, device_type=None, clusters=[0]
2: profile=0xfc01, device_type=None, clusters=[]
$ bellows zdo 00:0d:6f:00:05:7d:2d:34 get_endpoint 1
<SimpleDescriptor endpoint=1 profile=260 device_type=1026 device_version=0 input_clusters=[0, 1, 3, 32, 1026, 1280, 2821] output_clusters=[25]>
$ bellows zcl 00:0d:6f:00:05:7d:2d:34 1 1026 read_attribute 0
0=1806
配置
USB、UART/串行和GPIO适配器的端口配置
- 要配置使用本地连接的USB适配器设备的串行接口，请指定TTY（串行通信）端口，例如：
/dev/ttyUSB1- 值得注意的是，虽然一些适配器内置了USB核心（如基于EM3588的设备），它们可能适用于任何波特率速度，但大多数USB闪存盘/转接器都带有外部的USB转串行转换/桥接芯片（例如Silabs CP210x、FTDI FT23x或WCH CH340），这需要您设置特定的波特率。因此，请注意，某些NCP固件映像需要使用115200波特率速度，而其他则使用57600波特率速度。此外，有些使用无流控制（NSW流控制），而有些则要求使用软件流控制（SW或XON/XOFF流控制）或硬件流控制（HW或RTS/CTS流控制）。
- 如果USB无线电未识别，可能需要将串行适配器的设备ID告知驱动程序，例如Silicon Labs的CP210x驱动程序。
- 找到设备ID（如
lsusb命令所示）。例如，Bitron Video/Smabit BV AV2010/10的设备ID可能是10c4 8b34。 - 拔掉设备。
- 输入以下命令（将示例ID 10c4 8b34 替换为您系统上
lsusb列出的实际ID）
sudo -s modprobe cp210x echo 10c4 8b34 > /sys/bus/usb-serial/drivers/cp210x/new_id- 插入转接器。现在它应正确识别为ttyUSBx。
通过网络适配器的端口配置
- 要配置使用基于远程以太网或WiFi的网络连接的桥接/代理Zigbee适配器，例如Sonoff ZBBridge或ZiGate WiFi网关，请输入
socket://<适配器-IP>:<端口>并使用115200波特率作为端口速度。
NVRAM备份和还原
警告！请注意，这是一个高度实验性的功能！理论上，这允许在不同硬件版本之间备份和还原NCP状态。
NVRAM备份可以执行，以便在不同无线电硬件之间迁移，只要它们基于相同的芯片。其他任何东西都不会工作。如果在不同的硬件之间执行此操作，新硬件上的EUI64将不同，这意味着所有设备的绑定表都将错误。
To export TC config, see bellows backup --help usually it is just bellows backup > your-backup-file.txt.
The backup contains your network key, so you probably should keep that file secure.
To import, see bellows restore --backup-file your-backup-file.txt
注意！还原不会还原NCP子设备，并依赖于子设备找到新的父设备。您可以选择重新配置所有设备（建议这样做以更新绑定）或另外一种方法是在新硬件上覆盖EUI64，这本质上会产生一个克隆。如果您决定采取后一种方法，请务必小心。EUI64只能更改一次，一旦设置，就无法更改，除非使用专用硬件（SWD程序员）。
已测试迁移
- 待办事项
测试新版本
在Home Assistant发布之前测试bellows库的新版本。
如果您正在使用Supervised Home Assistant（以前称为Hassio/Hass.io发行版）
- 将https://github.com/home-assistant/hassio-addons-development作为“附加组件”存储库添加
- 安装“自定义依赖项部署”附加组件
- 更新配置如下
其中0.16.0是新版本pypi: - bellows==0.16.0 apk: [] - 启动附加组件
如果您正在使用Home Assistant的某些自定义Python安装，则进行如下操作
- 激活您的Python虚拟环境
- 使用
pip更新软件包pip install bellows==0.16.0
通过PyPI提供的软件包可用
标记版本的软件包也通过PyPI上的"bellows"项目发布
标记版本的旧版本软件包仍在PyPI上的"bellows-homeassistant"项目中提供
参考文档
- EZSP UART网关协议参考：https://www.silabs.com/Support%20Documents/TechnicalDocs/UG101.pdf
- EZSP 参考指南： http://www.silabs.com/Support%20Documents/TechnicalDocs/UG100-EZSPReferenceGuide.pdf
- EZSP UART 主机接口参考指南： https://www.silabs.com/documents/public/application-notes/an706-ezsp-uart-host-interfacing-guide.pdf
- Silicon Labs 论坛 https://www.silabs.com/community/wireless/zigbee-and-thread/forum
如何贡献
如果你想为此项目做出贡献，我们建议你遵循以下指南中的步骤
- https://github.com/firstcontributions/first-contributions/blob/master/README.md
- https://github.com/firstcontributions/first-contributions/blob/master/github-desktop-tutorial.md
一些开发者可能也对以硬件形式接收捐赠感兴趣，例如 Zigbee 模块或设备，即使这种捐赠通常是无附加条件的，但在许多情况下，这可以增强开发者的积极性，间接提高该项目的开发。
下载文件
下载适用于您平台的文件。如果您不确定选择哪个，请了解有关安装包的更多信息。
源代码发行版
构建发行版
bellows-0.40.6.tar.gz的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 60113aeb78db7870c4da50a4c0b661e44d71dd7b95902c550333514522b91790 |
|
| MD5 | 489fb2f5ac0275820637c85ee9b6a56a |
|
| BLAKE2b-256 | c68028ab9304cef2d5df5085c732592632e18c6b3cfe1868280cb216e8b0764e |
bellows-0.40.6-py3-none-any.whl的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 34341da7a814f4e46c9c201e44ee620eadf7f492084cb60fbc4d02382c05682d |
|
| MD5 | 02a9b249828d5c6967a925b145147993 |
|
| BLAKE2b-256 | 688732ad96b54d0b50e8455ef91aae323599f23c674ec9b27d1b2b266d08a919 |
