全部文档
概述 硬件支持 快速开发指南 内核 驱动 通用组件 专业组件 常见问题

阿里云平台用户指南

目录

简介

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

SDK使用说明

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

figure01

SDK功能列表

功能模块 功能
设备连接云 MQTT连接云,设备可通过MQTT与阿里云IoT物联网平台通信
CoAP连接云,设备可通过CoAP与阿里云IoT物联网平台通信,用于设备主动上报信息的场景
设备身份认证 一机一密
一型一密
x.509证书
物模型 使用属性、服务、事件对设备进行描述以及实现,包括:
属性上报、设置
服务调用
事件上报
云端region设置 厂商指定region,告知设备连接到阿里云的具体云端站点,例如中国上海、新加坡、美国、法国
动态连云设备自动连接到距离设备延时最短的云端站点
OTA 设备固件升级
远程配置 设备配置文件获取
子设备管理 用于让网关添加、删除子设备,以及对子设备进行控制
时间获取 从阿里云物联网平台获取当时的最新时间

代码目录

文件名 功能
demo 示例
external_lib 外部依赖
src 功能实现
tools 配置工具
wrappers 封装

API

MQTT协议API 说明
IOT_MQTT_Construct 与云建立MQTT连接
IOT_MQTT_Destroy 销毁指定MQTT连接并释放资源
IOT_MQTT_Yield 接收网络报文并将消息分发到用户的回调函数
IOT_MQTT_CheckStateNormal 获取当前MQTT连接状态
IOT_MQTT_Subscribe 向云端订阅指定的MQTT Topic
IOT_MQTT_Subscribe_Sync 同步接口,向云端订阅指定的MQTT Topic
IOT_MQTT_Unsubscribe 向云端取消订阅指定的topic
IOT_MQTT_Publish 向指定topic推送消息
IOT_MQTT_Publish_Simple 向指定topic推送消息
CoAP协议API 说明
IOT_CoAP_Init CoAP模块初始化函数
IOT_CoAP_Deinit CoAP反初始化函数
IOT_CoAP_DeviceNameAuth 向云端发送设备认证请求
IOT_CoAP_Yield 尝试从网络上接收报文
IOT_CoAP_SendMessage 向云端发送CoAP消息
IOT_CoAP_GetMessagePayload 获取CoAP消息中的Payload部分
IOT_CoAP_GetMessageCode 获取CoAP消息中的Code(错误码)部分
OTA API 说明
IOT_OTA_Init 初始化OTA模块
IOT_OTA_Deinit 反初始化OTA模块
IOT_OTA_ReportVersion 向云端上报当前SDK版本号
IOT_OTA_ReportProgress 向云端上报升级进度
IOT_OTA_IsFetching 检测当前OTA模块是否处于从云端获取数据的状态
IOT_OTA_IsFetchFinish 检测当前OTA模块是否获取数据完成
IOT_OTA_FetchYield 从网络接收报文
IOT_OTA_Ioctl 设置OTA部分参数或获取当前OTA运行状态
IOT_OTA_GetLastError 获取最近一次的错误码

使用说明

图形化配置

使用阿里云软件包需要通过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);
参数 说明
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 最近一次错误码为失败

注意事项

关闭加密传输

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

OTA相关

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

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

阿里云Wiki

results matching ""

    No results matching ""