Tuya.com
简体中文
English
注册
登录开发者平台
简体中文
English
注册
登录开发者平台
TuyaOS
search
根据文档目录筛选

Zigbee 业务接口

更新时间：2024-11-20 08:51:29下载pdf

本文介绍了综合 SDK 的 Zigbee 业务接口。

结构体定义

TY_Z3_DEV_S

typedef struct {
    CHAR_T *manu_name;
    CHAR_T *model_id;
} TY_Z3_DEV_S;

功能说明(Summary)

产品信息结构体。

成员说明

参数名称 说明
manu_name 设备的厂商名称
model_id 设备的型号

TY_Z3_DEVLIST_S

typedef struct {
    TY_Z3_DEV_S  *devs;
    UINT16_T      dev_num;
} TY_Z3_DEVLIST_S;

功能说明(Summary)

白名单设备列表结构体。

成员说明

参数名称 说明
devs 产品信息数组，详见 TY_Z3_DEV_S
dev_num 产品信息数组长度

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);
    VOID (*version)(CONST CHAR_T *dev_id, UCHAR_T version);
} TY_Z3_DEV_CBS_S;

功能说明(Summary)

Zigbee 设备管理回调结构体。

成员说明

参数名称 说明
join 白名单中的 Zigbee 子设备入网通知回调接口，详见 join
leave 白名单中的 Zigbee 子设备离网通知回调接口，详见 leave
report 白名单中的 Zigbee 子设备数据上报处理回调接口，详见 report
notify 白名单中的 Zigbee 子设备状态同步通知回调接口，详见 notify
upgrade_end 白名单中的 Zigbee 子设备升级完成通知回调接口，详见 upgrade_end
version 白名单中的 Zigbee 子设备上报版本号处理回调接口，详见 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;
    UCHAR_T    cmd_id;
    UCHAR_T    frame_type;
    UINT16_T   manufacturer_code;
    CHAR_T     disable_ack;
    UINT16_T   msg_length;
    UCHAR_T   *message;
} TY_Z3_APS_FRAME_S;

功能说明(Summary)

Zigbee ZCL 数据帧结构体。

成员说明

成员名称 说明
id 子设备的长地址
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 Command，1：Cluster Specific Command
cmd_id ZCL Command ID
frame_type 传输类型，定义如下：
  • 0：单播
  • 1：组播
  • 2：广播
disable_ack 是否关闭响应 ACK，
  • 1：关闭
  • 0：开启
msg_length ZCL payload 的长度
message ZCL payload

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;
    UCHAR_T    uc_num;
    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 子设备的长地址
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 是否为 rejoin 标志位
power_source 供电方式，定义如下：
0x03：弱电
0x04：强电
version Application Version

接口说明

tuya_zigbee_svc_init

OPERATE_RET tuya_zigbee_svc_init(ty_cJSON *cfg)

功能说明

Zigbee 服务初始化接口，用于初始化涂鸦 Zigbee 相关业务。

参数说明

参数名称 说明
cfg json 配置信息

JSON 配置说明：

{
	"storage_path": "./",       // 数据存储路径
	"cache_path": "/tmp/",      // 固件存储路径
	"dev_name": "/dev/ttyUSB0", // 串口设备号
	"cts": 0,                   // 是否支持硬件流控
	"thread_mode": 1,           // 是否用线程跑 Zigbee HOST 业务
	"sw_ver": "1.0.8"           // 该字段已废弃
}

返回值

返回值 说明
OPRT_OK 成功
错误码 错误码定义参考头文件 tuya_error_code.h

tuya_zigbee_svc_start

OPERATE_RET tuya_zigbee_svc_start(ty_cJSON *cfg)

功能说明

Zigbee 服务启动接口，用于运行涂鸦 Zigbee 相关业务。

参数说明

参数名称 说明
cfg json 配置信息，同 tuya_zigbee_svc_init 接口参数

返回值

