先确认 IRQ 的真实语义

环境光传感器常见的 IRQ 至少有两种：

• Data Ready IRQ：一次转换完成后通知 MCU 读取结果；
• Threshold IRQ：光照超过高阈值或低于低阈值时通知 MCU。

两者看起来都是一根中断线，功耗含义却完全不同。

Data Ready IRQ 如果能配合 single-shot 使用，传感器完成一次转换后可能自动回到 Standby，适合低功耗周期采集。Threshold IRQ 往往要求传感器保持连续测量；MCU 虽然可以睡眠，传感器本身却持续消耗 Active 电流。

因此，决定是否使用 IRQ 前应先回答：

1. IRQ 是转换完成中断，还是阈值中断？
2. IRQ 开启后，传感器能否自动回到 Standby？
3. 传感器等待 IRQ 时的典型和最大电流是多少？
4. 业务能接受多大的光照变化检测延迟？

如果数据手册只描述“Active 模式下设置上下阈值并等待中断”，它通常不是低功耗 single-shot 完成中断。

常见的四类设计

Single-shot 或 Forced Mode

主机发起一次转换，传感器完成后自动回到低功耗模式。MCU 可以通过定时器或 Data Ready IRQ 回收结果：

1
2
3
4
5
6

MCU 启动转换
  -> MCU 休眠
  -> 转换完成
  -> 定时器或 Data Ready 唤醒
  -> 读取结果
  -> 传感器已回到 Standby

这是周期采集最理想的模式，因为不需要 MCU 额外发命令关闭传感器，也不容易因错误路径遗漏休眠动作。

超低功耗自主阈值监测

部分器件有独立的低功耗比较器或专用监测引擎。它可以用较低电流持续判断阈值，只在环境发生明显变化时拉起 IRQ。

这种方案适合“平时不关心具体 lux，只在由亮变暗时唤醒”的产品，但必须确认数据手册给出的电流属于低功耗监测引擎，而不是普通连续测量模式。

MCU 定时按需采样

如果器件只有 Standby 和连续 Active，没有 single-shot 自动回休眠能力，常见做法是由 MCU 把一次连续模式裁剪成一次采样：

1
2
3
4
5
6
7

传感器保持 Standby
  -> 软件定时器到期
  -> MCU 设置 Active
  -> MCU 等待转换，条件允许时再次休眠
  -> 检查 Data Valid / New Data
  -> 读取结果
  -> 设置 Standby

这种设计需要状态机保证任何成功、超时或 I2C 错误路径最终都能让传感器回到 Standby，但其平均电流通常远低于长期连续 Active。

连续测量加阈值 IRQ

如果产品必须在较短时间内发现明暗变化，连续模式可能无法避免。此时可以：

• 使用业务可接受的最长 Measurement Rate；
• 设置高低阈值迟滞，避免在临界点反复触发；
• 使用 persistence，要求连续多次越界后才中断；
• MCU 被唤醒后批量处理必要工作，再尽快睡眠。

这是用功耗换取响应速度，不应包装成单纯的“IRQ 低功耗优化”。

用占空比估算方向

假设某颗环境光传感器的参数为：

• Active 电流：266 µA；
• Standby 电流：5 µA；
• 每 5 秒采集一次；
• 每次从唤醒到读取完成需要 25 ms。

只考虑传感器自身，平均电流约为：

1
2

(266 µA × 25 ms + 5 µA × 4975 ms) / 5000 ms
≈ 6.3 µA

如果异常情况下等待和重试使 Active 时间增加到 55 ms：

1
2

(266 µA × 55 ms + 5 µA × 4945 ms) / 5000 ms
≈ 7.9 µA

而长期连续 Active 可能仍是数百微安量级。这个简单估算足以判断架构方向，但不能代替测量：

• 手册电流可能只对应某组 Integration Time 和 Measurement Rate；
• Active 内部可能包含测量和 idle，平均电流未必能线性外推；
• MCU、I2C 上拉、稳压器和无线唤醒也会影响整机结果；
• Standby 电流应同时关注典型值、最大值和温度范围。

优先优化采样策略，而不是一两毫秒

低功耗优化最容易陷入“把等待时间减少 2 ms”的局部问题。对于几秒甚至几十秒才采一次的数据，减少采样次数通常更有效。

合并周期请求和事件请求

设备可能同时有固定周期采样和外部事件触发采样。如果事件刚好发生在周期采样之后，重复启动一次转换没有必要。

可以维护：

• 最近一次有效样本的时间；
• 当前是否正在采样；
• 哪些业务正在等待本次结果；
• 是否还存在必须重新采样的 pending 请求。

如果样本足够新就直接复用；如果采样正在进行，就让新的使用者等待当前结果，而不是再次启动传感器。

使用自适应采样周期

固定 5 秒并不总是合理。更常见的策略是：

1
2
3
4
5
6
7
8
9
10
11

环境稳定、无事件
  -> 30 至 60 秒慢速采样

检测到人体或其他业务事件
  -> 立即采样一次

光照接近业务判断阈值
  -> 短时间提高采样频率

环境重新稳定
  -> 退回慢速周期

如果业务只需要“事件发生时的光照”，甚至可以采用事件触发采样加慢速健康检查，而不是永久维持高频周期采样。

对齐已有唤醒窗口

传感器采样可以尽量对齐：

• 外部 GPIO 或 PIR 唤醒；
• 无线设备的 poll；
• 电池测量；
• 其他周期维护任务。

这样不仅降低传感器占空比，还能减少 MCU 从 retention 或 deep sleep 独立唤醒的次数。

采样频率和上报频率要解耦

采到新数据不代表必须立即发无线消息。常见策略是：

• 本地按业务需要采样；
• 只有变化超过阈值时更新并上报；
• 设置最大报告间隔，保证长期稳定时仍有周期状态；
• 事件发生时可以复用最近的新鲜样本。

无线发送的能量往往高于一次短 I2C 事务。只优化传感器模式，却让每次采样都触发无线报告，整体收益可能很有限。

MCU 在转换期间是否真的睡着

使用异步定时器只能说明系统具备休眠机会，并不保证每次等待都会进入低功耗状态。还要检查：

• 协议栈是否繁忙；
• 是否有尚未完成的任务或日志输出；
• 最近的软件定时器是否允许进入目标睡眠模式；
• I2C、GPIO 和传感器状态是否满足休眠门控；
• 唤醒后是否继续原状态机，而不是重复初始化采样。

因此验证时不仅要看传感器寄存器，还要同时观察 MCU 的睡眠进入率和整机电流波形。

是否值得电源门控

如果传感器 Standby 仍占据不可接受的电流，可以考虑用 load switch 或受控电源完全断电。但这通常不是第一优先级，因为它会引入：

• 每次采样重新上电和初始化；
• I2C SDA/SCL 通过上拉反向供电的风险；
• GPIO 上电时序和高阻态要求；
• 额外器件、板级面积和故障路径；
• 校准或寄存器配置丢失。

只有当整机预算确实需要节省最后几微安，并完成板级验证后，电源门控才可能值得。

建议的验证矩阵

至少比较三种 profile：

同时测量传感器电源轨和整机输入电流，覆盖：

• 环境长期稳定；
• 事件频繁发生；
• 光照在阈值附近波动；
• 明暗快速切换；
• I2C 失败和数据未就绪重试。

静止十分钟的平均值只能代表一种场景。低功耗设计最终要在功耗、数据新鲜度、事件延迟和可靠恢复之间取得平衡。

结论

环境光采集没有统一的“IRQ 一定更省电”答案。合理的选择顺序是：

1. 先确认传感器是否支持 single-shot 或低功耗阈值引擎；
2. 再明确业务需要周期 lux，还是实时明暗事件；
3. 不支持 single-shot 时，用状态机实现按需 Active 和可靠回 Standby；
4. 优先合并请求、降低采样频率并对齐已有唤醒；
5. 最后通过整机电流波形验证，而不是只依赖手册典型值。

