通用联网模块 SDK

版本记录

1 概述

联网模块SDK：借助设备的联网能力，直接与涂鸦云、涂鸦app建立通信链路并进行涂鸦标准数据交互的一个软件中间件；比如无线网络、有线网络、gprs、3g/4g等。

功能描述

• 提供符合涂鸦标准数据规范的上下行通道
• 提供数据过滤服务：数据校验、规则上报、上报频率控制等
• 提供涂鸦标准化服务，例如本地定时、本地联动等功能
• 通信传输过程中的数据安全服务

2 产品形态

2.1 联网模组+MCU类产品

利用联网模块+外部mcu做成的单品，功能相对复杂，模块资源不足以完成产品整体功能的开发、需要借助外部mcu实现。此时联网模块主要作为外部mcu与涂鸦云、涂鸦app之间的桥梁

联网模块同时提供模块自身以及客户mcu的固件升级能力。

2.2 SOC类产品

仅利用联网模块做成的单品，功能相对简单，所有的产品功能均在模块内实现。例如：智能插座、智能led灯等

2.3 网关类产品

利用联网模块+不同的协议控制器将产品做成实体网关产品，网关向下接入各类不同通信协议的产品，比如：zigbee、rf类、ble、有线485等。比如：智能家居中常见的控制中心、智慧主机等。

网关提供联网模块、协议控制器、终端设备的固件升级能力。

2.4 网关+设备类产品

利用联网模块+不同的协议控制器将产品做成带设备功能的网关产品，网关向下接入各类不同通信协议的产品，比如：zigbee、rf类、ble、有线485等，同时自身又是一个产品。自身的产品功能由联网模块实现。

网关提供联网模块、协议控制器、终端设备的固件升级能力

2.5 设备配网方式

设备完整的配网过程：设备要先连通外网，然后sdk去涂鸦云激活，完成整个设备的配网过程。

对于设备连通外网的过程，不同形态的设备方式如下：

1. 没有人机交互界面的wifi设备，使用前需要app通过smartconfig、ap等技术进行配网，当设备接收连网信息，连上路由器之后才可以接通外网。
2. 有人机交互界面的wifi设备、有线网络产品、gprs/4G等通过运营商方式已经具备联通外网能力的设备，无需app参与配置。

3 涂鸦云联网模块sdk适用范围

3.1 必备条件

• 支持linux 或 android
• 支持tcp/ip协议栈
• 标准linux系统，支持文件系统

3.2 说明

满足"3.1"，涂鸦云联网模块sdk可适用于不同芯片、不同os平台的应用场景。客户可根据产品类别、产品形态按需调用sdk提供的接口实现产品功能。

3.2 资源占用

• Flash，sdk代码占用2MB左右
• RAM，sdk运行后内存占用5MB，用户要根据开发产品的功能复杂度增加内存

4 编译说明

4.1 linux平台

涂鸦根据客户toolchain编译成的相关的库，附带开发手册以及相关demo等提供给客户。

4.2 android 平台

涂鸦根据客户提供的 API版本号，使用NDK产生工具链，并编译成的相关的库，附带开发手册以及相关demo等提供给客户。

5 SDK初始化

5.1 设备认证

• 设备认证：
  • 设备的身份认证采用一机一密的方式，在设备上烧写设备的唯一的UUID、AUTHKEY，这种方式要求对设备的产线工具进行一定的修改，需要对每个设备烧写不同的UUID和AUTHKEY；
  • UUID和AUTHKEY成对出现，每一台设备都必须有自己uuid & authkey，且唯一，请向涂鸦项目经理申请几组用于调试；
  • 设备认证消息通过接口tuya_iot_set_gw_prod_info设置

在demo 中 PID，uuid & authkey仅用作测试使用，不能用于实际产品，会导致后续产品不可用。PID需要用户自行从涂鸦开发者平台申请。每一台设备都必须有自己uuid &authkey，且唯一。

5.2 网关类产品

5.3 单品

5.4 初始化接口说明

5.4.1 tuya_iot_init

函数原型

OPERATE_RET tuya_iot_init(IN CONST CHAR_T *fs_storge_path)

功能说明

用于tuya iot 系统的初始化，必须最先调用

参数说明

返回值

5.4.2 tuya_iot_get_sdk_info

函数原型

CHAR_T *tuya_iot_get_sdk_info(VOID);

功能说明

获取tuya iot sdk版本信息。

参数说明

返回值

5.4.3 tuya_iot_sys_mag_hb_init

函数原型

