网关扩展 SDK

涂鸦网关扩展 SDK 是用于对接网关产品到涂鸦开发者平台的解决方案。SDK 封装了网关与 Zigbee 模组、网关与涂鸦 IoT、涂鸦 App 的通信，您无需关心通信层的实现，完全专注于其业务的开发，帮助您降低网关的开发门槛。

概述

以 Zigbee 网关为例，涂鸦网关扩展 SDK 下行与 Zigbee 模组通信，上行与涂鸦开发者平台 & 涂鸦 App 通信。您可以基于涂鸦网关扩展 SDK 开发其应用。网关扩展 SDK 的应用结构如下图所示：

网关类型

基于该 SDK 可以开发多种形态的网关产品，以增强产品的差异性。产品形态包括但不局限于：

类型	说明
Zigbee 网关	低代码实现 Zigbee 网关产品，SDK 赋予第三方系统具备 Zigbee 网关能力，默认支持涂鸦生态 Zigbee 子设备。
Zigbee 扩展网关	SDK 赋予第三方系统具备接入非涂鸦生态的 Zigbee 设备的能力，您可以把非涂鸦生态的 Zigbee 子设备接入到 涂鸦开发者平台。
多协议融合网关	SDK 赋予第三方系统具备接入子设备的能力，实现 Zigbee + 其他协议（如433、KNX、ZWave等）融合网关产品。
多功能网关	SDK 赋予第三方系统具备多功能网关的能力，如系统接小夜灯、声光报警器等外设，搭配各种传感器实现多种智能场景。

前提条件

在开发之前，您需要先注册涂鸦开发者平台账号，获取设备开发阶段的必要信息，如 PID、授权码等。具体操作指导，请参见 选品类创建产品。

硬件要求

• Flash：不同平台编译的 SDK 产物大小有差异，建议保留 5 MB 及以上的空间，并且分区可读写
• RAM：SDK 运行后占用 5 MB 左右内存

软件要求

• 支持 Linux 或 Android 系统（4.0 以上）
• 支持 TCP/IP 协议栈

获取 SDK

涂鸦网关扩展 SDK 是以 C 语言动态链接库(.so)或者静态库(.a)的形式提供给用户，因此，需要用户提供其系统的交叉编译工具链来打包 SDK。

同时，涂鸦网关扩展 SDK 的产物托管在 GitHub，在最新版本找到对应的交叉编译工具链可直接下载产物使用，如有问题请联系涂鸦技术支持。

获取到的 SDK 具有以下目录结构：

├── CHANGE_LOG.md   # 版本信息
├── Makefile
├── README.md       # 使用说明
├── build_app.sh    # 编译脚本
├── demos           # 示例代码目录
├── tools           # 工具代码目录，如Zigbee射频测试工具
└── sdk
	├── include     # SDK头文件
	└── lib         # SDK库文件

开发概览

用户应用是由您基于涂鸦网关扩展 SDK 开发，为了降低您的开发成本，开发指南的章节按功能划分。

基础功能章节是网关的基础，是网关开发必选章节，而其余章节，您只需要关注其业务所涉及的功能对应的章节。

产品类型	功能开发章节
Zigbee 网关	基础功能
多功能 Zigbee 网关	基础功能 + 设备功能点
多协议融合网关	基础功能 + 设备功能点 + 设备接入
Zigbee 扩展网关	基础功能 + 设备功能点 + 设备接入 + Zigbee设备接入

由于有线和无线驱动在不同平台有差异，所以适配层相关接口需要由您实现。

选择无线或有线+无线 SDK，需要实现 hal_wifi.c 的接口，接口说明请参见配网功能。

选择有线或有线+无线 SDK，需要实现 hal_wired.c 的接口，接口说明请参见配网功能。

基础功能

基本功能是开发网关产品的基础，包含了必选功能和可选功能。必选功能是基于涂鸦网关扩展 SDK 开发产品必须要实现的功能，可选功能是您可以根据实际需求来决定是否需要实现。

SDK 预初始化、SDK 初始化、网关本地日志、网关应用重启、网关升级、网关重置，其他为可选功能。

SDK 初始化

功能说明

SDK 初始化用于申请 SDK 运行时需要的系统资源，以及初始化网关基本业务。

开发流程

• 把 Zigbee 模组的串口设备和波特率，存储路径等 SDK 初始化相关的属性填充到网关基本属性结构体 ty_gw_attr_s 对应的成员变量。
• 实现 get_uuid_authkey_cb 回调函数，在函数中把在涂鸦开发者平台获取到 UUID 和 Authkey 赋值给 uuid 和 authkey 参数。
• 实现 get_product_key_cb 回调函数，在函数中把在涂鸦开发者平台创建产品获取到 PID 赋值给 pk 参数。
• 根据实际需求实现其他回调函数。
• 将相关回调函数赋值给网关基础回调结构体 ty_gw_infra_cbs_s 的对应成员变量。
• 调用 tuya_user_iot_init 接口，把网关基本属性结构体 ty_gw_attr_s 和网关基础回调结构体 ty_gw_infra_cbs_s 结构体分别作为输入参数。

网关本地日志

功能说明

对于量产的网关产品，可以通过涂鸦运营平台拉取本地日志进行故障分析。当在运营平台上拉取日志时，会触发网关本地日志回调，您需要在回调中实现获取本地日志的功能。

开发流程

• 实现 gw_fetch_local_log_cb 回调函数，在函数中将本地日志文件压缩，把压缩路径和文件名赋值给 path 变量，路径和文件名的总长度不能超过 path_len。
• 将该回调函数赋值给网关基础回调结构体 ty_gw_infra_cbs_s 的 gw_fetch_local_log_cb 成员变量。

网关应用重启

功能说明

网关完成 Zigbee 模组升级、网关重置等操作时，需要重启网关应用。当需要重启网关应用时，会触发网关应用重启回调，您要在回调中实现重启网关应用的功能。

开发流程

• 实现 gw_reboot_cb 回调函数，在函数中执行重启网关应用的操作。
• 将该回调函数赋值给网关基础回调结构体 ty_gw_infra_cbs_s 的 gw_reboot_cb 成员变量。

网关升级

功能说明

当网关有新版本可升级时，在涂鸦 APP 上触发网关升级，网关会自动下载固件，校验通过后会触发网关升级回调，您要在回调中实现网关升级的功能。

开发流程

• 实现 gw_upgrade_cb 回调函数，在函数中从 img 变量获取固件文件，执行升级操作。
• 将该回调函数赋值给网关基础回调结构体 ty_gw_infra_cbs_s 的 gw_upgrade_cb 成员变量。

网关重置

功能说明

当在涂鸦 APP 恢复网关出厂设置时，会触发网关重置回调，您可以在回调中实现其重置业务。

开发流程

• 实现 gw_reset_cb 回调函数，您可根据实际情况实现其特定业务。
• 将该回调函数赋值给网关基础回调结构体 ty_gw_infra_cbs_s 的 gw_reset_cb 成员变量。

网关激活通知

功能说明

当网关成功绑定或者解绑涂鸦开发者平台时，会触发网关激活通知回调，您可以在回调中处理其业务（如控制指示灯）。

开发流程

• 实现 gw_active_status_changed_cb 回调函数，在函数中根据 status 变量获取网关当前的激活状态，处理相应的业务。
• 将该回调函数赋值给网关基础回调结构体 ty_gw_infra_cbs_s 的 gw_active_status_changed_cb 成员变量。

网关上线通知

功能说明

当网关成功连接涂鸦开发者平台或连接断开时，会触发网关上线通知回调，您可以在回调中处理其业务（如控制指示灯）。

开发流程

• 实现 gw_online_status_changed_cb 回调函数，在函数中根据 online 变量获取网关在线或离线状态，处理相应的业务。
• 将该回调函数赋值给网关基础回调结构体 ty_gw_infra_cbs_s 的 gw_online_status_changed_cb 成员变量。

工程部署模式

功能说明

工程部署模式用于离线部署，搭配涂鸦施工 APP 使用。部署完成后切换到普通模式，用户绑定网关后会同步工程部署的子设备、场景以及自动化。

开发流程

• SDK 初始化的时候，将结构体 ty_gw_attr_s 的 is_engr 成员变量赋值为 1（0 表示进入普通模式，1 表示进入工程模式）。

• 实现 gw_engineer_finished_cb 回调函数，在函数中重启网关应用，以普通模式运行。

  建议您设置系统标志，根据系统标志来启动网关应用，工作在普通模式运行还是工程模式。系统首次启动标志为工程模式，直到工程部署完成回调被触发，将标志改为普通模式。

• 将该回调函数赋值给网关基础回调结构体 ty_gw_infra_cbs_s 的 gw_engineer_finished_cb 成员变量。

网关绑定

功能说明

SDK 留有本地绑定网关的能力，您可以用有效的 token 将网关绑定到涂鸦开发者平台。常见的有蓝牙配网，设备端通过手机 APP 蓝牙通信获取激活 token 然后进行激活。

