简体中文
简体中文
English
联系我们
注册
登录
layout空间导航

API 说明

更新时间:2022-11-24 09:20:13下载pdf

本文主要提供涂鸦 NB-IoT 模组用户 SDK API 接口。API 采用接口功能分类,相关组合接口均是放在同一处。

在 API 使用过程中,若存在疑问以及释义不清晰的地方,请在文档下方提交反馈。

名词解释

名词 释义
PID 即 Product ID,是涂鸦 IoT 开发平台创建产品的唯一 ID。
DP 点 即用户在涂鸦 IoT 开发平台创建产品时配置的设备功能点。
IMEI IMEI 是设备唯一标识符,是记录在 NB-IoT 设备的一串字符信息,可以用 IMEI 来区分是某一台 NB 设备。
IMSI IMSI 表示国际移动用户识别码,是区别移动用户的标志,储存在 SIM 卡中,可用于区别移动用户的有效信息。其总长度不超过 15 位,同样使用 0~9 的数字。
ICCID ICCID 是集成电路卡识别码即 SIM 卡的卡号,相当于手机号码的身份证。 ICCID 为 IC 卡的唯一识别号码,共有 20 位字符组成。
Schema 文件 涂鸦 IoT 开发平台生成的包含产品 DP 点信息的 JSON 文件,一般在设备首次上电或者更改 PID 以后进行下载。
记录性数据与非记录型数据 记录型数据是保证数据稳定性的一种数据类型,即在 NB-IoT 设备处于弱网场景下上报该数据点失败时,模组会保存该数据,确保在网络良好的时候再次上报,而非记录型数据在弱网上报失败时则会丢失。
产测 即生产测试,产测一般包含烧录和授权的过程。
绑定 即手机 App 与设备进行绑定的操作,前提是设备已经完成了上电初始化激活。

调试接口

日志调试相关的接口调用。

设置日志开关

函数原型 void tuya_user_elog_switch (IN bool on)
参数
  • true:打开日志
  • false:关闭日志
功能 设置日志开关(系统重启生效,开启日志影响功耗)
头文件 #include <tuya_user_api.h>
返回值

设置涂鸦 SDK 层的日志过滤级别

函数原型 void tuya_user_api_set_sdk_dbg_filter_level (unsigned char filter_level)
参数 filter_level:SDK 层的日志级别,具体请参照下文 filter_level 取值宏定义的详细说明
功能 设置涂鸦 SDK 层的日志过滤级别
头文件 #include <tuya_user_api.h>
返回值

filter_level 取值宏定义

filter_level 取值下高等级的打印等级,会打印本身级别以下(包含本身等级)的日志:

  • ELOG_LVL_ASSERT:值为 0,表示只会打印 ASSERT 级以下日志。
  • ELOG_LVL_ERROR:值为 1,表示只会打印 ERROR 级以下日志,调用 USER_API_LOGE
  • ELOG_LVL_WARN:值为 2,表示只会打印 WARN 级以下日志,调用 USER_API_LOGW
  • ELOG_LVL_INFO:值为 3,表示只会打印 INFO 级以下日志,调用 USER_API_LOGI
  • ELOG_LVL_DEBUG:值为 4,表示只会打印 DEBUG 级以下日志,调用 USER_API_LOGD
  • ELOG_LVL_VERBOSE:值为 5,表示只会打印 VERBOSE 级以下日志,调用 USER_API_LOGV

打印 HEX 类型的数据信息

函数原型 #define USER_API_HEX_DUMP(name, width, buf, size) elog_hexdump(name, width, buf, size)
参数
  • name:作为此次打印数据的数据对象标识符,会在打印头显示
  • width:每一行打印的 16 进制数个数,比如,16/32 个。
  • Buf:待打印的数据缓存区指针
  • Size:待打印的数据缓存区的数据字节长度。
功能 打印 HEX 类型的数据信息。
头文件 #include <tuya_user_api.h>
返回值

数据 KV 存储接口

用户可以使用以下接口写入/获取/删除相关数据信息。

写入数据信息至 flash

函数原型 int tuya_user_api_config_item_set(IN const char *in_key, IN const void *val, IN int len)
参数
  • in_key:待写入配置的标识符。
  • val:待写入配置的数据。
  • len:待写入配置的数据长度。
功能 写入配置信息至 flash。
头文件 #include <tuya_user_api.h>
返回值
  • 0:写入配置成功
  • 其它值:写入配置失败

从 flash 中读取数据信息

函数原型 int tuya_user_api_config_item_get (IN const char *in_key, OUT void *out_buffer, OUT int *out_buffer_len)
参数
  • in_key:待读取配置的标识符
  • val:待读取配置的数据缓存区
  • len:待读取配置的缓存数据字节长度。
功能 从 flash 中读取配置信息
头文件 #include <tuya_user_api.h>
返回值
  • 0:读取配置成功
  • 其它值:读取配置失败

从 flash 中删除该数据

函数原型 int32_t tuya_user_api_config_item_delete (IN const char *key)
参数 key:待删除配置的标识符
功能 从 flash 中删除该配置
头文件 #include <tuya_user_api.h>
返回值
  • 0:删除配置成功
  • 其它值:删除配置失败

写入数据信息至 flash(大数据量)

函数原型 INT_T tuya_user_api_kv_large_set(IN CONST PCHAR_T in_key, IN CONST PVOID_T val, IN INT_T len);
参数
  • in_key:待写入的 key 标识符
  • val:待写入的数据
  • len:待写入的数据长度
功能 写入数据信息至 flash(大数据量)
头文件 #include <tuya_user_api.h>
返回值
  • 0:成功
  • -1:空间不足
  • -2:未找到 key
  • -3:其他错误
  • -4:key 长度过长

从 flash 中读取数据信息(大数据量)

函数原型 INT_T tuya_user_api_kv_large_get(IN CONST PCHAR_T in_key, OUT CONST PVOID_T out_buffer, OUT PINT_T out_buffer_len);
参数
  • in_key:待读取的 key 标识符
  • out_buffer:待读取数据所在的缓冲区
  • lout_buffer_len:待读取数据的长度
功能 从 flash 中读取数据信息(大数据量)
头文件 #include <tuya_user_api.h>
返回值
  • 0:成功
  • -1:空间不足
  • -2:未找到 key
  • -3:其他错误
  • -4:key 长度过长

从 flash 中删除数据(大数据量)

