Skip to content

Commit af362aa

Browse files
spikelinspikelin
committed
C-SDK v3.1.3
1.优化ota_mqtt_sample，将ota流程以及需要文件操作的地方解耦分离，并且sample支持MQTT断开重连之后仍然可以恢复下载。 2.优化gateway_sample，并增加代理一个以上子设备示例代码。 3.增加查询MQTT主题是否订阅成功的接口。 4.优化及更新文档。 5.修复一些编译警告及bug
1 parent e2ef5e0 commit af362aa

33 files changed

+894
-405
lines changed

‎CMakeLists.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ set(FEATURE_MQTT_DEVICE_SHADOW ON)
2828
set(FEATURE_COAP_COMM_ENABLED ON)
2929

3030
# 是否打开MQTT通道网关功能
31-
set(FEATURE_GATEWAY_ENABLED OFF)
31+
set(FEATURE_GATEWAY_ENABLED ON)
3232

3333
# 是否打开OTA固件升级总开关
3434
set(FEATURE_OTA_COMM_ENABLED ON)

‎docs/C-SDK_API及可变参数说明.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ C-SDK 的使用可以根据具体场景需求，配置相应的参数，满足
3838

3939
## API 函数说明
4040
以下是 C-SDK v3.1.0版本提供的主要功能和对应 API 接口说明，用于客户编写业务逻辑，更加详细的说明如接口参数及返回值可查看SDK代码 include/exports/qcloud_iot_export_*.h 等头文件中的注释
41+
接口使用示例代码请参考samples目录下的对应代码，以及docs/IoT_Hub目录下的文档说明
4142

4243
### 1. MQTT 接口
4344

@@ -154,3 +155,8 @@ SDK对于MQTT接口在多线程环境下的使用有如下注意事项：
154155
| 5 | IOT_Gateway_Subscribe | 订阅 MQTT 主题 |
155156
| 6 | IOT_Gateway_Unsubscribe | 取消订阅已订阅的 MQTT 主题 |
156157

158+
### 8. 动态注册接口
159+
160+
| 序号 | 函数名 | 说明 |
161+
| ---- | ---------------------------- | ------------------------------------------------- |
162+
| 1 | IOT_DynReg_Device | 向后台动态注册设备并获取设备密钥或者证书 |

‎docs/C-SDK_Build编译环境及配置选项说明.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ sdk_src为SDK的核心逻辑及协议相关代码，一般不需要修改，其
6363
| FEATURE_LOG_UPLOAD_ENABLED | ON/OFF | 日志上报开关 |
6464
| FEATURE_DEBUG_DEV_INFO_USED | ON/OFF | 设备信息获取来源开关 |
6565
| FEATURE_SYSTEM_COMM_ENABLED | ON/OFF | 获取后台时间开关 |
66+
| FEATURE_OTA_USE_HTTPS | ON/OFF | 是否使用HTTPS下载固件 |
6667
| FEATURE_AT_TCP_ENABLED | ON/OFF | AT模组TCP功能开关 |
6768
| FEATURE_AT_UART_RECV_IRQ | ON/OFF | AT模组中断接受功能开关 |
6869
| FEATURE_AT_OS_USED | ON/OFF | AT模组多线程功能开关 |

‎docs/IoT_Hub/IoT_Hub通信平台快速入门.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@
88
## 设备影子
99
请参考**shadow_sample_设备影子.md**文档，介绍设备影子功能，并结合 SDK 的**shadow_sample**展示影子的数据流和功能
1010

11+
## 固件升级
12+
请参考**ota_sample_固件升级.md**文档，介绍固件升级功能，并结合 SDK 的**ota_mqtt_sample**展示固件升级的流程和功能
13+
1114
## 网关功能
1215
请参考**gateway_sample_网关功能.md**文档，介绍如何在腾讯IoT Hub控制台申请网关设备并绑定子设备, 并结合本 SDK 的**gateway_sample**快速体验网关设备通过 MQTT 协议连接到腾讯云IoT Hub, 代理子设备上下线，发送和接收消息。
1316

