SDK使用

设备端SDK的使用

对设备端SDK的使用分为如下几步:

• 修改编译配置进行编译, 详见设备端SDK的编译页面
• 获取编译好的SDK, 如成功存放在output/release/lib/*.a
• 将libiot_sdk.a libiot_platform.a libmbedcrypto.a libmbedtls.a libmbedtls.a等配合output/release/include/目录下的头文件, 加入您自己的工程使用

SDK编译产物说明

output/release/
+-- bin
+-- include
|   +-- exports
|   |   +-- qcloud_iot_export_coap.h
|   |   +-- qcloud_iot_export_err.h
|   |   +-- qcloud_iot_export_log.h
|   |   +-- qcloud_iot_export_mqtt.h
|   |   +-- qcloud_iot_export_shadow.h
|   +-- qcloud_iot_export.h
|   +-- qcloud_iot_import.h
+-- lib
|   +-- libiot_sdk.a
|   +-- libiot_platform.a
|   +-- libmbedcrypto.a
|   +-- libmbedtls.a
|   +-- libmbedx509.a
+-- unittest

概要说明如下:

文件	说明
include/qcloud_iot_import.h	这个头文件中列出为 SDK 适配新硬件平台时, 需要实现的平台抽象层函数, 以 HAL_*() 的方式命名; 编写平台抽象层实现时, 包含此头文件即可
include/qcloud_iot_export.h	这个头文件中列出 SDK 能提供的所有用户级别 API, 以 IOT_*() 的方式命名, 也就是供用户调用编写业务应用程序的函数
include/exports/qcloud_iot_export_*.h	这组头文件按功能模块分列各模块提供的用户级别 API, 例如 qcloud_iot_export_mqtt.h 中定义了 MQTT 的通信接口 可直接忽略该文件
lib/*.a	编译出的 iotsdk iot 平台 sdk，mbedtls 相关库用于加密通信
unittest	单元测试的可执行文件

SDK编译开关说明

SDK顶层目录的make.settings文件, 列出了对功能进行裁剪时可以选择打开或者关闭的开关, 可以说明如下:

FEATURE_MQTT_COMM_ENABLED   	    = y
FEATURE_COAP_COMM_ENABLED   	    = y
FEATURE_SDKTESTS_ENABLED            = n
FEATURE_MQTT_RMDUP_MSG_ENABLED      = n

选项	含义
FEATURE_MQTT_COMM_ENABLED	是否使用 MQTT 通道功能的总开关，当前不得关闭
FEATURE_COAP_COMM_ENABLED	是否使用 CoAP 通道功能的总开关，当前不得关闭
FEATURE_SDKTESTS_ENABLED	是否编译测试代码
FEATURE_MQTT_RMDUP_MSG_ENABLED	是否启用 MQTT 消息去重功能
FEATURE_OTA_COMM_ENABLED	是否启用 OTA 功能
FEATURE_ASYMC_ENCRYPTION_ENABLED	是否启用非对称加密方式

通过编辑make.settings文件, 把不需要的功能模块关闭, 可以减小最终编译出libiot_sdk.a库文件的大小, 以节省嵌入式设备上的资源 例如只需要 MQTT 通道, 不需要 CoAP通道, 可以将默认的make.settings修改如下：

FEATURE_MQTT_COMM_ENABLED   	= y
FEATURE_COAP_COMM_ENABLED   	= n

SDK API说明

API列表

src/sdk-impl$ grep -o "IOT_[A-Z][_a-zA-Z]*[^_]\> *(" qcloud_iot_export.h exports/*.h|sed 's!.*:\(.*\)(!\1!'|cat -n
                          
     1	IOT_MQTT_KEEP_ALIVE_INTERNAL                         
     2	IOT_MQTT_COMMAND_TIMEOUT                             
     3	IOT_TLS_HANDSHAKE_TIMEOUT                            
     4	IOT_MQTT_TX_BUF_LEN                                  
     5	IOT_MQTT_RX_BUF_LEN                                  
     6	IOT_COAP_Construct
     7	IOT_COAP_Destroy
     8	IOT_COAP_Yield
     9	IOT_COAP_SendMessage
    10	IOT_COAP_GetMessageId
    11	IOT_COAP_GetMessagePayload
    12	IOT_COAP_GetMessageCode
    13	IOT_Log_Set_Level
    14	IOT_Log_Get_Level
    15	IOT_Log_Set_MessageHandler
    16	IOT_FUNC_EXIT_RC
    17	IOT_FUNC_EXIT_RC
    18	IOT_MQTT_Construct
    19	IOT_MQTT_Destroy
    20	IOT_MQTT_Yield
    21	IOT_MQTT_Publish
    22	IOT_MQTT_Subscribe
    23	IOT_MQTT_Unsubscribe
    24	IOT_MQTT_IsConnected
    25	IOT_MQTT_JSON_GetAction
    26	IOT_OTA_Init
    27	IOT_OTA_Destroy
    28	IOT_OTA_ReportVersion
    29	IOT_OTA_ReportProgress
    30	IOT_OTA_ReportUpgradeBegin
    31	IOT_OTA_ReportUpgradeSuccess
    32	IOT_OTA_ReportUpgradeFail
    33	IOT_OTA_IsFetching
    34	IOT_OTA_IsFetchFinish
    35	IOT_OTA_FetchYield
    36	IOT_OTA_Ioctl
    37	IOT_OTA_GetLastError
    38	IOT_Shadow_Construct
    39	IOT_Shadow_Publish
    40	IOT_Shadow_Subscribe
    41	IOT_Shadow_Unsubscribe
    42	IOT_Shadow_IsConnected
    43	IOT_Shadow_Destroy
    44	IOT_Shadow_Yield
    45	IOT_Shadow_Update
    46	IOT_Shadow_Update_Sync
    47	IOT_Shadow_Get
    48	IOT_Shadow_Get_Sync
    49	IOT_Shadow_Register_Property
    50	IOT_Shadow_UnRegister_Property
    51	IOT_Shadow_JSON_ConstructReport
    52	IOT_Shadow_JSON_ConstructReportAndDesireAllNull
    53	IOT_Shadow_JSON_ConstructDesireAllNull

日志接口

序号	函数名	说明
1	IOT_Log_Set_Level	设置打印的日志等级
2	IOT_Log_Get_Level	返回日志输出的等级
3	IOT_Log_Set_MessageHandler	设置日志回调函数，接管 SDK 日志用于其它输出方式

MQTT 接口

序号	函数名	说明
1	IOT_MQTT_Construct	构造 MQTTClient 并完成 MQTT 连接
2	IOT_MQTT_Destroy	关闭 MQTT 连接并销毁 MQTTClient
3	IOT_MQTT_Yield	在当前线程为底层 MQTT 客户端让出一定 CPU 执行时间
4	IOT_MQTT_Publish	发布 MQTT 消息
5	IOT_MQTT_Subscribe	订阅 MQTT 主题
6	IOT_MQTT_Unsubscribe	取消订阅 MQTT 主题
7	IOT_MQTT_IsConnected	客户端目前是否已连接
8	IOT_MQTT_JSON_GetAction	从 JSON 文档中解析出 action 字段

设备影子接口

序号	函数名	说明
1	IOT_Shadow_Construct	构造 ShadowClient
2	IOT_Shadow_Destroy	关闭 Shadow 连接并销毁 ShadowClient
3	IOT_Shadow_Yield	在当前线程为底层 Shadow 客户端让出一定 CPU 执行时间
4	IOT_Shadow_IsConnected	客户端目前是否已连接
5	IOT_Shadow_Publish	发布 MQTT 消息
6	IOT_Shadow_Subscribe	订阅 MQTT 主题
7	IOT_Shadow_Unsubscribe	取消订阅 MQTT 主题
8	IOT_Shadow_Update	异步方式更新设备影子文档
9	IOT_Shadow_Update_Sync	同步步方式更新设备影子文档
10	IOT_Shadow_Get	异步方式获取设备影子文档
11	IOT_Shadow_Get_Sync	同步方式获取设备影子文档
12	IOT_Shadow_Register_Property	注册当前设备的设备属性
13	IOT_Shadow_JSON_ConstructReport	在JSON文档中添加 reported 字段
14	IOT_Shadow_JSON_ConstructReportAndDesireAllNull	在JSON文档中添加 reported 字段，同时清空 desired 字段赋值为 null
15	IOT_Shadow_JSON_ConstructDesireAllNull	在JSON文档中将 desired 字段赋值为 null

CoAP 接口

序号	函数名	说明
1	IOT_COAP_Construct	构造 CoAPClient 并完成 CoAP 连接
2	IOT_COAP_Destroy	关闭 CoAP 连接并销毁 CoAPClient
3	IOT_COAP_Yield	在当前线程为底层 CoAP 客户端让出一定 CPU 执行时间
4	IOT_COAP_SendMessage	发布 CoAP 消息
5	IOT_COAP_GetMessageId	获取 CoAP Response 消息 msgId
6	IOT_COAP_GetMessagePayload	获取 CoAP Response 消息内容
7	IOT_COAP_GetMessageCode	获取 CoAP Response 消息错误码

OTA 接口

序号	函数名	说明
1	IOT_OTA_Init	OTA 实例的构造函数, 创建一个 OTA 会话的句柄并返回
2	IOT_OTA_Destroy	销毁并释放 OTA 相关的资源
3	IOT_OTA_ReportVersion	向 OTA 服务器上报固件版本信息
4	IOT_OTA_ReportUpgradeBegin	当进行升级前，需要向 OTA 服务器上报即将升级的状态
5	IOT_OTA_ReportUpgradeSuccess	当升级成功之后，需要向 OTA 服务器上报升级已完成的状态
6	IOT_OTA_ReportUpgradeFail	当升级失败之后，需要向 OTA 服务器上报升级失败的状态
7	IOT_OTA_IsFetching	检查是否处于下载固件的状态
8	IOT_OTA_IsFetchFinish	检查固件是否已经下载完成
9	IOT_OTA_FetchYield	OTA 下载阶段, 在指定的timeout时间内, 从固件服务器下载一段固件内容, 保存在入参buffer中
10	IOT_OTA_Ioctl	OTA 实例的输入输出函数, 根据不同的命令字可以设置 OTA 会话的属性, 或者获取 OTA 会话的状态