函数原型 INT_T tuya_user_api_kv_large_delete(IN CONST PCHAR_T in_key);
参数 in_key 待删除的 key 标识符
功能 从 flash 中删除数据(大数据量)
头文件 #include <tuya_user_api.h>
返回值
  • 0:成功
  • -1:空间不足
  • -2:未找到 key
  • -3:其他错误
  • -4:key 长度过长

系统事件处理接口

该接口主要用于用户层获取 SDK 层的相关事件。

设置事件捕获回调函数

函数原型 system_event_cb_t tuya_user_api_event_loop_set_cb (IN system_event_cb_t cb, IN void* ctx)
参数
  • cb:待注册的事件处理回调函数指针,具体请参照下文函数指针类型 system_event_cb_t 的详细说明
  • ctx:事件处理回调函数的第一个参数,(目前保留,可以用作用户数据传递)
功能 设置事件捕获回调函数
头文件 #include <tuya_user_api.h>
返回值 返回上一个注册的主事件处理回调函数指针

具体请参考 SDK 包 tuya_comm.h 头文件。可供用户使用的事件枚举如下:

typedef int (*system_event_cb_t)(void *ctx, system_event_t *event);

typedef enum {
    SYSTEM_EVENT_ID_CARD,        //设备识别到 SIM 卡正常
    SYSTEM_EVENT_NETWORK_READY,    //成功附着基站
    SYSTEM_EVENT_NETWORK_DISCONNECT,  //网络断开
    SYSTEM_EVENT_GOING_SLEEP,      //正在进入睡眠
    SYSTEM_EVENT_GOING_REBOOT,     //设备正在重启
    EVENT_LWM2M_CONNECTED,       //已连接 LWM2M 服务器
    EVENT_LWM2M_READY,         //LWM2M 网络服务已可用
    EVENT_LWM2M_UPDATE_SUCCESS,    //数据上报成功
    EVENT_LWM2M_RESPONSE_SUCCESS,   //数据响应成功
    EVENT_LWM2M_RESTART,        //LWM2M 重连
    EVENT_DEVICE_INFO_RESET,      //设备信息重置
    EVENT_DEVICE_BIND_ON,       //设备已绑定
    EVENT_DEVICE_UNBIND_ON,      //设备未绑定
    EVENT_DEVICE_DEACTIVE,       //设备重置 
    EVENT_POWERKEY_PRESS,       //POWER 按键按下
    EVENT_TRIGGER_TMSRV,    // 触发本地定时检测
    EVENT_COMPOSITE_ACTIVE_SUCCESS,  //复合产品 NB 为 X 模组激活成功
    EVENT_LWDP_PACKET_SEND,         //lwdp 数据包异步发送
    EVENT_SLEEP_TYPE,        //睡眠事件类型
    EVENT_DISCRETE_ON,       //离散开始
    EVENT_CFUN_ON,
    SYSTEM_EVENT_MAX
} system_event_id_t;

启动事件捕获任务

函数原型 int tuya_user_api_event_loop_start(void)
参数
功能 启动事件捕获任务
头文件 #include <tuya_user_api.h>
返回值
  • 0:函数执行正常
  • 其它:异常

设备信息操作接口

用户可以获取当前设备状态相关的一些信息。

获取设备激活状态

函数原型 int tuya_user_api_is_dev_actived (void)
参数
功能 获取设备激活状态(判断设备 ID 是否为空且设备密钥是否为空)
头文件 #include <tuya_user_api.h>
返回值
  • 1:设备已被激活
  • 0:设备未激活

获取当前设备绑定状态

函数原型 int tuya_user_api_is_dev_binded (void)
参数
功能 获取当前设备绑定状态
头文件 #include <tuya_user_api.h>
返回值
  • 0:设备未绑定
  • 1:设备已绑定

获取当前设备 schema 完整状态

函数原型 bool tuya_user_api_schema_is_completed (void)
参数
功能 获取当前设备 schema 完整状态
头文件 #include <tuya_user_api.h>
返回值
  • true: 完成;
  • false: 未完成

获取当前设备 cesq 相关参数

函数原型 INT_T tuya_user_api_cesq_get (extended_signal_quality_t *info)
参数 info:返回的 cesq 相关信息,具体请参照结构体 extended_signal_quality_t
功能 获取当前设备 cesq 相关参数
头文件 #include <tuya_user_api.h>
返回值
  • 0:函数执行正常
  • 其它:函数执行异常,数据不可用

详细说明

结构体 extended_signal_quality_t

typedef struct {
    int32_t rxlev; //接收信号等级,RSSI 收信信号电平将被映射到 0~63 之间的某个 RXLEV 值,基          站测干扰依据,RSSI 与 rxlev 存在对应关系 
    int32_t ber;   //误码率,不能太大,否则有噪声,取值 0~99,一般为 0 
    int32_t rscp;  //接收信号功率 
    int32_t ecno;  //信号的能量与干扰能量(如同频干扰,多径等)和加性噪声能量的和的比值 
    int32_t rsrq;  //参考信号接收质量,反映当前信号质量和信噪比和干扰水平取值 -3~-19.5,值越大越好  
    int32_t rsrp;  //参考信号接收功率,小区覆盖和小区选择和、重选依据,-44~-140dBm,值越大越好 
} extended_signal_quality_t;

获取设备接收信号强度值 RSSI

函数原型 INT_T tuya_user_api_rssi_get (void)
参数
功能 获取设备接收信号强度值 rssi
头文件 #include <tuya_user_api.h>
返回值 返回的信号强度(为带符号的整型,理论上 0 为最强,一般为负值)

详细说明

RSSI: 一般为接近 0 的负数,正常应处于 0~-70,小于 -70,则表示环境干扰太大。

获取当前设备的 IMSI

函数原型 CHAR_T *tuya_user_api_imsi_get (void)
参数
功能 获取当前设备的 IMSI
头文件 #include <tuya_user_api.h>
返回值 返回的 IMSI 字符串指针

详细说明

IMSI:表示国际移动用户识别码,是区别移动用户的标志,储存在 SIM 卡中,可用于区别移动用户的有效信息。其总长度不超过 15 位,同样使用 0~9 的数字。

获取当前设备的 ICCID

函数原型 CHAR_T *tuya_user_api_iccid_get (void)
参数
功能 获取当前设备的 ICCID
头文件 #include <tuya_user_api.h>
返回值 返回的 ICCID 字符串指针

