全部文档
OneOS简介 硬件支持 快速开发指南 编译构造工具 API参考文档 高级语言 用户编程手册 OnePos定位 应用笔记 FAQ

Aliiotkit第三方组件设计文档

简介

Aliiotkit-v3.1.0是OneOS操作系统移植的用于连接阿里云平台的第三方组件,适用于使用C语言开发产品业务处理逻辑的设备接入阿里云物联网平台,基础是阿里云的C-SDK软件包。

重要定义及数据结构

IOT_OpenLog

日志系统的初始化函数, 本接口被调用后, SDK才有可能向终端打印日志文本, 但打印的文本详细程度还是由 IOT_SetLogLevel() 确定, 默认情况下, 无日志输出。其函数原型如下:

void IOT_OpenLog(const char *ident);
参数 说明
ident 日志的标识符字符串, 例如: IOT_OpenLog("linkkit")
返回
无返回值

IOT_CloseLog

日志系统的销毁函数, 本接口被调用后, SDK停止向终端打印任何日志文本, 但之后可以由调用 IOT_OpenLog() 接口重新使能日志输出。

关闭和重新使能日志系统之后, 需要重新调用 IOT_SetLogLevel() 接口设置日志级别, 否则日志系统虽然使能了, 也不会输出文本。其函数原型如下:

void IOT_CloseLog(void);
参数 说明
无参数
返回值
无返回值

IOT_SetLogLevel

日志系统的日志级别配置函数, 本接口用于设置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;

IOT_DumpMemoryStats

该接口可显示出SDK各模块的内存使用情况, 当WITH_MEM_STATS=1时起效, 显示级别设置得越高, 显示的信息越多。其函数原型如下:

void IOT_DumpMemorStats(IOT_LogLevel level);
参数
leve 需要显示的日志级别
返回值
无返回值

IOT_SetupConnInfo

在连接云端之前, 需要做一些认证流程, 如一型一密获取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;

IOT_Ioctl

在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;

IOT_CoAP_Init

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: 需要连接的云端服务器地址
    • 使用DTLS: coaps://%s.coap.cn-shanghai.link.aliyuncs.com:5684, %s 为ProductKey
    • 使用PSK: coap-psk://%s.coap.cn-shanghai.link.aliyuncs.com:5682, %s 为ProductKey
  • wait_time_ms: CoAP收发消息的超时时间
  • p_devinfo: 设备信息, 包含 Product_Key/ProductSecret/DeviceName 和 DeviceSecret

IOT_CoAP_Deinit

CoAP反初始化函数,c 断开与云端的连接并释放所有指定Context中分配的资源。其函数原型如下:

void IOT_CoAP_Deinit(iotx_coap_context_t **pp_context);
参数 说明
pp_context 需要反初始化的CoAP Context
返回值
无返回值

IOT_CoAP_DeviceNameAuth

向云端发送设备认证请求, 认证通过后才能通过CoAP与云端正常通信。其函数原型如下:

int IOT_CoAP_DeviceNameAuth(iotx_coap_context_t *p_context)
参数 说明
pp_context CoAP Context
返回值
0 成功
-1 输入参数非法
-2 内存不足
-4 认证失败
-8 CoAP消息发送失败

IOT_CoAP_Yield

当CoAP连接云端后, 用于尝试从网络上接收报文。其函数原型如下:

int IOT_CoAP_Yield(iotx_coap_context_t *p_context)
参数 说明
p_context CoAP Context
返回值
0 成功
<0 失败

IOT_CoAP_SendMessage

当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_GetMessagePayload

当用户通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_GetMessageCode

当用户通 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;

IOT_MQTT_Construct

与云端建立MQTT连接, 入参pInitParamsNULL时将会使用默认参数建连。其函数原型如下:

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客户端ID
  • username: 登录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";

IOT_MQTT_Destroy

销毁指定MQTT连接并释放资源。其函数原型如下:

int IOT_MQTT_Destroy(void **phandle);
参数 说明
phandle MQTT句柄,可为NULL
返回值
0 成功
<0 失败