OPERATE_RET tuya_iot_sys_mag_hb_init(IN CONST DEV_HEARTBEAT_SEND_CB hb_send_cb);

功能说明

启动子设备心跳管理能力。

参数说明

返回值

5.4.4 wifi配置类设备接口，详见"tuya_iot_wifi_api.h"

tuya_iot_set_wf_gw_prod_info

函数原型

OPERATE_RET tuya_iot_set_wf_gw_prod_info(IN CONST WF_GW_PROD_INFO_S *wf_prod_info);

功能说明

设置配置类wifi设备的授权信息，授权信息需通过涂鸦获取，否则设备无法正常使用。

参数说明

返回值

tuya_iot_wf_mcu_dev_init

函数原型

OPERATE_RET tuya_iot_wf_mcu_dev_init(IN CONST GW_WF_CFG_MTHD_SEL cfg, IN CONST GW_WF_START_MODE start_mode, IN CONST TY_IOT_CBS_S *cbs, IN CONST CHAR_T *p_firmware_key, IN CONST CHAR_T *product_key,IN CONST CHAR_T *wf_sw_ver,IN CONST CHAR_T *mcu_sw_ver);

功能说明

联网模块+mcu 设备初始化接口。

参数说明

返回值

tuya_iot_wf_soc_dev_init

函数原型

OPERATE_RET tuya_iot_wf_soc_dev_init(IN CONST GW_WF_CFG_MTHD_SEL cfg, IN CONST GW_WF_START_MODE start_mode, IN CONST TY_IOT_CBS_S *cbs, IN CONST CHAR_T *product_key,IN CONST CHAR_T *wf_sw_ver);

功能说明

wifi soc 设备初始化接口。

参数说明

返回值

tuya_iot_wf_gw_init

函数原型

OPERATE_RET tuya_iot_wf_gw_init(IN CONST GW_WF_CFG_MTHD_SEL cfg, IN CONST GW_WF_START_MODE start_mode, IN CONST TY_IOT_CBS_S *cbs, IN CONST TY_IOT_GW_CBS_S *gw_cbs, IN CONST CHAR_T *product_key, IN CONST CHAR_T *wf_sw_ver, IN CONST GW_ATTACH_ATTR_T *attr, IN CONST UINT_T attr_num);

功能说明

wifi 网关初始化接口

参数说明

返回值

tuya_iot_wf_gw_dev_init

函数原型

OPERATE_RET tuya_iot_wf_gw_dev_init(IN CONST GW_WF_CFG_MTHD_SEL cfg, IN CONST GW_WF_START_MODE start_mode, IN CONST TY_IOT_CBS_S *cbs, IN CONST TY_IOT_GW_CBS_S *gw_cbs, IN CONST CHAR_T *product_key, IN CONST CHAR_T *wf_sw_ver, IN CONST GW_ATTACH_ATTR_T *attr, IN CONST UINT_T attr_num);

功能说明

wifi 网关加设备初始化接口，相比与tuya_iot_wf_gw_init，该函数使得网关具有设备的属性，可以设置功能点等。

参数说明

参考 tuya_iot_wf_gw_init 接口说明

返回值

参考 tuya_iot_wf_gw_init 接口说明

tuya_iot_reg_get_wf_nw_stat_cb

函数原型

OPERATE_RET tuya_iot_reg_get_wf_nw_stat_cb(IN CONST GET_NW_STAT_CB nw_stat_cb);

功能说明

获取wifi状态接口。

参数说明

返回值

5.4.5 非wifi配置类设备接口，详见"tuya_iot_base_api.h"

tuya_iot_set_gw_prod_info

函数原型

OPERATE_RET tuya_iot_set_gw_prod_info(IN CONST GW_PROD_INFO_S *prod_info);

功能说明

设置非wifi配置类联网模块的授权信息，授权信息需通过涂鸦获取，否则设备无法正常使用。

参数说明

返回值

tuya_iot_mcu_dev_init

函数原型

OPERATE_RET tuya_iot_mcu_dev_init(IN CONST TY_IOT_CBS_S *cbs,IN CONST CHAR_T *product_key, IN CONST CHAR_T *p_firmware_key, IN CONST CHAR_T *sw_ver,IN CONST CHAR_T *mcu_sw_ver);

功能说明

联网模块+mcu 设备初始化接口。

参数说明

返回值

tuya_io_soc_init

函数原型

OPERATE_RET tuya_iot_soc_init(IN CONST TY_IOT_CBS_S *cbs, IN CONST CHAR_T *product_key, IN CONST CHAR_T *sw_ver);

功能说明

联网模块soc 设备初始化接口。

参数说明