详细说明

ICCID:是集成电路卡识别码即 SIM 卡的卡号,相当于手机号码的身份证。ICCID 为 IC 卡的唯一识别号码,共有 20 位字符组成。

获取当前设备的 IMEI

函数原型 int tuya_user_api_get_dev_imei (OUT char* device_imei)
参数 device_imei:返回获取到的 IMEI 字符串指针
功能 获取当前设备的 IMEI
头文件 #include <tuya_user_api.h>
返回值 返回的 IMEI 的长度(正常为 15 位)

详细说明

IMEI:是设备唯一标识符,是记录在 NB-IoT 设备的一串字符信息,可以用 IMEI 来区分是某一台 NB-IoT 设备。每个出厂设备的 IMEI 由涂鸦在出厂就写入了设备,用户不要随意更改,如果设备 IMEI 查询为空,则设备无法正常使用。

获取当前设备的产品 ID(PID)

函数原型 int tuya_user_api_get_dev_product_key (OUT char* product_key)
参数 product_key:返回的产品 ID(PID)的指针
功能 获取当前设备的产品 ID(PID)
头文件 #include <tuya_user_api.h>
返回值 返回获取的产品 ID(PID)的长度

详细说明

产品 ID(PID):即是每一类产品,会由涂鸦分配一个专有的 ID,作为这类产品的标识。产品 ID 分类原则是以涂鸦为准,请用户使用涂鸦 NB-IoT 设备时,要核对自己的产品 ID 是否正确(联系涂鸦产品或者项目经理)。

设置当前设备的产品 ID(PID)

函数原型 int tuya_user_api_set_product_key (IN char* product_key)
参数 product_key:返回的产品 ID(PID)指针
功能 设置当前设备的产品 ID(PID)
头文件 #include <tuya_user_api.h>
返回值 返回设置的产品 ID(PID)的长度

详细说明

产品 ID(PID):即是每一类产品,会由涂鸦分配一个专有的 ID,作为这类产品的标识。产品 ID 分类原则是以涂鸦为准,请用户使用涂鸦 NB-IoT 设备时,要核对自己的产品 ID 是否正确(联系涂鸦产品或者项目经理)。

设置当前 MCU(上位机)的固件版本

函数原型 int tuya_user_api_set_soft_ver (IN char* version)
参数 version: 用来存放版本字符串的数组
功能 设置当前 MCU(上位机)的固件版本
头文件 #include <tuya_user_api.h>
返回值 写到 version[] 数组中的字符长度,单位:字节

详细说明

MCU(上位机)的固件版本:其表示与 NB-IoT 设备串口连接的 MCU 设备的固件版本,并不是 NB-IoT 设备的固件版本。

设置当前设备的心跳时间间隔

函数原型 void tuya_user_api_lifetime_set (IN uint32_t lifetime)
参数 lifetime:待设置的时间,单位:s
功能 设置当前设备的心跳时间间隔
头文件 #include <tuya_user_api.h>
返回值

详细说明

lifetime 取值范围:正常为 120 < lifetime ≤ 604800。如果 lifetime 设置小于 120,则实际设置为 120,如果 lifetime 设置值为 0 或大于 604800,则实际设置为 604800,单位:s。

接口适用范围:此接口配置的是非记录型 lifetime。

设备弱网下休眠后记录型数据的上报时间间隔

函数原型 void tuya_user_api_record_dp_lifetime_set (IN uint32_t lifetime)
参数 lifetime:待设置的时间,单位:s
功能 设备弱网下休眠后,设置记录型数据的上报时间间隔
头文件 #include <tuya_user_api.h>
返回值

lifetime 取值范围:正常为 120 < lifetime ≤ 604800。如果 lifetime 设置小于 120,则实际设置为 120,如果 lifetime 设置值为 0 或大于 604800,则实际设置为 604800,单位:s。

接口适用范围:此接口配置的是记录型 lifetime。

获取记录型数据的上报时间间隔

函数原型 uint32_t tuya_user_api_get_dev_record_dp_lifetime (void)
参数
功能 获取记录型数据的上报时间间隔
头文件 #include <tuya_user_api.h>
返回值 返回记录型数据的上报时间间隔值,单位:s

获取当前设备的心跳时间间隔

函数原型 uint32_t tuya_user_api_get_dev_lifetime (void)
参数
功能 获取当前设备的心跳时间间隔
头文件 #include <tuya_user_api.h>
返回值 当前设备的心跳时间,单位:s

获取当前网络健康状况分数

函数原型 unsigned int tuya_user_api_statistic_score (void);
参数
功能 获取当前网络健康状况分数
头文件 #include <tuya_user_api.h>
返回值 网络打分(网络附着/云端注册/数据发送)

OTA 升级处理接口

设置固件升级过程中的电量查询及升级状态回调函数

函数原型 void tuya_user_api_fota_notify_register (IN tuya_fota_context_t* ctx)
参数 ctx:fota 相关内容,具体请参照下文结构体 tuya_fota_context_t 的详细说明
功能 设置固件升级过程中的电量查询及升级状态回调函数
头文件 #include <tuya_user_api.h>
返回值

详细说明

结构体tuya_fota_context_t

typedef struct {
    battery_state_t (*hal_battery_level_get)();
    void (*event_notify)(tuya_fota_event_id_t event_id);
} tuya_fota_context_t;

成员 hal_battery_level_get 为此类函数指针,用户需要在系统启动初始化时,就初始化成员,用户将自身电量接口实现。

成员 event_notify 为 FOTA 事件上报处理函数。

请用户自行参照提供的 SDK 开发,具体定义请参照 SDK 包 tuya_comm.h 文件。

时间处理接口

获取当前系统的 Unix 时间戳

函数原型 TIME_T tuya_user_api_time_get_posix_time (VOID)
参数
功能 获取当前系统的 Unix 时间戳(Unix timestamp),或称 Unix 时间(Unix time)、POSIX 时间(POSIX time),不包含时区,单位 s
头文件 #include <tuya_user_api.h>
返回值 返回的系统 POSIX 时间,单位:s

详细说明

Unix 时间戳(Unix timestamp):或称 Unix 时间(Unix time)、POSIX 时间(POSIX time),从格林威治时间 1970 年 01 月 01 日 00 时 00 分 00 秒起至现在的总"秒数",不包含时区,单位:秒。

TIME_T 类型:也就是 unsigned int 类型。

