Zigbee 驱动
dc3-driver-zigbee把 Zigbee 设备接入 IoT DC3——通过串口协调器（coordinator）连入 Zigbee 网络，按 ZCL 属性周期性读取节点数据，并支持向 ZCL 属性写值的命令。
读完这页，你能理解 Zigbee 在物联网网络层中的位置、知道接一台 Zigbee 节点要在驱动侧和位号侧填哪些属性，并清楚当前实现到了哪一步、哪些能力还不能依赖。
协议背景
Zigbee 是一种低功耗、低速率的短距无线 Mesh 协议，建立在 IEEE 802.15.4 物理/链路层之上，工作在 2.4 GHz 免授权频段。它的典型用途是智能家居与楼宇自控里大量电池供电的传感节点——温湿度、门磁、人体感应、开关、灯具、智能插座等。这类设备数据量小、要求长续航，不适合直接跑 IP 协议栈，于是组成自己的 Zigbee 网络：节点之间可互相中继（mesh），由一个**协调器（coordinator）**统一组网与进出。
在物联网四层架构里，Zigbee 属于网络层的无线接入技术——它解决" 低速设备的信号怎么省电地传出去"，而不直接讲 IP。Zigbee 网络不直接连公网，而是通过协调器/网关汇聚后再上联，这一点和 BLE 类似、和 MQTT/CoAP 这类应用层消息协议不同。在 IoT DC3 中，协调器以一枚 USB 串口 dongle 的形式插在运行驱动的主机上，驱动作为 Zigbee 应用层 client，把每个位号映射到 Zigbee 网络中的一个 ZCL 属性来采数、写值。
Zigbee 的寻址分多级。每个 Zigbee 设备用 IEEE 地址（64 位长地址，出厂固定）唯一标识；设备内部再按 endpoint（端点）→ cluster（簇）→ attribute（ZCL 属性） 三级定位某个具体的数据点。理解这套寻址，是配置位号属性的前提。
三级寻址：endpoint / cluster / attribute
一个 Zigbee 节点可有多个端点（多功能设备），每个端点下挂若干 ZCL 簇（如温度测量簇 1026、相对湿度簇 1029），每个簇里再有若干属性。 cluster + attribute 决定读到的是哪一类物理量——位号的数据类型（Point 的 pointTypeFlag）要和该 ZCL 属性的实际类型对得上。
属性配置
接入一台 Zigbee 设备分两层填写：驱动属性（driver-attribute） 配的是协调器侧的接入参数，一个协调器服务整个 Zigbee 网络； 位号属性（point-attribute） 把每个采集位号定位到网络中具体的一个 ZCL 属性。下面两张表的字段都来自驱动的 application.yml（dc3.driver.driver-attribute / point-attribute），默认值即 yml 中的 default-value。
驱动属性（设备级 driver-attribute）
这些属性配在设备上，描述本机上那枚协调器 dongle 怎么连、组到哪张 Zigbee 网络里。 serialPort 与 baudRate 决定串口连接，dongleType 决定用哪种协调器适配器，panId 与 channel 决定加入哪张网络的哪个信道（填 0 表示自动）。
| 属性 | code | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| Serial Port | serialPort | STRING | /dev/ttyUSB0 | Zigbee 协调器串口 |
| Baud Rate | baudRate | INT | 115200 | 串口波特率 |
| Dongle Type | dongleType | STRING | TELEGESIS | 协调器 dongle 类型（TELEGESIS, EMBER, CONBEE） |
| PAN ID | panId | INT | 0 | PAN ID（0=自动） |
| Channel | channel | INT | 0 | 信道（0=自动，11-26） |
位号属性（point-attribute）
每个采集位号用 IEEE 地址 + 端点 + 簇 + 属性，唯一定位到 Zigbee 网络中的一个 ZCL 属性。 nodeIeeeAddress 选哪台节点，endpointId / clusterId / attributeId 按上文三级寻址逐级缩小到那个具体属性。
| 属性 | code | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| Node IEEE Address | nodeIeeeAddress | STRING | （空） | Zigbee 节点 IEEE 地址（如 00158D0001234567） |
| Endpoint ID | endpointId | INT | 1 | 端点 ID |
| Cluster ID | clusterId | INT | 0 | 簇 ID（如 1026=温度测量） |
| Attribute ID | attributeId | INT | 0 | 属性 ID（如 0=测量值） |
写命令属性（command-attribute）
可写位号在写命令上填同样的四级定位，但指向要写入的目标属性。字段与位号属性同名同义，只是用于 write 路径。
| 属性 | code | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| Node IEEE Address | nodeIeeeAddress | STRING | （空） | Zigbee 节点 IEEE 地址 |
| Endpoint ID | endpointId | INT | 1 | 端点 ID |
| Cluster ID | clusterId | INT | 0 | 写入目标的簇 ID |
| Attribute ID | attributeId | INT | 0 | 写入目标的属性 ID |
一个最小接入示例
把一个 IEEE 地址为 00158D0001234567 的温度传感节点接进来：
- 选
Zigbee Driver创建设备，driver 属性填serialPort=/dev/ttyUSB0、baudRate=115200、dongleType=TELEGESIS、panId=0、channel=0。 - 给设备绑定的模板加一个温度位号（
pointTypeFlag=FLOAT、READ_ONLY），point 属性填nodeIeeeAddress=00158D0001234567、endpointId=1、clusterId=1026（温度测量簇）、attributeId=0（测量值）。 - 确保节点已加入协调器的 Zigbee 网络，启动驱动，30 秒内就能在位号值里看到采集值。
故障排查
接入 Zigbee 设备时，问题大多出在串口、网络入网、地址格式或当前实现的边界上。下面按"先连上、再找到、再读对"的顺序排查。
协调器找不到 / 串口被占
默认串口是 /dev/ttyUSB0、波特率 115200。先确认 dongle 已插好、宿主能看到串口设备（如 ls /dev/ttyUSB* ），且该串口没有被其他进程占用。容器化部署时，需把宿主串口设备透传进容器（如 --device=/dev/ttyUSB0），否则驱动启动后会一直连不上协调器。 注意：当前实现的串口与波特率是硬编码的，见下文实现状态。
节点报 "node not found"
读写时报找不到节点，通常是 nodeIeeeAddress 写错或节点未入网。IEEE 地址是连续 16 位十六进制字符（如 00158D0001234567），* 不要加冒号或 0x 前缀*。地址出厂固定，可在协调器/网关的设备列表里查到。另外，节点必须先加入本协调器的 Zigbee 网络（permit-join 入网）后才能被寻址。
端点 / 簇 / 属性找不到
报 "endpoint/cluster/attribute not found" 说明三级寻址某一级填错。多功能设备的端点不一定是 1；簇 ID 要对应实际物理量（温度测量 1026、相对湿度 1029）；属性 ID 要对应该簇下的具体属性（测量值常为 0）。先用协调器工具查清目标节点暴露的端点与簇，再回填位号属性。
读路径取的是该 ZCL 属性的最近缓存值（attribute.getLastValue()）。若节点尚未上报过该属性、或属性绑定/上报未配置，可能读到 0（默认占位）。
数据类型对不上
位号的 pointTypeFlag 要与 ZCL 属性的实际类型一致。温度测量值是有符号整数（单位 0.01℃），按 FLOAT /数值解析；若把字符串类簇当数值读，或反之，会得到无意义的值。配置位号前先核对该 ZCL 属性的数据类型。
驱动 / 设备显示离线
驱动级健康检查依赖 networkManager 是否已初始化：协调器没连上时驱动级为离线。设备级在线态见设备的租约机制（健康检查 cron 0/15 * * * * ?、租约超时 45 秒）。注意当前实现中设备记录有效时设备级健康检查固定返回在线（未按 IEEE 地址做可达性校验），不能据此判断单个节点是否真实可达，见下文实现状态。
在 IoT DC3 中如何落地
dc3.driver.code：ZigbeeDriver（驱动名Zigbee Driver，类型DRIVER_CLIENT——主动连协调器、轮询节点）。这是稳定的路由标识，不要随意改。- 采集周期：默认 cron
0/30 * * * * ?，每 30 秒读一轮 ZCL 属性。 - 健康/在线：设备健康检查默认 cron
0/15 * * * * ?，租约超时45 秒，在线状态机制见设备。 - 读 / 写能力：读路径取协调器侧 ZCL 属性的最近缓存值（
attribute.getLastValue()），而非每次都同步轮询设备空口；这与请求-响应式驱动（如ble、coap）不同。 - 订阅能力（尚未实现）：
initial()目前只注册了协调器网络状态监听器（addNetworkStateListener，仅记录网络 UP/DOWN 日志），并未监听节点入网（node-join/announce）或 ZCL 属性上报 ，也未配置属性绑定/上报（binding/reporting）。因此读路径取到的缓存值依赖节点自行上报或外部工具配置上报，驱动本身不会捕获入网与上报事件——驱动能力矩阵 中 Zigbee 的"订阅"一栏据此标注为未实现。
当前为骨架实现（Work in Progress）
该驱动目前是骨架版本，协议层 I/O 尚未完整实现，请按"接入模板"而非生产可用驱动看待。源码方法体中有多处 TODO 标记，关键限制如下：
- 串口与波特率被硬编码：
initial()写死了/dev/ttyUSB0与115200，不读取serialPort/baudRate驱动属性。若协调器不在/dev/ttyUSB0，需先补齐配置读取逻辑，否则填了属性也不生效。 - 只打包了 Telegesis 适配器：代码只引入并使用
ZigBeeDongleTelegesis，dongleType填EMBER/CONBEE暂不会切换适配器。 - 设备级健康检查恒在线：
health(driverConfig, device)在设备记录有效时固定返回在线（仅当 device 或其 id 为空才返回离线），未真正按 IEEE 地址校验节点可达性。
写命令当前不真正下发
写路径（writeAttribute）会校验节点 / 端点 / 簇 / 属性是否存在，但只记一条日志，不会真正把值写到 ZCL 属性 。在写能力补全前，配置了写命令的位号会"看似成功"但设备状态不变——不要依赖它做实际控制。