系统函数

安全快速联网

初始化设备与云端交互的上下文环境，并与云端会建立长连接。当长连接断开时，会自动重连。注意，填写密钥时，需将官网的一串字符串转换成相应的十六进制编码，即在每个字节前增加0x作为开头。如字符串是5668，转换时应改为0x56，0x68。

    iot_s32 iot_start ( struct iot_context* ctx );

struct iot_context结构体的内容如下：

参数	长度	说明
product_id	4	产品ID，云平台生成，4字节的无符号整型数字
product_key	16	产品密钥，云平台生成，16字节的十六进制编码
mcu_version	5	mcu固件版本，"xx.xx"，0≤x≤9
recvbuf_size	4	接收数据buffer大小，范围1024-1048576，默认1024
sendbuf_size	4	发送数据buffer大小，范围1024-1048576，默认1024
server_addr	n	云服务器地址
server_port	2	云服务器端口
返回值	4	0：成功； -1：失败

设置设备运行状态

此函数用于设置设备的运行状态，设置结果请见3.3节“设备运行状态报告”。

void iot_status_set( DEV_STATUS_T dev_status,  iot_u32 timeout );

参数	说明
dev_status	DEV_STA_FACTORY_RESET(2)：恢复出厂设置，会删除云端设备信息，并解除与APP端的绑定关系，恢复出厂成功后自动调用3.3节函数告知。 DEV_STA_BIND_PERMIT(3)：允许用户通过局域网绑定设备，可在连接云端成功后调用。绑定成功或失败都会调用3.3节函数告知，告知参数为DEV_STA_BIND_FAILED(4) 或 DEV_STA_BIND_SUCCESS(5)。(02.07之后的版本必须调用此接口才能进行绑定操作！) DEV_STA_UNBIND(6)：设置解绑，设备会解除与APP端的绑定关系，成功后自动调用3.3节函数告知。
timeout	设备运行状态保持时长，单位为秒; timeout = 0表示不设置超时状态。

参数

说明

dev_status

DEV_STA_FACTORY_RESET(2)：恢复出厂设置，会删除云端设备信息，并解除与APP端的绑定关系，恢复出厂成功后自动调用3.3节函数告知。

DEV_STA_BIND_PERMIT(3)：允许用户通过局域网绑定设备，可在连接云端成功后调用。绑定成功或失败都会调用3.3节函数告知，告知参数为DEV_STA_BIND_FAILED(4) 或 DEV_STA_BIND_SUCCESS(5)。(02.07之后的版本必须调用此接口才能进行绑定操作！)

DEV_STA_UNBIND(6)：设置解绑，设备会解除与APP端的绑定关系，成功后自动调用3.3节函数告知。

timeout

设备运行状态保持时长，单位为秒;
timeout = 0表示不设置超时状态。

设备运行状态报告

当设备运行状态发生改变时，sdk自动调用此函数。

void iot_status_cb( DEV_STATUS_T dev_status,  iot_u32timestamp );

参数	说明
dev_status	DEV_STA_CONNECTED_CLOUD(0) : 连接云端成功 DEV_STA_DISCONN_CLOUD(1) : 网络异常连接断开 DEV_STA_FACTORY_RESET(2) : 恢复出厂成功，本地可重置设备 DEV_STA_BIND_FAILED(4) : 绑定失败（绑定超时或设备未联网），允许绑定终止 DEV_STA_BIND_SUCCESS(5) : 绑定成功，允许绑定终止 DEV_STA_UNBIND(6) : 解绑成功 DEV_STA_USER_SHARE_INC(7) : 分享用户增加 DEV_STA_USER_SHARE_DEC(8) : 分享用户减少 DEV_STA_AUTH_LIMIT(11) : 设备授权数达上限，无法通过云端认证 DEV_STA_MAC_BIND_OTHER_ID(12) : 设备mac地址已绑定其他产品，无法通过云端认证
timestamp	状态改变的时间点

参数

说明

dev_status

DEV_STA_CONNECTED_CLOUD(0) : 连接云端成功
DEV_STA_DISCONN_CLOUD(1) : 网络异常连接断开
DEV_STA_FACTORY_RESET(2) : 恢复出厂成功，本地可重置设备
DEV_STA_BIND_FAILED(4) : 绑定失败（绑定超时或设备未联网），允许绑定终止
DEV_STA_BIND_SUCCESS(5) : 绑定成功，允许绑定终止
DEV_STA_UNBIND(6) : 解绑成功
DEV_STA_USER_SHARE_INC(7) : 分享用户增加
DEV_STA_USER_SHARE_DEC(8) : 分享用户减少
DEV_STA_AUTH_LIMIT(11) : 设备授权数达上限，无法通过云端认证
DEV_STA_MAC_BIND_OTHER_ID(12) : 设备mac地址已绑定其他产品，无法通过云端认证

timestamp

状态改变的时间点

注意！回调函数中不可执行太多耗时代码。

获取网络时间

iot_u32 iot_get_onlinetime( void );

参数	说明
返回值	0：时间无效 >0：实时网络时间戳

解析时间

void iot_parse_timestamp ( iot_u32 timestamp, struct s_time* st );

参数	说明
timestamp	需要被转换的整型时间戳
st	转换后的时间结构体

时间结构体定义如下:

struct s_time {

    int     sec;        //秒

    int     min;        //分

    int     hour;       //时

    int     day;        //日

    int     mon;        //月

    int     year;       //年

    int     week;       //周

};

打印输出函数

此函数用于输出日志信息，需用户自行实现，可根据需要重定向到串口、屏幕、文件等位置。

void iot_print ( const char * str );

参数	说明
str	输出的日志内容

发送数据成功报告

发送数据成功后，sdk自动调用下面这个回调函数。当调用4.1.1节上传数据、4.2.1节透传自定义数据某个函数后，此回调函数会被调用。回调函数中不可执行太多耗时代码。

void iot_data_cb (     iot_u32  data_seq， DATA_LIST_T * data_list  );

参数	说明
data_seq	某条数据的序列号，如不关心何时上传成功，可不做处理
data_list	上传数据、透传数据的错误列表

数据列表结构体定义如下：

typedef struct data_list
{
    int                 count;               //列表信息个数
    DATA_INFO_T *       info;               //数据信息列表
}DATA_LIST_T;

数据列表结构体定义如下：

typedef struct data_info
{
    char            *       dev_id;         //设备id(主设备:NULL, 子设备:subid)
    DATA_INFO_TYPE_T    info_type;        //数据类型码
}DATA_INFO_T;

数据列表中信息类型结构体定义如下：

typedef enum DATA_INFO_TYPE {
    DATA_INFO_NULL           = 0,         //数据信息为空 
    DATA_INFO_NOT_ONLINE   = 16,        //子设备发送数据、透传数据、下线时，如果未上线，则返回此错误
    DATA_INFO_BIND_OTHER    = 17,        //子设备上线、下线时，如果已被其他主设备绑定，则返回此错误
    DATA_INFO_BIND_NONE     = 18,        //子设备上线、下线时，如果未被绑定，则返回此错误
}DATA_INFO_TYPE_T;

crc校验码计算

用户可使用该函数计算数据或文件的crc16校验码。

iot_u16     iot_crc16_calc(    iot_u8    * data, 
iot_u32     data_len,
iot_u16     pre_crc)

参数	说明
data	待校验数据
data_len	待校验数据长度
pre_crc	上一次crc校验码。（pre_crc的初始值为0xffff）
返回值	crc校验码