获取格林时间(UTC)

函数原型 OPERATE_RET tuya_user_api_get_green_time (OUT POSIX_TM_S *tm)
参数 tm:返回的时间参数,具体请参照下文结构体 POSIX_TM_S 的详细说明
功能 获取格林时间(utc),分解时间格式
头文件 #include <tuya_user_api.h>
返回值
  • OPRT_OK:获取时间正常
  • 其它:获取时间异常

详细说明

结构体 POSIX_TM_S

typedef struct {
    INT_T tm_sec;   //秒,[0-59]
    INT_T tm_min;   //分,[0-59]
    INT_T tm_hour;  //小时, [0-23]
    INT_T tm_mday;  //每月第几天, [1-31]
    INT_T tm_mon;   //每年第几个月, [0-11]
    INT_T tm_year;  //自 1990 开始,第几年
    INT_T tm_wday;  //每周第几天, [0-6] 0-星期天...6-星期六
} POSIX_TM_S;

获取本地时间

函数原型 OPERATE_RET tuya_user_api_get_local_time (OUT POSIX_TM_S *tm)
参数 tm:返回的时间参数,具体请参照下文结构体 POSIX_TM_S 的详细说明
功能 获取本地时间
头文件 #include <tuya_user_api.h>
返回值
  • OPRT_OK:获取本地时间正常
  • 其它:获取本地时间异常

详细说明

结构体 POSIX_TM_S

typedef struct {
  INT_T tm_sec;   //秒,[0-59]
  INT_T tm_min;   //分,[0-59]
  INT_T tm_hour;  //小时, [0-23]
  INT_T tm_mday;  //每月第几天, [1-31]
  INT_T tm_mon;   //每年第几个月, [0-11]
  INT_T tm_year;  //自 1990 开始,第几年
  INT_T tm_wday;  //每周第几天, [0-6] 0-星期天...6-星期六
} POSIX_TM_S;

本地时间转换为 Unix 时间戳

函数原型 OPERATE_RET tuya_user_api_local_time2posix_time (IN POSIX_TM_S *tm, OUT TIME_T *timestamp)
参数
  • tm:传入的的时间戳,具体请参照下文结构体 POSIX_TM_S 的详细说明
  • l timestamp:返回的时间秒值
功能 本地时间(utc+时区)转换为:Unix 时间戳(Unix timestamp),或 Unix 时间(Unix time)、POSIX 时间(POSIX time)的总"秒数",不包含时区
头文件 #include <tuya_user_api.h>
返回值
  • OPRT_OK:时间转换正常
  • 其它:时间转换异常

详细说明

结构体 POSIX_TM_S

typedef struct {
  INT_T tm_sec;   //秒,[0-59]
  INT_T tm_min;   //分,[0-59]
  INT_T tm_hour;  //小时, [0-23]
  INT_T tm_mday;  //每月第几天, [1-31]
  INT_T tm_mon;   //每年第几个月, [0-11]
  INT_T tm_year;  //自 1990 开始,第几年
  INT_T tm_wday;  //每周第几天, [0-6] 0-星期天...6-星期六
} POSIX_TM_S;

获取本地时间是否同步

函数原型 OPERATE_RET tuya_user_api_time_check_time_sync (void)
参数
功能 获取本地时间是否同步
头文件 #include <tuya_user_api.h>
返回值
  • OPRT_OK:正常
  • 其它:异常

获取系统从启动到现在的运行时间

函数原型 VOID tuya_user_api_get_system_runtime (OUT TIME_S *pSecTime,OUT TIME_MS *pMsTime);
参数
  • pSecTime:返回的时间值,单位:s
  • pMsTime:返回的时间值,单位:ms
功能 获取系统从启动到现在的运行时间(请注意参数返回值单位)
头文件 #include <tuya_user_api.h>
返回值

心跳包定时器重启

函数原型 void tuya_user_api_heart_beat_send_timer_restart (void);
参数
功能 心跳包定时器重启
头文件 #include <tuya_user_api.h>
返回值

休眠定时器启动接口

函数原型 void tuya_user_api_sleep_tmr_start(void (callback)(void data), uint32_t time_s);
参数
  • callback:定时器回调
  • time_s:定时时间
功能 休眠定时器启动
头文件 #include <tuya_user_api.h>
返回值

休眠定时器停止接口

函数原型 void tuya_user_api_sleep_tmr_stop(void);
参数
功能 休眠定时器停止
头文件 #include <tuya_user_api.h>
返回值

DP 数据点操作接口

提供了 DP 点相关的操作接口。

设置云端下发数据点的回调函数

函数原型 int tuya_user_api_dp_write_default_cb (IN lwdp_write_callback_t cb)
参数 cb:待设置的回调函数指针,具体请参照下文详细说明
功能 设置云端下发数据点的回调函数
头文件 #include <tuya_user_api.h>
返回值
  • 0:函数执行正常
  • 其它:函数执行异常

详细说明

函数指针lwdp_write_callback_t

// 用户根据此定义,定义自己的一个函数实现,并传入相应 API 接口
typedef uint8_t (*lwdp_write_callback_t)(lwdp_object_t* objectArrayP); 

设置非记录型数据点上报结果的回调函数

函数原型 void tuya_user_api_dp_report_ack_register_cb (IN tuya_dp_ack_callback_t cb)
参数 cb:待设置的回调函数指针,具体请参照下文详细说明
功能 设置非记录型数据点上报结果的回调函数
头文件 #include <tuya_user_api.h>
返回值
  • 0:函数执行正常
  • 其它:函数执行异常

详细说明

函数指针tuya_dp_ack_callback_t

// 用户根据此定义,定义自己的一个函数实现,并传入相应 API 接口
typedef void (*tuya_dp_ack_callback_t)(uint16_t msgid, uint8_t result);

获取非记录型数据的数量个数

函数原型 int tuya_user_api_not_record_packet_count(void)
参数
功能 获取非记录型数据的数量
头文件 #include <tuya_user_api.h>
返回值 返回非记录型数据数量

设置记录型数据点上报结果的回调函数

函数原型 void tuya_user_api_dp_report_record_ack_register_cb (IN tuya_dp_ack_callback_t cb)
参数 cb:待设置用户 DP 点上报回调函数指针
功能 设置记录型数据点上报结果的回调函数
头文件 #include <tuya_user_api.h>
返回值

详细说明

函数指针tuya_dp_ack_callback_t

