zigpy-cc

zigpy-cc 是一个用于 Python 3 的库实现，用于在 zigpy 项目中添加对德州仪器 CC 系列的 Zigbee 无线电模块芯片硬件的支持。包括但不限于德州仪器的 CC253x、CC26x2R 和 CC13x2 芯片，这些芯片被刷入定制的 Z-Stack 协调器固件。

本项目的目标是向 Home Assistant 内置的 ZHA (Zigbee 家庭自动化) 集成组件（通过 zigpy 库）添加对廉价德州仪器 CC 芯片 USB 棒的原生支持，使得配备此类硬件的 Home Assistant 能够原生支持直接控制兼容的 Zigbee 设备，例如飞利浦 HUE、GE、欧司朗 Lightify、小米/Aqara、宜家 Tradfri、三星 SmartThings 以及更多。

• https://www.home-assistant.io/integrations/zha/

zigpy-cc 允许 Zigpy 通过 TI Z-Stack 监视器测试 (MT) API 使用 UART/串行接口与德州仪器的 ZNP (Zigbee 网络处理器) 协调器固件进行交互。

zigpy-cc 库本身包含来自 zigbee-herdsman 项目（版本 0.12.24）的端口代码，该代码是由 Koen Kanters（又称 Koenkk GitHub）为 Zigbee2mqtt 项目编写的。zigbee-herdsman 库本身最初是 zigbee-shepherd 库的分支和重写，该库由 Zigbeer 项目创建。因此，如果代码改进或错误修正被提交到 zigbee-herdsman 库，那么理论上也可以将这些代码改进的一部分或大部分移植到 zigpy-cc 库中，以供其使用。

警告!!! - 工作正在进行中

免责声明：本软件按“原样”提供，不提供任何类型的保证。zigpy-cc 项目处于开发阶段，作为 WIP（工作进行中），目前尚未完全工作。

硬件要求

zigpy-cc 库目前正在使用基于德州仪器 CC2531 和 CC2652R 的适配器/板作为参考硬件进行测试，但从理论上讲，它应该可以在大多数基于德州仪器 CC Zigbee 无线电模块芯片硬件的 USB 适配器和 GPIO 模块上工作。请注意，除非您购买了预先刷入正确自定义固件的适配器，否则您还必须在使用硬件之前将芯片刷入兼容的 Z-Stack 协调器固件，请参阅下面的固件要求部分。

zigpy-cc 开发者正在测试的受支持参考硬件

• 带有 Zigbee2mqtt 项目中定制的 Z-Stack 1.2 协调器固件的 CC2531 USB 棒硬件
• 带有 Zigbee2mqtt 项目中定制的 Z-Stack 3.x 协调器固件的 CC2652R USB 棒和开发板硬件

zigpy-cc 开发者没有积极测试的受支持硬件

• 带有 Zigbee2mqtt 项目中定制的 Z-Stack 1.2 协调器固件的 CC2530 + CC2591 USB 棒和开发板硬件
• 带有 Zigbee2mqtt 项目中定制的 Z-Stack 1.2 协调器固件的 CC2530 + CC2592 USB 棒和开发板硬件
• 带有 Zigbee2mqtt 项目中定制的 Z-Stack 3.0 协调器固件的 CC2538 + CC2592 开发板硬件
• 带有 Zigbee2mqtt 项目中定制的 Z-Stack 3.0 协调器固件的 CC1352P-2 USB 棒和开发板硬件
• 带有 Zigbee2mqtt 项目中定制的 Z-Stack 3.x 协调器固件的 CC2652P USB 棒和开发板硬件
• 带有 Zigbee2mqtt 项目中定制的 Z-Stack 3.x 协调器固件的 CC2652RB USB 棒和开发板硬件

德州仪器芯片型号

德州仪器（TI）拥有相当多的不同无线 MCU 芯片，它们都用于/在开源 Zigbee 世界中被提及，如果您是初学者，可能会感到有些令人望而生畏。以下是型号和关键特性的快速摘要。

旧一代德州仪器（TI）芯片

• CC2530 = 2.4GHz Zigbee和IEEE 802.15.4无线MCU。8051内核，RAM非常少。需要昂贵的编译器许可证才能使用官方的TI堆栈。
• CC2531 = 带内置USB的CC2530。用于到处销售的廉价“Zigbee棒”。
• CC2538 = 2.4GHz Zigbee和IEEE 802.15.4无线MCU。CC253x带有更强大的ARM Cortex-M3 CPU内核，最高32KB RAM，以及最高512KB片上闪存。这是CC253x系列中唯一一款德州仪器官方发布了Zigbee 3.0（Z-Stack 3.0.x）固件的芯片，但仅作为选项，因为它仍然不如下面的新一代TI芯片强大。

新一代德州仪器芯片

仅2.4GHz频率芯片