开发流程

• 获取用于激活网关的有效 token。
• 调用 tuya_user_iot_active_gw 接口，将 token 作为输入参数。

网关解绑

功能说明

SDK 留有本地解绑网关的能力，您可通过按键等方式解绑网关，解绑不清空子设备数据，重新激活恢复之前的子设备列表。

开发流程

• 调用 tuya_user_iot_unactive_gw 接口。

网关重置

功能说明

SDK 留有本地重置网关的能力，您可通过按键等方式重置网关，网关的数据会被清空。

开发流程

• 调用 tuya_user_iot_reset_gw 接口。

设备入网

功能说明

SDK 留有本地控制子设备入网的能力，您可通过按键等方式进行开启或关闭子设备入网。

开发流程

• 调用 tuya_user_iot_permit_join 接口。

API 说明

tuya_user_iot_init()

int tuya_user_iot_init(ty_gw_attr_s *attr,
                       ty_gw_infra_cbs_s *cbs)

功能说明

初始化 SDK 基本业务的接口。

参数说明

参数名称	说明
attr	参考 ty_gw_attr_s 结构体说明
cbs	参考 ty_gw_infra_cbs_s 接口体说明

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_active_gw()

int tuya_user_iot_active_gw(const char *token);

功能说明

本地绑定网关的接口。

参数说明

参数名称	说明
token	绑定网关的 token

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_unactive_gw()

int tuya_user_iot_unactive_gw(void);

功能说明

本地解绑网关的接口。

参数说明

无

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_reset_gw()

int tuya_user_iot_reset_gw(void);

功能说明

本地重置网关的接口。

参数说明

无

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_permit_join()

int tuya_user_iot_permit_join(bool permit, uint32_t timeout);

功能说明

本地控制子设备入网的接口。

参数说明

参数名称	说明
permit	0：关闭。 1：开启。
timeout	配网超时时间，超时后关闭配网，单位是秒

返回值

返回值	说明
0	成功
非0	失败

get_uuid_authkey_cb()

int (*get_uuid_authkey_cb)(char *uuid,
                           int uuid_size,
                           char *authkey,
                           int authkey_size);

功能说明

获取设备 UUID 和 Authkey 的回调函数，您需要在此回调函数中把在涂鸦开发者平台上创建产品获取到的 UUID 和 Authkey 赋值给 uuid 和 authkey 变量。

参数说明

参数名称	说明
uuid	将 UUID 赋值给该变量
uuid_size	uuid 对应的 buf 大小
authkey	将 Authkey 赋值给该变量
authkey_size	authkey 对应的 buf 大小

返回值

返回值	说明
0	成功
非0	失败

get_product_key_cb()

int (*get_product_key_cb)(char *pk,
                          int pk_size);

功能说明

获取设备 PID 的回调函数，您需要在此回调函数中把在涂鸦开发者平台上创建产品获取到的 PID 赋值给 pk 变量。

参数说明

参数名称	说明
pk	将 PID 赋值给该变量
pk_size	pk 对应的 buf 大小

返回值

返回值	说明
0	成功
非0	失败

gw_reboot_cb()

int (*gw_reboot_cb)(void);

功能说明

重启 SDK 应用的回调函数。

参数说明

无

返回值

返回值	说明
0	成功
非0	失败

gw_reset_cb()

int (*gw_reset_cb)(void);

功能说明

重置网关的回调函数，您在根据实际情况此回调函数中实现清空网关数据的功能。

参数说明

无

返回值

返回值	说明
0	成功
非0	失败

gw_upgrade_cb()

int (*gw_upgrade_cb)(const char *img);

功能说明

涂鸦应用升级的回调函数，您在此回调函数中实现升级的功能。

参数说明

参数名称	说明
img	网关固件文件所在的路径

返回值

返回值	说明
0	成功
非0	失败

gw_fetch_local_log_cb()

int (*gw_fetch_local_log_cb)(char *path,
                             int path_len);

功能说明

从涂鸦运营平台拉取设备日志的回调函数。

参数说明

参数名称	说明
path	把日志文件的路径赋值给该变量
path_len	file 变量的长度

返回值

返回值	说明
0	成功
非0	失败

gw_engineer_finished_cb()

int (*gw_engineer_finished_cb)(void);

功能说明

工程部署完成的回调函数，您在此回调函数中实现重启 SDK 应用，并切换到普通模式。

参数说明

无

返回值

无

gw_online_status_changed_cb()

int  (*gw_online_status_changed_cb)(bool online);

功能说明

网关上下线状态变化的回调函数，您可以在此回调函数中根据网关上线或下线处理其特定业务。

参数说明

参数名称	说明
online	网关在线状态。 0：离线。 1：在线。

返回值

返回值	说明
0	成功
非0	失败

gw_active_status_changed_cb()

int  (*gw_active_status_changed_cb)(ty_gw_status_t status);

功能说明

网关成功绑定或解绑涂鸦开发者平台的通知回调函数，您可以在此回调函数中根据网关成功绑定或解绑处理其特定业务。

参数说明

参数名称	说明
status	网关激活状态。 0：未绑定。 1：已绑定。

返回值

返回值	说明
0	成功
非0	失败

ty_gw_attr_s

typedef struct {
    char          *storage_path;
    char          *cache_path;
    char          *tty_device;
    int            tty_baudrate;
    char          *ssid;
    char          *password;
    char          *ver;
    int            is_engr;
    int            is_fork;
    ty_conn_mode_t wifi_mode;
    ty_log_lovel_t log_level;
} ty_gw_attr_s;

功能说明

初始化 SDK 的基本属性。

成员说明

成员名称	说明
storage_path	存储路径是系统存储 SDK 数据库等文件的路径，所指定的路径必须有可读写权限，缺省是当前路径。 注意，存储路径必须以反斜杠结束。例如，若存储路径指定为 “/etc”，storage_path 则要被赋值为 “/etc/”。
cache_path	临时路径是系统保存临时文件的路径，必须有可读写权限，缺省是 /tmp
tty_device	网关与 Zigbee 模组的串口通讯所使用的串口设备，如 /dev/ttyS1
tty_baudrate	网关与 Zigbee 模组的串口通讯所使用的串口波特率，仅支持 115200 和 57600。 波特率为 115200 需要硬件流控 波特率为 57600 不需要硬件流控
ssid	AP 配网模式，指定网关 AP 的 SSID
password	AP 配网模式，指定网关 AP 的 Password
ver	网关应用的版本号，用于固件升级，必须是“x.x.x”的格式
is_engr	0：普通模式 1：工程模式
is_fork	0：以多线程方式启动 Zigbee 服务 1：以多进程方式启动 Zigbee 服务
wifi_mode	无线配网可以指定网关工作以哪种模式启动。 TY_CONN_MODE_AP_ONLY：仅工作在 AP 模式。 TY_CONN_MODE_EZ_ONLY：仅工作在 EZ 模式。 TY_CONN_MODE_AP_FIRST：支持 AP & EZ 模式，首次工作在 AP 模式，解绑或重置网关时切换。 TY_CONN_MODE_EZ_FIRST：支持 AP & EZ 模式，首次工作在 EZ 模式，解绑或重置网关时切换。
log_level	设置 log 打印等级，开发阶段可开启 debug 模式

ty_gw_infra_cbs_s

typedef struct {
    int  (*get_uuid_authkey_cb)(char *uuid, int uuid_size, char *authkey, int authkey_size);
    int  (*get_product_key_cb)(char *pk, int pk_size);
    int  (*gw_upgrade_cb)(const char *img_file);
    void (*gw_reboot_cb)(void);
    void (*gw_reset_cb)(void);
    void (*gw_engineer_finished_cb)(void);
    int  (*gw_fetch_local_log_cb)(char *path, int path_len);
    int  (*gw_configure_op_mode_cb)(ty_op_mode_t mode);
    int  (*gw_active_status_changed_cb)(ty_gw_status_t status);
    int  (*gw_online_status_changed_cb)(bool online);
} ty_gw_infra_cbs_s;

功能说明

网关相关的回调。

成员说明

成员名称	说明
get_uuid_authkey_cb	获取 UUID 和 Authkey 回调
get_product_key_cb	获取 PID 回调
gw_upgrade_cb	网关升级回调
gw_reboot_cb	网关应用重启回调
gw_reset_cb	网关重置回调
gw_engineer_finished_cb	网关工程部署完成回调
gw_fetch_local_log_cb	网关本地日志回调
gw_active_status_changed_cb	网关激活状态通知回调
gw_online_status_changed_cb	网关在线状态通知回调

设备功能点

涂鸦对设备功能进行了抽象，屏蔽了具体协议，以功能点的形式呈现给您，支持数值型、布尔型、枚举型、字符串型、故障型，RAW 型数据，像定义 C 变量一样简单。