返回值 说明
OPRT_OK 成功
错误码 错误码定义参考头文件 tuya_error_code.h

tuya_zigbee_reg_permit_join_cb

OPERATE_RET tuya_zigbee_reg_permit_join_cb(TY_Z3_PERMIT_JOIN_CB cb)

功能说明

注册 Zigbee NCP 允许子设备入网通知回调接口，要求在 tuya_zigbee_svc_init 接口之前调用。

参数说明

参数名称 说明
cb Zigbee NCP 允许/禁止子设备入网通知回调接口，详见 TY_Z3_PERMIT_JOIN_CB

返回值

返回值 说明
OPRT_OK 成功
错误码 错误码定义参考头文件 tuya_error_code.h

tuya_zigbee_reg_ncp_got_ver_cb

OPERATE_RET tuya_zigbee_reg_ncp_got_ver_cb(TY_Z3_NCP_GOT_VER_CB cb)

功能说明

注册成功获取 Zigbee NCP 版本号通知回调接口，要求在 tuya_zigbee_svc_init 接口之前调用。

参数说明

参数名称 说明
cb 已获取 Zigbee NCP 版本号通知回调接口，详见 TY_Z3_NCP_GOT_VER_CB

返回值

返回值 说明
OPRT_OK 成功
错误码 错误码定义参考头文件 tuya_error_code.h

tuya_zigbee_reg_ncp_hard_reset_cb

OPERATE_RET tuya_zigbee_reg_ncp_hard_reset_cb(TY_Z3_NCP_HARD_RESET_CB cb)

功能说明

注册 Zigbee NCP 硬重启通知回调接口，要求在 tuya_zigbee_svc_init 接口之前调用。

参数说明

参数名称 说明
cb Zigbee NCP 硬重启通知回调接口，详见 TY_Z3_NCP_HARD_RESET_CB

返回值

返回值 说明
OPRT_OK 成功
错误码 错误码定义参考头文件 tuya_error_code.h

tuya_zigbee_print_debug_info

OPERATE_RET tuya_zigbee_print_debug_info(VOID)

功能说明

打印 Zigbee NCP 调试信息接口。

参数说明

参数名称 说明
VOID /

返回值

返回值 说明
OPRT_OK 成功
错误码 错误码定义参考头文件 tuya_error_code.h

tuya_zigbee_set_tx_radio_power

OPERATE_RET tuya_zigbee_set_tx_radio_power(INT_T tx_power)

功能说明

设置 Zigbee NCP 发送功率接口。

参数说明

参数名称 说明
tx_power 发射功率，范围：[0, 19]

返回值

返回值 说明
OPRT_OK 成功
错误码 错误码定义参考头文件 tuya_error_code.h

tuya_zigbee_rftest

OPERATE_RET tuya_zigbee_rftest(TY_Z3_RFTEST_RESULT_CB cb, 
                               UCHAR_T channel, 
                               CHAR_T power,
                               UCHAR_T msg_len, 
                               UCHAR_T *msg, 
                               USHORT_T npacket)

功能说明

Zigbee 模组射频接口，该接口一般仅用于产测阶段。

参数说明

参数名称 说明
cb 数据发送完成后，返回接收数据结果通知回调接口，详见 TY_Z3_RFTEST_RESULT_CB
channel 发送信道，范围：[11, 26]
power 发射功率，范围：[0, 19]
msg_len 发送的数据长度
msg 发送的数据，使用涂鸦 ZigBee Dongle 测试时，数据固定为：
{0x55, 0xaa, 0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39}
npacket 发送的数据包个数

返回值

返回值 说明
OPRT_OK 成功
错误码 错误码定义参考头文件 tuya_error_code.h

tuya_zigbee_upgrade_ncp

OPERATE_RET tuya_zigbee_upgrade_ncp(CONST CHAR_T *fw_file, 
                                    TY_Z3_NCP_UPGRADE_STATUS_CB cb)

功能说明

本地升级 Zigbee NCP 固件接口。

参数说明