‎docs/IoT_Hub/gateway_sample_网关功能.md‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,4 +128,21 @@ INF|2019-09-16 14:35:35|gateway_common.c|_gateway_message_handler(134): client_i
128128
DBG|2019-09-16 14:35:35|mqtt_client_publish.c|qcloud_iot_mqtt_publish(329): publish topic seq=27804|topicName=S3EUVBRJLB/test_device/data|payload={"data":"test gateway"}
129129
INF|2019-09-16 14:35:35|gateway_sample.c|_event_handler(88): publish success, packet-id=27804
130130
INF|2019-09-16 14:35:35|gateway_sample.c|_message_handler(111): Receive Message With topicName:S3EUVBRJLB/test_device/data, payload:{"data":"test gateway"}
131-
```
131+
```
132+
133+
## 三. 代码说明
134+
135+
gateway_sample示例演示了网关代理一个子设备的情况，如果用户需要增加更多子设备，可以先在控制台添加子设备，然后在代码里面通过创建更多GatewayParam参数实例，并将GatewayParam参数传递给网关各个API，即可以实现网关代理多个子设备进行通讯。
136+
```
137+
// one GatewayParam only support one sub-device
138+
// use more GatewayParam to add more sub-device
139+
GatewayParam gw_param1 = DEFAULT_GATEWAY_PARAMS;;
140+
gw_param1.product_id = gw_dev_info.gw_info.product_id;
141+
gw_param1.device_name = gw_dev_info.gw_info.device_name;
142+
143+
gw_param1.subdev_product_id = "SUB-PRODUCT1";
144+
gw_param1.subdev_device_name = "SUB-DEVICE1";
145+
146+
IOT_Gateway_Subdev_Online(client, &gw_param1);
147+
```
148+