对于只需偶尔获取照度的电池设备，MCU 定时按需采样通常比连续 Active 加阈值 IRQ 更合适；而真正需要快速明暗检测时，连续 IRQ 的功耗代价应作为产品需求的一部分明确接受。

三个平台分别在做什么

它们都要解决三件事：

1. 识别是哪一类设备；
2. 把 Zigbee 消息转换成平台状态；
3. 把平台操作转换成 Zigbee 命令或属性写入。

先判断是否真的需要第三方脚本

如果设备正确实现标准 Device Type、Cluster、Attribute、Command 和 Reporting，平台的通用处理通常已经能够覆盖主要功能。

适配脚本更适合处理：

• Basic Cluster 身份或描述符与实际行为不一致；
• 厂商自定义 Cluster、Attribute 或 Command；
• 标准位图需要拆成多个平台实体；
• 原始数值需要单位、比例或枚举转换；
• 特定固件版本存在兼容差异；
• 标准功能存在，但平台没有自动生成期望的实体或 Capability。

能在固件端修复的标准合规问题，不应长期依赖三个平台分别打补丁。

建立一份协议事实矩阵

每项能力至少记录：

平台代码只消费这份事实，不重新猜测协议含义。

平台映射表

名字相近不表示行为自动相同。例如同一个 IAS Zone 位图，在一个平台可能拆成多个 Binary Sensor，在另一个平台可能形成一组 MQTT 属性，在 SmartThings 中则对应多个 Capability。

推荐开发顺序

1
2
3
4
5
6
7
8
9

抓取真实 interview 与空口行为
  -> 建立协议事实矩阵
  -> 先验证标准能力
  -> 实现最小身份匹配
  -> 实现上行状态
  -> 实现下行控制
  -> 配置 reporting / binding
  -> 验证重启、rejoin 与低功耗
  -> 三平台对照回归

不要一开始就复制相似设备脚本。先比较 Endpoint、Cluster 方向、属性类型和命令载荷，确认差异后再复用。

身份匹配要足够窄

过宽匹配会让行为不同的设备误用同一脚本：

• 只按常见 Model ID 匹配，可能碰到多个厂商共用；
• 只按 Cluster 集合匹配，可能覆盖大量标准设备；
• 忽略固件版本，可能把旧固件 workaround 应用于新固件；
• 忽略 Endpoint，可能把多路设备映射到错误 Component。

优先使用稳定的 Manufacturer + Model；必要时叠加 Endpoint、Cluster 或固件版本条件。更换身份字符串会破坏已经发布的三平台兼容代码，应视为协议接口变更。

上行与下行必须成对验证

一个“可见的开关”不代表完整兼容：

• 设备主动变化能否更新平台；
• 平台写入能否改变设备；
• Read Back 是否与平台状态一致；
• 失败是否返回真实错误；
• 重启后状态能否恢复；
• reporting 丢失后能否重新配置；
• Sleepy End Device 是否在唤醒窗口处理配置。

如果只验证 UI 点击成功，很容易漏掉设备侧主动变化和离线恢复。

三个平台的状态命名

建议先定义平台无关语义：

1
2
3
4

contact: open / closed
tamper: detected / clear
battery: percentage
alarm: active / inactive

然后分别映射为：

• ZHA 的 Entity 和 Device Class；
• Z2M 的 exposes property；
• SmartThings 的 Capability attribute/event。

协议枚举值保持不变，显示文案可以平台化。不要为了让 UI 好看而改变空口数值。

低功耗设备专项

兼容脚本常在设备刚加入时集中执行 bind、read 和 configure reporting。对休眠设备，应检查：

• 配置发生时设备是否仍处于 Fast Poll；
• 平台是否会自动重试；
• rejoin 后 reporting 是否保留；
• 父节点更换后是否需要重新绑定；
• 多条配置是否超出单次唤醒窗口；
• 失败是否被静默忽略。

“第一次加入能用”不足以证明长期兼容。

验证证据分层

1
2
3
4
5
6
7
8

脚本能加载
  != 匹配到目标设备
  != Entity / Exposes / Capability 正确
  != 上行状态正确
  != 下行控制正确
  != 重启和 rejoin 正确
  != 平台正式收录
  != Zigbee 认证或生态认证

每个平台都应保存版本、脚本提交、interview、调试日志、测试动作和预期结果。公开问题单要脱敏设备唯一地址、Network Key、install code 和私有仓库信息。

继续阅读：

• ZHA Device Handlers
• Zigbee2MQTT 新设备支持
• SmartThings Edge 架构

Quirk 的边界

一个 Quirk 通常包含：

• Matcher：识别 Manufacturer、Model 和可选的设备条件；
• Cluster modification：增加、移除或替换 Cluster；
• Entity metadata：把属性或命令映射成 Entity；
• Automation trigger：把遥控器命令映射成设备动作；
• Reporting configuration：声明需要配置的属性上报。

Quirk 不会修复射频、入网安全或设备没有发送报文的问题。先确认目标报文确实到达 Zigpy，再处理映射。

优先使用 V2 QuirkBuilder

当前 zha-device-handlers 推荐新适配使用声明式 QuirkBuilder。一个只补充 IAS Zone Tamper 实体的通用示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

from zigpy.zcl.clusters.security import IasZone

from zhaquirks.builder import BinarySensorDeviceClass, QuirkBuilder

(
    QuirkBuilder("Example Manufacturer", "GENERIC-CONTACT-01")
    .binary_sensor(
        attribute_name=IasZone.AttributeDefs.zone_status.name,
        cluster_id=IasZone.cluster_id,
        device_class=BinarySensorDeviceClass.TAMPER,
        attribute_converter=lambda value: bool(
            value & IasZone.ZoneStatus.Tamper
        ),
        unique_id_suffix="tamper",
        fallback_name="Tamper",
    )
    .add_to_registry()
)

这个示例假设设备已经正确提供 IAS Zone Cluster，只是平台需要把 zone_status 的 Tamper 位拆成独立实体。它没有虚构 Cluster，也没有改变空口数据。

Matcher 为什么经常失败

先从 ZHA Device Signature 或调试日志确认：

• Basic Cluster 的 Manufacturer；
• Model；
• Endpoint 列表；
• 每个 Endpoint 的 Profile、Device Type；
• Server / Client Cluster。

字符串必须与设备实际返回完全一致。营销名称、包装型号和 Basic Cluster Model 可能不同。

如果多个固件共享 Manufacturer/Model 但行为不同，可使用固件版本过滤或更具体条件，避免一个 workaround 覆盖所有版本。

什么时候替换 Cluster

只有出现以下情况才需要自定义 Cluster：

• 厂商 Cluster 未在 Zigpy 中定义；
• 属性类型、Manufacturer Code 或访问方式需要补充；
• 报告值需要稳定、可证明的转换；
• 标准 Cluster 的设备实现存在已确认偏差。

自定义属性应明确：

• Attribute ID；
• Zigbee 数据类型；
• 读写权限；
• Manufacturer Code；
• 单位与缩放；
• 无效值；
• reporting 行为。

不要根据一条抓包就猜测类型。至少验证边界值、重启和多个样机。

Server 与 Client 方向

ZHA 中：

• in_clusters 对应设备提供的 Server Cluster；
• out_clusters 对应设备使用的 Client Cluster。

命令定义的方向也要与 Zigpy 当前 API 一致。升级 Zigpy 时，如果命令定义模型发生变化，应保持 Command ID、载荷类型和空口序列化不变。

Entity 映射注意点

建立 Entity 时核对：

• endpoint_id；
• cluster_id；
• attribute_name 或 command_name；
• Device Class；
• Entity Type：Standard、Config 或 Diagnostic；
• 单位、倍率和显示精度；
• unique_id_suffix 是否稳定且无冲突；
• 是否默认禁用。

同一个位图拆成多个实体时，每个实体都要使用稳定且不同的 suffix。已有用户依赖 Entity ID 后，不应随意更换。

本地加载

Home Assistant 可通过 ZHA 配置加载自定义 quirks：

1
2