• CC2652R = 仅2.4GHz的IEEE 802.15.4多协议（Zigbee、蓝牙、Thread、IEEE 802.15.4g IPv6启用智能对象如6LoWPAN以及专有系统）无线MCU。用于无线电堆栈的Cortex-M0内核和用于应用的Cortex-M4F内核，RAM充足。提供TI的免费编译器选项。
• CC2652RB = 与CC2652R引脚兼容的“无晶振”CC2652R，但与CC2652R不兼容固件。
• CC2652P = 带内置RF PA（功率放大器）的CC2652R，大大提高了范围。与CC2652R/CC2652RB neither引脚也不兼容固件。

多频段芯片

• CC1352R = sub 1 GHz和2.4 GHz无线MCU。基本上是CC2652R，带有一个额外的sub-1GHz无线电。
• CC1352P = 带内置RF PA（功率放大器）的CC1352R，大大提高了范围。

辅助TI芯片

• CC2591和CC2592 = 2.4 GHz范围扩展器。这些不是无线MCU，只是同一封装中的辅助PA（功率放大器）和LNA（低噪声放大器），以改善任何2.4 GHz无线电芯片的RF（射频）范围。

固件要求

固件要求是它们支持德州仪器“Z-Stack监控和测试”API，通过UART接口（串行通信协议），如果它们被刷入Zigbee Home Automation 1.2（Z-Stack Home 1.2）或Zigbee 3.0（Z-Stack 3.0.x或Z-Stack 3.x.0）固件，则它们应该这样做。

• https://github.com/Koenkk/Z-Stack-firmware/tree/master/coordinator

闪存固件和设备准备过程的必要硬件和设备最好由Zigbee2mqtt项目描述，该项目的社区维护和分发Zigbee-Heardsman库的自定义预编译Z-Stack协调器固件（.hex文件），该库也与zigpy-cc库兼容。

基于CC253x的USB适配器、模块和开发板通常不包含出厂时的引导加载程序，因此需要首先通过德州仪器的CC调试器或使用德州仪器的官方“SmartRF Flash-Programmer”（v1.1x）软件或类似替代方法和软件，通过硬件将预编译的Z-Stack协调器固件（.hex文件）闪存到硬件中。这些较旧的、功能较弱的芯片仅设计用于Zigbee Home Automation 1.2（Z-Stack Home 1.2）固件，因为它们实际上没有足够强大的功能来运行较新的Zigbee 3.0（Z-Stack 3.0.x）固件。应该指出，技术上可以在CC253x上运行非官方的Zigbee 3.0（Z-Stack 3.0.x）固件版本，但通常不推荐在这些较旧的适配器上使用较新的固件，如果您想实现具有多个配对设备的稳定Zigbee网络。

基于CC13x2/CC13x2x和CC26x2/CC26x2x的USB适配器、模块和开发板通常已经包含出厂时的引导加载程序，因此可以直接通过USB使用德州仪器的官方“SmartRF Flash-Programmer-2”（v1.8+）或“UniFlash”（6.x）或类似替代方法和软件，通过软件将预编译的Z-Stack协调器固件（.hex文件）闪存。这些较新的、功能更强的芯片仅支持较新的Zigbee 3.0（Z-Stack 3.0.x或Z-Stack 3.x.0）固件。

The Zigbee2mqtt 项目提供了详细的步骤说明，包括使用德州仪器的官方软件进行烧录，以及如何在新的 CC253x、CC13x2、CC26x2 和其他基于德州仪器的 CCxxxx 的 USB 适配器和开发板上首次烧录定制的 Z-Stack 协调器固件，无论这些设备是否包含引导加载程序。

• https://www.zigbee2mqtt.io/information/supported_adapters.html
• https://www.zigbee2mqtt.io/getting_started/what_do_i_need.html
• https://www.zigbee2mqtt.io/getting_started/flashing_the_cc2531.html
• https://www.zigbee2mqtt.io/information/alternative_flashing_methods.html

请注意，Zigbee2mqtt 项目还提供了一个 FAQ 和知识库，这些内容对于使用这些德州仪器的 ZNP 协调器硬件适配器/设备以及如何使用他们的 Z-Stack 很有帮助，同时还列出了应支持的网络设备。

端口配置

• 要配置 TI CC 串行设备的 usb 端口路径，只需指定 TTY（串行通信）端口，例如：/dev/ttyACM0
  • 或者，您可以尝试将端口设置为 auto 以启用自动 USB 端口发现（不保证一定能工作）。

开发人员应注意，德州仪器为不同 TI CC 芯片的 UART 接口推荐不同的波特率。

• CC2530 和 CC2531 默认推荐的 UART 波特率是 115200 波特。
• CC2538 也支持灵活的 UART 波特率生成，但最高不超过 460800 波特。
• CC13x2 和 CC26x2 支持灵活的 UART 波特率生成，最高可达 1.5 Mbps。

故障排除