// 用户根据此定义,定义自己的一个函数实现,并传入相应 API 接口
typedef void (*tuya_dp_ack_callback_t)(uint16_t msgid, uint8_t result);

发送心跳数据

函数原型 void tuya_user_api_heartbeat_send (void)
参数
功能 发送心跳数据
头文件 #include <tuya_user_api.h>
返回值

数据点上报

函数原型 int tuya_user_api_dp_report (IN bool is_record_type, IN int size, IN lwdp_object_t* dataP)
参数
  • is_record_type : true(记录型数据),false(非记录型数据)
  • size : 多少个数据项
  • dataP : DP 点数据指针,具体请参照下文结构体[^lwdp_object_t] 的详细说明
功能 数据点上报
头文件 #include <tuya_user_api.h>
返回值
  • 0:正常
  • 其它值:异常,数据不可用

创建数据点空间

函数原型 lwdp_object_t* tuya_user_api_lwdp_object_new(IN int size)
参数 size : 创建数据点个数
功能 创建数据点空间
头文件 #include <tuya_user_api.h>
返回值 返回 DP 点实例的指针,具体请参考详细说明结构体[^lwdp_object_t]

释放数据点空间

函数原型 void tuya_user_api_lwdp_object_free (IN int size, IN lwdp_object_t* dataP)
参数
  • size : 释放的数据点个数
  • dataP : 释放的数据点起始地址,具体请参考详细说明结构体[^lwdp_object_t]
功能 释放数据点空间
头文件 #include <tuya_user_api.h>
返回值 DP 点实例的指针

获取 当前 DP 数据包的字节长度

函数原型 uint16_t tuya_user_api_get_lwdp_object_length (IN lwdp_object_t* dataP)
参数 dataP:待获取的lwdp_object_t对象,具体请参考详细说明结构体[^lwdp_object_t]
功能 获取 当前 DP 数据包的字节长度
头文件 #include <tuya_user_api.h>
返回值

解码一个布尔型数据点信息

函数原型 int tuya_user_api_lwdp_decode_bool (IN lwdp_object_t* dataP, OUT bool* outP)
参数
  • dataP:待解码的lwdp_object_t对象,具体请参考详细说明结构体[^lwdp_object_t]
  • outP:解码出来的bool数据
功能 解码一个布尔型数据点信息
头文件 #include <tuya_user_api.h>
返回值

解码一个整型数据点信息

函数原型 int tuya_user_api_lwdp_decode_int (IN lwdp_object_t* dataP, OUT int32_t* outP)
参数
  • dataP:待解码的lwdp_object_t对象,具体请参考详细说明结构体[^lwdp_object_t]
  • outP:解码出来的 int 数据
功能 解码一个整型数据点信息
头文件 #include <tuya_user_api.h>
返回值
  • 0:函数执行正常
  • 其它函数执行异常,数据不可用

解码一个原始数据类型数据点信息

函数原型 int tuya_user_api_lwdp_decode_raw (IN lwdp_object_t* dataP, OUT uint8_t* outP, OUT size_t* olen)
参数
  • dataP:待解码的lwdp_object_t对象,具体请参考详细说明结构体[^lwdp_object_t]
  • outP:解码出来的 raw 数据
  • olen:解码出来的 raw 数据字节长度
功能 解码一个原始数据类型数据点信息
头文件 #include <tuya_user_api.h>
返回值
  • 0:函数执行正常
  • 其它函数执行异常,数据不可用

解码一个字符串型数据点信息

函数原型 int tuya_user_api_lwdp_decode_string (IN lwdp_object_t* dataP, OUT char* outP, OUT size_t* olen)
参数
  • dataP:待解码的lwdp_object_t对象,具体请参考详细说明结构体[^lwdp_object_t]
  • outP:解码出来的string字符串指针
  • olen:返回解码出来的string字符串长度
功能 解码一个字符串型数据点信息
头文件 #include <tuya_user_api.h>
返回值
  • 0:函数执行正常
  • 其它:函数执行异常,数据不可用

解码一个枚举类型数据点信息

函数原型 int tuya_user_api_lwdp_decode_enum (IN lwdp_object_t* dataP, OUT uint8_t* enum_idx)
参数
  • dataP:待解码的lwdp_object_t对象,具体请参考详细说明结构体[^lwdp_object_t]
  • enum_idx:解码出来的enum枚举下标
功能 解码一个枚举类型数据点信息
头文件 #include <tuya_user_api.h>
返回值
  • 0:函数执行正常
  • 其它:函数执行异常,数据不可用

编码一个布尔型数据点信息

函数原型 void tuya_user_api_lwdp_encode_bool (IN bool value, OUT lwdp_object_t* dataP)
参数
  • value:待编码的bool数据
  • dataP:待编码的lwdp_object_t对象,具体请参考详细说明结构体[^lwdp_object_t]
功能 编码一个布尔型数据点信息
头文件 #include <tuya_user_api.h>
返回值

编码一个原始数据类型数据点信息

函数原型 void tuya_user_api_lwdp_encode_raw (IN uint8_t* buffer, IN size_t length, OUT lwdp_object_t* dataP)
参数
  • buffer:待编码成 lwdp_object_t 对象的 raw 类型数据指
  • length:待编码的 raw 类型数据的字节长度
  • dataP:封装后返回的对象,具体请参考详细说明结构体[^lwdp_object_t]
功能 编码一个原始数据类型数据点信息
头文件 #include <tuya_user_api.h>
返回值

编码一个字符串型数据点信息

函数原型 void tuya_user_api_lwdp_encode_string (IN const char* string, OUT lwdp_object_t* dataP)
参数
  • string:待封装成lwdp_object_t对象的string类型数据指针
  • dataP:封装后返回的对象,具体请参考详细说明结构体[^lwdp_object_t]
功能 编码一个字符串型数据点信息
头文件 #include <tuya_user_api.h>
返回值

编码一个字符串型数据点信息(带字符长度)

函数原型 void tuya_user_api_lwdp_encode_nstring (IN const char* string, IN size_t length, OUT lwdp_object_t* dataP)
参数
  • string:待编码成lwdp_object_t对象的 string 类型数据指针
  • length:待编码的string字符串长度
  • dataP:封装后返回的对象,具体请参考详细说明结构体[^lwdp_object_t]
功能 编码一个字符串型数据点信息
头文件 #include <tuya_user_api.h>
返回值