返回值

tuya_iot_gw_init

函数原型

OPERATE_RET tuya_iot_gw_init(IN CONST TY_IOT_CBS_S *cbs,IN CONST TY_IOT_GW_CBS_S *gw_cbs, IN CONST CHAR_T *product_key,IN CONST CHAR_T *sw_ver, IN CONST GW_ATTACH_ATTR_T *attr, IN CONST UINT_T attr_num);

功能说明

联网模块网关初始化接口。

参数说明

返回值

tuya_iot_gw_dev_init

函数原型

OPERATE_RET tuya_iot_gw_dev_init(IN CONST TY_IOT_CBS_S *cbs, IN CONST TY_IOT_GW_CBS_S *gw_cbs, IN CONST CHAR_T *product_key, IN CONST CHAR_T *sw_ver,IN CONST GW_ATTACH_ATTR_T *attr,IN CONST UINT_T attr_num);

功能说明

联网模块网关加设备初始化接口，相比与tuya_iot_gw_init，该函数使得网关具有设备的属性，可以设置功能点等。

参数说明

参考 tuya_iot_gw_init 接口说明

返回值

参考 tuya_iot_gw_init 接口说明

tuya_iot_reg_get_nw_stat_cb

函数原型

OPERATE_RET tuya_iot_reg_get_nw_stat_cb (IN CONST GET_NW_STAT_CB nw_stat_cb);

功能说明

注册联网网络状态获取函数，在注册的回调函数中，用户可以根据获取当前的网络状态信息。

参数说明

返回值

5.4.6 有线加wifi 配置接口，详见 "tuya_iot_wired_wifi_api.h"

tuya_iot_set_wired_wifi_gw_prod_info

函数原型

tuya_iot_set_wired_wifi_gw_prod_info(IN CONST WF_GW_PROD_INFO_S *wf_prod_info);

参看 tuya_iot_set_wf_gw_prod_info 函数说明，只用方法以及参数与其一直。

tuya_iot_wired_wifi_gw_dev_init

函数原型

OPERATE_RET tuya_iot_wired_wifi_gw_dev_init(IN CONST IOT_GW_NET_TYPE_T net_mode,

IN CONST GW_WF_CFG_MTHD_SEL cfg, IN CONST GW_WF_START_MODE start_mode,

IN CONST TY_IOT_CBS_S *cbs, IN CONST TY_IOT_GW_CBS_S *gw_cbs,

IN CONST CHAR_T *product_key, IN CONST CHAR_T *wf_sw_ver,

IN CONST GW_ATTACH_ATTR_T *attr, IN CONST UINT_T attr_num);

功能说明

有线 + wifi 网关 （网关同时作为设备）初始化接口。

功能说明

wifi 网关加设备初始化接口。

参数说明

返回值

tuya_iot_reg_get_wired_wifi_nw_stat_cb

函数原型

OPERATE_RET tuya_iot_reg_get_wired_wifi_nw_stat_cb(nw_stat_cb, wf_nw_stat_cb);

功能说明

注册网络状态管理回调函数

参数说明

返回值

tuya_iot_wired_wifi_gw_unactive

函数原型

OPERATE_RET tuya_iot_wired_wifi_gw_unactive(VOID);

参看 tuya_iot_wf_gw_unactive 使用方法一直。

tuya_iot_gw_wired_wifi_set_net_name

函数原型

VOID tuya_iot_gw_wired_wifi_set_net_name(IN CONST CHAR_T *wired_net_name, IN CONST CHAR_T *wifi_net_name);

功能说明

设置有线，以及wifi 网络接口名称。

参数说明

返回值

6 设备配网

说明：tuya_sdk会开启多线程，进入配网模式生效必须重启整个进程。

因为涂鸦sdk兼顾的平台很多，无法兼顾所有的联网模块的硬件细节特性，因此对于sdk内部而言，抽象出了一套需要实现的联网设备相关的硬件接口，按产品形态分为两类：wifi配置类网络接口、非wif配置类网络接口，具体说明详见"demo"代码

6.1 有线设备配网

设备通过有线接入互联网,不用输入路由器的热点名称和密码，设备已连接外网；只需从APP端获取激活token，即可申请在涂鸦云激活设备。

6.1.1 重置设备(进入待配网状态)

tuya_iot_gw_unactive

函数原型

OPERATE_RET tuya_iot_gw_unactive(VOID);

功能说明

重置网关设备，解除网关有APP的绑定关系，使得网关处于非激活(待配网)状态。

参数说明

返回值

6.1.2 配网流程交互图

