Skip to content

Commit 5381d0e

Browse files
author
spikelin
committed
v3.2.2
1. 新增远程配置功能及示例 2. 网关增加获取子设备列表接口 3. 更新文档
1 parent 0d2c305 commit 5381d0e

23 files changed

+1190
-33
lines changed

‎CMakeLists.txt

+11-7
Original file line numberDiff line numberDiff line change
@@ -60,12 +60,6 @@ set(FEATURE_SYSTEM_COMM_ENABLED ON)
6060
# 是否使用HTTPS下载固件
6161
set(FEATURE_OTA_USE_HTTPS ON)
6262

63-
# 是否打开广播功能
64-
set(FEATURE_BROADCAST_ENABLED ON)
65-
66-
# 是否打开RRPC功能
67-
set(FEATURE_RRPC_ENABLED ON)
68-
6963
# 是否打开AT模组TCP功能
7064
set(FEATURE_AT_TCP_ENABLED OFF)
7165

@@ -76,11 +70,20 @@ set(AT_DEVICE_NAME "esp8266")
7670
set(FEATURE_AT_UART_RECV_IRQ OFF)
7771

7872
# 是否打开AT模组多线程功能
79-
set(FEATURE_AT_OS_USED OFF)
73+
set(FEATURE_AT_OS_USED ON)
8074

8175
# 是否打开AT模组调试功能
8276
set(FEATURE_AT_DEBUG OFF)
8377

78+
# 是否打开广播功能
79+
set(FEATURE_BROADCAST_ENABLED ON)
80+
81+
# 是否打开RRPC功能
82+
set(FEATURE_RRPC_ENABLED ON)
83+
84+
# 是否打开远程配置功能
85+
set(FEATURE_REMOTE_CONFIG_MQTT_ENABLED ON)
86+
8487
######################CONFIG END######################################
8588

8689
# 设置CMAKE使用编译工具及编译选项
@@ -155,6 +158,7 @@ option(OTA_USE_HTTPS "Enable OTA_USE_HTTPS" ${FEATURE_OTA_USE_HTTPS})
155158
option(AT_TCP_ENABLED "Enable AT_TCP" ${FEATURE_AT_TCP_ENABLED})
156159
option(BROADCAST_ENABLED "Enable BROADCAST" ${FEATURE_BROADCAST_ENABLED})
157160
option(RRPC_ENABLED "Enable RRPC" ${FEATURE_RRPC_ENABLED})
161+
option(REMOTE_CONFIG_MQTT "Enable REMOTE_CONFIG_MQTT" ${FEATURE_REMOTE_CONFIG_MQTT_ENABLED})
158162

159163
if(AT_TCP_ENABLED STREQUAL "ON")
160164
option(AT_UART_RECV_IRQ "Enable AT_UART_RECV_IRQ" ${FEATURE_AT_UART_RECV_IRQ})

‎Makefile

+4
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,10 @@ $(call CompLib_Map, RRPC_ENABLED, \
9898
$(SRC_DIR)/services/rrpc \
9999
)
100100

101+
$(call CompLib_Map, REMOTE_CONFIG_MQTT_ENABLED, \
102+
$(SRC_DIR)/services/config \
103+
)
104+
101105
IOTSDK_SRC_FILES := \
102106