参数名称 说明
fw_file 固件文件的路径
cb 升级结果通知回调接口，详见 TY_Z3_NCP_UPGRADE_STATUS_CB

返回值

返回值 说明
OPRT_OK 成功
错误码 错误码定义参考头文件 tuya_error_code.h

tuya_zigbee_set_ncp_mac

OPERATE_RET tuya_zigbee_set_ncp_mac(CONST CHAR_T *mac)

功能说明

设置 Zigbee NCP MAC 地址接口。该接口一般仅用于故障替换调试，避免跟代替网关冲突，故障网关需要写入新的 MAC 地址。

参数说明

参数名称 说明
mac MAC 地址

返回值

返回值 说明
OPRT_OK 成功
错误码 错误码定义参考头文件 tuya_error_code.h

tuya_zigbee_reset_ncp

OPERATE_RET tuya_zigbee_reset_ncp(VOID)

功能说明

Zigbee NCP 重置接口。

参数说明

参数名称 说明
VOID /

返回值

返回值 说明
OPRT_OK 成功
错误码 错误码定义参考头文件 tuya_error_code.h

tuya_zigbee_get_ncp_ver

OPERATE_RET tuya_zigbee_get_ncp_ver(CHAR_T *ver)

功能说明

读取 Zigbee NCP 固件版本号接口。

参数说明

参数名称 说明
ver version buf

返回值

返回值 说明
OPRT_OK 成功
错误码 错误码定义参考头文件 tuya_error_code.h

tuya_zigbee_custom_dev_mgr_init

OPERATE_RET tuya_zigbee_custom_dev_mgr_init(TY_Z3_DEVLIST_S *devlist, 
                                            TY_Z3_DEV_CBS_S *cbs)

功能说明

第三方 Zigbee 设备接入初始化接口，要求在 tuya_zigbee_svc_init 接口之前调用。

接入非涂鸦生态 Zigbee 协议子设备需要开发者实现，SDK 采用白名单机制，开发者通过注册白名单设备列表，通知 SDK 白名单设备列表由应用处理，SDK 会把 Zigbee 数据透传给应用。

注意，当白名单为空时，表示所有设备都由应用处理。

参数说明

参数名称 说明
devlist 白名单设备列表，详见 TY_Z3_DEVLIST_S
cbs Zigbee 设备管理回调结构体，详见 TY_Z3_DEV_CBS_S

返回值

返回值 说明
OPRT_OK 成功
错误码 错误码定义参考头文件 tuya_error_code.h

tuya_zigbee_send_data

OPERATE_RET tuya_zigbee_send_data(TY_Z3_APS_FRAME_S *frame)

功能说明

发送 Zigbee ZCL 数据，该接口是给第三方 Zigbee 设备接入使用的。

参数说明

参数名称 说明
frame ZigBee ZCL 数据帧，详见 TY_Z3_APS_FRAME_S

返回值

返回值 说明
OPRT_OK 成功
错误码 错误码定义参考头文件 tuya_error_code.h

tuya_zigbee_del_dev

OPERATE_RET tuya_zigbee_del_dev(CONST CHAR_T *dev_id)

功能说明

从 Zigbee 网络剔除子设备接口，该接口是给第三方 Zigbee 设备接入使用的。

参数说明

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

返回值

返回值 说明
OPRT_OK 成功
错误码 错误码定义参考头文件 tuya_error_code.h

tuya_zigbee_upgrade_dev

OPERATE_RET tuya_zigbee_upgrade_dev(CONST CHAR_T *dev_id, 
                                    CONST FW_UG_S *fw)

功能说明

升级 Zigbee 子设备接口，该接口是给第三方 Zigbee 设备接入使用的。

参数说明

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

返回值

返回值 说明
OPRT_OK 成功
错误码 错误码定义参考头文件 tuya_error_code.h

回调接口

join

VOID (*join)(TY_Z3_DESC_S *dev)

功能说明