• 实现6.1.2 ~6.1.4 接口；
• 如上图，本地重置设备后，需要重启sdk进程，才可进入配网模式。
• DEV_RESET_IFM_CB 参考常见问题说明

6.1.3 需要用户实现的接口

hwl_bnw_get_ip

函数原型

OPERATE_RET hwl_bnw_get_ip(OUT NW_IP_S *ip);

功能说明

获取联网模块ip 信息。

参数说明

返回值

hwl_bnw_station_conn

函数原型

BOOL_T hwl_bnw_station_conn(VOID);

功能说明

获取网络连接状态。

参数说明

VOID

返回值

hwl_bnw_get_mac

函数原型

OPERATE_RET hwl_bnw_get_mac(OUT NW_MAC_S *mac);

功能说明

获取设备网络接口的mac 地址。可选实现。

参数说明

返回值

hwl_bnw_set_mac

函数原型

OPERATE_RET hwl_bnw_set_mac(IN CONST NW_MAC_S *mac);

功能说明

设定设备mac 地址，可选实现。

参数说明

返回值

hwl_bnw_set_station_connect

函数原型

OPERATE_RET hwl_bnw_set_station_connect(IN CONST CHAR_T *ssid,IN CONST CHAR_T *passwd)

功能说明

当产品形态为有线+无线模式，需要用户自己实现 wifi 连接的函数，配网时app会将指定路由的ssid，password传下来。

参数说明

返回值

hwl_bnw_need_wifi_cfg

函数原型

BOOL_T hwl_bnw_need_wifi_cfg(VOID);

功能说明

是否需要wifi 配置。

参数说明

返回值

hwl_bnw_station_get_conn_ap_rssi

函数原型

OPERATE_RET hwl_bnw_station_get_conn_ap_rssi(OUT SCHAR_T *rssi);

功能说明

当产品形态为有线+无线时，此接口用于获取wifi与router之间的 rssi值。

参数说明

返回值

6.2 Wifi设备配网

• 用户需要先确定wifi网卡支持的工作模式，然后在tuya_iot_wf_xx_init接口初始化时告知sdk支持的配网模式，具体参考tuya_iot_wf_xx_dev_init 类接口的cfg参数说明
• SDK支持smart config配网以及ap配网模式。smart config也称为快速配网，是设备的wifi处于monitor模式下，获取手机app发出的无线空口报文，sdk会解析这些报文，并从中获取配置信息，切换为station模式进行联网；ap配网过程相对复杂，是指设备开启ap热点，手机连接上，通过局域网发送配置信息，设备获取配置信息之后，切换为station模式，进行联网。

6.2.1 重置设备(进入待配网模式)

• 如上图，本地重置设备后，需要重启sdk进程，才可进入配网模式。
• DEV_RESET_IFM_CB 参考常见问题说明；
• 当初始化时设置同时支持AP和Smart配网模式时，调用此接口会循环切换配网模式；

tuya_iot_wf_gw_unactive

函数原型

OPERATE_RET tuya_iot_gw_unactive(VOID);

功能说明

重置网关设备，解除网关有APP的绑定关系，使得网关处于非激活(待配网)状态。

参数说明

返回值

6.2.3 AP配网

1. 实现6.2.4需要用户实现的接口
2. 实现6.2.1逻辑，使sdk进入待配网状态
3. GET_WF_NW_STAT_CB参考

6.2.4 需要用户实现的接口

hwl_wf_get_ip

函数原型

OPERATE_RET hwl_wf_get_ip(IN CONST WF_IF_E wf,OUT NW_IP_S *ip);

功能说明

获取wifi设备ip信息。

参数说明

返回值

hwl_wf_get_mac

函数原型

OPERATE_RET hwl_wf_get_mac(IN CONST WF_IF_E wf,OUT NW_MAC_S *mac);

功能说明

获取wifi设备mac。

参数说明

返回值

hwl_wf_set_mac

函数原型

OPERATE_RET hwl_wf_set_mac(IN CONST WF_IF_E wf,IN CONST NW_MAC_S *mac);

功能说明

设置wifi设备mac，可选实现。

参数说明

返回值

hwl_wf_wk_mode_set

函数原型

OPERATE_RET hwl_wf_wk_mode_set(IN CONST WF_WK_MD_E mode);

功能说明

设置wifi工作模式。

参数说明

返回值

hwl_wf_wk_mode_get

函数原型

OPERATE_RET hwl_wf_wk_mode_get(OUT WF_WK_MD_E *mode);

功能说明

获取wifi工作模式。

参数说明

返回值

hwl_wf_station_connect

