Aliiotkit-v3.1.0是OneOS操作系统移植的用于连接阿里云平台的第三方组件,适用于使用C语言开发产品业务处理逻辑的设备接入阿里云物联网平台,基础是阿里云的C-SDK软件包。
日志系统的初始化函数, 本接口被调用后, SDK才有可能向终端打印日志文本, 但打印的文本详细程度还是由 IOT_SetLogLevel()
确定, 默认情况下, 无日志输出。其函数原型如下:
void IOT_OpenLog(const char *ident);
参数 | 说明 |
---|---|
ident | 日志的标识符字符串, 例如: IOT_OpenLog("linkkit") |
返回 | |
无返回值 | 无 |
日志系统的销毁函数, 本接口被调用后, SDK停止向终端打印任何日志文本, 但之后可以由调用 IOT_OpenLog()
接口重新使能日志输出。
关闭和重新使能日志系统之后, 需要重新调用 IOT_SetLogLevel()
接口设置日志级别, 否则日志系统虽然使能了, 也不会输出文本。其函数原型如下:
void IOT_CloseLog(void);
参数 | 说明 |
---|---|
无参数 | 无 |
返回值 | |
无返回值 | 无 |
日志系统的日志级别配置函数, 本接口用于设置SDK的日志显示级别, 需要在 IOT_OpenLog()
后被调用。其函数原型如下:
void IOT_SetLogLevel(IOT_LogLevel level);
参数 | 说明 |
---|---|
level | 需要显示的日志级别 |
返回值 | |
无返回值 | 无 |
typedef enum _IOT_LogLevel {
IOT_LOG_EMERG = 0,
IOT_LOG_CRIT,
IOT_LOG_ERROR,
IOT_LOG_WARNING,
IOT_LOG_INFO,
IOT_LOG_DEBUG,
} IOT_LogLevel;
该接口可显示出SDK各模块的内存使用情况, 当WITH_MEM_STATS=1时起效, 显示级别设置得越高, 显示的信息越多。其函数原型如下:
void IOT_DumpMemorStats(IOT_LogLevel level);
参数 | |
---|---|
leve | 需要显示的日志级别 |
返回值 | |
无返回值 | 无 |
在连接云端之前, 需要做一些认证流程, 如一型一密获取DeviceSecret或者根据当前所选认证模式向云端进行认证。
该接口在SDK基础版中需要在连接云端之前由用户显式调用. 而在高级版中SDK会自动进行调用, 不需要用户显式调用。其函数原型如下:
int IOT_SetupConnInfo(const char *product_key,
const char *device_name,
const char *device_secret,
void **info_ptr);
参数 | 说明 |
---|---|
product_key | 设备三元组的ProductKey |
device_name | 设备三元组的DeviceName |
device_secret | 设备三元组的DeviceSecret |
info_ptr | 该void**数据类型为iotx_conn_info_t, 在认证流程通过后, 会得到云端的相关信息, 用于建立与云端连接时使用 |
返回值 | |
0 | 成功 |
<0 | 失败 |
typedef struct {
uint16_t port;
char host_name[HOST_ADDRESS_LEN + 1];
char client_id[CLIENT_ID_LEN + 1];
char username[USER_NAME_LEN + 1];
char password[PASSWORD_LEN + 1];
const char *pub_key;
} iotx_conn_info_t, *iotx_conn_info_pt;
在SDK连接云端之前, 用户可用此接口进行SDK部分参数的配置或获取, 如连接的region, 是否使用一型一密等。
该接口在基础版和高级版中均适用, 需要注意的是, 该接口需要在SDK建立网络连接之前调用. 关于一型一密的。其函数原型如下:
int IOT_Ioctl(int option, void *data);
参数 | 说明 |
---|---|
option | 选择需要配置或获取的参数 |
data | 在配置或获取参数时需要的buffer, 依据option 而定 |
返回值 | |
0 | 成功 |
<0 | 失败 |
typedef enum {
IOTX_IOCTL_SET_DOMAIN, /* value(int*): iotx_cloud_domain_types_t */
IOTX_IOCTL_GET_DOMAIN, /* value(int*) */
IOTX_IOCTL_SET_DYNAMIC_REGISTER, /* value(int*): 0 - Disable Dynamic Register, 1 - Enable Dynamic Register */
IOTX_IOCTL_GET_DYNAMIC_REGISTER /* value(int*) */
} iotx_ioctl_option_t;
CoAP模块初始化函数, 在使用CoAP的功能之前, 需要使用该函数进行初始化。其函数原型如下:
iotx_coap_context_t *IOT_CoAP_Init(iotx_coap_config_t *p_config);
参数 | 说明 |
---|---|
p_config | CoAP模块初始化参数 |
返回值 | |
iotx_coap_context_t * | CoAP当前实例的Context |
typedef struct {
char *p_url;
int wait_time_ms;
iotx_device_info_t *p_devinfo;
iotx_event_handle_t event_handle; /* not supported now */
} iotx_coap_config_t;
p_url
: 需要连接的云端服务器地址coaps://%s.coap.cn-shanghai.link.aliyuncs.com:5684
, %s
为ProductKeycoap-psk://%s.coap.cn-shanghai.link.aliyuncs.com:5682
, %s
为ProductKeywait_time_ms
: CoAP收发消息的超时时间p_devinfo
: 设备信息, 包含 Product_Key/ProductSecret/DeviceName 和 DeviceSecretCoAP反初始化函数,c 断开与云端的连接并释放所有指定Context中分配的资源。其函数原型如下:
void IOT_CoAP_Deinit(iotx_coap_context_t **pp_context);
参数 | 说明 |
---|---|
pp_context | 需要反初始化的CoAP Context |
返回值 | |
无返回值 | 无 |
向云端发送设备认证请求, 认证通过后才能通过CoAP与云端正常通信。其函数原型如下:
int IOT_CoAP_DeviceNameAuth(iotx_coap_context_t *p_context)
参数 | 说明 |
---|---|
pp_context | CoAP Context |
返回值 | |
0 | 成功 |
-1 | 输入参数非法 |
-2 | 内存不足 |
-4 | 认证失败 |
-8 | CoAP消息发送失败 |
当CoAP连接云端后, 用于尝试从网络上接收报文。其函数原型如下:
int IOT_CoAP_Yield(iotx_coap_context_t *p_context)
参数 | 说明 |
---|---|
p_context | CoAP Context |
返回值 | |
0 | 成功 |
<0 | 失败 |
当CoAP连接云端后, 用于向云端发送CoAP消息。其函数原型如下:
int IOT_CoAP_SendMessage(iotx_coap_context_t *p_context, char *p_path, iotx_message_t *p_message);
参数 | 说明 |
---|---|
p_context | CoAP Context |
p_path | 发送消息的目标资源地址 |
p_message | 待发送消息 |
返回值 | |
0 | 成功 |
-1 | 输入参数非法 |
-5 | 设备尚未认证成功 |
-7 | 待发送消息的payload过长 |
typedef struct {
unsigned char *p_payload;
unsigned short payload_len;
iotx_content_type_t content_type;
iotx_msg_type_t msg_type;
void *user_data;
iotx_response_callback_t resp_callback;
} iotx_message_t;
p_payload
: 需要发送的数据内容payload_len
: 需要发送的数据长度content_type
: 数据的格式iotx_msg_type_t
: CoAP消息类型(是否需要Confirmx消息)user_data
: 用户数据, 在收到应答后, 会送回给用户resp_callback
: 用户注册的回调函数, 当收到该消息的应答时被调用当用户通IOT_CoAP_SendMessage送消息并收到应答时, 用该接口可获取CoAP消息中的Payload部分。其函数原型如下:
int IOT_CoAP_GetMessagePayload(void *p_message, unsigned char **pp_payload, int *p_len);
参数 | 说明 |
---|---|
p_message | CoAP应答消息句柄, 在应答消息的回调函数中可获得 |
pp_payload | 用于存放从p_message 中获取的消息Payload |
p_len | pp_payload 的长度 |
返回值 | |
0 | 成功 |
-1 | 输入参数非法 |
-2 | 内存不足 |
当用户通 IOT_CoAP_SendMessage送消息并收到应答时, 用该接口可获取CoAP消息中的Code(错误码)部分。其函数原型如下:
int IOT_CoAP_GetMessageCode(void *p_message, iotx_coap_resp_code_t *p_resp_code);
参数 | 说明 |
---|---|
p_message | CoAP应答消息句柄, 在应答消息的回调函数中可获得 |
pp_payload | 用于存放从p_message 中获取的消息Code |
返回值 | |
0 | 成功 |
-1 | 输入参数非法 |
typedef enum {
IOTX_COAP_RESP_CODE_CONTENT = 0x45, /* Mapping to 2.05, Content*/
IOTX_COAP_RESP_CODE_BAD_REQUEST = 0x80, /* Mapping to 4.00, Bad Request*/
IOTX_COAP_RESP_CODE_UNAUTHORIZED = 0x81, /* Mapping to 4.01, Token is invalid or expire*/
IOTX_COAP_RESP_CODE_NOT_FOUND = 0x84, /* Mapping to 4.04, Path or uri is not found*/
IOTX_COAP_RESP_CODE_URL_TOO_LONG = 0x8E, /* Mapping to 4.14, The request url is too long*/
IOTX_COAP_RESP_CODE_INTERNAL_SERVER_ERROR = 0xA0,/* Mapping to 5.00, Internal server error*/
} iotx_coap_resp_code_t;
与云端建立MQTT连接, 入参pInitParams
为NULL
时将会使用默认参数建连。其函数原型如下:
void *IOT_MQTT_Construct(iotx_mqtt_param_t *pInitParams)
参数 | 说明 |
---|---|
pInitParams | MQTT初始化参数,填写NULL将以默认参数建连 |
返回值 | |
NULL | 失败 |
非NULL | MQTT句柄 |
typedef struct {
uint16_t port;
const char *host;
const char *client_id;
const char *username;
const char *password;
const char *pub_key;
const char *customize_info;
uint8_t clean_session;
uint32_t request_timeout_ms;
uint32_t keepalive_interval_ms;
uint32_t write_buf_size;
uint32_t read_buf_size;
iotx_mqtt_event_handle_t handle_event;
} iotx_mqtt_param_t, *iotx_mqtt_param_pt;
port
: 云端服务器端口host
: 云端服务器地址client_id
: MQTT客户端IDusername
: 登录MQTT服务器用户名password
: 登录MQTT服务器密码pub_key
: MQTT连接加密方式及密钥clean_session
: 选择是否使用MQTT协议的clean session特性request_timeout_ms
: MQTT消息发送的超时时间keepalive_interval_ms
: MQTT心跳超时时间write_buf_size
: MQTT消息发送buffer最大长度read_buf_size
: MQTT消息接收buffer最大长度handle_event
: 用户回调函数, 用与接收MQTT模块的事件信息customize_info
: 用户自定义上报信息,是以逗号为分隔符kv字符串,如用户的厂商信息,模组信息自定义字符串为"pid=123456,mid=abcd";销毁指定MQTT连接并释放资源。其函数原型如下:
int IOT_MQTT_Destroy(void **phandle);
参数 | 说明 |
---|---|
phandle | MQTT句柄,可为NULL |
返回值 | |
0 | 成功 |
<0 | 失败 |
用于接收网络报文并将消息分发到用户的回调函数中。其函数原型如下:
int IOT_MQTT_Yield(void *handle, int timeout_ms);
参数 | 说明 |
---|---|
handle | MQTT句柄,可为NULL |
timeout_ms | 尝试接收报文的超时时间 |
返回值 | |
0 | 成功 |
获取当前MQTT连接状态。其函数原型如下:
int IOT_MQTT_CheckStateNormal(void *handle);
参数 | 说明 |
---|---|
handle | MQTT句柄,可为NULL |
返回值 | |
0 | 未连接 |
1 | 已连接 |
向云端订阅指定的MQTT Topic。其函数原型如下:
int IOT_MQTT_Subscribe(void *handle,
const char *topic_filter,
iotx_mqtt_qos_t qos,
iotx_mqtt_event_handle_func_fpt topic_handle_func,
void *pcontext);
参数 | 说明 |
---|---|
handle | MQTT句柄,可为NULL |
topic_filter | 需要订阅的topic |
qos | 采用的QoS策略 |
topic_handle_func | 用于接收MQTT消息的回调函数 |
pcontext | 用户Context, 会通过回调函数送回 |
返回值 | |
0 | 成功 |
<0 | 失败 |
向云端订阅指定的MQTT Topic, 该接口为同步接口。其函数原型如下:
int IOT_MQTT_Subscribe_Sync(void *handle,
const char *topic_filter,
iotx_mqtt_qos_t qos,
iotx_mqtt_event_handle_func_fpt topic_handle_func,
void *pcontext,
int timeout_ms);
参数 | 说明 |
---|---|
handle | MQTT句柄,可为NULL |
topic_filter | 需要订阅的topic |
qos | 采用的QoS策略 |
topic_handle_func | 用于接收MQTT消息的回调函数 |
pcontext | 用户Context, 会通过回调函数送回 |
timeout_ms | 该同步接口的超时时间 |
返回值 | |
0 | 成功 |
<0 | 失败 |
向云端取消订阅指定的topic。其函数原型如下:
int IOT_MQTT_Unsubscribe(void *handle, const char *topic_filter);
参数 | 说明 |
---|---|
handle | MQTT句柄,可为NULL |
topic_filter | 需要订阅的topic |
返回值 | |
0 | 成功 |
<0 | 失败 |
向指定topic推送消息。其函数原型如下:
int IOT_MQTT_Publish(void *handle, const char *topic_name, iotx_mqtt_topic_info_pt topic_msg);
参数 | 说明 |
---|---|
handle | MQTT句柄,可为NULL |
topic_name | 接收此推送消息的目标topic |
topic_msg | 需要推送的消息 |
返回值 | |
> 0 | 成功(消息是QoS1时, 返回值就是这个上报报文的MQTT消息ID, 对应协议里的messageId ) |
0 | 成功(消息是QoS0时) |
< 0 | 失败 |
向指定topic推送消息。其函数原型如下:
int IOT_MQTT_Publish_Simple(void *handle, const char *topic_name, int qos, void *data, int len
参数 | 说明 |
---|---|
handle | MQTT句柄,可为NULL |
topic_name | 接收此推送消息的目标topic |
qos | 采用的QoS策略 |
data | 需要发送的数据 |
len | 数据长度 |
返回值 | |
> 0 | 成功(消息是QoS1时, 返回值就是这个上报报文的MQTT消息ID, 对应协议里的messageId ) |
0 | 成功(消息是QoS0时) |
< 0 | 失败 |
初始化OTA模块, 需要先建立与云端的MQTT连接后才能使用。其函数原型如下:
void *IOT_OTA_Init(const char *product_key, const char *device_name, void *ch_signal);
参数 | 说明 |
---|---|
product_key | 设备三元组中的Product Key |
device_name | 设备三元组中的Device Name |
ch_signal | MQTT句柄 |
返回值 | |
NULL | 失败 |
非NULL | OTA句柄 |
反初始化OTA模块, 释放所有资源。其函数原型如下:
int IOT_OTA_Deinit(void *handle)
参数 | 说明 |
---|---|
handle | OTA句柄 |
返回值 | |
0 | 成功 |
< 0 | 失败 |
向云端上报升级进度。其函数原型如下:
int IOT_OTA_ReportProgress(void *handle, IOT_OTA_Progress_t progress, const char *msg);
参数 | 说明 |
---|---|
handle | OTA句柄 |
version | 版本号 |
返回值 | |
0 | 成功 |
< 0 | 失败 |
typedef enum {
IOT_OTAP_BURN_FAILED = -4,
IOT_OTAP_CHECK_FALIED = -3,
IOT_OTAP_FETCH_FAILED = -2,
IOT_OTAP_GENERAL_FAILED = -1,
IOT_OTAP_FETCH_PERCENTAGE_MIN = 0,
IOT_OTAP_FETCH_PERCENTAGE_MAX = 100
} IOT_OTA_Progress_t;
IOT_OTAP_BURN_FAILED
: 固件烧写失败IOT_OTAP_CHECK_FALIED
: 固件校验失败IOT_OTAP_FETCH_FAILED
: 固件下载失败IOT_OTAP_GENERAL_FAILED
: OTA其他错误IOT_OTAP_FETCH_PERCENTAGE_MIN
: 固件OTA进度最小值, 值为0IOT_OTAP_FETCH_PERCENTAGE_MAX
: 固件OTA进度最大值, 值为100检测当前OTA模块是否处于从云端获取数据的状态。其函数原型如下:
int IOT_OTA_IsFetching(void *handle);
参数 | 说明 |
---|---|
handle | OTA句柄 |
返回值 | |
0 | 未处于获取数据状态 |
1 | 正在从云端获取数据 |
检测当前OTA模块是否获取数据完成。其函数原型如下:
int IOT_OTA_IsFetchFinish(void *handle);
参数 | 说明 |
---|---|
handle | OTA句柄 |
返回值 | |
0 | 获取数据未完成 |
1 | 已从云端获取数据完成 |
该接口用于从网络接收报文, 需要用户周期性调用。其函数原型如下:
int IOT_OTA_FetchYield(void *handle, char *buf, uint32_t buf_len, uint32_t timeout_s);
参数 | 说明 |
---|---|
handle | OTA句柄 |
buf | 用于获取配置文件的临时buffer |
buf_len | data_buf 的长度 |
返回值 | |
0 | 成功 |
< 0 | 失败 |
用于设置OTA部分参数或获取当前OTA运行状态。其函数原型如下:
int IOT_OTA_Ioctl(void *handle, IOT_OTA_CmdType_t type, void *buf, size_t buf_len);
参数 | 说明 |
---|---|
handle | OTA句柄 |
type | 命令类型 |
buf | 命令buffer |
buf_len | buf 的长度 |
返回值 | |
0 | 成功 |
< 0 | 失败 |
typedef enum {
IOT_OTAG_COTA_CONFIG_ID,
IOT_OTAG_COTA_CONFIG_SIZE,
IOT_OTAG_COTA_SIGN,
IOT_OTAG_COTA_SIGN_METHOD,
IOT_OTAG_COTA_URL,
IOT_OTAG_COTA_GETTYPE,
IOT_OTAG_OTA_TYPE,
IOT_OTAG_FETCHED_SIZE, /* option for get already fetched size */
IOT_OTAG_FILE_SIZE, /* size of file */
IOT_OTAG_MD5SUM, /* md5 in string format */
IOT_OTAG_VERSION, /* version in string format */
IOT_OTAG_CHECK_FIRMWARE, /* Check firmware is valid or not */
IOT_OTAG_CHECK_CONFIG, /* Check config file is valid or not */
IOT_OTAG_RESET_FETCHED_SIZE /* reset the size_fetched parameter to be 0 */
} IOT_OTA_CmdType_t;
IOT_OTAG_COTA_CONFIG_ID
: 当前可升级配置文件IDIOT_OTAG_COTA_CONFIG_SIZE
: 当前可升级配置文件大小IOT_OTAG_COTA_SIGN
: 当前可升级配置文件签名IOT_OTAG_COTA_SIGN_METHOD
: 当前可升级配置文件计算签名的方法IOT_OTAG_COTA_URL
: 当前可升级配置文件下载地址IOT_OTAG_COTA_GETTYPE
: 当前可升级配置文件类型IOT_OTAG_OTA_TYPE
: 当前OTA类型, COTA或FOTAIOT_OTAG_FETCHED_SIZE
: 当前可升级配置文件已下载大小IOT_OTAG_FILE_SIZE
: 当前可升级固件文件大小IOT_OTAG_MD5SUM
: 当前已下载文件MD5值IOT_OTAG_VERSION
: 当前可升级固件版本号IOT_OTAG_CHECK_FIRMWARE
: 对已下载固件文件进行校验IOT_OTAG_CHECK_CONFIG
: 对已下载配置文件进行校验IOT_OTAG_RESET_FETCHED_SIZE
: 下载开始前, 将已下载的数据量大小size_fetched值清零获取最近一次的错误码。其函数原型如下:
int IOT_OTA_GetLastError(void *handle);
参数 | 说明 |
---|---|
handle | OTA句柄 |
返回值 | |
0 | 最近一次错误码为成功 |
< 0 | 最近一次错误码为失败 |
HTTP模块初始化函数, 在使用HTTP的功能之前, 需要使用该函数进行初始化。其函数原型如下:
void *IOT_HTTP_Init(iotx_http_param_t *pInitParams);
参数 | 说明 |
---|---|
pInitParams | HTTP模块初始化参数 |
返回值 | |
NULL | 初始化失败 |
非NULL | HTTP Context |
typedef struct {
iotx_device_info_t *device_info;
int keep_alive;
int timeout_ms;
} iotx_http_param_t;
device_info
: 设备信息, 包含Product_Key/ProductSecret/DeviceName和DeviceSecretkeep_alive
: 选择是否采用http的keep alive模式, 即每次与云端通信完成后是否需要断开http连接timeout_ms:
: 设置等待应答消息的超时时间HTTP反初始化函数, 断开与云端的连接并释放所有指定Context中分配的资源。其函数原型如下:
void IOT_HTTP_DeInit(void **handle);
参数 | 说明 |
---|---|
handle | HTTP Context |
返回值 | |
无返回值 | 无 |
向云端发送设备认证请求, 认证通过后才能通过HTTP与云端正常通信。其函数原型如下:
int IOT_HTTP_DeviceNameAuth(void *handle);
参数 | 说明 |
---|---|
handel | HTTP Context |
返回值 | |
0 | 成功 |
< 0 | 失败 |
当HTTP连接云端后, 用于向云端发送HTTP消息。其函数原型如下:
int IOT_HTTP_SendMessage(void *handle, iotx_http_message_param_t *msg_param);
参数 | 说明 |
---|---|
handle | HTTP Context |
msg_param | 待发送到云端的消息 |
返回值 | |
0 | 成功 |
< 0 | 失败 |
typedef struct {
char *topic_path;
uint32_t request_payload_len;
char *request_payload;
uint32_t response_payload_len;
char *response_payload;
uint32_t timeout_ms;
} iotx_http_message_param_t;
topic_path
: 待发送消息的目标资源地址request_payload_len
: 待发送消息的长度request_payload
: 待发送消息的数据response_payload_len
: 应答消息buffer长度response_payload
: 应答消息buffertimeout_ms
: 等待应答消息的超时时间该接口用于断开指定HTTP Context的连接。其函数原型如下:
void IOT_HTTP_Disconnect(void *handle)
参数 | 说明 |
---|---|
handle | HTTP Context |
返回值 | |
无返回值 | 无 |