您需要根据设备功能在涂鸦开发者平台创建对应的功能点，详细可以参考功能定义。

回调注册

功能说明

通过设备功能点控制设备需要您实现，涂鸦网关扩展 SDK 采用回调函数的方式，使用此接口注册回调函数。

开发流程

• 实现相关的回调函数，并将它们填充到回调结构体 ty_dev_cmd_cbs_s。

• 在 SDK 初始化之前，调用 tuya_user_iot_reg_dev_cmd_cb 接口，把 ty_dev_cmd_cbs_s 结构体作为输入参数。

设备指令下发

功能说明

通过涂鸦 APP 控制设备时，会触发设备指令下发回调。您要把功能点格式转成具体的设备可识别的数据，进行设备控制。

开发流程

• 实现 dev_obj_cmd_cb / dev_raw_cmd_cb 回调函数，在函数中根据 dp 变量解析接收到的功能点信息，将其转成具体设备的协议，把控制指令下发给设备。

  obj 类型的功能点不满足用户的需求时，可以定义 raw 类型的功能点，raw 为透传数据。

• 将该回调函数赋值给设备功能点回调结构体 ty_dev_cmd_cbs_s 的 dev_obj_cmd_cb /dev_raw_cmd_cb 成员变量。

• 调用注册设备功能点回调 tuya_user_iot_reg_dev_cmd_cb 时，把设备功能点回调结构体作为输入参数。

设备状态上报

功能说明

当设备本地状态变化时，要上报新的状态到涂鸦开发者平台，用于同步设备状态。

开发流程

• 用户应用接收到设备的状态上报，将其封装成功能点格式。
• 调用 tuya_user_iot_report_obj_dp / tuya_user_iot_report_raw_dp 接口。

设备本地控制

功能说明

SDK 留有本地控制的能力，您可以本地控制设备，用户本地化处理。

开发流程

• 调用 tuya_user_iot_send_obj_cmd / tuya_user_iot_send_raw_cmd 接口。

设备数据上报回调

功能说明

设备上报数据时，通过回调的方式通知应用，您可以注册回调函数来获取设备上报的数据，用于本地化处理。

开发流程

• 实现 dev_obj_dp_report_cb / dev_raw_dp_report_cb 回调函数，从函数的入参中解析接收到的数据处理自己的业务。
• 将回调函数赋值给设备功能点回调结构体 ty_dev_data_cbs_s 对应的成员变量。
• 在 SDK 初始化之前，调用 tuya_user_iot_reg_dev_data_cb 接口注册回调。

API 说明

tuya_user_iot_reg_dev_cmd_cb()

int tuya_user_iot_reg_dev_cmd_cb(ty_dev_cmd_cbs_s *cbs);

功能说明

注册指令下发回调。

参数说明

参数名称	说明
cbs	参考 ty_dev_cmd_cbs_s 结构体说明

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_reg_dev_data_cb()

int tuya_user_iot_reg_dev_data_cb(const ty_dev_data_cbs_s *cbs);

功能说明

注册指令下发回调。

参数说明

参数名称	说明
cbs	参考 ty_dev_data_cbs_s 结构体说明

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_report_obj_dp()

int tuya_user_iot_report_obj_dp(const char *dev_id,
                                ty_dp_s *dps,
                                uint32_t dps_cnt);

功能说明

上报设备属性值（obj）到涂鸦开发者平台。

参数说明

参数名称	说明
dev_id	dev_id == NULL，表示网关功能点 dev_id != NULL，表示子设备功能点，且 dev_id 为子设备的 MAC 地址
dps	参考 ty_dp_s 结构体说明
dps_cnt	功能点数量

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_report_raw_dp()

int tuya_user_iot_report_raw_dp(const char *dev_id,
                                uint32_t dpid,
                                uint8_t *data,
                                uint32_t len,
                                uint32_t timeout);

功能说明

上报设备属性值（raw）到涂鸦开发者平台。

参数说明

参数名称	说明
dev_id	dev_id == NULL，表示网关功能点 dev_id != NULL，表示子设备功能点，且 dev_id 为子设备的 MAC 地址
dpid	对应在涂鸦开发者平台上创建产品时定义的功能点编号
data	透传的数据
len	透传的数据长度
timeout	函数阻塞的最大时间，单位是秒

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_send_obj_cmd()

int tuya_user_iot_send_obj_cmd(const ty_obj_cmd_s *cmd);

功能说明

本地控制设备函数(obj类型指令)。

参数说明

参数名称	说明
dp	参考 ty_obj_cmd_s 结构体说明

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_send_raw_cmd()

int tuya_user_iot_send_raw_cmd(const ty_raw_cmd_s *cmd);

功能说明

本地控制设备函数(raw类型指令)。

参数说明

参数名称	说明
dp	参考 ty_raw_cmd_s 结构体说明

返回值

返回值	说明
0	成功
非0	失败

dev_obj_cmd_cb()

int (*dev_obj_cmd_cb)(ty_obj_cmd_s *dp);

功能说明

控制设备功能点（obj）的回调函数。

参数说明

参数名称	说明
dp	参考 ty_obj_cmd_s 结构体说明

返回值

返回值	说明
0	成功
非0	失败

dev_raw_cmd_cb()

int (*dev_raw_cmd_cb)(ty_raw_cmd_s *dp);

功能说明

控制设备功能点（raw）的回调。

参数说明

参数名称	说明
dp	参考 ty_raw_cmd_s 结构体说明

返回值

返回值	说明
0	成功
非0	失败

dev_obj_dp_report_cb()

int (*dev_obj_dp_report_cb)(const char *dev_id, const ty_dp_s *dps, uint32_t dps_cnt);

功能说明

设备数据(obj类型)上报回调。

参数说明

同 tuya_user_iot_report_obj_dp 接口。

返回值

返回值	说明
0	成功
非0	失败

dev_raw_dp_report_cb()

int (*dev_raw_dp_report_cb)(const char *dev_id, uint32_t dpid, uint8_t *data, uint32_t len);

功能说明

设备数据(raw类型)上报回调。

参数说明

同 tuya_user_iot_report_raw_dp 接口。

返回值

返回值	说明
0	成功
非0	失败

ty_dev_cmd_cbs_s

typedef struct {
	int (*dev_obj_cmd_cb)(ty_obj_cmd_s *dp);
	int (*dev_raw_cmd_cb)(ty_raw_cmd_s *dp);
} ty_dev_cmd_cbs_s;

功能说明

设备功能点的回调。

成员说明

成员名称	说明
dev_obj_cmd_cb	obj 类型功能点的回调
dev_raw_cmd_cb	raw 类型功能点的回调

ty_dev_data_cbs_s

typedef struct {
    int (*dev_obj_dp_report_cb)(const char *dev_id, const ty_dp_s *dps, uint32_t dps_cnt);
    int (*dev_raw_dp_report_cb)(const char *dev_id, uint32_t dpid, uint8_t *data, uint32_t len);
} ty_dev_data_cbs_s;

功能说明

设备功能点的回调。

成员说明

成员名称	说明
dev_obj_dp_report_cb	obj 类型数据上报回调
dev_raw_dp_report_cb	raw 类型数据上报回调

ty_obj_cmd_s

typedef struct {
    uint8_t      cmd_tp;
    uint8_t      dtt_tp;
    char        *cid;
    char        *mb_id;
    uint32_t     dps_cnt;
    ty_dp_s      dps[0];
} ty_obj_cmd_s;

功能说明

控制设备（json）的命令格式。

成员说明

成员名称	说明
cmd_tp	指令类型。 0：LAN 触发 1：MQTT 触发 2：本地定时触发 3：场景联动触发 4：重发
dtt_tp	传输方式。 0：单播 1：广播 2：组播 3：场景
cid	cid == NULL，表示网关功能点 cid != NULL，表示子设备功能点，cid 为子设备的 MAC 地址
mb_id	群组 ID，只有当 dtt_tp = 2 时，该字段才有效
dps_cnt	下发的功能点数量，即 dps 的长度
dps	参见 ty_dp_s 结构体说明

ty_dp_s

typedef struct {
	uint8_t dpid;
	uint8_t type;
	union {
		int       dp_value;
		uint32_t  dp_enum;
		char     *dp_str;
		int       dp_bool;
		uint32_t  dp_bitmap;
	} value;
	uint32_t time_stamp;
} ty_dp_s;

功能说明

dp 功能点的信息。

成员说明

成员名称	说明
dpid	对应在涂鸦开发者平台上创建产品时定义的功能点编号
type	功能点的数据类型，支持的数据类型请参见自定义功能的功能点定义
value	功能点的值，数据类型对应 type
time_stamp	时间戳

ty_raw_cmd_s

typedef struct {
	uint8_t   cmd_tp;
	uint8_t   dtt_tp;
	char     *cid;
	uint8_t   dpid;
	char     *mb_id;
	uint32_t  len;
	uint8_t   data[0];
} ty_raw_cmd_s;