函数原型

OPERATE_RET hwl_wf_station_connect(IN CONST CHAR_T *ssid,IN CONST CHAR_T *passwd);

功能说明

设置wifi设备建立与AP/热点/wifi路由器 的连接。

参数说明

返回值

hwl_wf_station_disconnect

函数原型

OPERATE_RET hwl_wf_station_disconnect(VOID);

功能说明

断开wifi设备与AP/热点/wifi路由器 的连接。

参数说明

返回值

hwl_wf_station_get_conn_ap_rssi

函数原型

OPERATE_RET hwl_wf_station_get_conn_ap_rssi(OUT SCHAR_T *rssi);

功能说明

获取作为station 模式的wifi设备与AP连接的信号强度。

参数说明

返回值

hwl_wf_station_stat_get

函数原型

OPERATE_RET hwl_wf_station_stat_get(OUT WF_STATION_STAT_E *stat);;

功能说明

获取station模式下wifi设备的连接状态。

参数说明

返回值

hwl_wf_set_country_code

函数原型

OPERATE_RET hwl_wf_set_country_code(IN CONST CHAR_T *p_country_code);

功能说明

设置wifi 的国家码。

参数说明

返回值

6.2.5 需要用户实现的接口(AP配网)

hwl_wf_ap_start

函数原型

OPERATE_RET hwl_wf_ap_start(IN CONST WF_AP_CFG_IF_S *cfg);

功能说明

启动wifi ap热点。

参数说明

返回值

hwl_wf_ap_stop

函数原型

OPERATE_RET hwl_wf_ap_stop(VOID);

功能说明

停止wifi ap热点。

参数说明

返回值

6.2.5 EZ配网

6.2.6 用户需实现的接口(EZ配网)

hwl_wf_all_ap_scan

函数原型

OPERATE_RET hwl_wf_all_ap_scan(OUT AP_IF_S **ap_ary,OUT UINT_T *num);

功能说明

扫描所有ap。

参数说明

返回值

hwl_wf_assign_ap_scan

函数原型

OPERATE_RET hwl_wf_assign_ap_scan(IN CONST CHAR_T *ssid,OUT AP_IF_S **ap);

功能说明

扫描指定的ap。

参数说明

返回值

hwl_wf_release_ap

函数原型

OPERATE_RET hwl_wf_release_ap(IN AP_IF_S *ap);

功能说明

"5.2.1"、"5.2.2"过程中分配资源的释放处理。

参数说明

返回值

hwl_wf_set_cur_channel

函数原型

OPERATE_RET hwl_wf_set_cur_channel(IN CONST BYTE_T chan);

功能说明

设置wifi 工作信道。

参数说明

返回值

hwl_wf_get_cur_channel

函数原型

OPERATE_RET hwl_wf_get_cur_channel(OUT BYTE_T *chan);

功能说明

获取当前工作信道。

参数说明

返回值

hwl_wf_sniffer_set

函数原型

OPERATE_RET hwl_wf_sniffer_set(IN CONST BOOL_T en,IN CONST SNIFFER_CALLBACK cb);

功能说明

wifi设备混杂模式设置。

参数说明

返回值

6.2.7 其他配网方式

• 此类配网设备用户层通过其他方式获取路由器的ssid、passwd和配网token，直接调用接口申请设备激活
• 二维码配网，设备通过摄像头扫描TuyaApp上生成的二维码获取ssid/passwd/token信息
• 蓝牙配网，设备通过蓝牙获取TuyaApp上的二维码获取ssid/passwd/token信息
• 串口、声波配网等

tuya_iot_gw_wf_user_cfg

函数原型

OPERATE_RET tuya_iot_gw_wf_user_cfg(IN CONST CHAR_T *ssid,IN CONST CHAR_T *passwd,IN CONST CHAR_T *token);

功能说明

当通过其他模式配网时（非ap、非smartconfig），比如摄像头的二维码配网、声波配网等，调用此接口处理。

参数说明

返回值

7 设备固件升级(OTA)

• 固件升级主要用于修复设备bug和增加设备新功能。固件升级主要分两种，第一种是设备升级，第二种是MCU升级。这里的wifi设备的固件升级均指设备升级。

• 设备升级过程涉及手机APP 、设备、涂鸦云三端

  • 手机APP：升级进度结果的展示 或者 升级消息的发起者
  • 涂鸦云： 升级过程中的管理者，负责升级固件的存储，设备升级状态的更新，升级文案推送
  • 设备: 负责接收固件，固件升级的执行者

7.1 固件包配置说明