zha:
  custom_quirks_path: /config/custom_zha_quirks

把 Python 文件放入该目录后重启 Home Assistant。随后在设备信息与日志中确认实际加载的 Quirk 类。

如果 Quirk 已匹配但新实体仍未出现，可先执行重新配置；只有在确认平台没有重建设备实体时，再评估删除并重新配对。重新配对不是验证 Matcher 的替代方法。

最小验证

开发仓库中的常见检查：

1
2
3

python -m py_compile path/to/quirk.py
ruff check path/to/quirk.py
pytest path/to/relevant_tests.py

还需要设备侧验证：

1. Quirk 被目标设备匹配；
2. 相似设备不被误匹配；
3. 属性报告更新正确实体；
4. 写入或命令使用正确 Endpoint 和方向；
5. 重启 Home Assistant 后仍可加载；
6. 设备 rejoin 后 reporting 正常；
7. 未知值不会导致异常或错误状态。

常见问题

正式贡献前应遵守仓库当前的格式、类型检查、测试和贡献说明。官方入口：

• zha-device-handlers
• Home Assistant ZHA 集成

开始前先做三件事

1. 检查设备是否已在 Zigbee2MQTT 开发分支获得支持；
2. 把日志级别设为 Debug；
3. 完成设备 interview，并保存 Endpoint、Cluster 与 Basic 信息。

能加入网络只代表 Zigbee2MQTT 可以访问设备，不代表已有 converter 能理解它。

先生成外部定义

当前 Zigbee2MQTT 前端可以在设备的 Dev console 中生成 external definition。生成结果基于发现到的标准 Cluster，应先验证 Exposes 页面中的能力是否真实可用。

自动生成的定义是起点，不是最终结论：

• 设备可能没有上报全部能力；
• 厂商 Cluster 无法自动理解；
• reporting 可能尚未配置；
• 命令型遥控器可能没有普通状态属性；
• 相同 Model ID 可能对应多个厂商变体。

Modern Extend 示例

标准温湿度与电池设备可以从最小定义开始：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

import {
    battery,
    humidity,
    temperature,
} from "zigbee-herdsman-converters/lib/modernExtend";

export default {
    zigbeeModel: ["GENERIC-ENV-01"],
    model: "GENERIC-ENV-01",
    vendor: "Example Vendor",
    description: "Temperature and humidity sensor",
    extend: [
        temperature(),
        humidity(),
        battery(),
    ],
};

Modern extends 会组合常见的 fromZigbee、toZigbee、exposes 和配置逻辑。能复用时优先复用，减少重复的解析和 reporting 代码。

External Converter 放在哪里

文件通常放在与 Zigbee2MQTT configuration.yaml 同级的 external_converters 目录，例如：

1
2
3
4

data/
├── configuration.yaml
└── external_converters/
    └── generic-env.mjs

也可以从前端的 Settings → Dev console → External converters 加载和更新。

当前版本对外部 JavaScript 有额外安全控制。它会在 Zigbee2MQTT 进程中执行任意代码，只应在隔离的开发环境中启用，并只加载经过审查的来源。

什么时候使用 fromZigbee

fromZigbee 负责把设备发来的消息转换成平台状态或 action：

1
2
3
4
5

Attribute Report / Read Response / Cluster Command
  -> 匹配 cluster 与 message type
  -> 解析原始字段
  -> 校验范围和特殊值
  -> 返回 MQTT property

如果日志持续出现 No converter available，先确认：

• Cluster 名称；
• Message type；
• Endpoint；
• Attribute 或 Command ID；
• 是否已存在可复用 converter；
• 是否已经被某个 modern extend 覆盖。

不要用一个接受所有消息的 converter 隐藏未知数据。

什么时候使用 toZigbee

toZigbee 把 MQTT Set/Get 转换成 Attribute Read/Write 或 Cluster Command。必须定义：

• 支持的 property；
• 输入类型和范围；
• 枚举字符串与协议数值；
• 目标 Endpoint；
• Manufacturer Code；
• 写入后的状态确认策略；
• 错误返回。

下发函数返回成功不等于设备状态已经改变。应结合响应、Read Back 或后续 Report。

Exposes 是公开契约

exposes 决定前端和 MQTT 使用者看到什么。每个 property 应明确：

• 名称与显示 Label；
• 读、写、状态访问；
• 数据类型；
• 单位；
• 最小值、最大值和步进；
• 枚举；
• Endpoint 后缀；
• 描述。

一旦用户用 property 编写自动化，随意改名会造成兼容破坏。显示文案可以优化，但 MQTT property 应保持稳定。

Configure 与 reporting

设备没有主动上报时，可能需要在 configure 中：

• bind 到 Coordinator Endpoint；
• Configure Reporting；
• 读取倍率、除数或初始状态；
• 设置厂商初始化属性。

对 Sleepy End Device，配置必须落在唤醒窗口，并验证失败重试。不要假设一次 configure 成功就会永久保留；还要测试断电、rejoin 和恢复出厂。

匹配多个设备变体

zigbeeModel 简单但可能过宽。多个厂商共用同一 Model ID 时，应使用更精确的 fingerprint 条件，并把真正相同的行为复用到公共 extend。

兼容层次建议：

1
2
3
4

标准 modern extend
  -> 品类公共 converter
  -> 厂商公共逻辑
  -> 设备或固件差异

不要把所有变体堆进一个充满 Model 判断的转换函数。

验证清单

1. Converter 成功加载；
2. 只匹配预期设备；
3. Exposes 完整且访问方向正确；
4. 所有上行属性和命令均可解析；
5. Set/Get 有真实设备结果；
6. reporting、单位和缩放正确；
7. 多 Endpoint property 不冲突；
8. Zigbee2MQTT 重启后仍可加载；
9. 设备断电和 rejoin 后恢复；
10. Debug 日志没有未解释的消息和异常。

External Converter 验证完成后，可按 zigbee-herdsman-converters 当前结构转成正式 TypeScript definition 并提交上游。发布版本已经包含支持后，应移除本地 converter，避免重复匹配。

官方资料：

• 支持新设备
• External Converters
• Exposes
• 外部脚本安全说明

Driver 目录结构

一个 Zigbee Edge Driver 通常包含：

1
2
3
4
5
6
7
8
9
10
11

zigbee-example/
├── config.yml
├── fingerprints.yml
├── profiles/
│   └── sensor.yml
└── src/
    ├── init.lua
    └── sub_drivers/
        └── device_variant/
            ├── can_handle.lua
            └── init.lua

• config.yml：包信息、权限和 Edge API 版本；
• fingerprints.yml：设备匹配与 Profile 选择；
• profiles/：Component 和 Capability；
• src/：Zigbee Handler、Capability Handler 与生命周期逻辑；
• sub_drivers/：只覆盖特定设备差异。

Fingerprint

Manufacturer-specific fingerprint 适合已知设备：

1
2
3
4
5
6

zigbeeManufacturer:
  - id: "example/generic-contact-v1"
    manufacturer: "Example Manufacturer"
    model: "GENERIC-CONTACT-01"
    deviceProfileName: "contact-battery"
    deviceLabel: "Generic contact sensor"

字段必须来自设备实际报告，而不是包装名称。

SmartThings 也支持按 Profile、Device ID 和 Server/Client Cluster 匹配的 generic fingerprint。它适合真正遵循标准且行为一致的设备；设备存在特殊处理时，精确 Manufacturer/Model 匹配更安全。

Profile 是平台契约

Profile 决定 App 和自动化看到的 Capability：

1
2
3
4
5
6
7
8
9
10
11
12

name: contact-battery
components:
  - id: main
    capabilities:
      - id: contactSensor
        version: 1
      - id: battery
        version: 1
      - id: tamperAlert
        version: 1
    categories:
      - name: ContactSensor

只有 Driver 能稳定产生和处理的 Capability 才应加入 Profile。删除或重命名已部署 Profile 会影响现有设备，应作为兼容性变更评估。

先使用默认 Zigbee Handler

