对设备端SDK的使用分为如下几步:
- 修改编译配置进行编译, 详见设备端SDK的编译页面
- 获取编译好的SDK, 如成功存放在
output/release/lib/*.a
- 将
libiot_sdk.a libiot_platform.a libmbedcrypto.a libmbedtls.a libmbedtls.a等配合output/release/include/目录下的头文件, 加入您自己的工程使用
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顶层目录的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
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 日志用于其它输出方式 |
| 序号 |
函数名 |
说明 |
| 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 |
| 序号 |
函数名 |
说明 |
| 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 消息错误码 |
| 序号 |
函数名 |
说明 |
| 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 会话的状态 |