TuyaOSZigbee 子设备开发框架能力地图

能力地图

更新时间：2023-12-14 06:47:15下载pdf

TuyaOS Zigbee 开发框架是基于业务包的概念设计的，提供了产品级的能力，高度封装了 Zigbee 协议栈的能力，您无需关心具体的实现原理，使用业务接口可快速开发 Zigbee 产品。

能力框图如下所示：

能力地图

产品功能

设备构建

能力	说明
设备类型	支持 ZRD 和 ZED 设备开发。 ZRD 即 Zigbee Router Device，有中继能力，通常是常供电设备。 ZED 即 Zigbee End Device，无中继能力，通常是电池供电的低功耗设备。
属性构建	根据 Zigbee 标准规范构建设备支持的 Endpoint、Cluster、Attribute。同时支持自定义 Cluster 和 Attribute。
设备信息	可自定义 Device ID、Manufactory Name、Model ID、Firmware Version 等设备信息。

网络管理

能力	说明
普通配网	通过配置上电行为参数，或者调用 API 进入配网，加入到 Zigbee 网络中。普通配网一般是通过设备复位，例如设备上电，或者在设备上进行某种特殊操作后，让设备进入配网状态。
扫码配网	通过 App 扫描设备上的二维码，通知网关开启配网，并由网关主动找寻 Zigbee 子设备。扫码配网一般不需要对 Zigbee 子设备进行特殊操作。
TouchLink	一种无网关的配网方式，例如照明遥控器与灯具建立直接连接。TouchLink 一般要求在进行配网时，两个设备要尽量靠近，配网与以后的使用过程，都无需网关与 App。
本地重置	本地重置可把设备恢复到配网之前状态，也可以选择是否清除数据，例如群组，场景，设备状态等。
被动离网	收到网关发送的离网指令，可恢复到配网前状态。
安装码	配网时使用的安装码（Install Code），可选择是否使用。安装码是一个 16 字节长度的码，每一个设备都不相同。TuyaOS 支持配网三种方式：只使用 Global Key 配网只使用 Install Code 配网同时使用 Global Key 和 Install Code 配网
网络自恢复	用于防止本地误操作导致设备主动离网。本地重置后进入配网状态，若配网超时或者设备重启，则恢复之前的网络信息，且所有数据都会保留，例如群组，场景等。

数据传输

能力	说明
属性上报	Zigbee 设备通过主动上报属性（Attribute）至网关，用于同步自身的状态。例如灯具的开关状态改变时，主动上报 `onoff` 属性值的 `on` 或者 `off`。
命令发送	向 Zigbee 网络中其他设备发送命令（Command），例如照明遥控器向灯具发送 `on` 或者 `off` 命令。
命令接收	接收来自 Zigbee 网络中其他设备发送的命令，例如灯具接收来自网关的 `on` 或者 `off` 命令。
属性读写	通常是网关来查询或者配置 Zigbee 子设备的某个属性，例如网关可以查询灯具的 `onoff` 属性值，以同步灯具的开关状态。
DP 透传	当设备在涂鸦 IoT 开发平台的定义的 DP 无法映射到 Zigbee3.0 标准属性或命令时，通过涂鸦定义的私有 Zigbee 命令进行 DP 数据内容透传。一般用于实现非 Zigbee3.0 标准的功能。

设备关系

能力	说明
本地群组（Group）	当需要对群组设备进行控制时，只需要向群组发送一条命令即可，避免了向多个设备发送相同的命令。这样可以有效的减少空中报文的数量，且群组设备的行为可以保持同步。多个 Zigbee 子设备可以加入到一个群组中，同一个 Zigbee 子设备也可以加入到多个群组中。
本地场景（Scene）	场景是指设备的多个状态的组合，这些状态可以如同快照一样存储在设备本地，并分配一个场景 ID 进行索引。用户可以在任意时间通过场景唤醒指令，让设备进入特定状态，而不需要发多条指令。例如给灯具添加一个场景，包含开关，亮度，色温等信息，当唤醒此场景时灯具会恢复此场景对应的开关，亮度，色温等状态。
发现并绑定（Find&Bind）	用于 Zigbee 设备之间直接控制，效果类似于指令订阅，通过 Find&Bind 流程，两个设备之间可以建立绑定关系，之后一个设备可以直接发送指令给另一个设备，即使此时网关已经断电。