SmartThings Zigbee library 已提供常见 ZCL 到 Capability 的默认映射：

1
2
3
4
5
6
7
8
9
10

local capabilities = require "st.capabilities"
local defaults = require "st.zigbee.defaults"

defaults.register_for_default_handlers(
  driver_template,
  {
    capabilities.contactSensor,
    capabilities.battery,
  }
)

标准功能优先使用默认处理。自定义 zigbee_handlers 会覆盖相同 Cluster/Attribute 的默认 Handler，因此只覆盖设备真正偏离标准的部分。

自定义 Zigbee Handler

Handler 按消息类型组织：

• attr：Attribute Report 或 Read Response；
• cluster：Cluster-specific Command；
• global：ZCL Global Command；
• zdo：ZDO 消息。

一个属性处理的结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

local clusters = require "st.zigbee.zcl.clusters"
local OnOff = clusters.OnOff

local function on_off_handler(driver, device, value, zb_rx)
  -- 校验 value，再产生对应 Capability event
end

driver_template.zigbee_handlers = {
  attr = {
    [OnOff.ID] = {
      [OnOff.attributes.OnOff.ID] = on_off_handler,
    },
  },
}

真实实现还应处理数据类型、Endpoint、多 Component 映射和未知值。

Capability Handler

App 发出的 Capability command 需要转换成 Zigbee Command 或 Attribute Write：

1
2
3
4
5
6

Capability command
  -> 校验参数
  -> 选择 Component / Endpoint
  -> 构造 ZCL message
  -> device:send(...)
  -> 等待设备响应或后续 report

不要在发送后无条件伪造成功状态，除非平台交互明确要求 optimistic update，并且随后有校正机制。

Reporting 与 doConfigure

ZigbeeDevice 可以登记 configured 或 monitored attributes。设备配置时，库可执行 bind 和 Configure Reporting；特殊设备也可以在 doConfigure 中发送自定义配置。

核对：

• Cluster、Attribute 和数据类型；
• Minimum / Maximum Interval；
• Reportable Change；
• Hub Endpoint；
• Sleepy End Device 的唤醒窗口；
• 配置失败后的重试；
• rejoin 后是否需要重新配置。

过度频繁的 reporting 会增加网络负载和电池消耗。

Sub-driver 隔离设备差异

同一品类 Driver 可以支持多种设备。标准行为放在主 Driver，只有特定设备的差异放入 sub-driver，并通过 can_handle 精确匹配。

1
2
3
4

主 Driver：通用 Capability 与默认 Handler
  -> sub-driver A：特殊属性转换
  -> sub-driver B：不同 Endpoint 映射
  -> sub-driver C：旧固件 workaround

避免在每个 Handler 中堆叠大量 Manufacturer/Model 判断。

生命周期

常见生命周期包括：

• added：设备首次创建；
• init：Driver 启动或设备初始化；
• doConfigure：配置 binding 和 reporting；
• infoChanged：Preferences 变化；
• removed：设备移除。

不要把所有网络操作都放在 init，否则每次 Driver 重启可能重复配置大量设备。

本地打包与设备验证

SmartThings CLI 可以只构建 zip、不上传：

1
2
3

smartthings edge:drivers:package \
  --build-only driver.zip \
  path/to/driver

这个步骤验证包结构，但不证明 Hub 运行正确。上传、Channel 分配和 Hub 安装会改变云端或设备状态，应在明确的测试环境中单独执行。

Hub 验证时使用 live log：

1

smartthings edge:drivers:logcat --hub-address=<HUB_IP>

Hub 地址、Channel ID、Driver ID 和认证 Token 不应提交到公开仓库。

测试矩阵

至少覆盖：

1. fingerprint 选中正确 Profile；
2. 相似设备不会误匹配；
3. Attribute Report 产生正确 Capability event；
4. Cluster Command 产生正确 action；
5. Capability command 发送正确 ZCL 消息；
6. reporting 配置与低功耗行为；
7. 多 Endpoint 到 Component 的映射；
8. Driver 重启、设备 rejoin 和恢复出厂；
9. Preferences 更新；
10. 未知值和发送失败。

涉及公开 SmartThingsEdgeDrivers 仓库与认证的变更，还应提供官方要求的集成测试。Package build、Hub 实测、公开仓库合入和 Works with SmartThings 认证是四个不同结果。

官方资料：

• Driver 结构与 Fingerprint
• Zigbee Driver Structures
• Zigbee 默认 Handler
• Edge Driver 测试

协议栈分层

1
2
3
4
5
6
7
8
9
10
11

应用逻辑
  │
ZCL：Cluster、Attribute、Command
  │
ZDO / ZDP：设备与服务发现、网络管理
  │
APS：应用数据传输、绑定、组寻址、应用层安全
  │
NWK：组网、路由、网络地址、网络层安全
  │
IEEE 802.15.4 MAC / PHY：信道、帧、确认、射频

• IEEE 802.15.4 提供低速率无线链路；
• NWK 负责 Zigbee Mesh 网络；
• APS 把上层应用消息送到指定设备和 Endpoint；
• ZDO/ZDP 提供节点、Endpoint 和服务发现；
• ZCL 定义设备功能的通用数据模型。

因此，收到 MAC ACK 只说明链路层收到了帧，不代表 NWK 解密、APS 接受或 ZCL 命令处理成功。

三种逻辑设备角色

Coordinator 是网络形成时的角色；网络形成后，Mesh 路由并不要求所有报文都经过它。Router 或 Coordinator 都可以成为 End Device 的父节点。

地址、Endpoint 与设备功能

一个 Zigbee 节点通常同时涉及：

• EUI-64：设备的全局扩展地址；
• 16 位 NWK 地址：加入网络后使用的短地址，可能变化；
• PAN ID / Extended PAN ID：识别网络；
• Endpoint：节点内部的应用端点；
• Profile ID 与 Device ID：声明应用配置和设备类型；
• Cluster：Endpoint 提供或使用的标准功能。

排障时不要把短地址当作永久身份。跨重启、离网重入或地址冲突处理后，应使用 EUI-64、时间线和设备公告重新确认节点。

Cluster、Attribute 与 Command

ZCL 把设备能力拆成 Cluster：

• Server 保存状态、提供属性或接收命令；
• Client 发起命令或消费 Server 产生的信息；
• Attribute 表示状态或配置；
• Command 表示一次操作或协议动作；
• Reporting 让属性按配置主动上报。

同一个 Cluster ID 的 Server 和 Client 是两个方向，不能因为 Endpoint 列出了 Cluster 就认为双向能力都存在。

单播、广播、组播与绑定

• 单播：发送给一个目标节点；
• 广播：发送给一类或全部节点，成本较高；
• 组播：发送给 Group ID 对应的一组 Endpoint；
• Binding：在源 Endpoint 中保存逻辑目标，使应用不必每次指定完整目的地址。

广播不是“更可靠的单播”。它会增加全网负载，且不同广播范围、重试和确认语义并不相同。

一条应用消息经过什么

以属性上报为例：

1
2
3
4
5
6

传感器状态变化
  -> ZCL 生成 Report Attributes
  -> APS 选择目的 Endpoint、绑定或地址
  -> NWK 选择下一跳并进行网络层保护
  -> MAC 在当前信道发送
  -> 目标逐层解密、分发并处理

每一层都有独立失败点。可靠分析应记录：

1. 应用是否生成消息；
2. APS 是否接受发送请求；
3. NWK 是否找到路由；
4. MAC 是否发出并收到确认；
5. 对端是否通过安全校验；
6. 对端 Endpoint 与 Cluster 是否接受；
7. 应用状态是否真正改变。

规范边界

Zigbee 仍在演进。学习基础概念可以使用公开资料，但实现和认证必须冻结对应的 Zigbee Core、BDB、ZCL、Device Type Library、Errata、PICS 和测试规范，不能把不同 Revision 的要求拼在一起。

可从 Zigbee 官方概览、Zigbee FAQ 和 CSA 规范下载入口继续阅读。

先区分三条路径