• 网关或子设备配网成功后，从TuyaApp上获取设备信息里的虚拟ID，作为固件升级的白名单
• 编译出要升级的固件包，固件版本要高于设备中运行的固件版本
• 登录 https://iot.tuya.com/index 开发者平台，到对应创建的产品下，上传配置固件包
• 操作说明：https://docs.tuya.com/cn/product/ota.html

7.2 升级开始的方式

设备固件上传到云端后，设备不会立即收到升级消息，目前涂鸦支持以下几种方式：

• App提醒升级: 用户首次打开设备面板时，会收到升级提醒弹框，可选择升级或不升级；
• App静默升级: 即设备静默升级，设备重启后，会向云端请求一次是否有静默升级任务，有的话直接进行升级；如果用户去打开设备面板，此时会有进度框显示，此时设备是无法操作的；
• App强制升级: 用户首次打开设备面板时，会收到升级提醒弹框，只有确定可选，负责设备无法操作；
• App检测升级: 即App用户主动点击对应设备的面板，然后点击右上角进入设备信息界面，检测设备固件版本，主动更新；

7.3 数据交互图

• 说明：下图中上报升级进度为tuya_sdk上报，也可通过tuya_iot_upgrade_gw_notify配置为应用层上报

7.4 相关接口说明

tuya_iot_upgrade_gw_notify

函数原型

OPERATE_RET tuya_iot_upgrade_gw(IN CONST FW_UG_S *fw,

IN CONST GET_FILE_DATA_CB get_file_cb,\

IN CONST UPGRADE_NOTIFY_CB upgrd_nofity_cb,\

IN CONST PVOID_T pri_data,\

BOOL_T notify, UINT_T download_buf_size);

功能说明

联网模块固件升级处理接口。

参数说明

返回值

7.5 应用层上报升级进度

当需要应用层控制升级进度上报时，请先用tuya_iot_upgrade_gw_notify接口关闭tuya_sdk上报升级进度

tuya_iot_dev_upgd_progress_rept

函数原型

OPERATE_RET tuya_iot_dev_upgd_progress_rept(IN CONST UINT_T percent,

IN CONST CHAR_T *devid,

IN CONST DEV_TYPE_T tp);

功能说明

上报升级进度。

参数说明

返回值

8 设备功能点(dp点)

涂鸦提供基于mqtt网络应用协议，实现设备控制和状态上报，MQTT是一个轻量的发布订阅模式消息传输协议，专门针对低带宽和不稳定网络环境的物联网应用设计。

tuya_sdk封装了mqtt协议层实现，以功能点(以下称为dp点)的形式呈现，支持数值型、布尔型、枚举型、字符串型、故障型，RAW型数据，像定义C变量一样简单。

开发者需要根据设备功能在涂鸦开发者平台创建对应的功能点，新建dp点说明:https://docs.tuya.com/cn/product/function.html

特点

1. 目前支持每个产品最多创建35个dp，复杂功能请用raw型数据实现;
2. obj型：布尔型(bool)、数值型(value)、字符串型(string)、枚举型(enum)、故障型(bitmap)，tuya_sdk会对连续上报的数值进行过滤，相同则不予上传；

8.1 设备指令下发回调

dev_obj_dp_cb

函数原型

VOID dev_obj_dp_cb(IN CONST TY_RECV_OBJ_DP_S *dp);

功能说明

OBJ 功能点信息命令回调。

参数说明

返回值

dev_raw_dp_cb

函数原型

VOID dev_raw_dp_cb(IN CONST TY_RECV_RAW_DP_S *dp);

功能说明

透传类功能点信息命令回调。

参数说明

返回值

dev_dp_query_cb

函数原型

VOID dev_dp_query_cb(IN CONST TY_DP_QUERY_S *dp_qry);

功能说明

设备特定数据查询入口。可选实现。

参数说明

返回值

8.2 设备状态上报

dev_report_dp_json_async

函数原型

OPERATE_RET dev_report_dp_json_async(IN CONST CHAR_T *dev_id,IN CONST TY_OBJ_DP_S *dp_data,IN CONST UINT_T cnt);

功能说明

异步方式，上报功能点信息。

参数说明

返回值

dev_report_dp_raw_sync

函数原型

OPERATE_RET dev_report_dp_raw_sync (IN CONST CHAR_T *dev_id, IN CONST BYTE_T dpid, IN CONST BYTE_T *data,IN CONST UINT_T len, IN CONST UINT_T timeout);

功能说明

设备透传数据同步上报接口，由调用者保障数据上报的可靠性

参数说明

返回值

dev_report_dp_stat_sync