对于使用 Home Assistant 的故障排除，一般建议首先在 Home Assistant 中仅启用 homeassistant.core 和 homeassistant.components.zha 的 DEBUG 日志记录，然后查看 home-assistant.log 文件，并尝试在将问题直接发布到如 zigpy-cc 这样的无线电库之前，利用 Home Assistant 社区解决他们的 ZHA 组件组合故障排除知识。

也就是说，首先检查 Home Assistant 核心和 ZHA 组件的调试日志，然后（从上往下而不是从下往上）进行故障排除/调试，在将调试日志发布到 zigpy 和 zigpy-cc 之前，尝试通过 Home Assistant 社区论坛寻求帮助。这是为了帮助过滤掉常见问题，而不是让 zigpy-cc 开发者被过多的日志淹没。

请也尝试最新的 zigpy 和 zigpy-cc 版本，（参见下面关于“测试新版本”的部分），如果使用最新版本仍然存在相同的问题，则除了核心和 zha 之外，在 Home Assistant 中还启用 zigpy 和 zigpy_cc 的调试日志记录。一旦在 Home Assistant 中启用了所有这些库的调试日志记录，您应尝试重现问题，然后携带这些日志在 zigpy-cc 仓库中提出问题。

要启用 Home Assistant 中的调试以获取调试日志，可以更新配置文件中的日志记录器配置部分，或者使用具有数据 {"level": "debug"} 的 logger.set_default_level 服务。

检查您想要在 Home Assistant 配置文件中设置日志记录器组件的地方，如下所示

logger:
default: info
logs:
asyncio: debug
homeassistant.core: debug
homeassistant.components.zha: debug
zigpy: debug
zigpy_cc: debug

测试新版本

在 Home Assistant 发布之前测试 zigpy-cc 库的新版本。

如果您正在使用 Supervised Home Assistant（以前称为 Hassio/Hass.io 发行版）

• 将 https://github.com/home-assistant/hassio-addons-development 添加为“附加组件”存储库
• 安装“自定义依赖部署”附加组件
• 更新配置如下

  pypi:
    - zigpy-cc==0.2.3
  apk: []
  

  其中 0.2.3 是新版本
• 启动附加组件

此版本即使在更新 HA 核心后也将保留。您可以使用此配置删除自定义依赖项

pypi: []
apk: []

如果您正在使用一些自定义 Python 安装的家庭助手，则执行以下操作

• 激活您的 Python 虚拟环境
• 使用 pip 更新包

  pip install zigpy-cc==0.2.3
  

通过 PyPI 发布

标记的版本也将通过 PyPI 发布

• https://pypi.ac.cn/project/zigpy-cc/
  • https://pypi.ac.cn/project/zigpy-cc/#history
  • https://pypi.ac.cn/project/zigpy-cc/#files

外部文档和参考

• http://www.ti.com/tool/LAUNCHXL-CC26X2R1
• http://www.ti.com/tool/LAUNCHXL-CC1352P

如何贡献

如果您想为此项目贡献代码或文档，我们建议您遵循以下指南中的步骤

• https://github.com/firstcontributions/first-contributions/blob/master/README.md
• https://github.com/firstcontributions/first-contributions/blob/master/github-desktop-tutorial.md

相关项目

Zigpy

zigpy是一个Zigbee协议栈集成项目，用于将Zigbee智能家居标准实现为Python 3库。使用zigpy进行Zigbee智能家居集成，您可以通过与zigpy兼容的Zigbee无线电库模块连接多个现成的Zigbee适配器来控制基于Zigbee的设备。目前支持控制二进制传感器（例如，运动和门传感器）、传感器（例如，温度传感器）、灯泡、开关和风扇等Zigbee设备类型。在Home Assistant（基于Python的开源智能家居软件）中存在一个zigbe的有效实现，作为其ZHA组件的一部分

ZHA 设备处理器

Home Assistant中的ZHA偏差处理依赖于第三方ZHA设备处理器项目。偏离或未完全符合由Zigbee联盟设定的标准规范的Zigbee设备可能需要开发定制的ZHA设备处理器（ZHA自定义quirks处理器实现），以使其所有功能都能与Home Assistant中的ZHA组件正常工作。这些Home Assistant的ZHA设备处理器可以用来解析非符合规范的Zigbee设备的自定义消息。作为ZHA设备处理器实现的zigpy的定制quirks实现类似于Zigbee-Herdsman转换器/ Zigbee-Shepherd转换器（Zigbee2mqtt使用）以及SmartThings Classic平台连接的设备处理器的概念，这意味着它们是物理设备的虚拟表示，提供了这些平台现有集成之外的功能。

ZHA 地图

Home Assistant可以使用zha-map项目构建ZHA网络拓扑地图。

zha-network-visualization-card

zha-network-visualization-card是一个自定义Lovelace元素，用于在Home Assistant中可视化ZHA Zigbee网络。

ZHA 网络卡

zha-network-card是一个自定义Lovelace卡片，用于在Home Assistant中显示ZHA网络和设备信息。