• 首次加入：Factory New 设备通过 Network Steering 寻找允许加入的网络；
• Rejoin：设备保留网络信息后重新连接，流程和安全条件不同；
• Touchlink：近距离发现和引导入网的另一套 commissioning 方法。

本文讨论经典的首次 Network Steering。实际实现应以目标 BDB、Zigbee Core 和安全策略版本为准。

阶段一：打开网络与扫描

网络侧进入 Permit Join 状态。待入网设备在配置的主信道集扫描 Beacon，必要时再扫描次信道集，并根据网络容量、信号和安全信息选择候选网络。

这一阶段的成功锚点是：

• 找到目标 PAN；
• 目标网络允许加入；
• 设备选择了预期信道与 Extended PAN ID。

只看到 Beacon 不能证明设备已经发起关联。

阶段二：关联并获得网络地址

设备向父节点候选发起关联，父节点返回状态和 16 位网络地址。此后设备具备拓扑位置，但还不代表已经拿到可用的安全材料。

1
2
3
4
5

Scan
  -> Select network
  -> Association Request
  -> Association Response
  -> Short address assigned

MAC 层关联成功只证明链路和父子关系初步建立。

阶段三：安全准入与 Network Key

集中式安全网络中，Trust Center 决定设备是否被接纳，并通过受保护的密钥传输把 Network Key 交给新设备。设备必须：

1. 接收到正确的 Transport Key；
2. 使用匹配的预配置或 install-code 派生 Link Key 验证并解密；
3. 安装正确的 Network Key 及其序列号；
4. 启动受保护的 NWK 通信。

所以“Transport Key 已发出”不等于“设备已安装 Network Key”。决定性证据在接收端的 APS 安全处理和密钥安装结果。

阶段四：设备公告与 Trust Center Link Key

设备通常会发送 Device Announcement，让网络获知其地址映射。根据 BDB 版本和 Trust Center 策略，后续还可能执行 Trust Center Link Key 的更新或交换。

1
2
3
4
5

Network Key installed
  -> secure network communication
  -> Device Announcement
  -> Trust Center Link Key procedure
  -> commissioning complete

如果日志显示网络层通信已经成功，但 BDB 最终报告 Trust Center Link Key 交换失败，就不应把问题归回“没有收到 Network Key”。

阶段五：应用发现

网络接入完成后，控制端通常还会：

• 查询 Node Descriptor；
• 查询 Active Endpoints；
• 读取 Simple Descriptor；
• 读取 Basic 属性；
• 配置 Reporting；
• 建立 Binding 或执行专用 Cluster 初始化。

设备在网络里可达，不等于已经被生态完整识别。应用发现失败应与基础入网失败分开记录。

推荐排障时间线

抓包与日志怎么对齐

记录统一时间基准，并同时保留：

• 设备串口日志；
• Coordinator / Trust Center 日志；
• 802.15.4 抓包；
• 测试工具或网关事件；
• 固件版本和本次安全策略。

密钥、install code、地址和抓包解密材料只应在授权的本地环境使用，不应复制到公开问题单或文章。

规范入口可参考 CSA Zigbee 规范下载页；认证自测还应使用目标版本的 BDB PICS 和正式测试规范。

一张作用域表

表格描述的是概念边界。具体必选能力和密钥派生方法必须回到目标 Zigbee Core、BDB、ZCL、Green Power 与安全策略版本确认。

Network Key

Network Key 是网络范围的共享密钥，主要用于 NWK 层的机密性、完整性和重放保护。它让节点能够参与正常 Zigbee 网络通信。

要点：

• 同一时刻会有活动 Key Sequence；
• 网络可以执行 Network Key Update 和 Switch；
• 拿到 Network Key 不等于拥有与 Trust Center 的唯一信任关系；
• Network Key 泄露的影响通常覆盖整个网络。

抓包能用 Network Key 解密 NWK 帧，也不代表内部 APS 负载一定能继续解密。

Trust Center Link Key

Trust Center Link Key 是设备与 Trust Center 之间的 APS Link Key，用于安全管理和特定 APS 加密流程。

它可能经历：

1
2
3
4

初始 bootstrap key
  -> 安全加入
  -> Trust Center Link Key 更新或交换
  -> 唯一设备级 TCLK

具体路径由 BDB 版本、设备能力和 Trust Center 策略决定。调试时要分开记录“初始 Key 可用”和“最终 TCLK 交换完成”。

Install code 的位置

Install code 本身不是日常 NWK 通信使用的 Network Key。它经过规范定义的处理后，形成设备唯一的初始 Link Key，用于安全加入。

它改善了共享 bootstrap key 的风险，但同时要求：

• 生产、标签或扫码数据正确绑定到设备；
• Trust Center 预先获得匹配信息；
• 长度、校验和、字节序与派生过程一致；
• 测试数据不能进入量产。

任何 install code、派生 Key 或二维码内容都不应出现在公开日志中。

Application Link Key

Application Link Key 用于两个应用节点之间的端到端 APS 安全。它不能替代 Network Key，因为 Zigbee 路由仍依赖受保护的 NWK 层；它也不应被笼统称为 TCLK，因为通信对端可能不是 Trust Center。

分析加密帧时可按顺序判断：

1
2
3
4

MAC frame
  -> NWK security：Network Key
  -> APS security：对应 Link Key
  -> ZCL payload

全局 bootstrap key 为什么要谨慎

某些兼容路径使用规范定义的全局共享初始 Link Key。因为它不是每台设备唯一的秘密，安全强度依赖后续策略，例如尽快升级到唯一 TCLK、限制 Permit Join 时间和执行设备鉴权。

公开文章无需、也不应抄写这个 Key 的实际值。知道“它是共享 bootstrap 材料”已经足够用于设计和排障。

Touchlink 与 Green Power 不要混入普通路径

Touchlink commissioning Key 服务于 Touchlink 的网络参数交换；Green Power 还有自己的共享、组或单设备安全材料。它们不应被当成普通 Zigbee 设备的 Network Key 或 TCLK。

排障时至少记录什么

不要记录 Key 内容，而是记录元数据：

• 安全层：NWK 还是 APS；
• Key 类型和逻辑槽位；
• Key Sequence；
• 对端角色；
• frame counter 是否前进；
• 解密、MIC 验证和重放检查结果；
• Key 安装、更新、切换或删除事件。

“发送成功”只能证明本端协议栈接收了请求或下层完成传输；只有对端安全层验证通过，才能证明使用了匹配的 Key。

可从 Zigbee 官方规范入口获取当前公开规范。认证或量产策略必须再与芯片平台安全指南及实验室冻结版本核对。

核心对比

这只是概念表。允许的设备类型、加入方式、密钥交换和兼容条件随 Zigbee/BDB 版本变化，认证时必须看冻结规范。

集中式网络

集中式网络通常由 Coordinator 建网并承担 Trust Center 角色。Trust Center 负责：

• 决定是否允许新设备加入；
• 管理初始信任与设备鉴权；
• 传输或更新 Network Key；
• 管理设备级 Trust Center Link Key；
• 移除不再可信的设备。

路由仍由 Mesh 完成。设备 A 到设备 B 的正常业务帧不必每次穿过 Trust Center。

分布式网络

分布式网络没有一个持续承担中央信任决策的 Trust Center。形成网络、扩展网络和安全管理依赖分布式规则及共享的安全基础。

它减少了对中央角色的依赖，但不代表：

• 没有 Network Key；
• 没有加密和重放保护；
• 任意设备都可无条件加入；
• 与集中式设备天然完全兼容。

分布式是另一套受规范约束的安全模型，不是“关闭安全”。

Coordinator、Trust Center 与 Router 的关系

三个概念容易混淆：

• Coordinator：形成 PAN 的逻辑设备；
• Trust Center：集中式安全网络中的信任管理角色；
• Router：参与 Mesh 路由并可能允许子节点关联。

集中式网络中 Coordinator 通常兼任 Trust Center，但这不等于它是所有应用报文的中心转发器。

选择时看什么