函数原型

OPERATE_RET dev_report_dp_raw_sync (IN CONST CHAR_T *dev_id,IN CONST TY_OBJ_DP_S *dp_data, IN CONST UINT_T cnt,IN CONST UINT_T timeout);

功能说明

设备结构化数据同步上报接口，由调用者保障数据上报的可靠性，通常用于统计类数据的上报。

参数说明

返回值

9 子设备管理

9.1 子设备配网

9.1.1 数据交互图

• 此图为从手机APP端添加子设备；
• 网关端也可调用tuya_iot_gw_bind_dev_attr直接绑定
• sub_device 和 gateway之间通信协议由用户实现

9.1.2 接口&回调说明

gw_add_dev_cb

函数原型

BOOL_T gw_add_dev_cb(IN CONST GW_PERMIT_DEV_TP_T tp,IN CONST BOOL_T permit,IN CONST UINT_T timeout);

功能说明

当添加子设备时，在此回调中实现使能设备入网功能。

参数说明

返回值

gw_del_cb

函数原型

VOID gw_del_cb(IN CONST CHAR_T *dev_id);

功能说明

当子设备被删除时，通过此回调通知用户。

参数说明

返回值

tuya_iot_gw_bind_dev

函数原型

OPERATE_RET tuya_iot_gw_bind_dev(IN CONST GW_PERMIT_DEV_TP_T tp,IN CONST USER_DEV_DTL_DEF_T uddd, IN CONST CHAR_T *id,IN CONST CHAR_T *pk,IN CONST CHAR_T *ver);

功能说明

网关绑定子设备接口。当涂鸦app使能网关添加子设备时，调用此接口将发现的子设备绑定。

参数说明

返回值

gw_bind_ifm_cb

函数原型

VOID gw_bind_ifm_cb(IN CONST CHAR_T *dev_id,IN CONST OPERATE_RET op_ret);

功能说明

当子设备被bind后，通过此回调通知用户bind结果。

参数说明

返回值

9.2 子设备固件升级(OTA)

9.2.1 数据交互图

• sub_device 和 gateway设备层的通信由客户实现，这里只简单说明；
• 升级进度上报完全可由用户控制，这里只在网关给子设备发送固件包的过程中更新上报进度；
• 涂鸦智能App固件升级超时60s机制：每收到设备的一包进度更新消息，重新计时；应用层可通过控制升级进度上报以延长TuyaApp超时

9.2.2 接口&回调说明

dev_ug_inform_cb

函数原型

VOID dev_ug_inform_cb(IN CONST CHAR_T *dev_id,IN CONST FW_UG_S *fw)

功能说明

子设备OTA 固件升级通知，表示服务器有可更新的子设备固件。

参数说明

返回值

tuya_iot_upgrade_dev

函数原型

OPERATE_RET

OPERATE_RET tuya_iot_upgrade_dev(IN CONST CHAR_T *devid,

IN CONST FW_UG_S *fw, \

IN CONST GET_FILE_DATA_CB get_file_cb,\

IN CONST UPGRADE_NOTIFY_CB upgrd_nofity_cb,\

IN CONST PVOID_T pri_data)

功能说明

设备固件升级接口，包含网关上的主控设备以及各终端子设备的升级。

参数说明

返回值

tuya_iot_gw_subdevice_update

函数原型

OPERATE_RET tuya_iot_gw_subdevice_update (IN CONST CHAR_T *id,IN CONST CHAR_T *ver);

功能说明

刷新子设备的固件版本号。

参数说明

返回值

9.3 子设备在线管理

• 开启tuya_sdk的心跳检测机制

如下图为开启sdk的心跳保活机制时接口调用图

tuya_iot_dev_online_stat_update

函数原型

OPERATE_RET tuya_iot_dev_online_stat_update(IN CONST CHAR_T *dev_id,IN CONST BOOL_T online);

功能说明

网关更新子设备在线/离线状态。

参数说明

返回值

tuya_iot_sys_mag_hb_init

函数原型

OPERATE_RET tuya_iot_sys_mag_hb_init(IN CONST DEV_HEARTBEAT_SEND_CB hb_send_cb);

功能说明

启动子设备心跳管理能力。

参数说明

返回值

tuya_iot_set_dev_hb_timeout

函数原型

OPERATE_RET tuya_iot_set_dev_hb_timeout (IN CONST CHAR_T *dev_id,IN CONST TIME_S hb_timeout_time);

功能说明

子设备心跳超时时间设置，若网关在超过设置时间内未收到子设备心跳，则网关会将子设备设置为离线。