功能说明

控制设备（raw）的命令格式。

成员说明

成员名称	说明
cmd_tp	指令类型。 0：LAN 触发 1：MQTT 触发 2：本地定时触发 3：场景联动触发 4：重发
dtt_tp	传输方式。 0：单播 1：广播 2：组播 3：场景
cid	cid == NULL，表示网关功能点 cid != NULL，表示子设备功能点，cid 为子设备的 MAC 地址
dpid	对应在涂鸦开发者平台上创建产品时定义的功能点编号
mb_id	群组 ID，只有当 dtt_tp = 2 时，该字段才有效
len	透传的数据长度
data	透传的数据

一键配网

一键配网是网关通过按键的方式，给 Wi-Fi 类型的智能设备配网，网关要支持无线功能才能使用一键配网功能。这一章节对一键配网相关接口进行说明。

API 说明

tuya_user_iot_smconfig_init()

int tuya_user_iot_smconfig_init(const char *ifname, int (*cb)(char *ssid, \
                                                              uint32_t ssid_size, \
                                                              char *passwd, \
                                                              uint32_t passwd_size));

功能说明

一键配网初始化接口，申请相关资源。您需要指定 2.4G 无线接口以及实现获取 SSID 和密码的回调。

参数说明

参数名称	说明
ifname	2.4G 无线接口
cb	获取 SSID 和密码的回调

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_smconfig_start()

int tuya_user_iot_smconfig_start(uint32_t timeout);

功能说明

开启一键配网，调用该接口发送无线空中包。

参数说明

参数名称	说明
timeout	超时时间，单位是秒。超时后自动关闭一键配网

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_smconfig_stop()

int tuya_user_iot_smconfig_stop(void);

功能说明

关闭一键配网初始化接口，调用该接口停止发送无线空中包。

参数说明

无

返回值

返回值	说明
0	成功
非0	失败

设备接入

涂鸦网关扩展 SDK 帮助您将子设备接入涂鸦开发者平台。通过本章节的介绍，您能了解接入子设备接入的流程以及接口使用。

回调注册

功能说明

接入子设备需要您实现，涂鸦网关扩展 SDK 采用回调函数的方式，使用此接口注册回调函数。

开发流程

• 实现相关的回调函数，并将它们填充到回调结构体 ty_misc_dev_cbs_s。

• 在 SDK 初始化之前，调用 tuya_user_iot_reg_misc_dev_cb 接口，把 ty_misc_dev_cbs_s 结构体作为输入参数。

添加设备

功能说明

当在涂鸦 APP 添加子设备时，会触发添加设备回调。您要完成添加设备的业务逻辑。

开发流程

• 实现 misc_dev_add_cb 回调函数，在函数中根据 permit 参数允许或禁止子设备入网。

• 实现 misc_dev_bind_ifm_cb 回调函数，在函数中根据 result 参数获取设备绑定结果，处理其特定业务。

• 您需要实现子设备入网的业务，子设备加入网关后，调用 tuya_user_iot_misc_dev_bind 接口将子设备绑定到涂鸦开发者平台。

• 在调用注册回调接口 tuya_user_iot_reg_misc_dev_cb 之前，把 misc_dev_add_cb 和 misc_dev_bind_ifm_cb 赋值给回调结构体 ty_misc_dev_cbs_s 的对应成员变量。

  

心跳保活

功能说明

涂鸦平台子设备的在线和离线状态是通过心跳机制来实现的，网关收到子设备任何数据都需要刷新心跳时间。在设置的心跳超时时间内，没收到子设备任何数据，网关会主动下发心跳数据。

开发流程

• 子设备定时向网关发送心跳包，或者网关定时向子设备发送心跳查询包。

• 实现 misc_dev_heartbeat_cb 回调函数，在函数中读取子设备数据，一般是读取版本号。

• 网关接收到子设备的上报数据，调用 tuya_user_iot_misc_dev_fresh_hb 接口刷新子设备的在线状态。

  

删除设备

功能说明

当在涂鸦 APP 删除子设备时，会触发设备删除回调。您要在回调中实现删除设备的功能。

开发流程

• 实现 misc_dev_del_cb 回调函数，在函数中实现移除子设备的功能。
• 在调用注册回调接口之前，把 misc_dev_del_cb 赋值给 ty_misc_dev_cbs_s 结构体的 misc_dev_del_cb 成员变量。

设备重置

功能说明

当在涂鸦 APP 重置子设备时，会触发设备复位回调。您要在回调中实现将设备恢复出厂设置的功能 。

开发流程

• 实现 misc_dev_reset_cb 回调函数，在函数中实现将子设备恢复出厂设置。
• 在调用注册回调接口之前，把 misc_dev_reset_cb 赋值给 ty_misc_dev_cbs_s 结构体的 misc_dev_reset_cb 成员变量。

命令下发

功能说明

当在涂鸦 APP 控制子设备时，会触发设备指令下发回调。您需要实现协议转换功能。

开发流程

• 实现 dev_obj_cmd_cb 回调函数，在函数中实现将涂鸦功能点转换成用户子设备的通讯协议，并且将指令下发给子设备。

• 子设备执行指令后，要将其新状态上报给网关，网关接收到子设备的上报数据，您需要将其转换成涂鸦功能点格式，调用 tuya_user_iot_report_obj_dp 把状态同步到涂鸦开发者平台。

  

状态上报

功能说明

当子设备的功能值发生变化时，子设备要将新的功能值上报到网关，您需要将子设备的通讯协议转成涂鸦功能点同步到涂鸦开发者平台。

开发流程

子设备执行指令后，要将其新状态上报给网关，网关接收到子设备的上报数据，您需要将其转换成涂鸦功能点格式，调用 tuya_user_iot_report_obj_dp 把状态同步到涂鸦开发者平台。

设备升级

功能说明

OTA 作为设备升级与维护的最重要途径之一，当有固件需要升级时，通过涂鸦 APP 升级设备，涂鸦网关扩展 SDK 会下载设备固件，校验成功后通知您进行 OTA 升级。

开发流程

• 实现 misc_dev_upgrade_cb 回调函数，在函数中根据 img 参数获取固件文件，以及 dev_id 参数找到要升级的设备，完成设备升级功能。
• 在调用注册回调接口之前，把 misc_dev_upgrade_cb 赋值给 ty_misc_dev_cbs_s 结构体的 misc_dev_upgrade_cb 成员变量。

群组控制

功能说明

群组用于把多个同类型的设备加入一个组，控制时通过发送组播命令实现多控。

开发流程

• 实现 misc_dev_group_cb 回调函数，在函数中实现组的创建、删除操作。
• 在调用注册回调接口之前，把 misc_dev_group_cb 赋值给 ty_misc_dev_cbs_s 结构体的 misc_dev_group_cb 成员变量。

场景控制

功能说明

有些无线协议，如 Zigbee，支持标准场景联动，用于设备间联动，可以脱离网关工作。

开发流程

• 实现 misc_dev_scene_cb 回调函数，在函数中实现场景的创建、删除和执行操作。
• 在调用注册回调接口之前，把 misc_dev_scene_cb 赋值给 ty_misc_dev_cbs_s 结构体的 misc_dev_scene_cb 成员变量。

API 说明

tuya_user_iot_reg_misc_dev_cb()

int tuya_user_iot_reg_misc_dev_cb(ty_misc_dev_cbs_s *cbs);

功能说明

注册接入其他子设备相关回调的接口。

参数说明

参数名称	说明
cbs	参考 ty_misc_dev_cbs_s 结构体说明

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_misc_dev_bind()

int tuya_user_iot_misc_dev_bind(ty_dev_tp_t tp,
                                uint32_t uddd,
                                const char *dev_id,
                                const char *pid,
                                const char *ver);

功能说明

绑定子设备到涂鸦开发者平台的接口。

参数说明

参数名称	说明
tp	协议类型
uddd	用户自定义，可用于区分不同类型的设备
dev_id	子设备的 MAC 地址
pid	在涂鸦开发者平台上创建子设备产品得到的 PID
ver	子设备的软件版本，用于固件升级

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_misc_dev_unbind()

int tuya_user_iot_misc_dev_unbind(const char *dev_id);

功能说明

将子设备从涂鸦开发者平台上解绑的接口。

参数说明

参数名称	说明
dev_id	子设备的 MAC 地址

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_misc_dev_hb_cfg()

int tuya_user_iot_misc_dev_hb_cfg(const char *dev_id,
                                  uint32_t timeout,
                                  uint32_t max_retry,
                                  int lowpower);

功能说明

子设备心跳配置的接口。

参数说明

参数名称	说明
dev_id	子设备的 MAC 地址
timeout	在线的超时时间，单位是秒
max_retry	心跳包最大发送次数
lowpower	是否为休眠设备

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_misc_dev_fresh_hb()

int tuya_user_iot_misc_dev_fresh_hb(const char *dev_id);

功能说明