编码一个整型数据点信息

函数原型 void tuya_user_api_lwdp_encode_int (IN int32_t value, OUT lwdp_object_t* dataP)
参数
  • value:待编码成 int 类型的数据
  • dataP:编码后返回的对象,具体请参考详细说明结构体[^lwdp_object_t]
功能 编码一个整型数据点信息
头文件 #include <tuya_user_api.h>
返回值

编码一个枚举类型数据点信息

函数原型 void tuya_user_api_lwdp_encode_enum (IN uint32_t value, OUT lwdp_object_t* dataP)
参数
  • value:待编码成枚举类型的数据
  • dataP:编码后返回的对象,具体请参考详细说明结构体[^lwdp_object_t]
功能 编码一个枚举类型数据点信息
头文件 #include <tuya_user_api.h>
返回值

编码一个位图类型数据点信息

函数原型 void tuya_user_api_lwdp_encode_map (IN uint32_t value, OUT lwdp_object_t* dataP)
参数
  • value:待编码成位图类型的数据
  • dataP:编码后返回的对象,具体请参考详细说明结构体[^lwdp_object_t]
功能 编码一个位图类型数据点信息
头文件 #include <tuya_user_api.h>
返回值

获取系统 rssi 的 DP 数字

函数原型 int tuya_user_api_get_rssi_dp_digit (void)
参数
功能 获取系统 rssi 的 DP 数字
头文件 #include <tuya_user_api.h>
返回值 rssi 的 DP 数字

获取系统时间戳的 DP 数字

函数原型 int tuya_user_api_get_timestamp_dp_digit (void)
参数
功能 获取系统时间戳的 DP 数字
头文件 #include <tuya_user_api.h>
返回值 时间戳的 DP 数字

获取请求数据点对应的数字

函数原型 int tuya_user_api_get_request_dp_digit (void)
参数
功能 获取请求数据点对应的数字
头文件 #include <tuya_user_api.h>
返回值 请求数据点对应的数字

结构体详细说明

typedef struct _lwdp_object_t {
    struct _lwdp_object_* next;   //指向下一个 lwdp_object_t 节点,做链表使用
    uint16_t       id;    //其实就是 DP ID
    lwdp_obj_type_t    type; //参照其它地方赋值即可
    lwdp_obj_mode_t    mode; //参照其它地方赋值即可
    lwdp_obj_value_t   value;  //参照其它地方赋值即可
    lwdp_obj_property_t  property; //参照其它地方赋值即可
} lwdp_object_t;

工作模式配置接口

SIM 卡和设备等模式获取和设置等接口。

设置需谨慎。

获取系统启动原因

函数原型 TAL_PSM_POWER_ON_RESULT_E tuya_user_api_get_powerOn_result (VOID)
参数
功能 获取系统启动原因
头文件 #include <tuya_user_api.h>
返回值 返回系统启动原因枚举值,具体请参照下文详细说明枚举TAL_PSM_POWER_ON_RESULT_E

详细说明,详细请见 SDK 包的tuya_comm.h文件。

枚举TAL_PSM_POWER_ON_RESULT_E

typedef enum {
  TAL_FIRST_BOOT_UP    = 0,   //初次启动
  TAL_DEEP_SLEEP     = 1,   //从轻度睡眠启动
  TAL_DEEPER_SLEEP    = 2,   //从深度睡眠启动
  TAL_SYS_RESET      = 3,   //系统重启
  TAL_WDT_HW_RESET    = 4,   //硬件看门狗启动
  TAL_WDT_SW_RESET    = 5,   //软件看门狗启动
  TAL_FORCED_SHUT_DOWN  = 6,   //强制关机启动
  TAL_FORCED_RESET    = 7,   //强制重启
  TAL_POWER_ON_RESULT_MAX
} TAL_PSM_POWER_ON_RESULT_E;

获取设备唤醒类型

函数原型 TY_WAKEUP_SOURCE_E ty_mw_wakeup_source_get (void)
参数
功能 获取系统唤醒类型
头文件 #include <tuya_user_api.h>
返回值 返回系统启动原因枚举值,具体请参照下文详细说明枚举TY_WAKEUP_SOURCE_E

详细说明

typedef enum {
  TY_WAKEUP_FROM_NONE, //未知唤醒源
  TY_WAKEUP_FROM_POR,  //开机或者复位唤醒
  TY_WAKEUP_FROM_RTC, //从 RTC 唤醒
  TY_WAKEUP_FROM_KEY, //按键唤醒
}TY_WAKEUP_SOURCE_E;

设置当前设备的工作模式

函数原型 OPERATE_RET tuya_user_api_sim_mode_set (IN char* mode)
参数 mode:待设置的 SIM 卡低功耗模式,具体请参照下文详细说明
功能 设置当前设备的工作模式(PSMDRXEDRX)
头文件 #include <tuya_user_api.h>
返回值
  • OPRT_OK:正常
  • 其它:异常,不可取

详细说明

参数 mode 取值范围:“psm”,“drx”,“edrx”,或者"PSM",“DRX”,“EDRX”,禁止"Psm"这类大小写混用的情况(此类传入无效)。字符串字面意思即表示设置的功耗模式。

设置当前设备的连接模式

函数原型 bool tuya_user_api_connect_mode_set (IN char* mode)
参数 mode:带设置的连接模式(tuya/代理),具体请参照下文详细说明
功能 设置当前设备的连接模式
头文件 #include <tuya_user_api.h>
返回值
  • true:设置成功
  • false:设置失效

详细说明

参数 mode 取值范围:可传入"tuya"或"TUYA",表示设置 NB 设备直连云端。其它字符串,则表示设置为"ISP"连接模式,即 NB 设备连接代理服务器(运营商云平台)。

获取当前设备的工作模式(功耗模式)

函数原型 nbiot_mode_t tuya_user_api_sim_mode_get (void)
参数
功能 获取当前设备的工作模式(功耗模式)
头文件 #include <tuya_user_api.h>
返回值 返回此时的设备的工作模式(功耗模式),具体请参照枚举nbiot_mode_t

详细说明

枚举 nbiot_mode_t:

typedef enum {
  NBIoT_MODE_PSM,      //PSM 模式
  NBIoT_MODE_DRX,      //DRX 模式
  NBIoT_MODE_EDRX      //EDRX 模式
} nbiot_mode_t;

禁止当前设备进入睡眠模式