IOT_MQTT_Yield

用于接收网络报文并将消息分发到用户的回调函数中。其函数原型如下:

int IOT_MQTT_Yield(void *handle, int timeout_ms);
参数 说明
handle MQTT句柄,可为NULL
timeout_ms 尝试接收报文的超时时间
返回值
0 成功

IOT_MQTT_CheckStateNormal

获取当前MQTT连接状态。其函数原型如下:

int IOT_MQTT_CheckStateNormal(void *handle);
参数 说明
handle MQTT句柄,可为NULL
返回值
0 未连接
1 已连接

IOT_MQTT_Subscribe

向云端订阅指定的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 失败

IOT_MQTT_Subscribe_Sync

向云端订阅指定的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 失败

IOT_MQTT_Unsubscribe

向云端取消订阅指定的topic。其函数原型如下:

int IOT_MQTT_Unsubscribe(void *handle, const char *topic_filter);
参数 说明
handle MQTT句柄,可为NULL
topic_filter 需要订阅的topic
返回值
0 成功
<0 失败

IOT_MQTT_Publish

向指定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 失败

IOT_MQTT_Publish_Simple

向指定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 失败

IOT_OTA_Init

初始化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句柄

IOT_OTA_Deinit

反初始化OTA模块, 释放所有资源。其函数原型如下:

int IOT_OTA_Deinit(void *handle)
参数 说明
handle OTA句柄
返回值
0 成功
< 0 失败

IOT_OTA_ReportProgress

向云端上报升级进度。其函数原型如下:

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进度最小值, 值为0
  • IOT_OTAP_FETCH_PERCENTAGE_MAX: 固件OTA进度最大值, 值为100
  • 升级进度取值范围为: [0,100]区间的整数

IOT_OTA_IsFetching

检测当前OTA模块是否处于从云端获取数据的状态。其函数原型如下:

int IOT_OTA_IsFetching(void *handle);
参数 说明
handle OTA句柄
返回值
0 未处于获取数据状态
1 正在从云端获取数据

IOT_OTA_IsFetchFinish

检测当前OTA模块是否获取数据完成。其函数原型如下:

int IOT_OTA_IsFetchFinish(void *handle);
参数 说明
handle OTA句柄
返回值
0 获取数据未完成
1 已从云端获取数据完成

IOT_OTA_FetchYield

该接口用于从网络接收报文, 需要用户周期性调用。其函数原型如下:

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 失败

IOT_OTA_Ioctl

用于设置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: 当前可升级配置文件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: 当前OTA类型, COTA或FOTA
  • IOT_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值清零

IOT_OTA_GetLastError

获取最近一次的错误码。其函数原型如下:

int IOT_OTA_GetLastError(void *handle);
参数 说明
handle OTA句柄
返回值
0 最近一次错误码为成功
< 0 最近一次错误码为失败

IOT_HTTP_Init

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和DeviceSecret
  • keep_alive: 选择是否采用http的keep alive模式, 即每次与云端通信完成后是否需要断开http连接
  • timeout_ms:: 设置等待应答消息的超时时间

IOT_HTTP_DeInit

HTTP反初始化函数, 断开与云端的连接并释放所有指定Context中分配的资源。其函数原型如下:

void IOT_HTTP_DeInit(void **handle);
参数 说明
handle HTTP Context
返回值
无返回值

IOT_HTTP_DeviceNameAuth

向云端发送设备认证请求, 认证通过后才能通过HTTP与云端正常通信。其函数原型如下:

int IOT_HTTP_DeviceNameAuth(void *handle);
参数 说明
handel HTTP Context
返回值
0 成功
< 0 失败

IOT_HTTP_SendMessage

当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: 应答消息buffer
  • timeout_ms: 等待应答消息的超时时间

IOT_HTTP_Disconnect

该接口用于断开指定HTTP Context的连接。其函数原型如下:

void IOT_HTTP_Disconnect(void *handle)
参数 说明
handle HTTP Context
返回值
无返回值

results matching ""

    No results matching ""

    返回顶部