‎docs/IoT_Hub/ota_sample_固件升级.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# OTA设备固件升级
2+
3+
关于物联平台 OTA 固件升级功能及流程介绍，请参考官网文档[设备固件升级](https://cloud.tencent.com/document/product/634/14674)
4+
5+
## 一. 上传固件
6+
7+
进行固件升级，首先要上传固件到物联网后台，可以通过控制台进行上传，如下图示：
8+
![](https://main.qcloudimg.com/raw/219ab155f886e2ac1a1ebd0d7a1184aa.png)
9+
10+
## 二. 编译运行示例程序(以**MQTT密钥认证设备**为例)
11+
#### 1. 编译 SDK
12+
修改CMakeLists.txt确保以下选项存在
13+
```
14+
set(BUILD_TYPE "release")
15+
set(COMPILE_TOOLS "gcc")
16+
set(PLATFORM "linux")
17+
set(FEATURE_MQTT_COMM_ENABLED ON)
18+
set(FEATURE_OTA_COMM_ENABLED ON)
19+
set(FEATURE_OTA_SIGNAL_CHANNEL "MQTT")
20+
set(FEATURE_AUTH_MODE "KEY")
21+
set(FEATURE_AUTH_WITH_NOTLS OFF)
22+
set(FEATURE_DEBUG_DEV_INFO_USED OFF)
23+
```
24+
执行脚本编译
25+
```
26+
./cmake_build.sh
27+
```
28+
示例输出ota_mqtt_sample位于`output/release/bin`文件夹中
29+
30+
#### 2. 填写设备信息
31+
将设备信息填写到配置文件device_info.json中
32+
```
33+
{
34+
"auth_mode":"KEY",
35+
"productId":"S3EUVBRJLB",
36+
"deviceName":"test_device",
37+
"key_deviceinfo":{
38+
"deviceSecret":"vX6PQqazsGsMyf5SMfs6OA6y"
39+
}
40+
}
41+
```
42+
43+
#### 3. 运行示例
44+
执行OTA MQTT例程ota_mqtt_sample：
45+
```
46+
./output/release/bin/ota_mqtt_sample
47+
INF|2020-03-04 16:50:35|qcloud_iot_device.c|iot_device_info_set(50): SDK_Ver: 3.1.2, Product_ID: S3EUVBRJLB, Device_Name: test_device
48+
DBG|2020-03-04 16:50:35|HAL_TLS_mbedtls.c|HAL_TLS_Connect(206): Setting up the SSL/TLS structure...
49+
DBG|2020-03-04 16:50:35|HAL_TLS_mbedtls.c|HAL_TLS_Connect(248): Performing the SSL/TLS handshake...
50+
DBG|2020-03-04 16:50:35|HAL_TLS_mbedtls.c|HAL_TLS_Connect(249): Connecting to /S3EUVBRJLB.iotcloud.tencentdevices.com/8883...
51+
INF|2020-03-04 16:50:35|HAL_TLS_mbedtls.c|HAL_TLS_Connect(271): connected with /S3EUVBRJLB.iotcloud.tencentdevices.com/8883...
52+
INF|2020-03-04 16:50:35|mqtt_client.c|IOT_MQTT_Construct(111): mqtt connect with id: BzaMF success
53+
INF|2020-03-04 16:50:35|ota_mqtt_sample.c|main(516): Cloud Device Construct Success
54+
DBG|2020-03-04 16:50:35|mqtt_client_subscribe.c|qcloud_iot_mqtt_subscribe(141): topicName=$ota/update/S3EUVBRJLB/test_device|packet_id=63333
55+
INF|2020-03-04 16:50:35|ota_mqtt_sample.c|_event_handler(77): subscribe success, packet-id=63333
56+
DBG|2020-03-04 16:50:35|ota_mqtt.c|_otamqtt_event_callback(117): OTA topic subscribe success
57+
INF|2020-03-04 16:50:36|ota_mqtt_sample.c|_get_local_fw_running_version(363): FW running version: 1.0.0
58+
DBG|2020-03-04 16:50:36|mqtt_client_publish.c|qcloud_iot_mqtt_publish(334): publish topic seq=63334|topicName=$ota/report/S3EUVBRJLB/test_device|payload={"type": "report_version", "report":{"version":"1.0.0"}}
59+
INF|2020-03-04 16:50:36|ota_mqtt_sample.c|_event_handler(89): publish success, packet-id=63334
60+
DBG|2020-03-04 16:50:36|ota_mqtt.c|_otamqtt_upgrage_cb(103): topic=$ota/update/S3EUVBRJLB/test_device
61+
INF|2020-03-04 16:50:36|ota_mqtt.c|_otamqtt_upgrage_cb(104): len=86, topic_msg={"result_code":0,"result_msg":"success","type":"report_version_rsp","version":"1.0.0"}
62+
INF|2020-03-04 16:50:36|ota_client.c|_ota_callback(102): Report version success!
63+
INF|2020-03-04 16:50:36|ota_mqtt_sample.c|process_ota(389): wait for ota upgrade command...
64+
INF|2020-03-04 16:50:37|ota_mqtt_sample.c|process_ota(389): wait for ota upgrade command...
65+
```
66+
可以看到设备已经上报了当前的固件版本，并在等待固件升级的命令下发
67+
68+
#### 4. 执行固件升级命令
69+
70+
在收到设备上报的固件版本之后，可以选择要升级的新固件版本并执行升级命令，可以通过控制台进行操作，如下图示：
71+
![](https://main.qcloudimg.com/raw/ac71788c5bc5d542eb10292751e12fbe.png)
72+
73+
这个时候再观察sample的示例打印，可以看到设备端通过MQTT接收到升级命令，并且通过HTTPS去下载固件并保存到本地
74+
```
75+
INF|2020-03-04 16:50:38|ota_mqtt_sample.c|process_ota(389): wait for ota upgrade command...
76+
DBG|2020-03-04 16:50:39|ota_mqtt.c|_otamqtt_upgrage_cb(103): topic=$ota/update/S3EUVBRJLB/test_device
77+
INF|2020-03-04 16:50:39|ota_mqtt.c|_otamqtt_upgrage_cb(104): len=454, topic_msg={"file_size":175436,"md5sum":"ad4615b866c13afb8b293a679bfa5dc4","type":"update_firmware","url":"https://ota-1255858890.cos.ap-guangzhou.myqcloud.com/100008768029_S3EUVBRJLB_1.3.0?sign=q-sign-algorithm%3Dsha1%26q-ak%3DAKIDdO8ldrUa0Uts4H5Gzx6FZ9nfedjpiCd7%26q-sign-time%3D1583311839%3B1583398239%26q-key-time%3D1583311839%3B1583398239%26q-header-list%3D%26q-url-param-list%3D%26q-signature%3D1215yt303628f88f31c9a7734ead8a7fa32ed1b3%00","version":"1.3.0"}
78+
79+
INF|2020-03-04 16:50:39|ota_mqtt_sample.c|process_ota(389): wait for ota upgrade command...
80+
ERR|2020-03-04 16:50:39|ota_mqtt_sample.c|_get_local_fw_info(251): open file ./FW_S3EUVBRJLBtest_device.json failed
81+
DBG|2020-03-04 16:50:39|ota_client.c|IOT_OTA_StartDownload(347): to download FW from offset: 0, size: 175436
82+
DBG|2020-03-04 16:50:39|ota_fetch.c|ofc_Init(83): head_content:Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
83+
Accept-Encoding: gzip, deflate
84+
Range: bytes=0-175436
85+
86+
DBG|2020-03-04 16:50:39|HAL_TLS_mbedtls.c|_mbedtls_client_init(134): psk/pskid is empty!|psk=(null)|psd_id=(null)
87+
DBG|2020-03-04 16:50:39|HAL_TLS_mbedtls.c|HAL_TLS_Connect(206): Setting up the SSL/TLS structure...
88+
DBG|2020-03-04 16:50:39|HAL_TLS_mbedtls.c|HAL_TLS_Connect(248): Performing the SSL/TLS handshake...
89+
DBG|2020-03-04 16:50:39|HAL_TLS_mbedtls.c|HAL_TLS_Connect(249): Connecting to /ota-1255858890.cos.ap-guangzhou.myqcloud.com/443...
90+
INF|2020-03-04 16:50:40|HAL_TLS_mbedtls.c|HAL_TLS_Connect(271): connected with /ota-1255858890.cos.ap-guangzhou.myqcloud.com/443...
91+
DBG|2020-03-04 16:50:40|utils_httpc.c|qcloud_http_client_connect(747): http client connect success
92+
DBG|2020-03-04 16:50:40|mqtt_client_publish.c|qcloud_iot_mqtt_publish(340): publish packetID=0|topicName=$ota/report/S3EUVBRJLB/test_device|payload={"type": "report_progress", "report": {"progress": {"state":"downloading", "percent":"0", "result_code":"0", "result_msg":""}, "version": "1.3.0"}}
93+
DBG|2020-03-04 16:50:41|mqtt_client_publish.c|qcloud_iot_mqtt_publish(340): publish packetID=0|topicName=$ota/report/S3EUVBRJLB/test_device|payload={"type": "report_progress", "report": {"progress": {"state":"downloading", "percent":"31", "result_code":"0", "result_msg":""}, "version": "1.3.0"}}
94+
DBG|2020-03-04 16:50:42|mqtt_client_publish.c|qcloud_iot_mqtt_publish(340): publish packetID=0|topicName=$ota/report/S3EUVBRJLB/test_device|payload={"type": "report_progress", "report": {"progress": {"state":"downloading", "percent":"59", "result_code":"0", "result_msg":""}, "version": "1.3.0"}}
95+
DBG|2020-03-04 16:50:43|mqtt_client_publish.c|qcloud_iot_mqtt_publish(340): publish packetID=0|topicName=$ota/report/S3EUVBRJLB/test_device|payload={"type": "report_progress", "report": {"progress": {"state":"downloading", "percent":"88", "result_code":"0", "result_msg":""}, "version": "1.3.0"}}
96+
DBG|2020-03-04 16:50:43|mqtt_client_publish.c|qcloud_iot_mqtt_publish(340): publish packetID=0|topicName=$ota/report/S3EUVBRJLB/test_device|payload={"type": "report_progress", "report": {"progress": {"state":"downloading", "percent":"100", "result_code":"0", "result_msg":""}, "version": "1.3.0"}}
97+
INF|2020-03-04 16:50:43|ota_client.c|IOT_OTA_Ioctl(638): FW MD5 check: origin=ad4615b866c13afb8b293a679bfa5dc4, now=ad4615b866c13afb8b293a679bfa5dc4
98+
INF|2020-03-04 16:50:43|ota_mqtt_sample.c|process_ota(456): The firmware is valid
99+
DBG|2020-03-04 16:50:43|mqtt_client_publish.c|qcloud_iot_mqtt_publish(334): publish topic seq=63335|topicName=$ota/report/S3EUVBRJLB/test_device|payload={"type": "report_progress", "report":{"progress":{"state":"done", "result_code":"0", "result_msg":""}, "version":"1.3.0"}}
100+
INF|2020-03-04 16:50:44|ota_mqtt_sample.c|_event_handler(89): publish success, packet-id=63335
101+
INF|2020-03-04 16:50:44|mqtt_client_connect.c|qcloud_iot_mqtt_disconnect(450): mqtt disconnect!
102+
INF|2020-03-04 16:50:44|ota_mqtt.c|_otamqtt_event_callback(135): mqtt client has been destroyed
103+
INF|2020-03-04 16:50:44|mqtt_client.c|IOT_MQTT_Destroy(171): mqtt release!
104+
```
105+
106+
## 三. 代码使用说明
107+
108+
1. 固件升级，支持通过HTTP或者HTTPS来下载固件，可以通过编译选项FEATURE_OTA_USE_HTTPS来选择
109+
2. SDK的固件升级，支持断点续传功能，即当固件下载过程因为网络或者其他原因中断了，则再次下载的时候，可以从上一次中断的位置继续下载。
110+
3. 在ota_mqtt_sample.c中，process_ota函数为OTA的核心流程，包括了版本上报，等待升级命令，发起下载并保存，校验文件MD5以及回复升级结果的过程，同时为断点续传功能实时保存下载状态。该函数在各个平台适配的时候可以保持不变。而跟固件保存，断点续传状态保存相关的功能函数，则跟平台密切相关，示例中使用了文件操作，在支持标准文件操作的系统比如Linux/Windows上面可以直接使用，对于其他平台则需要进行适配。
111+
112+

‎include/exports/qcloud_iot_export_gateway.h‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,15 @@ int IOT_Gateway_Subscribe(void *client, char *topic_filter, SubscribeParams *par
131131
*/
132132
int IOT_Gateway_Unsubscribe(void *client, char *topic_filter);
133133

134+
/**
135+
* @brief check if MQTT topic has been subscribed or not
136+
*
137+
* @param pClient handle to MQTT client
138+
* @param topicFilter MQTT topic filter
139+
*
140+
* @return true when successfully subscribed, or false if not yet
141+
*/
142+
int IOT_Gateway_IsSubReady(void *client, char *topic_filter);
134143

135144
/**
136145
* @brief Check connection and keep alive state, read/handle MQTT message in synchronized way
@@ -142,6 +151,14 @@ int IOT_Gateway_Unsubscribe(void *client, char *topic_filter);
142151
*/
143152
int IOT_Gateway_Yield(void *client, uint32_t timeout_ms);
144153

154+
/**
155+
* @brief Return the MQTT client dedicated to this gateway handle
156+
*
157+
* @param pClient handle to gateway client
158+
*
159+
* @return a valid mqtt client handle when success, or NULL otherwise
160+
*/
161+
void *IOT_Gateway_Get_Mqtt_Client(void *handle);
145162

146163
#ifdef __cplusplus
147164
}

‎include/exports/qcloud_iot_export_mqtt.h‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -248,6 +248,16 @@ int IOT_MQTT_Subscribe(void *pClient, char *topicFilter, SubscribeParams *pParam
248248
*/
249249
int IOT_MQTT_Unsubscribe(void *pClient, char *topicFilter);
250250

251+
/**
252+
* @brief check if MQTT topic has been subscribed or not
253+
*
254+
* @param pClient handle to MQTT client
255+
* @param topicFilter MQTT topic filter
256+
*
257+
* @return true when successfully subscribed, or false if not yet
258+
*/
259+
bool IOT_MQTT_IsSubReady(void *pClient, char *topicFilter);
260+
251261
/**
252262
* @brief Check if MQTT is connected
253263
*

‎include/exports/qcloud_iot_export_ota.h‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,6 +148,8 @@ int IOT_OTA_StartDownload(void *handle, uint32_t offset, uint32_t size);
148148
*/
149149
void IOT_OTA_UpdateClientMd5(void *handle, char * buff, uint32_t size);
150150

151+
int IOT_OTA_ResetClientMD5(void *handle);
152+
151153
/**
152154
* @brief Report local firmware version to server
153155
* NOTE: do this report before real download

‎include/exports/qcloud_iot_export_shadow.h‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,7 @@ typedef struct _JSONNode {
101101
char *key; // Key of this JSON node
102102
void *data; // Value of this JSON node
103103
JsonDataType type; // Data type of this JSON node
104+
bool delta_arrived;
104105
} DeviceProperty;
105106

106107

@@ -173,6 +174,15 @@ typedef void (*OnPropRegCallback)(void *pClient, const char *pJsonValueBuffer, u
173174
*/
174175
void* IOT_Shadow_Construct(ShadowInitParams *pParams);
175176

177+
/**
178+
* @brief Return the MQTT client dedicated to this shadow handle
179+
*
180+
* @param pClient handle to shadow client
181+
*
182+
* @return a valid mqtt client handle when success, or NULL otherwise
183+
*/
184+
void *IOT_Shadow_Get_Mqtt_Client(void *handle);
185+
176186
/**
177187
* @brief Publish MQTT message
178188
*

0 commit comments

Comments
 (0)