参数说明

返回值

tuya_iot_fresh_dev_hb

函数原型

OPERATE_RET tuya_iot_fresh_dev_hb(IN CONST CHAR_T *dev_id);

功能说明

当网关收到子设备心跳信息，调用此函数刷新该子设备心跳状态。

参数说明

返回值

9.4 获取子设备信息

tuya_iot_dev_traversal

函数原型

DEV_DESC_IF_S *tuya_iot_dev_traversal(INOUT VOID **iterator);

功能说明

子设备遍历，通过此接口可以遍历网关下所有的子设备。

参数说明

返回值

9.5 子设备群组控制

gw_dev_grp_cb

函数原型

OPERATE_RET gw_dev_grp_cb(IN CONST GRP_ACTION_E action,IN CONST CHAR_T *dev_id,IN CONST CHAR_T *grp_id);

功能说明

在该回调中实现组操作处理命令的实现。

参数说明

返回值

9.6 子设备场景功能

gw_dev_scene_cb

函数原型

OPERATE_RET gw_dev_scene_cb(IN CONST SCE_ACTION_E action,IN CONST CHAR_T *dev_id,\

IN CONST CHAR_T *grp_id,IN CONST CHAR_T *sce_id)

功能说明

在该回调中实现场景处理命令功能。

参数说明

返回值

12 日志管理

AddOutputTerm

函数原型

OPERATE_RET AddOutputTerm(IN CONST CHAR_T *name,IN CONST LOG_OUTPUT term);

功能说明

为tuya_sdk日志新增一个输出回调，用于将日志写到文件。

参数说明

返回值

DelOutputTerm

函数原型

VOID DelOutputTerm(IN CONST CHAR_T *name);

功能说明

注销AddOutputTerm接口注册的日志回调。

参数说明

返回值 VOID

SetLogManageAttr

#include "uni_log.h"
/***********************************************************
 * @Function:SetLogManageAttr
 * @Desc:   设置日志等级
 * @Param:  curLogLevel，可选参数：
 *          LOG_LEVEL_ERR       0  // 错误信息，程序正常运行不应发生的信息 
            LOG_LEVEL_WARN      1  // 警告信息
            LOG_LEVEL_NOTICE    2  // 需要注意的信息
            LOG_LEVEL_INFO      3  // 通知信息
            LOG_LEVEL_DEBUG     4  // 程序运行调试信息，RELEASE版本中删除
            LOG_LEVEL_TRACE     5  // 程序运行路径信息，RELEASE版本中删除
 * @Return: OPRT_OK: success  Other: fail
 * @Note:   不设置时，sdk默认为DEBUG日志等级
***********************************************************/
OPERATE_RET SetLogManageAttr(IN CONST LOG_LEVEL curLogLevel);

SetLogManageAttr

函数原型

OPERATE_RET SetLogManageAttr(IN CONST LOG_LEVEL curLogLevel);

功能说明

设置日志等级。

参数说明

返回值

13 错误码说明

• 便于开发调试过程中定位问题，会持续更新。

14 常见问题(FAQ)

14.1 tuya_sdk会占用那些端口，用途是？

• 6668->tcp,局域网通信端口
• 6667->udp,局域网广播端口
• 8883,mqtt_tls通信端口
• https通信端口

14.2 固件下载过程中网络断开时，tuya_sdk会超时多久退出升级状态 ？

• 设备和https服务器断开后，tuya_sdk会尝试重新建立连接(连接超时参数30s)，
• 累积重试8次还没有连接成功，即退出升级状态。

14.3 设备安装固件还没完成，TuyaApp已经提示升级失败，是什么原因 ？

• 涂鸦智能APP，固件升级结果显示的机制：超时60s没有收到设备上报的进度更新时，即显示升级失败；
• 收到进度更新时，重新计时，等待60s;
• 设备端可在安装固件时，上报进度更新延长TuyaApp超时时间。

14.4 tuya_sdk下载固件是否支持断点续传 ？

• 支持～

14.5 是否有取消升级接口，比如对于电池供电的设备，当电量不足时，设备收到升级消息后，取消升级

• OPERATE_RET tuya_iot_refuse_upgrade(IN CONST FW_UG_S fw, IN CONST CHAR_T dev_id);

14.6 设备和手机APP无法建立局域网通信 ？

• 确认下6667/6668端口是否被其他进程占用
• 确认下手机ip地址和设备ip地址是否处于同一个网段
• 确认下设备是否分享给他人，设备只可以和一个手机建立局域网通信
• 检查get_ip接口实现，传给sdk的ip字段是否正确