刷新子设备在线状态的接口。

参数说明

参数名称	说明
dev_id	子设备的 MAC 地址

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_misc_dev_ver_update()

int tuya_user_iot_misc_dev_ver_update(const char *dev_id, const char *version);

功能说明

更新子设备版本号接口，用于升级后版本号更新。

参数说明

参数名称	说明
dev_id	子设备的 MAC 地址
version	版本号

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_misc_dev_desc_get()

DEV_DESC_IF_S *tuya_user_iot_misc_dev_desc_get(const char *dev_id);

功能说明

获取子设备的基本信息接口。

参数说明

参数名称	说明
dev_id	子设备的 MAC 地址

返回值

返回值	说明
DEV_DESC_IF_S *	成功
NULL	失败

tuya_user_iot_misc_dev_traversal()

DEV_DESC_IF_S *tuya_user_iot_misc_dev_traversal(void **iter);

功能说明

遍历所有子设备接口。

参数说明

参数名称	说明
iter	迭代器

返回值

返回值	说明
DEV_DESC_IF_S *	成功
NULL	失败

void *iter            = NULL;
DEV_DESC_IF_S *dev_if = NULL;

dev_if = tuya_user_iot_misc_dev_traversal(&iter);
while (dev_if) {
    // USER TODO
    dev_if = tuya_user_iot_misc_dev_traversal(&iter);
}

misc_dev_add_cb()

int (*misc_dev_add_cb)(bool permit, uint32_t timeout);

功能说明

添加设备的回调函数。

参数说明

参数名称	说明
permit	允许 or 禁止子设备入网
timeout	允许配网的时间，单位为秒

返回值

返回值	说明
0	成功
非0	失败

misc_dev_del_cb()

int (*misc_dev_del_cb)(const char *dev_id);

功能说明

删除设备的回调函数。

参数说明

参数名称	说明
dev_id	子设备的 MAC 地址

返回值

返回值	说明
0	成功
非0	失败

misc_dev_bind_ifm_cb()

int (*misc_dev_bind_ifm_cb)(const char *dev_id,
                            int result);

功能说明

子设备绑定涂鸦开发者平台结果通知的回调函数。

参数说明

参数名称	说明
dev_id	子设备的 MAC 地址
result	绑定结果。 0：绑定成功 1：绑定失败

返回值

返回值	说明
0	成功
非0	失败

misc_dev_reset_cb()

int (*misc_dev_reset_cb)(const char *dev_id);

功能说明

重置设备的回调函数。

参数说明

参数名称	说明
dev_id	子设备的 MAC 地址

返回值

返回值	说明
0	成功
非0	失败

misc_dev_upgrade_cb()

int (*misc_dev_upgrade_cb)(const char *dev_id, const char *img);

功能说明

通知子设备升级的回调函数。

参数说明

参数名称	说明
dev_id	子设备的 MAC 地址
img	固件文件所在的路径

返回值

返回值	说明
0	成功
非0	失败

misc_dev_heartbeat_cb()

int (*misc_dev_heartbeat_cb)(const char *dev_id);

功能说明

设备心跳发送回调函数。

参数说明

参数名称	说明
dev_id	子设备的 MAC 地址

返回值

返回值	说明
0	成功
非0	失败

misc_dev_group_cb()

void (*misc_dev_group_cb)(ty_group_action_t action,
                          const char *dev_id,
                          const char *grp_id);

功能说明

子设备群组操作回调函数。

参数说明

参数名称	说明
action	添加、删除操作
dev_id	子设备的 MAC 地址
grp_id	组ID

返回值

返回值	说明
0	成功
非0	失败

misc_dev_scene_cb()

void (*misc_dev_scene_cb)(ty_group_action_t action,
                          const char *dev_id,
                          const char *grp_id,
                          const char *sce_id);

功能说明

子设备场景操作回调函数。

参数说明

参数名称	说明
action	添加、删除、执行操作
dev_id	子设备的 MAC 地址
grp_id	群组ID
sce_id	场景ID

返回值

返回值	说明
0	成功
非0	失败

ty_misc_dev_cbs_s

typedef struct {
    void (*misc_dev_add_cb)(bool permit, uint32_t timeout);
    void (*misc_dev_del_cb)(const char *dev_id);
    void (*misc_dev_bind_ifm_cb)(const char *dev_id, int result);
    void (*misc_dev_upgrade_cb)(const char *dev_id, const char *img);
    void (*misc_dev_reset_cb)(const char *dev_id);
    void (*misc_dev_heartbeat_cb)(const char *dev_id);
    void (*misc_dev_group_cb)(ty_group_action_t action, const char *dev_id, const char *grp_id);
    void (*misc_dev_scene_cb)(ty_scene_action_t action, const char *dev_id, const char *grp_id, const char *sce_id);
} ty_misc_dev_cbs_s;

功能说明

子设备管理相关的回调。

成员说明

成员名称	说明
misc_dev_add_cb	添加设备回调
misc_dev_del_cb	删除设备回调
misc_dev_bind_ifm_cb	绑定结果通知回调
misc_dev_upgrade_cb	升级通知回调
misc_dev_reset_cb	重置设备回调
misc_dev_heartbeat_cb	设备心跳发送回调
misc_dev_group_cb	设备群组操作回调
misc_dev_scene_cb	设备场景操作回调

Zigbee设备接入

涂鸦网关扩展 SDK 赋予第三方系统具备接入非涂鸦生态的 Zigbee 设备的能力，把非涂鸦生态的 Zigbee 子设备接入到涂鸦开发者平台。

通过本章节的介绍，您能了解接入第三方 Zigbee 子设备的流程以及接口使用。

设备管理

功能说明

接入 Zigbee 协议子设备需要您来实现，涂鸦网关扩展 SDK 采用白名单机制，您可以通过注册白名单设备列表，告知 SDK 白名单设备列表由第三方处理，SDK 会把 Zigbee 透传给应用。当白名单为空时，表示所有设备都由第三方处理。

该接口用于注册白名单列表和设备管理回调。

开发流程

• 实现相关的回调函数，并将它们填充到回调结构体 TY_Z3_DEV_CBS_S。
• 将白名单设备列表填充到结构体 TY_Z3_DEVLIST_S。
• 在 SDK 初始化之前，调用 tuya_user_iot_zig_mgr_register 接口，把 TY_Z3_DEVLIST_S 和 TY_Z3_DEV_CBS_S 结构体作为输入参数。

设备入网

功能说明

符合 Zigbee3.0 标准协议的子设备加入到网关的 Zigbee 网络后，设备在白名单列表中会触发设备入网回调，您需要在回调中实现设备入网的功能。

开发流程

• 实现 join 回调函数，在函数中解析子设备的基本信息，调用 tuya_user_iot_misc_dev_bind 接口将子设备绑定到涂鸦开发者平台。

• 实现 report 回调函数，在函数中解析读取子设备的属性响应信息（Read Attributes Response），将 ZCL 数据帧转换成涂鸦功能点调用 tuya_user_iot_report_obj_dp 接口把设备当前状态同步到涂鸦开发者平台，并且调用 tuya_user_iot_misc_dev_hb_fresh 接口刷新在线状态。

• 将 join 和 report 赋值给回调结构体 TY_Z3_DEV_CBS_S 对应的成员变量，调用 tuya_user_iot_zig_mgr_register 接口进行注册。

• 实现 misc_dev_bind_ifm_cb 回调函数，在函数中读取设备当前属性值，并且调用 tuya_user_iot_misc_dev_hb_cfg 接口设置心跳配置。

• 将 misc_dev_bind_ifm_cb 赋值给回调结构体 ty_misc_dev_cbs_s 的对应成员变量。

  

设备离网

功能说明

符合 Zigbee3.0 标准协议的子设备离开网关的 Zigbee 网络后，设备在白名单列表中会触发设备离网回调，您可以在回调中实现其特定业务处理。

开发流程

• 实现 leave 回调函数，在函数中调用 tuya_user_iot_misc_dev_unbind 从涂鸦开发者平台解绑。

• 在调用回调注册接口之前，将此回调赋值给回调结构体 TY_Z3_DEV_CBS_S 的 leave 成员变量。

状态上报

功能说明

当子设备上报数据时，设备在白名单列表中会触发状态上报回调，您需要在回调中实现 ZCL 数据帧的解析功能。

开发流程

• 实现 report 回调函数，在函数中解析 ZCL 数据帧，将其转换成涂鸦功能点格式，调用 tuya_user_iot_report_obj_dp 接口同步到涂鸦开发者平台，并且调用 tuya_user_iot_misc_dev_hb_fresh 接口刷新在线状态。
• 在调用回调注册接口之前，将该回调赋值给回调结构体 TY_Z3_DEV_CBS_S 的 report 成员变量。

命令下发

功能说明

当在涂鸦 APP 控制子设备时，会触发设备指令下发回调。您需要在回调中实现将涂鸦功能点转成 ZCL 数据帧功能。