OTA 升级

能力	说明
全量 OTA	OTA 包是完整的固件，固件传输时间较长，根据不同 OTA 固件的大小，整个 OTA 过程大约 10~15 分钟。全量 OTA 是 Zigbee 规范的标准用法。
差分 OTA	涂鸦自行设计的 Zigbee 差分 OTA 功能，OTA 固件是通过差分运算得出的差分固件。当 OTA 固件与设备当前运行固件差异较小时，OTA 固件也会很小，可极大缩短传输时间。整个 OTA 过程可以缩短到 1 分钟以内。注意，新固件与当前运行固件差异越小，效果越明显。
群升 OTA	当一个群组内有多个相同的设备时，逐个给每个设备进行 OTA 是非常耗时的。群升 OTA 可以同时对群组内相同设备进行 OTA，从而缩短总体所需时长。注意，群升 OTA 在设备数量越大时，效果越明显。差分 OTA 和群升 OTA 可同时使用。群升 OTA 也是涂鸦自行设计的流程。

通用服务

能力	说明
时间服务	Zigbee 子设备向网关请求时间信息，并转换成年、月、日、时、分、秒。
设备心跳	ZRD 和 ZED 都可以开启设备心跳，用于保持云端在线状态，TuyaOS 是通过主动上报属性（设备版本号或电池电量）来维持心跳的。另外，涂鸦网关对于 Router 设备定期进行属性查询，来判断设备是否在线，因此 Router 设备无需自己主动上报。
异常日志	用于记录设备的特殊操作（例如重启，本地重置等）及异常，日志中包含特殊操作及异常发生的时间点。这些日志信息会在设备上电或者配网成功后，上报至网关，用于分析一些历史行为。注意，异常日志一旦上报成功后，本地则会清除此条记录。
产测	通过产测可以在设备出厂之前，发现设备异常（例如管脚焊接松动，信号接收差等），防止不良产品流入市场。TuyaOS 支持多种方式进入产测模式：通过串口（UART）进入产测模式，通常是在 PCBA 阶段。通过涂鸦产测信标进入产测模式，通常是指成品阶段。通过网关进入产测模式（这种方法已经不推荐使用）。注意，产测需要搭配特定的工具，例如涂鸦产测上位机，产测信标，产测网关等，具体取决于采用何种产测方式。

基础工具

能力	说明
数据存储	8K 的 User Flash 给应用层存储数据。
软件定时	开发框架提供软件定时器，您可以通过设置软件定时器执行定时任务。
打印日志	开发框架提供串口日志服务，在开发过程中开启打印服务设备调试。
ECC 签名	使用涂鸦提供的开发框架编译后的固件会带固件签名，如果用于量产开发需要购买涂鸦的激活码。
JSON	开发框架内置精简版 CJSON 解析组件，在产测时使用。

硬件驱动抽象

能力	说明
GPIO	GPIO 驱动，可以控制任意 GPIO 输出高低电平，也可以查询任意 GPIO 的当前电平。
UART	UART 驱动，可以设置任意 UART 的波特率，也可以控制任意 UART 发送自定义数据。
PWM	PWM 驱动，可以设置任意通道 PWM 的频率和占空比，也可以控制任意通道 PWM 恢复初始状态。
ADC	ADC 驱动，可以读取任意 ADC 通道的数值或电压值，也可以修改 ADC 的分辨率。
FLASH	FLASH 驱动，提供片上 FLASH 任意地址安全的擦除、写入、读取操作接口。
RTC	RTC 驱动，提供初始化或复位 RTC 模组，设置或查询设备的 RTC 时间接口。
Watchdog	Watchdog 驱动，支持开启或关闭看门狗、喂狗功能。

支持与帮助

在开发过程遇到问题，您可以登录 TuyaOS 开发者论坛子设备开发版块进行沟通咨询。

上一篇Zigbee 子设备开发框架

下一篇设备构建