阿里云平台用户指南

目录

• 阿里云平台用户指南
• 目录
• 简介

• SDK说明

  • SDK使用说明
  • SDK功能列表

• 代码目录

  • API
• 使用说明
  • menuconfig配置
• API说明
• 注意事项

简介

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

SDK使用说明

产品的业务逻辑、SDK、HAL的关系如下图所示。

SDK功能列表

代码目录

API

使用说明

图形化配置

使用阿里云软件包需要通过Menuconfig的图形化工具进行配置选择，默认配置如下所示：

(Top) → Components→ Cloud→ Aliyun
                                                                          OneOS Configuration
[*] Ali-iotkit: Aliyun cloud sdk 'iotkit-embedded'
        Version (v3.1.0)  --->
() Config Product Key 
() Config Product Secret 
() Config Device Name 
() Config Device Secret 
[*]     PLATFROM_HAS_MBEDTLS 
-*-     PLATFORM_HAS_STDINT 
[*]     PLATFORM_HAS_DYNMEM
[*]     FEATURE_INFRA_NETWORK_PAYLOAD
[*]     FEATURE_INFRA_LOG 
            Log Configurations  --->
[*]     FEATURE_MQTT_COMM_ENABLED 
            MQTT Configurations  --->
[ ]     FEATURE_SUPPORT_TLS 
[ ]     FEATURE_OTA_ENABLED 
[ ]     FEATURE_COAP_COMM_ENABLED 
[ ]     Samples

配置相关协议连入阿里云平台需配置相关选项，以及根据阿里云平台上产品需求及验证方式配置ProductKey、ProductSecret、DeviceName、DeviceSecret。

重要定义及数据结构

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

注意事项

关闭加密传输

开启阿里云加密传输功能后悔自动勾选mbedtls加密组件，当用户取消阿里云的加密传输功能时需记得手动关闭阿里云的加密选项，并同时关闭mbedtls组件。

OTA相关

由于aliiot组件目前暂不支持https协议传输，阿里云组件的ota远程升级功能下载受限，推荐使用oneos自带的fota远程升级组件，配置路径(Top) → Components→ OTA→ Fota by CMIOT。

更多资料请前往阿里云官方

阿里云Wiki