开发流程

• 实现 dev_obj_cmd_cb 回调函数，在函数中实现将涂鸦功能点转换成 ZCL 数据帧，并且调用 tuya_user_iot_zig_send 接口将指令下发给子设备。
• 实现 report 回调函数，在函数中解析 ZCL 数据帧，将其转换成涂鸦功能点格式，调用 tuya_user_iot_report_obj_dp 接口同步到涂鸦开发者平台，并且调用 tuya_user_iot_misc_dev_hb_fresh 接口刷新在线状态。

状态同步

功能说明

Zigbee 模组启动成功后，会触发通知回调，您需要在回调中实现读取所有接入的子设备属性值功能。

开发流程

• 实现 notify 回调函数，在函数中分别读取所有已入网的子设备属性值。
• 实现 report 回调函数，在函数中解析读取子设备的属性响应信息（Read Attributes Response），将其转换成涂鸦功能点格式，调用 tuya_user_iot_report_obj_dp 接口同步到涂鸦开发者平台，并且调用 tuya_user_iot_misc_dev_hb_fresh 接口刷新在线状态。
• 在调用注册回调接口之前，将 notify 赋值给回调结构体 TY_Z3_DEV_CBS_S 的 notify 成员变量。

设备升级

功能说明

当有固件需要升级时，通过涂鸦 APP 升级设备，涂鸦网关扩展 SDK 会下载设备固件，校验成功后通知您进行 OTA 升级。

开发流程

• 实现 misc_dev_upgrade_cb 回调函数，在函数中根据 img 参数获取固件文件，以及 dev_id 参数找到要升级的设备，调用 tuya_user_iot_zig_upgrade 接口升级 Zigbee 子设备。
• 在调用注册回调接口之前，把 misc_dev_upgrade_cb 赋值给 ty_misc_dev_cbs_s 结构体的 misc_dev_upgrade_cb 成员变量。

设备移除

功能说明

当在涂鸦 APP 删除子设备时，会触发设备删除回调。您需要在回调中实现删除设备的功能。

开发流程

• 实现 misc_dev_del_cb 回调函数，在函数中调用 tuya_user_iot_zig_del 移除子设备。
• 在调用注册回调接口之前，把 misc_dev_del_cb 赋值给 ty_misc_dev_cbs_s 结构体的 misc_dev_del_cb 成员变量。

API 说明

tuya_user_iot_zig_mgr_register()

OPERATE_RET tuya_user_iot_zig_mgr_register(TY_Z3_DEVLIST_S *devlist,
                                           TY_Z3_DEV_CBS_S *cbs);

功能说明

Zigbee 子设备管理注册接口。

参数说明

参数名称	说明
devlist	白名单设备列表
cbs	参考 TY_Z3_DEV_CBS_S 结构体说明

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_zig_send()

OPERATE_RET tuya_user_iot_zig_send(TY_Z3_APS_FRAME_S *frame);

功能说明

下发 ZCL 数据帧给 Zigbee 子设备。

参数说明

参数名称	说明
frame	参考 ty_z3_aps_frame_s 结构体说明

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_zig_del()

OPERATE_RET tuya_user_iot_zig_del(CONST CHAR_T *dev_id);

功能说明

本地移除 Zigbee 子设备的接口。

参数说明

参数名称	说明
id	子设备的 MAC 地址

返回值

返回值	说明
0	成功
非0	失败

tuya_user_iot_zig_upgrade()

OPERATE_RET tuya_user_iot_zig_upgrade(CONST CHAR_T *dev_id, CONST CHAR_T *img);

功能说明

本地升级 Zigbee 子设备的接口。

参数说明

参数名称	说明
id	子设备的 MAC 地址
img	Zigbee 子设备固件文件所在的路径

返回值

返回值	说明
0	成功
非0	失败

join()

VOID (*join)(TY_Z3_DESC_S *dev);

功能说明

用户处理的 Zigbee 子设备入网的回调。

参数说明

参数名称	说明
desc	参考 ty_z3_desc_s 结构体说明

返回值

返回值	说明
0	成功
非0	失败

leave()

VOID (*join)(TY_Z3_DESC_S *dev);

功能说明

用户处理的 Zigbee 子设备离网的回调。

参数说明

参数名称	说明
id	子设备的 MAC 地址

返回值

返回值	说明
0	成功
非0	失败

report()

VOID (*report)(TY_Z3_APS_FRAME_S *frame);

功能说明

用户处理的 Zigbee 子设备状态上报的回调。

参数说明

参数名称	说明
frame	参考 ty_z3_aps_frame_s 结构体说明

返回值

返回值	说明
0	成功
非0	失败

notify()

int (*notify)(void);

功能说明

Zigbee 模组启动通知回调。

参数说明

无

返回值

返回值	说明
0	成功
非0	失败

TY_Z3_DEV_CBS_S

typedef struct {
    VOID (*join)(TY_Z3_DESC_S *dev);
    VOID (*leave)(CONST CHAR_T *dev_id);
    VOID (*report)(TY_Z3_APS_FRAME_S *frame);
    VOID (*notify)(VOID);
    VOID (*upgrade_end)(CONST CHAR_T *dev_id, INT_T rc, UCHAR_T version);
} TY_Z3_DEV_CBS_S;

功能说明

Zigbee 子设备管理回调。

成员说明

成员名称	说明
notify	Zigbee 模组启动完成通知回调
join	用户处理的 Zigbee 子设备入网回调
leave	用户处理的 Zigbee 子设备离网回调
report	用户处理的 Zigbee 子设备状态上报回调
upgrade_end	用户处理的 Zigbee 子设备升级结果通知回调

TY_Z3_DESC_S

typedef struct {
    CHAR_T     id[Z3_DEV_ID_LEN+1];
    UINT16_T   profile_id[MAX_EP_NUM];
    UINT16_T   device_id[MAX_EP_NUM];
    UINT16_T   cluster_id[MAX_EP_NUM][MAX_CLUSTER_NUM];
    UINT16_T   endpoint[MAX_EP_NUM];
    UCHAR_T    ep_num; // endpoints count
    UCHAR_T    uc_num; // clusters count
    UINT16_T   node_id;
    CHAR_T     manu_name[MANU_NAME_LEN+1];
    CHAR_T     model_id[MODEL_ID_LEN+1];
    CHAR_T     rejoin_flag;
    CHAR_T     power_source;
    UCHAR_T    version;
} TY_Z3_DESC_S;

功能说明

Zigbee 子设备的基本信息。

成员说明

成员名称	说明
id	子设备的 MAC 地址
profile_id	Zigbee Profile ID
device_id	Zigbee Device ID
cluster_id	Zigbee Cluster ID
endpoint	Zigbee Endpoint
ep_num	Endpoint 数量
uc_num	Cluster 数量
node_id	子设备的短地址
manu_name	厂商名称
model_id	设备型号
rejoin_flag	重新入网标记
power_source	供电方式，标识强电/弱点设备
version	Application Version

TY_Z3_APS_FRAME_S

typedef struct {
    CHAR_T     id[Z3_DEV_ID_LEN+1];
    UINT16_T   node_id;
    UINT16_T   profile_id;
    UINT16_T   cluster_id;
    UCHAR_T    src_endpoint;
    UCHAR_T    dst_endpoint;
    UINT16_T   group_id;
    UCHAR_T    cmd_type;          // zcl command type. 0x00: global command, 0x01: command is specific to a cluster.
    UCHAR_T    cmd_id;            // zcl command id
    UCHAR_T    frame_type;        // 0: Unicast, 1: Multicast, 2: Broadcast
    UINT16_T   manufacturer_code;
    CHAR_T     disable_ack;
    UINT16_T   msg_length;
    UCHAR_T   *message;
} TY_Z3_APS_FRAME_S;

功能说明

涂鸦封装的 Zigbee ZCL 数据帧。

成员说明

成员名称	说明
id	子设备的 MAC 地址
node_id	子设备的短地址
profile_id	Zigbee Profile ID
cluster_id	Zigbee Cluster ID
src_endpoint	源 endpoint
dst_endpoint	目的 endpoint
group_id	组 ID，组播才需要
cmd_type	ZCL 命令类型。 0 表示 global。 1 表示特定 cluster
cmd_id	ZCL Command ID
frame_type	传输类型。 0 表示单播。 1 表示组播。 2 表示广播
disable_ack	禁止响应。 1 表示禁止响应。 0 表示使能响应
msg_length	ZCL payload 的长度
message	ZCL payload

安防功能

回调注册

功能说明

硬件相关控制需要您实现，如布防撤防、报警声音控制或指示灯控制，涂鸦网关扩展 SDK 采用回调函数的方式，使用此接口注册回调函数。

开发流程

• 实现相关的回调函数，并将它们填充到回调结构体 ty_home_security_cbs_s。