1. 目标生态是否要求中央 Trust Center；
2. 是否需要 install code 和设备唯一 TCLK；
3. 目标设备及历史 Profile 是否支持该网络类型；
4. 是否需要 Touchlink；
5. 网络形成、备份、迁移与恢复策略；
6. 对失窃节点、共享 bootstrap 材料和密钥轮换的风险接受度；
7. 对应认证计划和 PICS 允许什么。

不要只因为“想避免单点故障”就选择分布式网络。集中式安全角色与 Mesh 数据路径是不同问题；Zigbee Router 的多路径转发仍可提供网络韧性。

抓包如何识别

单靠一帧普通 NWK 数据通常不足以判断网络模型。应结合：

• 网络形成日志；
• Trust Center 地址与策略；
• Beacon 或网络安全相关信息；
• 加入时的密钥传输路径；
• TCLK 交换行为；
• BDB 配置与 PICS。

版本与兼容边界

旧的 Zigbee Light Link、Home Automation 与 Zigbee 3.x/4.x 之间存在特定兼容规则，不能用“都是 Zigbee”代替逐项核对。CSA 的 互操作白皮书可帮助理解历史关系；当前实现仍应以 CSA 规范下载入口和认证实验室确认的版本为准。

两个角色

• Initiator：发起 Touchlink 的控制设备；
• Target：被发现、识别、复位或加入网络的设备。

两者通过 Touchlink Commissioning Cluster 交互。是否支持某条命令、某种设备角色和网络类型，应由目标版本的 PICS 决定。

高层流程

1
2
3
4
5
6
7
8
9

Initiator 扫描信道
  -> Scan Request
  <- Scan Response
  -> 根据距离、能力和状态选择 Target
  -> 可选 Identify / Device Information
  -> Network Start 或 Network Join
  -> 受保护地传输网络参数
  -> Target 切换信道并启动网络
  -> 后续应用发现与配置

Touchlink 还可能提供 Reset to Factory New 等管理动作，因此触发条件和物理在场约束非常重要。

扫描与“近距离”判断

Initiator 会在规定信道上发送扫描请求，Target 返回能力、网络状态等信息。实现通常根据接收信号强度或协议定义的 proximity 条件筛选目标。

RSSI 只是一项输入：

• 不同硬件的接收链路和校准不同；
• 环境反射会造成波动；
• 强信号不等于身份可信；
• 过宽阈值可能误选附近其他设备。

因此还应结合用户动作、设备状态、响应事务标识和超时窗口。

Identify 不是入网

Identify 让用户确认正在操作哪台设备，例如闪灯或执行可见动作。它不表示网络参数已经写入，也不表示 Target 已完成加入。

推荐成功锚点：

1. Scan Response 匹配当前事务；
2. 选择了唯一目标；
3. Identify 行为可被用户确认；
4. Network Start/Join 响应成功；
5. Target 在目标信道启动；
6. 后续受保护 Zigbee 通信成功。

网络参数传输

Touchlink 使用专门的 commissioning 安全过程保护 Network Key 等网络参数。其 commissioning Key 只服务于这一阶段，不应与日常 NWK 使用的 Network Key 混淆。

公开日志中不应输出：

• commissioning Key；
• Network Key；
• 未脱敏的设备唯一地址；
• 可用于复现实网加入的数据。

与经典加入的区别

Touchlink 成功后仍需要正常 Zigbee 网络和应用层交互；它不是独立的日常通信协议。

常见失败分类

• 扫描不到：信道集、时序、角色能力或距离门限；
• 响应被丢弃：事务标识、重复帧或状态不匹配；
• Identify 成功但 Join 失败：网络状态、目标角色或安全参数；
• 参数写入后未启动：信道切换、持久化或状态机；
• 入网后不可用：Endpoint 发现、Cluster、binding 或 reporting；
• Reset 行为异常：Factory New 判定和持久化清理不完整。

规范边界

旧 ZCL 中可以找到 Touchlink Commissioning Cluster，但认证实现不能只照抄旧章节。应同时冻结目标 Zigbee Core、BDB、ZCL、PICS、Errata 和测试用例，并确认当前认证计划是否接受所选 Touchlink 能力。

公开入口包括 CSA Zigbee 规范下载页与 Zigbee 认证工具页。

第一步不是运行工具

先向 CSA 或授权实验室确认并冻结：

• 认证计划和 Zigbee 版本；
• Zigbee Core / PRO、BDB、ZCL、Device Type Library；
• Approved Errata；
• PICS / PIXIT 模板；
• Test Specification 与测试用例版本；
• ZUTH、脚本、dongle 和固件版本。

“Zigbee 3.0”是一个过于宽泛的标签。公开工具可能同时保留多个 BDB、ZCL 和 PRO 输入；不能自行把最新版文档和旧测试脚本拼在一起。

建立声明矩阵

从每个 Endpoint 展开：

1
2
3
4
5
6
7
8

Profile ID / Device ID
  -> Server / Client Cluster
  -> Mandatory / Optional / Conditional
  -> Attribute 类型、范围、默认值和权限
  -> Reporting
  -> Commands Received / Generated
  -> PICS / PIXIT
  -> 对应测试用例

一旦实现了 Optional 能力，它通常也会进入声明和测试范围。为了减少测试，不应把已经对外可见的能力错误标成不支持。

四层自测

静态核对

• Simple Descriptor 与实际 Cluster 注册一致；
• ClusterRevision 和 ZCLVersion 对应冻结版本；
• 属性类型、默认值、访问权限和范围正确；
• 接收与发送命令方向正确；
• PICS 与固件能力一致；
• 认证配置确实进入最终镜像。

功能与状态机

• 标准读写、命令和 reporting；
• 默认响应与异常状态；
• 初始化、重启、掉电与恢复出厂；
• 入网、退网、rejoin、换父与丢网恢复；
• binding、group、scene 等已声明能力；
• OTA、低电量和持久化边界。

安全与 BDB

• Network Steering 和 Permit Join；
• install-code 策略；
• Network Key 安装、更新和切换；
• Trust Center Link Key 流程；
• frame counter 与重放拒绝；
• 集中式或分布式网络声明；
• Touchlink 等可选 commissioning 能力。

正式工具预跑

CSA 的 ZUTH 是 Zigbee 正式认证测试工具，也向成员提供预认证测试能力。导入已审查的 PICS，运行所有被选择用例，并保留原始结果。

Sleepy End Device 专项

低功耗设备常在正式测试中暴露时序问题：

• Poll Control 行为；
• Fast Poll 窗口；
• 父节点缓存与间接传输；
• reporting 延迟；
• enrollment 或 commissioning 期间的接收窗口；
• 测试刺激与设备睡眠状态的同步。

不要通过永久关闭休眠来“通过认证”，除非认证固件与量产行为差异得到明确允许并被记录。

失败归类

修复后要回归相关用例集合，不能只重跑最初失败的一步。

自测证据包

每轮保存：

• 固件版本、源码提交和构建哈希；
• PICS / PIXIT；
• 环境和工具版本；
• 测试用例列表；
• 原始 ZUTH 报告；
• DUT、测试端与抓包日志；
• 失败分析、修复提交和回归结果；
• 尚未验证的限制。

证据层级必须分开：

1
2
3
4
5
6
7

规范要求
  != PICS 声明
  != 静态实现
  != 设备运行通过
  != ZUTH 自测通过
  != 授权实验室通过
  != CSA 正式认证

可从 CSA 认证工具页获取 PICS Tool 和 ZUTH 说明。当前版本和送测范围仍应由 授权测试机构确认。

先确认认证对象

常见对象包括：

• Compliant Platform：无线芯片、处理器和 Zigbee 协议栈形成的平台基础；
• Certified Product：面向最终用途的完整产品；
• 认证转移、产品系列或相似产品路径：是否适用由当前政策决定。

大多数终端产品以合规平台为基础，但平台证书不会自动覆盖产品的 Endpoint、Device Type、Cluster 和应用行为。

全流程

1
2
3
4
5
6
7
8
9
10
11
12