函数原型 void tuya_user_api_psm_disable (void)
参数
功能 禁止当前设备进入睡眠模式
头文件 #include <tuya_user_api.h>
返回值

允许当前设备进入睡眠模式

函数原型 void tuya_user_api_psm_enable (void)
参数
功能 允许当前设备进入睡眠模式
头文件 #include <tuya_user_api.h>
返回值

立刻释放睡眠锁允许当前设备进入睡眠模式

函数原型 void tuya_user_api_enter_psm (void)
参数
功能 立刻释放睡眠锁,允许当前设备进入睡眠模式
头文件 #include <tuya_user_api.h>
返回值

设置当前的网络接入 APN 名称

函数原型 void tuya_user_api_set_apn (char *apn, char *pdp_type)
参数
  • apn : APN 名称字符串
  • pdp_type : 分组数据协议的类型,IP,IPV6,IPV4V6,Non-IP,一般取IP即可
功能 设置当前的网络接入 APN 名称
头文件 #include <tuya_user_api.h>
返回值

详细说明

此接口用户无需自主设置。

强迫当前设备立即进入睡眠模式

函数原型 void tuya_user_api_forced_sleep (void)
参数
功能 强迫当前设备立即进入睡眠模式
头文件 #include <tuya_user_api.h>
返回值

重启设备

函数原型 void tuya_user_api_going_reboot(void);
参数
功能 重启设备
头文件 #include <tuya_user_api.h>
返回值

设置当前设备 T3324 时间

函数原型 OPERATE_RET tuya_user_api_write_t3324(int64_t req_time)
参数 req_time:待写入的时间,单位:s
功能 设置当前设备 T3324 时间
头文件 #include <tuya_user_api.h>
返回值
  • OPRT_OK:正常
  • 其它:异常,不可取

设置当前设备 T3412 时间

函数原型 OPERATE_RET tuya_user_api_write_t3412(int64_t req_time)
参数 req_time:待写入的时间,单位:s
功能 设置当前设备 T3412 时间
头文件 #include <tuya_user_api.h>
返回值
  • OPRT_OK:正常
  • 其它:异常,不可取

设置离散信息

函数原型 OPERATE_RET tuya_user_api_set_discrete_info(bool discrete_on, uint16_t duration, uint8_t step)
参数
  • discrete_on:开启/关闭离散
  • duration:离散的随机数种子范围(120-1800)单位为S
  • step:离散的最小梯度,1:step为60S 0:step为30S
功能 设置离散信息
头文件 #include <tuya_user_api.h>
返回值
  • 0:函数执行正常
  • 其它:函数执行异常

详细说明

该接口可配置 NB-IoT 模组首次启动的离散信息,使设备错峰启动、优化网络阻塞,可用于安装比较密集的产品中。

请酌情使用该接口,若设备采用主动断电的场景,禁用该功能!

非涂鸦 IoT 云接入相关用户层接口

设置当前接入非涂鸦 IoT 云的信息

函数原型 INT_T tuya_user_api_3rd_cloud_config(TAL_NBIOT_LWM2M_REGISTER_T *lwm2m_config)
参数 lwm2m_config:非涂鸦 IoT 云的接入信息
功能 设置当前接入非涂鸦云的信息
头文件 #include <tuya_user_api.h>
返回值
  • 0:函数执行正常
  • 其它:函数执行异常

详细说明

typedef struct {
    TAL_NBIOT_EVENT_CB 	event_cb;                   // lwm2m event send callback
    UCHAR_T                 evt_id_ready;               // lwm2m ready event 
    UCHAR_T 		    evt_id_connected;       // lwm2m connected event 
    UCHAR_T 		    evt_id_update_success;  // lwm2m update successful event 
    UCHAR_T 		    evt_id_rsp_success;     // lwm2m response successful event 
    
    BOOL_T  		    bootstrap_en;           // boot strap enable
    TAL_NBIOT_ISP_T     isp_type;                   // connect isp type,refer to TAL_NBIOT_ISP_T
    UINT_T   		    lifetime;               // life time with the server
    UINT_T	            srv_port;               // desired port of lwm2m server
    CHAR_T *                srv_ip;                 // desired ip address of lwm2m server
    CHAR_T *		    imei;                   // imei of the client
    CHAR_T *                psk;                    // psk used for dtls
    TAL_NBIOT_OBJ_ATTRI attri;                      // object attribute;
    
    TAL_NBIOT_REV_DATA_CB data_recv_cb;             // data reveive callback
}TAL_NBIOT_LWM2M_REGISTER_T;

注意事项:

