Aliiotkit第三方组件设计文档

简介

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

重要定义及数据结构

IOT_OpenLog

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

void IOT_OpenLog(const char *ident);

IOT_CloseLog

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

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

void IOT_CloseLog(void);

IOT_SetLogLevel

日志系统的日志级别配置函数, 本接口用于设置SDK的日志显示级别, 需要在 IOT_OpenLog() 后被调用。其函数原型如下：

void IOT_SetLogLevel(IOT_LogLevel 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);

IOT_SetupConnInfo

在连接云端之前, 需要做一些认证流程, 如一型一密获取DeviceSecret或者根据当前所选认证模式向云端进行认证。

该接口在SDK基础版中需要在连接云端之前由用户显式调用. 而在高级版中SDK会自动进行调用, 不需要用户显式调用。其函数原型如下：

int IOT_SetupConnInfo(const char *product_key,
                        const char *device_name,
                        const char *device_secret,
                        void **info_ptr);

参数附加说明

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

附加参数说明

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

参数附加说明

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

IOT_CoAP_DeviceNameAuth

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

int IOT_CoAP_DeviceNameAuth(iotx_coap_context_t *p_context)

IOT_CoAP_Yield

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

int IOT_CoAP_Yield(iotx_coap_context_t *p_context)

IOT_CoAP_SendMessage

当CoAP连接云端后, 用于向云端发送CoAP消息。其函数原型如下：

int IOT_CoAP_SendMessage(iotx_coap_context_t *p_context, char *p_path, iotx_message_t *p_message);

参数附加说明

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

IOT_CoAP_GetMessageCode

当用户通 IOT_CoAP_SendMessage送消息并收到应答时, 用该接口可获取CoAP消息中的Code(错误码)部分。其函数原型如下：

int IOT_CoAP_GetMessageCode(void *p_message, iotx_coap_resp_code_t *p_resp_code);

参数附加说明

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连接, 入参pInitParams为NULL时将会使用默认参数建连。其函数原型如下：

void *IOT_MQTT_Construct(iotx_mqtt_param_t *pInitParams)

参数附加说明

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

IOT_MQTT_Yield

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

int IOT_MQTT_Yield(void *handle, int timeout_ms);

IOT_MQTT_CheckStateNormal

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

int IOT_MQTT_CheckStateNormal(void *handle);

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

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

IOT_MQTT_Unsubscribe

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

int IOT_MQTT_Unsubscribe(void *handle, const char *topic_filter);

IOT_MQTT_Publish

向指定topic推送消息。其函数原型如下：

int IOT_MQTT_Publish(void *handle, const char *topic_name, iotx_mqtt_topic_info_pt topic_msg);

IOT_MQTT_Publish_Simple

向指定topic推送消息。其函数原型如下：

int IOT_MQTT_Publish_Simple(void *handle, const char *topic_name, int qos, void *data, int len

IOT_OTA_Init

初始化OTA模块, 需要先建立与云端的MQTT连接后才能使用。其函数原型如下：

void *IOT_OTA_Init(const char *product_key, const char *device_name, void *ch_signal);

IOT_OTA_Deinit

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

int IOT_OTA_Deinit(void *handle)

IOT_OTA_ReportProgress

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

int IOT_OTA_ReportProgress(void *handle, IOT_OTA_Progress_t progress, const char *msg);

参数附加说明

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

IOT_OTA_IsFetchFinish

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

int IOT_OTA_IsFetchFinish(void *handle);

IOT_OTA_FetchYield

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

int IOT_OTA_FetchYield(void *handle, char *buf, uint32_t buf_len, uint32_t timeout_s);

IOT_OTA_Ioctl

用于设置OTA部分参数或获取当前OTA运行状态。其函数原型如下：

int IOT_OTA_Ioctl(void *handle, IOT_OTA_CmdType_t type, void *buf, size_t buf_len);

参数附加说明

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

IOT_HTTP_Init

HTTP模块初始化函数, 在使用HTTP的功能之前, 需要使用该函数进行初始化。其函数原型如下：

void *IOT_HTTP_Init(iotx_http_param_t *pInitParams);

参数附加说明

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

IOT_HTTP_DeviceNameAuth

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

int IOT_HTTP_DeviceNameAuth(void *handle);

IOT_HTTP_SendMessage

当HTTP连接云端后, 用于向云端发送HTTP消息。其函数原型如下：

int IOT_HTTP_SendMessage(void *handle, iotx_http_message_param_t *msg_param);

参数附加说明

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)