确定产品与市场范围
  -> 确认 CSA 会员与认证路径
  -> 选择合规平台
  -> 冻结规范和测试输入
  -> 完成实现与 PICS / PIXIT
  -> 内部自测
  -> 选择授权测试机构
  -> 正式测试与问题关闭
  -> 提交认证申请与报告
  -> CSA 审核
  -> 证书、公开记录与标志授权
  -> 版本变更与再认证判断

开发阶段要准备什么

至少固定以下内容：

• 硬件、软件和固件版本；
• 合规平台及其证书范围；
• Endpoint、Profile ID、Device ID；
• Server / Client Cluster；
• Mandatory、Optional 和 Conditional 能力；
• commissioning、安全与网络类型；
• 量产配置和认证配置差异；
• 目标生态的附加要求。

生态认证和 Zigbee 认证是两套范围。通过 CSA Zigbee 认证，不自动代表通过某个商业生态的兼容性认证。

PICS 与 PIXIT

• PICS 声明实现支持哪些协议能力；
• PIXIT 提供测试所需的实现参数；
• 它们驱动用例选择，也是实验室解释行为的依据。

填写原则是“与被测固件真实能力一致”。少报会导致声明不实，多报会扩大测试范围并暴露未完成能力。

授权测试机构做什么

授权测试机构根据冻结的测试计划和 PICS：

• 审核样机与文档；
• 配置正式测试环境；
• 执行必选及已实现可选能力的用例；
• 记录偏差和失败；
• 在问题关闭后出具正式测试报告。

测试机构不替代产品团队做 Device Type 设计，也不能用口头经验覆盖规范和 PICS。

CSA 审核做什么

正式测试通过后，还需要通过 CSA 的认证工具提交申请材料。审核关注产品身份、声明、测试报告、合规平台和政策要求。批准后，产品才会获得对应证书、公开记录及标志使用资格。

“实验室测试通过”和“CSA 已正式认证”必须分开表述。

失败与重测

出现失败时，建议维护：

1. 用例、前置条件和失败步骤；
2. 规范条款与 PICS 项；
3. DUT、测试端、抓包时间线；
4. 根因属于实现、环境还是用例解释；
5. 修复影响范围；
6. 实验室确认的重测集合；
7. 新固件标识和回归结果。

不要在未与实验室确认前自行判断“只改一行，无需重测”。

认证后的版本管理

认证绑定具体产品和版本信息。后续变更应评估：

• 协议栈或合规平台升级；
• Device Type、Cluster、属性和命令变化；
• 安全策略或 commissioning 变化；
• 硬件和射频变化；
• 修复是否触及已测试行为；
• 是否适用转移、系列、相似或再认证路径。

当前版本提醒

截至本文更新时，Zigbee 规范、PICS 和认证工具仍在演进。项目名称里写“Zigbee 3.0”不代表可以自行选择任意历史输入；新申请是否继续采用某个 3.0 组合，应在立项时由 CSA 或授权实验室书面确认。

官方入口：

• CSA Certification
• 认证工具与 ZUTH
• 授权测试机构
• Zigbee 规范下载

Matter 在协议栈中的位置

1
2
3
4
5
6

设备应用
  -> Data Model：Node / Endpoint / Device Type / Cluster
  -> Interaction Model：Read / Write / Invoke / Subscribe
  -> 安全会话：PASE / CASE / Group
  -> IPv6 + UDP
  -> Thread、Wi-Fi 或 Ethernet

Bluetooth LE 通常作为设备初次 commissioning 的近距离通道，不是 Matter 日常业务通信的 IP 承载。

Node 与 Endpoint

• Node：一个可寻址的 Matter 逻辑节点；
• Endpoint 0：根端点，承载基础设施和管理 Cluster；
• 其他 Endpoint：承载产品功能；
• Device Type：声明 Endpoint 符合哪类标准设备语义；
• Cluster：一组相关属性、命令和事件。

同一物理设备可以有多个 Endpoint，也可以在一个 Fabric 中对应一个 Node。

Cluster、Attribute、Command 与 Event

Interaction Model 统一了：

• Read：读取属性或事件；
• Write：修改允许写入的属性；
• Invoke：调用命令；
• Subscribe：建立持续订阅并接收报告。

实现了 Cluster 不等于实现了全部可选 Feature。Device Type、Cluster 规范、FeatureMap、全局属性与实际处理逻辑必须一致。

Fabric 是什么

Fabric 是一组共享信任域和管理关系的 Matter 节点。一个设备可以加入多个 Fabric，每个 Fabric 拥有独立的：

• Fabric Index；
• Node ID；
• Operational Certificate；
• Group Key 与访问控制状态；
• 订阅和管理关系。

删除一个订阅不等于删除 Fabric；某个 Fabric 断开，也不代表其他 Fabric 必然受影响。

Commissioning 的阶段

一个简化流程：

1
2
3
4
5
6
7
8

发现 commissionable device
  -> PASE 建立初始安全通道
  -> Device Attestation
  -> 配置法规与网络参数
  -> 设备进入目标 IP 网络
  -> CSR / AddNOC 建立 Fabric 身份
  -> CASE 可用
  -> Commissioning Complete

每一步都有独立成功条件：

• BLE 连接成功不等于 PASE 成功；
• Thread Attach 成功不等于 AddNOC 成功；
• AddNOC 成功不等于 Commissioning Complete；
• Commissioning 完成不等于后续 Subscribe 一定稳定。

PASE 与 CASE

• PASE：基于 setup passcode 建立，主要用于初次 commissioning；
• CASE：基于 Fabric 的 operational credentials，服务于日常单播安全会话；
• Group：服务于一对多组通信。

setup passcode、证书私钥和 Thread Dataset 都是敏感材料，不应出现在公开日志或仓库。

发现与地址

Matter 使用 DNS-SD / mDNS 发现节点和服务，并依赖 IPv6 地址。排障时要区分：

• commissionable discovery；
• operational discovery；
• Thread 或 Wi-Fi 网络接入；
• IPv6 路由；
• CASE 会话；
• Interaction Model 操作。

“mDNS 找不到”可能是网络接口、组播、防火墙或地址作用域问题，不应直接归因于 Cluster。

从哪里继续学习

• Matter 官方开源 SDK
• Matter SDK 文档
• CSA Matter 规范下载入口

SDK 示例用于学习，不自动代表某个具体 Device Type 的完整产品或认证实现。

协议栈位置

1
2
3
4
5

Matter 或其他 IP 应用
  -> UDP / IPv6
  -> 6LoWPAN
  -> Thread Mesh Link Establishment 与路由
  -> IEEE 802.15.4 MAC / PHY

这也是 Matter over Thread 与 Zigbee 的关键区别：Thread 承载 IP，Zigbee 使用自己的 NWK、APS 和应用层体系。

常见设备角色

Leader 不是所有报文的中央转发器。角色可以变化，网络会根据拓扑自动维护 Router 集合。

Border Router 不是应用网关

Thread Border Router 的核心职责是 IP 路由和网络数据传播。它让 Thread 节点能与 Wi-Fi/Ethernet 等相邻 IPv6 网络通信。

它通常不负责把一个应用协议翻译成另一个应用协议。Zigbee-to-Matter Bridge 执行的是应用数据模型映射，与 Thread Border Router 是不同角色。

一个 Thread 网络可以有多个 Border Router，从而减少单点依赖。

Thread 网络凭据

Active Operational Dataset 描述 Thread 网络的关键参数，例如信道、PAN 标识、Mesh-Local Prefix 和网络安全材料。

它是敏感配置：

• 不提交到公开仓库；
• 不直接粘贴到问题单；
• 抓包时只在授权本地环境加载；
• 示例使用占位符，不复用真实网络数据。

IPv6 地址为什么不止一个

Thread 节点通常具有多类 IPv6 地址：

• Link-Local：邻居链路上的本地通信；
• Mesh-Local EID：拓扑无关的 Mesh 内地址；
• Routing Locator：反映当前拓扑位置；
• Border Router 提供前缀形成的地址；
• 多播地址。