白名单中的 Zigbee 子设备入网通知回调接口。

参数说明

参数名称 说明
dev 设备信息结构体，详见 TY_Z3_DESC_S

返回值

返回值 说明
VOID /

leave

VOID (*leave)(CONST CHAR_T *dev_id)

功能说明

白名单中的 Zigbee 子设备离网通知回调接口。

参数说明

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

返回值

返回值 说明
VOID /

report

VOID (*report)(TY_Z3_APS_FRAME_S *frame)

功能说明

白名单中的 Zigbee 子设备数据上报处理回调接口。

参数说明

参数名称 说明
frame Zigbee ZCL 数据帧，详见 TY_Z3_APS_FRAME_S

返回值

返回值 说明
VOID /

notify

VOID (*notify)(VOID);

功能说明

白名单中的 Zigbee 子设备升级完成通知回调接口，要求开发者在回调接口中实现遍历所有子设备，读取子设备当前状态操作。

参数说明

参数名称 说明
VOID /

返回值

返回值 说明
VOID /

upgrade_end

VOID (*upgrade_end)(CONST CHAR_T *dev_id, 
                    INT_T rc, 
                    UCHAR_T version);

功能说明

设备升级结果回调。

参数说明

参数名称 说明
dev_id 子设备的长地址
rc 升级结果
version 子设备的版本号

返回值

返回值 说明
VOID /

version

VOID (*version)(CONST CHAR_T *dev_id, 
                UCHAR_T version)

功能说明

白名单中的 Zigbee 子设备上报版本号处理回调接口。

参数说明

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

返回值

返回值 说明
VOID /

TY_Z3_PERMIT_JOIN_CB

typedef VOID (*TY_Z3_PERMIT_JOIN_CB)(BOOL_T permit, 
                                     UINT_T timeout)

功能说明

Zigbee NCP 允许子设备入网通知回调接口。

参数说明

参数名称 说明
permit 配网状态，TRUE：允许 Zigbee 子设备入网，FALSE：禁止 Zigbee 子设备入网
timeout permit == TRUE 时有效，表示配网超时时间，单位为秒

返回值

返回值 说明
VOID /

TY_Z3_NCP_GOT_VER_CB

typedef VOID (*TY_Z3_NCP_GOT_VER_CB)(CHAR_T *ver)

功能说明

已获取 Zigbee NCP 版本号通知回调接口。

参数说明

参数名称 说明
ver Zigbee NCP 固件版本号

返回值

返回值 说明
VOID /

TY_Z3_NCP_HARD_RESET_CB

typedef VOID (*TY_Z3_NCP_HARD_RESET_CB)(VOID)

功能说明

Zigbee NCP 硬重启通知回调接口，开发者需要在回调中实现通过 GPIO 控制 Zigbee 模组的 nRST 引脚让其硬重启。

参数说明

参数名称 说明
VOID /

返回值

返回值 说明
VOID /

TY_Z3_NCP_UPGRADE_STATUS_CB

typedef VOID (*TY_Z3_NCP_UPGRADE_STATUS_CB)(BOOL_T status)

功能说明

Zigbee NCP 升级结果通知回调接口。

参数说明

参数名称 说明
status 升级状态
  • TRUE：成功
  • FALSE：失败

返回值

返回值 说明
VOID
语言
简体中文
简体中文
English
400-881-8611
7×24小时服务热线
市场合作
marketing@tuya.com
业务合作
service@tuya.com
媒体联络
pr@tuya.com
关注“涂鸦智能”
涂鸦服务尽在掌握
关注“全球智能商业”
第一时间获取物联网资讯
联系我们加入我们TuyaExpoApp 商城TuyaGoTuyaGo服务商查询
法律声明隐私协议加州隐私权利声明服务条款廉正合规安全应急响应中心
©2014-2025 杭州涂鸦信息技术有限公司 版权
浙ICP备2022000504号
浙B2-20210233号
浙公网安备33010602004238号
简体中文
简体中文
English