• 在 SDK 初始化之前，调用 tuya_user_iot_reg_home_security_cb 接口，把 ty_home_security_cbs_s 结构体作为输入参数。

API 说明

tuya_user_iot_reg_home_security_cb()

int tuya_user_iot_reg_home_security_cb(ty_home_security_cbs_s *cbs);

功能说明

注册安防硬件相关控制回调的接口。

参数说明

参数名称	说明
frame	参考 ty_z3_aps_frame_s 结构体说明

返回值

返回值	说明
0	成功
非0	失败

home_security_alarm_cb()

void (*home_security_alarm_cb)(void);

功能说明

报警回调，您需要在此函数控制声音或者指示灯。

参数说明

无

返回值

无

home_security_alarm_cancel_cb()

void (*home_security_alarm_cancel_cb)(void);

功能说明

取消报警回调，您需要在此函数控制声音或者指示灯。

参数说明

无

返回值

无

home_security_disarmed_cb()

void (*home_security_disarmed_cb)(void);

功能说明

进入撤防状态的回调，您需要在此函数控制声音或者指示灯。

参数说明

无

返回值

无

home_security_away_armed_cb()

void (*home_security_away_armed_cb)(void);

功能说明

进入离家布防状态的回调，您需要在此函数控制声音或者指示灯。

参数说明

无

返回值

无

home_security_stay_armed_cb()

void (*home_security_stay_armed_cb)(void);

功能说明

进入在家布防状态的回调，您需要在此函数控制声音或者指示灯。

参数说明

无

返回值

无

home_security_arm_ignore_cb()

void (*home_security_arm_ignore_cb)(void);

功能说明

忽略布防的回调，您需要在此函数控制声音或者指示灯。

参数说明

无

返回值

无

home_security_arm_countdown_cb()

void (*home_security_arm_countdown_cb)(uint32_t time);

功能说明

延时布防的回调，您需要在此函数控制声音或者指示灯。

参数说明

参数名称	说明
time	倒计时持续的时间

返回值

无

home_security_alarm_countdown_cb()

void (*home_security_alarm_countdown_cb)(uint32_t time);

功能说明

延时报警的回调，您需要在此函数控制声音或者指示灯。

参数说明

参数名称	说明
time	倒计时持续的时间

返回值

无

home_security_door_opened_cb()

void (*home_security_door_opened_cb)(uint32_t time);

功能说明

门磁打开的回调，您需要在此函数控制声音或者指示灯。

参数说明

无

返回值

无

home_security_alarm_dev_cb()

void (*home_security_alarm_dev_cb)(char *dev);

功能说明

设备报警的回调，您需要在此函数获取哪个设备报警。

参数说明

参数名称	说明
dev	设备名称

返回值

无

ty_home_security_cbs_s

typedef struct {
    void (*home_security_alarm_cb)(void);
    void (*home_security_alarm_cancel_cb)(void);
    void (*home_security_disarmed_cb)(void);
    void (*home_security_away_armed_cb)(void);
    void (*home_security_stay_armed_cb)(void);
    void (*home_security_arm_ignore_cb)(void);
    void (*home_security_arm_countdown_cb)(uint32_t time);
    void (*home_security_alarm_countdown_cb)(uint32_t time);
    void (*home_security_door_opened_cb)(void);
    void (*home_security_alarm_dev_cb)(char *dev);
} ty_home_security_cbs_s;

功能说明

安防硬件相关控制的回调。

成员说明

成员名称	说明
home_security_alarm_cb	报警的回调
home_security_alarm_cancel_cb	取消报警的回调
home_security_disarmed_cb	进入撤防状态的回调
home_security_away_armed_cb	进入离家布防状态的回调
home_security_stay_armed_cb	进入在家布防状态的回调
home_security_arm_ignore_cb	忽略布防的回调
home_security_arm_countdown_cb	延迟布防的回调
home_security_alarm_countdown_cb	延迟报警的回调
home_security_door_opened_cb	门磁打卡的回调
home_security_alarm_dev_cb	设备报警的回调

配网功能

涂鸦网关扩展 SDK 搭建了一套完整的用以引导设备配网的框架，您只需要实现对应的函数即可。此章节主要阐述配网的流程以及各函数的用途，建议您按照文档介绍，实现 hal_wired.c 或 hal_wifi.c 文件的接口。

举例，假设 wifi_mode 指定为 TY_CONN_MODE_AP_FIRST，首次使用网关会工作在 AP 模式，只有当网关在未激活状态被解绑或重置时，重启后自动切换到 EZ 模式。再进行解绑或重置时，重启后自动切换回 AP 模式，这样交替工作。

建议您通过指示灯来标识当前的工作模式，AP 模式可以在 hal_wifi_ap_start 接口控制指示灯，EZ 模式可以在 hal_wifi_set_sniffer 接口控制指示灯。

有线配网

功能说明

有线配网有 SDK 内部实现，您仅需要实现相关的 HAL 接口。

开发流程

• 实现 hal_wired_get_ip 接口，在函数中实现获取有线网口的 IP 地址。
• 实现 hal_wired_get_status 接口，在函数中实现获取有线网口已插网线或未插网关状态。

Wi-Fi 快速配网

功能说明

Wi-Fi 快速配网是涂鸦 APP 直接通过无线发送包含 Wi-Fi 用户名和 Wi-Fi 密码的广播包，网关的无线接口处于监听模式，抓取无线广播包并解密出 Wi-Fi 用户名和密码，然后发起连接。

开发流程

• 在网关初始化之前，设置 ty_gw_attr_s 的 wifi_mode 成员变量的值为 TY_CONN_MODE_EZ。

• 实现 hal_wifi_get_work_mode 接口，在函数中根据实际情况获取网关的 Wi-Fi 的工作模式。

• 实现 hal_wifi_set_cur_channel 接口，在函数中根据 channel 参数设置 Wi-Fi 的工作信道。

• 实现 hal_wifi_scan_all_ap 接口，在函数中把扫描到的 Wi-Fi 信息填充到 ap_scan_info_s 结构体。

• 实现 hal_wifi_set_sniffer 接口，在函数中根据实际情况，实现接收空口包功能，并通过 cb 参数把接收到的数据回传给 SDK。

• 实现 hal_wifi_set_work_mode 接口，在函数中根据参数 mode 设置 Wi-Fi 的工作模式。

• 实现 hal_wifi_get_cur_channel 接口，在函数中根据实际情况获取网关的 Wi-Fi 的当前信道。

• 实现 hal_wifi_connect_station 接口，在函数中根据参数 ssid 和 passwd 实现联网操作。

• 实现 hal_wifi_get_station_conn_stat 接口，在函数中获取 Station 工作模式的状态，并将结果赋值到 stat 参数。

  

AP 配网功能

功能说明

网关开启 AP，涂鸦 APP 连接到网关的 AP，通过 UDP 广播包含将要配置的 Wi-Fi 用户名和 Wi-Fi 密码，网关收到 UDP 广播包并解析出 Wi-Fi 用户名和密码，然后发起连接。

开发流程

• 在网关初始化之前，设置 ty_gw_attr_s 的 wifi_mode 成员变量的值为 TY_CONN_MODE_AP，同时，也可以通过 ssid 和 password 成员变量指定 AP 的 SSID 和密码。

• 实现 hal_wifi_get_work_mode 接口，在函数中根据实际情况获取网关的 Wi-Fi 的工作模式。

• 实现 hal_wifi_ap_start 接口，在函数中根据 ap_cfg_info_s 结构体参数的信息，打开 AP 模式。

• 实现 hal_wifi_set_work_mode 接口，在函数中根据参数 mode 设置 Wi-Fi 的工作模式。

• 实现 hal_wifi_connect_station 接口，在函数中根据参数 ssid 和 passwd 实现联网操作。

• 实现 hal_wifi_get_station_conn_stat 接口，在函数中获取 Station 工作模式的状态，并将结果赋值到 stat 参数。

• 实现 hal_wifi_ap_stop 接口，在函数中关闭网关的 AP。

  

API 说明

hal_wifi_scan_all_ap()

int hal_wifi_scan_all_ap(ap_scan_info_s **aps,
                         uint32_t *num)

功能说明

扫描当前环境所有的 AP。

参数说明

参数名称	说明
aps	参见 ap_scan_info_s 结构体说明
num	当前环境 AP 信息列表长度

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_scan_assigned_ap()

int hal_wifi_scan_assigned_ap(char *ssid,
                              ap_scan_info_s **aps)

功能说明

扫描当前环境特定的 AP。

参数说明

参数名称	说明
ssid	指定 AP 的 SSID
aps	参见 ap_scan_info_s 结构体说明

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_release_ap()

int hal_wifi_release_ap(ap_scan_info_s *ap)

功能说明

若扫描接口把扫描到的 AP 信息存放在堆栈空间，则在此接口释放。

参数说明

参数名称	说明
ap	参见 ap_scan_info_s 结构体说明

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_set_cur_channel()