连接方式 支持模式 端口 bootstrap 状态 支持 SIM 卡类型 备注
移动 非 DTLS 5683
  • DRX 模式:禁用
  • PSM 模式:开启
  • 移动卡 DRX 仅支持移动专网 APN(CMNBIOTONENET)
    电信 DTLS 5684 禁用 电信卡
    直连 DTLS 5684 禁用 移动卡

    使用举例

    电信运营商 :
    TAL_NBIOT_LWM2M_REGISTER_T params;
    params.bootstrap_en     = 0;                        // ctcc及直连:不开启bs。cmcc:drx 专网不开启,psm 网络开启
    params.srv_ip           = "221.229.214.202";         //服务器地址,电信线上
    params.srv_port         = 5684;                     //服务器端口号,5684(加密),5683(不加密),移动暂时支持不加密
    params.isp_type         = NBIOT_ISP_OTHER;          //NBIOT_ISP_TUYA:表示直连三方云,否则连运营商云中转
    params.lifetime         = 7200;                     //LwM2M 协议交互心跳间隔,单位:秒
    params.psk              = "bFFFcDDDEB7aaBbc";       //16~32 个字符 LwM2M 协议交互秘钥
    //params.imei             = "862363050000149";        //15 个字符的 IMEI,可以由底层获取,可选!/*endpoint_name,pskid*/
    //device attribute:
    params.attri.obj_id = 19;
    params.attri.ins_id_up = 0;
    params.attri.ins_id_down = 1;
    params.attri.res_id = 0;
    tuya_user_api_3rd_cloud_config(&params);  
    
    移动运营商 DRX 模式:
    
    TAL_NBIOT_LWM2M_REGISTER_T params;
    params.bootstrap_en     = 0;                        // ctcc及直连:不开启bs。cmcc:drx 专网不开启,psm 网络开启
    params.srv_ip           = "192.168.24.100";         //服务器地址,移动专网
    params.srv_port         = 5683;                     //服务器端口号,5684(加密),5683(不加密),移动暂时支持不加密
    params.isp_type         = NBIOT_ISP_OTHER;          //NBIOT_ISP_TUYA:表示直连三方云,否则连运营商云中转
    params.lifetime         = 7200;                     //LwM2M 协议交互心跳间隔,单位:秒
    //params.psk              = "bFFFcDDDEB7aaBbc";       //16~32 个字符 LwM2M 协议交互秘钥
    //params.imei             = "862363050000149";        //15 个字符的 IMEI,可以由底层获取,可选!/*endpoint_name,pskid*/
    //device attribute:
    params.attri.obj_id = x;
    params.attri.ins_id_up = x;
    params.attri.ins_id_down = x;
    params.attri.res_id = x;
    tuya_user_api_3rd_cloud_config(&params);  
    
    移动运营商 PSM 模式:
    
    TAL_NBIOT_LWM2M_REGISTER_T params;
    params.bootstrap_en     = 1;                        // ctcc及直连:不开启bs。cmcc:drx 专网不开启,psm 网络开启
    params.srv_ip           = "183.230.40.39";         //服务器地址,移动
    params.srv_port         = 5683;                     //服务器端口号,5684(加密),5683(不加密),移动暂时支持不加密
    params.isp_type         = NBIOT_ISP_OTHER;          //NBIOT_ISP_TUYA:表示直连三方云,否则连运营商云中转
    params.lifetime         = 7200;                     //LwM2M 协议交互心跳间隔,单位:秒
    //params.psk              = "bFFFcDDDEB7aaBbc";       //16~32 个字符 LwM2M 协议交互秘钥
    //params.imei             = "862363050000149";        //15 个字符的 IMEI,可以由底层获取,可选!/*endpoint_name,pskid*/
    //device attribute:
    params.attri.obj_id = x;
    params.attri.ins_id_up = x;
    params.attri.ins_id_down = x;
    params.attri.res_id = x;
    tuya_user_api_3rd_cloud_config(&params);  
    
    直连第三方云:
    
    TAL_NBIOT_LWM2M_REGISTER_T params;
    params.bootstrap_en     = 0;                        // ctcc及直连:不开启 bs。cmcc:drx 专网不开启,psm 网络开启
    params.srv_ip           = "XXX.XXX.XXX.XXX";         //服务器地址,第三方云
    params.srv_port         = 5684;                     //服务器端口号,5684(加密),5683(不加密),移动暂时支持不加密
    params.isp_type         = NBIOT_ISP_TUYA;          //NBIOT_ISP_TUYA:表示直连三方云,否则连运营商云中转
    params.lifetime         = 7200;                     //LwM2M 协议交互心跳间隔,单位:秒
    params.psk              = "bFFFcDDDEB7aaBbc";       //16~32 个字符 LwM2M 协议交互秘钥
    //params.imei             = "862363050000149";        //15 个字符的 IMEI,可以由底层获取,可选!/*endpoint_name,pskid*/
    //device attribute:
    params.attri.obj_id = x;
    params.attri.ins_id_up = x;
    params.attri.ins_id_down = x;
    params.attri.res_id = x;
    tuya_user_api_3rd_cloud_config(&params);  
    

    注册原始数据接收回调

    函数原型 INT_T tuya_user_api_raw_data_recv_register_cb(void (data_recv_cb_t)(const uint8_t data, uint32_t data_len))
    参数 ata_recv_cb_t:接收回调函数指针
    功能 注册原始数据接收回调
    头文件 #include <tuya_user_api.h>
    返回值
    • 0:函数执行正常
    • 其它:函数执行异常

    发送原始数据接口

    函数原型 INT_T tuya_user_api_raw_data_send(uint8_t* buffer, uint16_t length)
    参数
    • buffer:发送数据缓存
    • length:发送数据长度
    功能 发送原始数据接口
    头文件 #include <tuya_user_api.h>
    返回值
    • 0:函数执行正常
    • 其它:函数执行异常

    数据发送失败时,云连接协议重置调用接口

    函数原型 void tuya_user_api_cloud_connect_restart(void)
    参数
    功能 数据发送失败时,云连接协议重置调用接口
    头文件 #include <tuya_user_api.h>
    返回值

    恢复出厂设置接口

    模块重置并恢复出厂设置

    函数原型 int32_t tuya_user_api_factory_data_reset (tuya_user_api_dev_reset_cb cb)
    参数 cb:上报事件的回调处理函数,具体请参照下文函数指针类型 tuya_user_api_dev_reset_cb 的详细说明。
    功能 模块重置,恢复出厂设置
    头文件 #include <tuya_user_api.h>
    返回值
    • 0:函数执行正常
    • 其它:函数执行异常

    详细说明

    函数指针 tuya_user_api_dev_reset_cb

    // 用户按此实现具体函数接口即可,详细见 SDK 包”tuya_user_api.h”文件
    typedef void (*tuya_user_api_dev_reset_cb)(int code);
    

    产测相关接口

    此类接口为产测相关接口,用户需要在此处查询需要的接口调用。

    用户产测接口回调注册

    函数原型 void tuya_user_api_mf_test_cb_reg (int (*user_test_callback)(IN USHORT_T cmd, IN UCHAR_T *data, IN UINT_T len, OUT UCHAR_T *ret_data,OUT USHORT_T *ret_len))
    参数
    • user_test_callback :回调函数
    • cmd : 子命令
    • data : 子命令负载指针
    • len : 子命令负载长度
    • ret_data : 返回结果指针
    • ret_len : 返回结果长度
    功能 用户产测接口回调注册
    头文件 #include <tuya_user_api.h>
    返回值
    • 0:函数执行正常
    • 其它:函数执行异常

    用户自定义原始数据产测回调注册接口

    函数原型 void tuya_user_api_mf_test_raw_reg(mf_user_test_custom_cb user_custom_cb, mf_user_test_custom_check_cb check_cb);
    参数
    • tuya_user_api_dev_reset_cb``user_custom_cb :用户自定义产测数据处理回调函数
    • check_cb :用户自定义产测是否有效回调
    功能 用户自定义原始数据产测回调注册接口
    头文件 #include <tuya_user_api.h>
    返回值
    使用说明 该接口主要用于同一个串口进行 NB-IoT 模组与外设 PCBA 产测时,进行数据分时复用的场景。