103107
$(foreach v, \

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

+24-14
Original file line numberDiff line numberDiff line change
@@ -145,19 +145,21 @@ MQTT构造时候除了提供设备信息，还需要提供一个回调函数，
145145
### 网关功能接口
146146
关于网关功能介绍，可以参考SDK docs/IoT_Hub/网关功能文档
147147

148-
| 序号 | 函数名 | 说明 |
149-
| ---- | ---------------------------- | ------------------------------------------------- |
150-
| 1 | IOT_Gateway_Construct | 构造 Gateway client 并完成 MQTT 连接 |
151-
| 2 | IOT_Gateway_Destroy | 关闭 MQTT 连接并销毁 Gateway client |
152-
| 3 | IOT_Gateway_Subdev_Bind | 网关绑定子设备 |
153-
| 4 | IOT_Gateway_Subdev_Unbind | 网关解绑子设备 |
154-
| 5 | IOT_Gateway_Subdev_Online | 代理子设备上线 |
155-
| 6 | IOT_Gateway_Subdev_Offline | 代理子设备下线 |
156-
| 7 | IOT_Gateway_Yield | 在当前线程上下文中，进行 MQTT 报文读取，消息处理，超时请求，心跳包及重连状态管理等任务 |
157-
| 8 | IOT_Gateway_Publish | 发布 MQTT 消息 |
158-
| 9 | IOT_Gateway_Subscribe | 订阅 MQTT 主题 |
159-
| 10 | IOT_Gateway_Unsubscribe | 取消订阅已订阅的 MQTT 主题 |
160-
| 11 | IOT_Gateway_Get_Mqtt_Client | 获取该GatewayClient对应的MQTTclient |
148+
| 序号 | 函数名 | 说明 |
149+
| ---- | ---------------------------------- | ----------------------------------------------------|
150+
| 1 | IOT_Gateway_Construct | 构造 Gateway client 并完成 MQTT 连接 |
151+
| 2 | IOT_Gateway_Destroy | 关闭 MQTT 连接并销毁 Gateway client |
152+
| 3 | IOT_Gateway_Subdev_Bind | 网关绑定子设备 |
153+
| 4 | IOT_Gateway_Subdev_Unbind | 网关解绑子设备 |
154+
| 5 | IOT_Gateway_Subdev_Online | 代理子设备上线 |
155+
| 6 | IOT_Gateway_Subdev_Offline | 代理子设备下线 |
156+
| 7 | IOT_Gateway_Yield | 在当前线程上下文中，进行 MQTT 报文读取，消息处理，超时请求，心跳包及重连状态管理等任务 |
157+
| 8 | IOT_Gateway_Publish | 发布 MQTT 消息 |
158+
| 9 | IOT_Gateway_Subscribe | 订阅 MQTT 主题 |
159+
| 10 | IOT_Gateway_Unsubscribe | 取消订阅已订阅的 MQTT 主题 |
160+
| 11 | IOT_Gateway_Get_Mqtt_Client | 获取该GatewayClient对应的MQTTclient |
161+
| 12 | IOT_Gateway_Subdev_GetBindList | 获取网关在云平台已绑定的子设备列表 |
162+
| 13 | IOT_Gateway_Subdev_DestoryBindList | 销毁获取到的已绑定子设备列表数据 |
161163

162164
### 动态注册接口
163165
关于动态注册功能介绍，可以参考SDK docs/IoT_Hub/动态注册文档
@@ -179,4 +181,12 @@ MQTT构造时候除了提供设备信息，还需要提供一个回调函数，
179181
| 序号 | 函数名 | 说明 |
180182
| ---- | ---------------------------- | ------------------------------------------------- |
181183
| 1 | IOT_RRPC_Init | 订阅接收rrpc消息的主题并提供消息回调处理函数 |
182-
| 2 | IOT_RRPC_Reply | 回复rrpc消息 |
184+
| 2 | IOT_RRPC_Reply | 回复rrpc消息 |
185+
186+
### 远程配置接口
187+
关于远程配置功能介绍，可以参考SDK docs/IoT_Hub/remote_config_mqtt_sample_远程配置文档
188+
189+
| 序号 | 函数名 | 说明 |
190+
| ---- | ---------------------------- | -------------------------- |
191+
| 1 | IOT_Subscribe_Config | 向云平台订阅远程配置 topic |
192+
| 2 | IOT_Get_Config | 向云平台获取设备配置 |

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

+8
Original file line numberDiff line numberDiff line change
@@ -156,3 +156,11 @@ gateway_sample示例演示了网关代理一个子设备的情况，如果用户
156156
IOT_Gateway_Subdev_Online(client, &gw_param1);
157157
```
158158

159+
#### 获取网关在云平台上已绑定的设备列表
160+
网关在进行子设备绑定前可获取云平台上已绑定的子设备列表，SDK 提供了对应的接口
161+
```
162+
int IOT_Gateway_Subdev_GetBindList(void *client, GatewayParam *param, SubdevBindList *subdev_bindlist);
163+
void IOT_Gateway_Subdev_DestoryBindList(SubdevBindList *subdev_bindlist);
164+
165+
```
166+

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

+13-3
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
## 一. 上传固件
66

77
进行固件升级，首先要上传固件到物联网后台，可以通过控制台进行上传，如下图示：
8-
![](https://main.qcloudimg.com/raw/219ab155f886e2ac1a1ebd0d7a1184aa.png)
8+
![](https://main.qcloudimg.com/raw/2ccbc69f812c91884941060b17db86e8.png)
99

1010
## 二. 编译运行示例程序(以**MQTT密钥认证设备**为例)
1111
#### 1. 编译 SDK
@@ -67,8 +67,18 @@ INF|2020-03-04 16:50:37|ota_mqtt_sample.c|process_ota(389): wait for ota upgrade
6767

6868
#### 4. 执行固件升级命令
6969

70-
在收到设备上报的固件版本之后，可以选择要升级的新固件版本并执行升级命令，可以通过控制台进行操作，如下图示：
71-
![](https://main.qcloudimg.com/raw/ac71788c5bc5d542eb10292751e12fbe.png)
70+
在收到设备上报的固件版本之后，可以选择要升级的新固件版本并执行升级命令，可以通过控制台进行操作，控制台有三种升级方式供选择，分别是：
71+
72+
1. 按固件版本号升级所有设备。选择的版本号是待升级的版本号，可选多个待升级版本号。
73+
![](https://main.qcloudimg.com/raw/dcc27c9875ee4f94b9016e6ee094895e.png)
74+
2. 按固件版本号批量升级指定设备。选择的版本号是待升级的版本号，可选多个待升级版本号；选择的设备是本次待升级的设备，可选多个待升级设备。
75+
![](https://main.qcloudimg.com/raw/aea220c450a1d32fadf3f3b693840f4c.png)
76+
3. 按设备名称批量升级模板文件中的设备。不关心待升级的版本号，直接将模板文件中的设备升级为选择的固件。
77+
![](https://main.qcloudimg.com/raw/86c1c899ce0723162cd851b18ffdc973.png)
78+
79+
***选择 1、2 方式如果待升级设备当前运行的固件没有上传到控制台，那么在选择待升级版本号时就不能选择待升级设备的版本号，此时可以通过在控制台上传待升级设备当前运行的固件版本或者选择方式 3 升级。***
80+
81+
7282

7383
这个时候再观察sample的示例打印，可以看到设备端通过MQTT接收到升级命令，并且通过HTTPS去下载固件并保存到本地
7484
```

‎docs/IoT_Hub/remote_config_mqtt_sample_远程配置.md

+143
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# 远程配置
2+
3+
本文档介绍通过 MQTT 对产品设备进行远程配置的功能，并结合 SDK 的**remote_config_mqtt_sample**展示远程配置功能。
4+
5+
## 一. 控制台创建设备
6+
7+
#### 1. 背景介绍
8+
9+
设备运维阶段，需要对设备配置参数进行更新以满足现场使用环境的需求。
10+
如温湿度设备需要更改温湿度上下限的设置；modbus 网关设备需要更改串口参数及 modbus 参数信息；zigbee 网关需要更改 zigbee 配置参数信息等等。
11+
* 配置推送 topic 和配置请求响应 topic： `$config/update/${productID}/${deviceName}`
12+
* 配置请求 topic: `$config/report/${productID}/${deviceName}`
13+
14+
#### 2. 远程配置流程图
15+
16+
##### 2.1 云平台主动下发配置流程
17+
18+
![image.png](https://main.qcloudimg.com/raw/5000bef6371f1080bc44deba57e34565.png)
19+
20+
##### 2.2 设备主动请求配置更新
21+
22+
![image.png](https://main.qcloudimg.com/raw/c0236c38e9e46b8e99424fa96f89c605.png)
23+
24+
#### 3. 创建产品和设备
25+
26+
请参考[设备互通](https://cloud.tencent.com/document/product/634/11913) 创建 AirConditioner 空调产品和设备标题内容。
27+
创建 airConditioner1 空调设备。
28+
29+
## 二. 编译运行示例程序(以**密钥认证设备**为例)
30+
31+
#### 1. 编译 SDK
32+
33+
修改CMakeLists.txt确保以下选项存在
34+
```
35+
set(BUILD_TYPE "release")
36+
set(COMPILE_TOOLS "gcc")
37+
set(PLATFORM "linux")
38+
set(FEATURE_REMOTE_CONFIG_MQTT_ENABLED ON)
39+
set(FEATURE_AUTH_MODE "KEY")
40+
set(FEATURE_AUTH_WITH_NOTLS OFF)
41+
set(FEATURE_DEBUG_DEV_INFO_USED OFF)
42+
```
43+
执行脚本编译
44+
```
45+
./cmake_build.sh
46+
```
47+
示例输出 `remote_config_mqtt_sample` 位于 `output/release/bin` 文件夹中
48+
49+
#### 2. 填写设备信息
50+
51+
将上面创建的 airConditioner1 设备的设备信息填写到JSON文件 aircond_device_info1.json 中:
52+
```
53+
{
54+
"auth_mode":"KEY",
55+
"productId":"YI7XCD5DRH",
56+
"deviceName":"airConditioner1",
57+
"key_deviceinfo":{
58+
"deviceSecret":"+PBSkYlvNffjLDTGLpVOQA=="
59+
}
60+
}
61+
```
62+
63+
#### 3. 执行`remote_config_mqtt_sample`示例程序
64+
65+
可以看到设备 airConditioner1 订阅了远程配置消息。
66+
67+
```
68+
./output/release/bin/remote_config_mqtt_sample -l
69+
INF|2020-08-26 19:31:03|qcloud_iot_device.c|iot_device_info_set(50): SDK_Ver: 3.2.1, Product_ID: YI7XCD5DRH, Device_Name: airConditioner1
70+
DBG|2020-08-26 19:31:03|HAL_TLS_mbedtls.c|HAL_TLS_Connect(200): Setting up the SSL/TLS structure...
71+
DBG|2020-08-26 19:31:03|HAL_TLS_mbedtls.c|HAL_TLS_Connect(242): Performing the SSL/TLS handshake...
72+
DBG|2020-08-26 19:31:03|HAL_TLS_mbedtls.c|HAL_TLS_Connect(243): Connecting to /YI7XCD5DRH.iotcloud.tencentdevices.com/8883...
73+
INF|2020-08-26 19:31:03|HAL_TLS_mbedtls.c|HAL_TLS_Connect(265): connected with /YI7XCD5DRH.iotcloud.tencentdevices.com/8883...
74+
INF|2020-08-26 19:31:03|mqtt_client.c|IOT_MQTT_Construct(118): mqtt connect with id: 9AEwi success
75+
INF|2020-08-26 19:31:03|remote_config_mqtt_sample.c|main(300): Cloud Device Construct Success
76+
DBG|2020-08-26 19:31:03|mqtt_client_subscribe.c|qcloud_iot_mqtt_subscribe(142): topicName=$config/update/YI7XCD5DRH/airConditioner1|packet_id=13502
77+
INF|2020-08-26 19:31:03|remote_config_mqtt_sample.c|_mqtt_event_handler(128): subscribe success, packet-id=13502
78+
DBG|2020-08-26 19:31:03|remote_config_mqtt.c|_config_mqtt_sub_event_handler(156): mqtt config topic subscribe success
79+
INF|2020-08-26 19:31:03|remote_config_mqtt_sample.c|main(315): config topic subscribe success, packetid:13502
80+
```
81+
82+
##### 3.1 设备订阅远程配置函数
83+
84+
```
85+
int IOT_Subscribe_Config(void *client, ConfigSubscirbeUserData *config_sub_userdata, int subscribe_timeout)
86+
```
87+
88+
#### 4. 云平台上给产品添加远程配置内容
89+
90+
点击 AirConditioner 产品的管理按钮，然后点击远程配置选项卡添加远程配置内容保存和启用远程配置
91+
![image.png](https://main.qcloudimg.com/raw/16001d465cc7f5765d44842b6a47ef0d.png)
92+
93+
#### 5. 观察设备主动请求配置更新
94+
95+
观察设备 airConditioner1 的打印输出，可以看到设备发布获取配置消息并收到了云平台的下行配置回复。 `Recv Msg Topic:$config/update/YI7XCD5DRH/airConditioner1` `"type":"reply"`
96+
97+
配置信息是 `{"baud rate":9600,"data bits":8,"stop bit":1,"parity":"NONE","thread sleep":1000}`
98+
```
99+
DBG|2020-08-26 19:31:03|mqtt_client_publish.c|qcloud_iot_mqtt_publish(340): publish packetID=0|topicName=$config/report/YI7XCD5DRH/airConditioner1|payload={"type":"get"}
100+
DBG|2020-08-26 19:31:08|remote_config_mqtt.c|_config_mqtt_message_callback(90): Recv Msg Topic:$config/update/YI7XCD5DRH/airConditioner1, buff data:{
101+
"type":"reply",
102+
"result":0,
103+
"payload": {"baud rate":9600,"data bits":8,"stop bit":1,"parity":"NONE","thread sleep":1000}
104+
}
105+
INF|2020-08-26 19:31:08|remote_config_mqtt_sample.c|_on_config_proc_handler(94): config message arrived , proc result: 9600, 8, 0, 1, 1000
106+
INF|2020-08-26 19:31:08|remote_config_mqtt_sample.c|_on_config_proc_handler(96): config message arrived , configData: {"baud rate":9600,"data bits":8,"stop bit":1,"parity":"NONE","thread sleep":1000}
107+
108+
```
109+
110+
##### 5.1 设备主动请求配置更新函数
111+
112+
```
113+
int IOT_Get_Config(void *client, char *json_buffer, int buffer_size, int reply_timeout)
114+
```
115+
116+
#### 6. 观察云平台主动下发配置
117+
118+
观察设备 airConditioner1 的打印输出，可以看到已经处理了远程配置下行消息。 `Recv Msg Topic:$config/update/YI7XCD5DRH/airConditioner1` `"type":"push"`
119+
120+
配置信息是 `{"baud rate":115200,"data bits":8,"stop bit":1,"parity":"NONE","thread sleep":1000}`
121+
122+
```
123+
DBG|2020-08-26 19:31:30|remote_config_mqtt.c|_config_mqtt_message_callback(90): Recv Msg Topic:$config/update/YI7XCD5DRH/airConditioner1, payload:{
124+
"type":"push",
125+
"payload": {"baud rate":115200,"data bits":8,"stop bit":1,"parity":"NONE","thread sleep":1000}
126+
}
127+
INF|2020-08-26 19:31:30|remote_config_mqtt_sample.c|_on_config_proc_handler(44): config message arrived , configData: {"baud rate":115200,"data bits":8,"stop bit":1,"parity":"NONE","thread sleep":1000}
128+
INF|2020-08-26 19:31:30|remote_config_mqtt_sample.c|_on_config_proc_handler(96): config message arrived , proc end: 115200, 8, 0, 1, 1000
129+
130+
```
131+
132+
#### 7. 云平台远程配置下行结果码 result 字段说明
133+
134+
| 结果码 | 说明 |
135+
|--------|----------------------------------|
136+
| 0 | 远程配置获取成功 |
137+
| 1001 | 产品在云平台上的远程配置被禁用 |
138+
| 1002 | 产品在云平台上不存在远程配置内容 |
139+
| 1003 | 产品在云平台上的远程配置不合法 |
140+
141+
***至此，完成了远程配置的示例运行***
142+
143+
使用远程配置功能时，参考例子程序，修改 `_on_config_proc_handler` 函数适配实际设备的配置解析与更新。

‎include/config.h

+3
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,6 @@
1515
/* #undef AT_DEBUG */
1616
#define OTA_USE_HTTPS
1717
#define MULTITHREAD_ENABLED
18+
#define BROADCAST_ENABLED
19+
#define RRPC_ENABLED
20+
#define REMOTE_CONFIG_MQTT

‎include/exports/qcloud_iot_export_gateway.h

+35
Original file line numberDiff line numberDiff line change
@@ -183,6 +183,41 @@ int IOT_Gateway_Yield(void *client, uint32_t timeout_ms);
183183
*/
184184
void *IOT_Gateway_Get_Mqtt_Client(void *handle);
185185

186+
/* The structure of subdevice bindinfo */
187+
typedef struct _SubdevBindInfo {
188+
char product_id[MAX_SIZE_OF_PRODUCT_ID + 1];
189+
char device_name[MAX_SIZE_OF_DEVICE_NAME + 1];
190+
struct _SubdevBindInfo *next;
191+
} SubdevBindInfo;
192+
193+
/* The structure of subdevice bindlist */
194+
typedef struct _SubdevBindList {
195+
SubdevBindInfo *bindlist_head;
196+
int bind_num;
197+
} SubdevBindList;
198+
199+
/**
200+
* @brief get sub-device bind list from cloud platform
201+
*
202+
* @param client handle to gateway client
203+
* @param param gateway parameters
204+
* @param subdev_bindlist output subdev bind list
205+
*
206+
* @return QCLOUD_RET_SUCCESS for success, or err code for failure
207+
*/
208+
int IOT_Gateway_Subdev_GetBindList(void *client, GatewayParam *param, SubdevBindList *subdev_bindlist);
209+
210+
/**
211+
* @brief destory sub dev bind list
212+
*
213+
* @param subdev_bindlist input subdev bind list pointer, ref IOT_Gateway_Subdev_GetBindList
214+
* output param subdev_bindlist
215+
*
216+
* @return QCLOUD_RET_SUCCESS for success, or err code for failure
217+
*/
218+
void IOT_Gateway_Subdev_DestoryBindList(SubdevBindList *subdev_bindlist);
219+
220+
186221
#ifdef __cplusplus
187222
}
188223
#endif

0 commit comments

Comments
 (0)