int hal_wifi_set_cur_channel(uint8_t channel)

功能说明

设置 Wi-Fi 的工作信道。

参数说明

参数名称	说明
channel	信道值

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_get_cur_channel()

int hal_wifi_get_cur_channel(uint8_t *channel)

功能说明

获取 Wi-Fi 当前的工作信道。

参数说明

参数名称	说明
channel	信道值

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_set_sniffer()

int hal_wifi_set_sniffer(int enable,
                         sniffer_callback cb)

功能说明

设计混杂模式。

参数说明

参数名称	说明
enable	使能/关闭 sniffer 模式
cb	调用该回调将抓取到的 802.11 数据帧发送给 SDK

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_get_ip()

int hal_wifi_get_ip(wifi_type_t type,
                    ip_info_s *ip)

功能说明

获取 Wi-Fi 接口的 IP 信息。

参数说明

参数名称	说明
type	Wi-Fi 工作模式。 0：表示 STATION 模式 1：表示 AP 模式
ip	参见 ip_info_s 结构体说明

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_get_mac()

int hal_wifi_get_mac(wifi_type_t type,
                     mac_info_t *mac)

功能说明

获取 Wi-Fi 接口的 MAC 信息。

参数说明

参数名称	说明
type	Wi-Fi 工作模式。 0：表示 STATION 模式 1：表示 AP 模式
mac	参见 mac_info_s 结构体说明

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_set_work_mode()

int hal_wifi_set_work_mode(wifi_work_mode_t mode)

功能说明

设置 Wi-Fi 工作模式。

参数说明

参数名称	说明
mode	工作模式。 0：低功耗模式 1：混杂模式 2：STATION 模式 3：AP 模式 4：STATION + AP 模式

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_get_work_mode()

int hal_wifi_get_work_mode(wifi_work_mode_t *mode)

功能说明

获取 Wi-Fi 工作模式。

参数说明

参数名称	说明
mode	工作模式。 0：低功耗模式 1：混杂模式 2：STATION 模式 3：AP 模式 4：STATION + AP 模式

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_connect_station()

int hal_wifi_connect_station(char *ssid,
                             char *passwd)

功能说明

连接到上级 AP。

参数说明

参数名称	说明
ssid	上级 AP 的 SSID
passwd	上级 AP 的 密码

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_disconnect_station()

int hal_wifi_disconnect_station(void)

功能说明

断开与上级 AP 的连接。

参数说明

无

返回值

参数名称	说明
0	成功
非0	失败

hal_wifi_get_station_rssi()

int hal_wifi_get_station_rssi(char *rssi)

功能说明

获取 Station 模式与上级 AP 连接的信号强度。

参数说明

参数名称	说明
rssi	信号强度值

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_get_station_conn_stat()

int hal_wifi_get_station_conn_stat(station_conn_stat_t *stat)

功能说明

获取 Station 模式与上级 AP 的连接状态。

参数说明

参数名称	说明
stat	连接状态值。 STAT_IDLE: 无连接 STAT_CONNECTING: 正在连接 STAT_PASSWD_WRONG: 密码错误 STAT_NO_AP_FOUND: 没找到 AP STAT_CONN_FAIL: 连接失败 STAT_CONN_SUCCESS: 连接成功 STAT_GOT_IP: 连接成功并分配到了 IP 地址

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_ap_start()

int hal_wifi_ap_start(ap_cfg_info_s *cfg)

功能说明

开启 AP。

参数说明

参数名称	说明
cfg	参见 ap_cfg_info_s 结构体说明

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_ap_stop()

int hal_wifi_ap_stop(void)

功能说明

关闭 AP。

参数说明

无

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_set_country_code()

int hal_wifi_set_country_code(char *code)

功能说明

设置 Wi-Fi 的国家码。

参数说明

参数名称	说明
code	国家码

返回值

返回值	说明
0	成功
非0	失败

ap_scan_info_s

typedef struct {
	uint8_t channel;
	char rssi;
	uint8_t bssid[BSSID_MAX_LEN];
	uint8_t ssid[SSID_MAX_LEN+1];
	uint8_t s_len;
} ap_scan_info_s;

功能说明

扫描到的 AP 信息。

成员说明

成员名称	说明
channel	扫描到的某个 AP 的信道
rssi	扫描到的某个 AP 的信号强度
bssid	扫描到的某个 AP 的 MAC 地址
ssid	扫描到的某个 AP 的 SSID
s_len	扫描到的某个 AP 的 SSID 长度

ip_info_s

typedef struct {
	char ip[ADDR_MAX_LEN];
	char mask[ADDR_MAX_LEN];
	char gateway[ADDR_MAX_LEN];
} ip_info_s;

功能说明

网络接口的 IP 信息。

成员说明

成员名称	说明
ip	IP 地址
mask	子网掩码
gateway	网关 IP 地址

mac_info_s

typedef struct {
	uint8_t mac[MAC_MAX_LEN];
} mac_info_s;

功能说明

网络接口的 MAC 信息。

成员说明

成员名称	说明
mac	MAC 地址

ap_cfg_info_s

typedef struct {
	uint8_t ssid[SSID_MAX_LEN+1];
	uint8_t s_len;
	uint8_t key[KEY_MAX_LEN+1];
	uint8_t p_len;
	uint8_t channel;
	ap_encryption_type_t type;
	uint8_t hidden;
	uint8_t max_conn;
	uint16_t ms_interval;
} ap_cfg_info_s;

功能说明

设置网关为 AP 模式的配置。

成员说明

成员名称	说明
ssid	SSID
s_len	SSID 长度
password	密码
p_len	密码长度
channel	工作信道
encryption	加密方式
hidden	是否隐藏 SSID
max_conn	最大连接数
ms_interval	beacon 的间隔

功能说明

获取 Station 模式与上级 AP 连接的信号强度。

参数说明

参数名称	说明
rssi	信号强度值

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_get_station_conn_stat()

int hal_wifi_get_station_conn_stat(station_conn_stat_t *stat)

功能说明

获取 Station 模式与上级 AP 的连接状态。

参数说明

参数名称	说明
stat	连接状态值。 STAT_IDLE: 无连接 STAT_CONNECTING: 正在连接 STAT_PASSWD_WRONG: 密码错误 STAT_NO_AP_FOUND: 没找到 AP STAT_CONN_FAIL: 连接失败 STAT_CONN_SUCCESS: 连接成功 STAT_GOT_IP: 连接成功并分配到了 IP 地址

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_ap_start()

int hal_wifi_ap_start(ap_cfg_info_s *cfg)

功能说明

开启 AP。

参数说明

参数名称	说明
cfg	参见 ap_cfg_info_s 结构体说明

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_ap_stop()

int hal_wifi_ap_stop(void)

功能说明

关闭 AP。

参数说明

无

返回值

返回值	说明
0	成功
非0	失败

hal_wifi_set_country_code()

int hal_wifi_set_country_code(char *code)

功能说明

设置 Wi-Fi 的国家码。

参数说明

参数名称	说明
code	国家码

返回值

返回值	说明
0	成功
非0	失败

ap_scan_info_s

typedef struct {
	uint8_t channel;
	char rssi;
	uint8_t bssid[BSSID_MAX_LEN];
	uint8_t ssid[SSID_MAX_LEN+1];
	uint8_t s_len;
} ap_scan_info_s;

功能说明

扫描到的 AP 信息。

成员说明

成员名称	说明
channel	扫描到的某个 AP 的信道
rssi	扫描到的某个 AP 的信号强度
bssid	扫描到的某个 AP 的 MAC 地址
ssid	扫描到的某个 AP 的 SSID
s_len	扫描到的某个 AP 的 SSID 长度

ip_info_s

typedef struct {
	char ip[ADDR_MAX_LEN];
	char mask[ADDR_MAX_LEN];
	char gateway[ADDR_MAX_LEN];
} ip_info_s;

功能说明

网络接口的 IP 信息。

成员说明

成员名称	说明
ip	IP 地址
mask	子网掩码
gateway	网关 IP 地址

mac_info_s

typedef struct {
	uint8_t mac[MAC_MAX_LEN];
} mac_info_s;

功能说明

网络接口的 MAC 信息。

成员说明

成员名称	说明
mac	MAC 地址

ap_cfg_info_s

typedef struct {
	uint8_t ssid[SSID_MAX_LEN+1];
	uint8_t s_len;
	uint8_t key[KEY_MAX_LEN+1];
	uint8_t p_len;
	uint8_t channel;
	ap_encryption_type_t type;
	uint8_t hidden;
	uint8_t max_conn;
	uint16_t ms_interval;
} ap_cfg_info_s;

功能说明

设置网关为 AP 模式的配置。

成员说明

成员名称	说明
ssid	SSID
s_len	SSID 长度
password	密码
p_len	密码长度
channel	工作信道
encryption	加密方式
hidden	是否隐藏 SSID
max_conn	最大连接数
ms_interval	beacon 的间隔