因此，看到一个 IPv6 地址变化不一定代表节点身份变化。排障要结合地址类型、作用域、接口和 Node 身份。

Attach 的高层流程

1
2
3
4
5
6

扫描与发现 Partition
  -> 选择父节点
  -> MLE 建立安全邻居关系
  -> 获得网络数据和地址
  -> 成为 Child 或 Router
  -> IPv6 可达

Thread Attach 成功只证明网络层建立。Matter 还需要 operational discovery、CASE 和应用交互。

低功耗与父节点

Sleepy End Device 关闭接收机来省电，通过父节点缓存和周期性 Poll 接收数据。关键参数包括：

• Poll 周期；
• 消息等待时间；
• 应用订阅的最大间隔；
• 重试和父节点切换；
• 设备醒来后的处理预算。

过度延长 Poll 周期会降低功耗，但也可能造成控制延迟、消息过期或 commissioning 超时。

抓包识别

Thread 抓包常见层级包括：

• IEEE 802.15.4；
• 6LoWPAN；
• MLE；
• IPv6 / UDP；
• CoAP；
• 加密后的 Matter 消息。

Thread Network Key 可以帮助分析 Thread 网络层，但不能因此解密 Matter CASE 业务负载。

继续阅读：

• Thread 官方概览
• Thread Network Fundamentals
• OpenThread 文档

分层对照

共享 IEEE 802.15.4 不代表空口互通。Matter over Thread 帧不能由 Zigbee 节点直接当作 ZCL 消息处理。

数据模型对照

迁移时应从业务语义出发，而不是复制数值 ID。

入网与 commissioning 对照

1
2
3
4
5

Matter:
发现 -> PASE -> Attestation -> 网络配置 -> NOC -> CASE -> 完成

Zigbee:
扫描 -> 关联 -> Network Key -> 安全通信 -> TCLK/BDB -> 应用发现

两边都有“发现、鉴权、配网、建立长期身份”的目标，但协议消息、凭据和成功锚点完全不同。

安全概念不要硬映射

• Matter Fabric 不是 Zigbee PAN；
• Matter NOC 不是 Zigbee Network Key；
• Matter PASE setup passcode 不是 Zigbee install code；
• Matter CASE 不是 Zigbee APS 加密；
• Matter Device Attestation 不等于 Zigbee Trust Center 准入。

它们只能在安全目的层面类比，不能在实现或日志中互换。

Thread 与 Zigbee 的位置

Matter 可以运行在 Thread、Wi-Fi 或 Ethernet 上。Thread 提供 IPv6 Mesh，不规定应用 Cluster。

Zigbee 从网络到应用数据模型形成另一条完整栈。二者都可能占用 2.4 GHz IEEE 802.15.4 信道，因此还要考虑射频共存，但不能因为底层相同就混用密钥或抓包过滤器。

Bridge 真正映射什么

Zigbee-to-Matter Bridge 通常需要维护：

1. Zigbee 设备身份与 Matter Bridged Node Endpoint；
2. Device Type 与 Cluster 语义映射；
3. Zigbee Attribute / Command 与 Matter Attribute / Command / Event；
4. 单位、范围、无效值和质量状态；
5. 在线状态、删除、重入网和 Endpoint 生命周期；
6. Zigbee reporting 与 Matter subscription；
7. Zigbee 网络安全边界与 Matter Fabric 访问控制。

Bridge 不是透明转发器。它终止两边协议，并在应用层重建语义。

一个映射检查表

对每项功能记录：

官方基础资料可参考 Matter SDK 文档、Zigbee 官方介绍和 Thread 官方概览。

先冻结版本组合

在安装前确认：

• 目标 Matter Specification 版本；
• 对应 Test Plan、PICS/PIXIT 和 CCB；
• Test Harness 发布版本或镜像；
• Test Harness 使用的 Matter SDK commit；
• DUT 的网络传输：Thread、Wi-Fi 或 Ethernet；
• 认证路径：完整产品、平台或派生产品；
• 实验室接受的设备与辅助硬件。

Test Harness、SDK、测试脚本和 PICS 之间存在版本配套关系。只更新其中一项可能制造环境假失败。

推荐架构

1
2
3
4
5
6
7
8
9
10
11

浏览器工作站
      │
Matter Test Harness 主机
  ├── Web / Backend / Database
  ├── 参考 Commissioner 或 Accessory
  ├── 测试脚本与日志
  └── OTBR（Thread DUT 时）
          │
        RCP
          │ IEEE 802.15.4
         DUT

Wi-Fi / Ethernet DUT 还需要稳定、可控且支持 IPv6 与组播的局域网。

硬件准备

当前官方 Test Harness 用户指南以 Raspberry Pi 4 或 5、至少 8 GB RAM 和至少 64 GB 存储作为完整环境的基础示例。Thread DUT 还需要受支持固件的 RCP。

实际送测前以对应 Test Harness 版本的用户指南为准，不要把这组规格当作永久不变的认证要求。

建议额外准备：

• 两台或以上独立 DUT；
• 串口日志采集器；
• 可控电源与重启方式；
• 独立抓包器；
• 有线管理网络；
• 时间同步；
• 足够保存镜像、数据库和原始日志的空间。

网络准备

Matter 对本地网络提出的典型基础要求：

• IPv6 可用；
• mDNS / DNS-SD 组播不被错误阻断；
• 主机路由和接口选择明确；
• 防火墙不拦截测试流量；
• Wi-Fi SSID 与 Thread Dataset 独立保存；
• 测试网与办公网、生产网隔离。

不要在公开配置文件中提交 Wi-Fi 密码、Thread Dataset、setup passcode 或证书私钥。

安装原则

1. 从 官方 certification-tool 仓库选择目标 release 或 commit；
2. 完整阅读该版本的 Matter_TH_User_Guide；
3. 使用文档指定的系统镜像、容器和 SDK 配套；
4. 记录每个镜像、仓库和 RCP 固件的版本；
5. 先用官方参考节点完成环境冒烟测试；
6. 再接入自己的 DUT。

不要把 main 分支当天状态当作认证基线，也不要在问题出现后无记录地升级整个环境。

DUT 准备

DUT 至少应支持：

• 稳定进入和退出 commissioning 模式；
• 可靠恢复出厂；
• 可识别的固件、硬件版本；
• 测试要求的自动化触发或人工操作；
• 持续串口日志；
• 正确的 Device Attestation Credentials；
• 与 PICS 一致的 Endpoint、Device Type 和 Cluster。

开发测试凭据与认证/量产凭据必须隔离。正式认证是否要求独立 provisioned DUT 及具体样机数量，应按当前计划和实验室要求执行。

PICS 驱动测试

Test Harness 根据 PICS 选择适用用例。推荐流程：

1
2
3
4
5
6

审查 Data Model
  -> 填写 PICS / PIXIT
  -> PICS Tool 校验
  -> 导入 Test Harness
  -> 检查自动选择的用例
  -> 运行并审查原始日志

用例没被选中不自动表示“不适用”，也可能是 PICS 填错。

环境验收

在测试产品功能前，先证明环境：

• Web UI、Backend 与数据库健康；
• 参考 Commissioner / Accessory 可运行；
• BLE adapter 可发现参考 DUT；
• Thread 时 OTBR 与 RCP 正常；
• Wi-Fi / Ethernet 时 IPv6 和 mDNS 正常；
• 测试主机时间一致；
• 日志、报告和备份可导出；
• 恢复出厂后可重复 commissioning。

证据与故障隔离

每次运行保存：

• Test Harness、SDK、镜像和脚本版本；
• PICS / PIXIT；
• DUT 固件和构建标识；
• 测试项目配置的脱敏副本；
• Test Harness、DUT、OTBR 和抓包日志；
• 用例结果与人工操作记录。

先用参考节点区分“环境坏了”还是“DUT 有问题”，再进入产品代码分析。

官方入口：

• Matter Test Harness User Guide
• CSA 认证工具
• Matter SDK 测试文档