diff --git a/doc/08.QCloud_IoTHub_Quick_Start.md b/doc/08.QCloud_IoTHub_Quick_Start.md index 6f3784c7..1680419a 100644 --- a/doc/08.QCloud_IoTHub_Quick_Start.md +++ b/doc/08.QCloud_IoTHub_Quick_Start.md @@ -4,6 +4,7 @@ | -------- | --------- | ----------- | | 1.0 | 2019-1-15 | 文档初版 | | 2.0 | 2019-8-13 | 文档V2.0 | +| 2.0 | 2020-02-26| 文档V3.0 | 概览 ---- @@ -91,12 +92,14 @@ Client和Broker之间的发布和订阅是根据主题(Topic)来进行的, 不 我们可以在"权限列表"中看到Topic对应的操作权限, 此处还可以添加新的Topic. -在这里, 我们可以看到, 平台默认配置了两类的Topic, 用于执行发布和订阅. 这里之所以是两类而不是两个, 是因为Topic里使用了变量. 这里的`QOW7EO9S31`实际上是productID; `${deviceName}`为平台设置的变量, 即设备名; `control`和`event`为Topic名字. 所以, 在我们创建了2个设备dev1和dev2的情况下, 在my_product产品下, 即存在4个Topic, 分别为: +在这里, 我们可以看到, 平台默认配置了三类的Topic, 用于执行发布和订阅. 这里之所以是三类而不是三个, 是因为Topic里使用了变量. 这里的`25KCIUIR1G`实际上是productID; `${deviceName}`为平台设置的变量, 即设备名; `control`和`data`以及`event`为Topic名字. 所以, 在我们创建了2个设备dev1和dev2的情况下, 在my_product产品下, 即存在6个Topic, 分别为: -- QOW7EO9S31/dev1/control 订阅权限 -- QOW7EO9S31/dev1/event 发布权限 -- QOW7EO9S31/dev2/control 订阅权限 -- QOW7EO9S31/dev2/event 发布权限 +- 25KCIUIR1G/dev1/control 订阅权限 +- 25KCIUIR1G/dev1/data 发布和订阅权限 +- 25KCIUIR1G/dev1/event 发布权限 +- 25KCIUIR1G/dev2/control 订阅权限 +- 25KCIUIR1G/dev2/data 发布和订阅权限 +- 25KCIUIR1G/dev2/event 发布权限 这里默认的Topic已经足够我们使用, 不需要额外添加Topic和权限了. @@ -104,13 +107,13 @@ Client和Broker之间的发布和订阅是根据主题(Topic)来进行的, 不 > > 多层通配符"#" > -> 必须位于最后一个字符, 匹配多层级. 例如对于`QOW7EO9S31/#`, 将会匹配`QOW7EO9S31/dev1`, `QOW7EO9S31/dev2`, `QOW7EO9S31/dev1/control`, `QOW7EO9S31/dev1/event`, `QOW7EO9S31/dev2/control`和`QOW7EO9S31/dev2/event`主题. +> 必须位于最后一个字符, 匹配多层级. 例如对于`25KCIUIR1G/#`, 将会匹配`25KCIUIR1G/dev1`, `25KCIUIR1G/dev2`, `25KCIUIR1G/dev1/control`, `25KCIUIR1G/dev1/event`, `25KCIUIR1G/dev2/control`和`25KCIUIR1G/dev2/event`主题. > > 单层通配符"+" > > 匹配单个层级, 在主题的任何层级都可以使用, 包括第一个层级和最后一个层级. > -> 例如, 对于`QOW7EO9S31/+/event`, 将会匹配`QOW7EO9S31/dev1/event`和`QOW7EO9S31/dev2/event`. +> 例如, 对于`25KCIUIR1G/+/event`, 将会匹配`25KCIUIR1G/dev1/event`和`25KCIUIR1G/dev2/event`. @@ -120,9 +123,9 @@ Client和Broker之间的发布和订阅是根据主题(Topic)来进行的, 不 1. 为什么需要规则引擎 - 在上节的Topic中, 我们知道, 在平台侧, 对于不同的Topic, 规定了不同的权限, 例如, 对于`QOW7EO9S31/dev1/event`这个Topic, 只具有发布权限, 而对于`QOW7EO9S31/dev1/control`这个Topic, 只具有订阅权限. 对于设备dev1, 很自然的, 会朝`QOW7EO9S31/dev1/event`这个Topic发送数据, 并且订阅`QOW7EO9S31/dev1/control`这个Topic的消息. 但是这里就会涉及到, event的数据最后到哪去, control的数据从哪里来的问题. + 在上节的Topic中, 我们知道, 在平台侧, 对于不同的Topic, 规定了不同的权限, 例如, 对于`25KCIUIR1G/dev1/event`这个Topic, 只具有发布权限, 而对于`25KCIUIR1G/dev1/control`这个Topic, 只具有订阅权限. 对于设备dev1, 很自然的, 会朝`25KCIUIR1G/dev1/event`这个Topic发送数据, 并且订阅`25KCIUIR1G/dev1/control`这个Topic的消息. 但是这里就会涉及到, event的数据最后到哪去, control的数据从哪里来的问题. - 在本文的例子中, 我们希望dev1和dev2发生交互, 即相互收发消息. 由于MQTT是基于Topic的发布订阅机制, 因此, dev1想要获得dev2的数据, 直觉上, 需要订阅dev2发布消息的那个Topic. 假定dev2朝`QOW7EO9S31/dev2/event`Topic上发送数据, 那么dev1想要获得dev2发布的消息, 最直接的办法是订阅同样的Topic, 即`QOW7EO9S31/dev2/event`, 但是这里存在几个问题, 首先, event Topic只具有发布权限, 没有订阅权限, 其次, **在平台侧, 规定了, 不允许跨设备发布或是订阅Topic**, 也就是说, 对于dev1, 只能看到或只允许访问`QOW7EO9S31/dev1`这个Topic以及其下属的Topic, 不能访问`QOW7EO9S31/dev2`及其下属Topic. + 在本文的例子中, 我们希望dev1和dev2发生交互, 即相互收发消息. 由于MQTT是基于Topic的发布订阅机制, 因此, dev1想要获得dev2的数据, 直觉上, 需要订阅dev2发布消息的那个Topic. 假定dev2朝`25KCIUIR1G/dev2/event`Topic上发送数据, 那么dev1想要获得dev2发布的消息, 最直接的办法是订阅同样的Topic, 即`25KCIUIR1G/dev2/event`, 但是这里存在几个问题, 首先, event Topic只具有发布权限, 没有订阅权限, 其次, **在平台侧, 规定了, 不允许跨设备发布或是订阅Topic**, 也就是说, 对于dev1, 只能看到或只允许访问`25KCIUIR1G/dev1`这个Topic以及其下属的Topic, 不能访问`25KCIUIR1G/dev2`及其下属Topic. > 平台侧添加不允许跨设备访问Topic的规则虽然不直观, 但却是合理的. 如果不添加这条限制, 那么一个设备可以不加限制的订阅同一个产品下所有其他设备的Topic, 获取其上报的消息, 这存在潜在的安全漏洞. @@ -132,9 +135,9 @@ Client和Broker之间的发布和订阅是根据主题(Topic)来进行的, 不 ![](image/iothub_guide/rule_engine.png) - 上图介绍了规则引擎的主要作用"republish", 即将一个Topic下的消息republish到另一个Topic下. 从图中我们可以看到, 规则引擎将`QOW7EO9S31/dev2/event`的消息republish到了`QOW7EO9S31/dev1/control`下. 将`QOW7EO9S31/dev1/event`的消息republish到了`QOW7EO9S31/dev2/control`下. + 上图介绍了规则引擎的主要作用"republish", 即将一个Topic下的消息republish到另一个Topic下. 从图中我们可以看到, （产品ID以您实际的ID为准）规则引擎将`25KCIUIR1G/dev2/event`的消息republish到了`25KCIUIR1G/dev1/control`下. 将`25KCIUIR1G/dev1/event`的消息republish到了`25KCIUIR1G/dev2/control`下. - 这样, 对于dev1而言, 只需要订阅`QOW7EO9S31/dev1/control`就可以接收来自`QOW7EO9S31/dev2/event`的消息了. dev2同理. + 这样, 对于dev1而言, 只需要订阅`25KCIUIR1G/dev1/control`就可以接收来自`25KCIUIR1G/dev2/event`的消息了. dev2同理. 3. 设置规则引擎 @@ -148,7 +151,7 @@ Client和Broker之间的发布和订阅是根据主题(Topic)来进行的, 不 ![](image/iothub_guide/rule_set.png) - 上图是设置好的规则, 这里, 我们将"筛选数据"部分的筛选字段设置为`*`, 筛选的Topic为`QOW7EO9S31/dev1/event`, 条件设置为空, 即不筛选数据, 全部匹配. 然后, 执行的操作是将数据转发到`QOW7EO9S31/dev2/control`, 设置完这条规则, 就实现了dev2通过订阅control就能收到dev1发送到event的数据. + 上图是设置好的规则, 这里, 我们将"筛选数据"部分的筛选字段设置为`*`, 筛选的Topic为`25KCIUIR1G/dev1/event`, 条件设置为空, 即不筛选数据, 全部匹配. 然后, 执行的操作是将数据转发到`25KCIUIR1G/dev2/control`, 设置完这条规则, 就实现了dev2通过订阅control就能收到dev1发送到event的数据. > 关于"筛选数据"的设定 > @@ -156,7 +159,7 @@ Client和Broker之间的发布和订阅是根据主题(Topic)来进行的, 不 > > 如果在进行产品的时候, 使用数据格式是json, 那么此处就可以根据json中的字段进行SQL的匹配和筛选. - 同理, 我们再设置新的一个规则"2to1", 实现`QOW7EO9S31/dev2/event`到`QOW7EO9S31/dev1/control`的转发. + 同理, 我们再设置新的一个规则"2to1", 实现`25KCIUIR1G/dev2/event`到`25KCIUIR1G/dev1/control`的转发. ![](image/iothub_guide/rule_set_2to1.png) @@ -195,7 +198,7 @@ Client和Broker之间的发布和订阅是根据主题(Topic)来进行的, 不 在前文中我们提到, 设备终端跟腾讯云之间的通信采用的是MQTT协议, 而MQTT协议需要消息代理端和客户端相互配合, 因此, 我们在终端设备上, 需要**实现一个MQTT Client**. 腾讯云上支持的MQTT协议和标准协议区别不大, 可以在[MQTT协议说明](https://cloud.tencent.com/document/product/634/14065)查看具体区别. 因此, 技术上来说, 设备终端只要实现了标准的MQTT客户端, 均可以跟腾讯云正常通信. -在本节中, 我们介绍如何使用腾讯IoT OS与腾讯云通过MQTT进行通信. +在本节中, 我们介绍如何使用腾讯TencentOS tiny与腾讯云通过MQTT进行通信. 腾讯IoT OS集成了对MQTT和腾讯云的支持, 开发者只需要通过简单的设置即可实现与腾讯云的通信, 整体步骤主要包含: @@ -268,35 +271,33 @@ esp8266_sal_init(hal_uart_port_t uart_port); - Product ID - Device Name -- Password +- Device Password +- Client id +- mqtt username +- mqtt password -开发者在终端节点开发过程中, 可以使用`TencentOS_tiny\tools`下的`mqtt_config_gen.py`脚本来动态生成MQTT配置文件`mqtt_config.h` +![](image/iothub_guide/dev_info.png) + +开发者在终端节点开发过程中, 可以自行修改MQTT配置文件`mqtt_config.h` ```shell -$ python mqtt_config_gen.py -product id:QOW7EO9S31 -device name:dev1 -password:k05qMb3EXM5CE5ocNcsDvA== -subscribe topic:[default:control] -publish topic:[default:event] -===============Generate tos_mqtt_config.h================== #ifndef TOS_MQTT_CONFIG_H #define TOS_MQTT_CONFIG_H #define MQTT_SERVER_IP "111.230.189.156" #define MQTT_SERVER_PORT "1883" -#define MQTT_PRODUCT_ID "QOW7EO9S31" +#define MQTT_PRODUCT_ID "25KCIUIR1G" #define MQTT_DEV_NAME "dev1" -#define MQTT_CLIENT_ID "QOW7EO9S31dev1" -#define MQTT_USR_NAME "QOW7EO9S31dev1;21010406;12365;2147483648" -#define MQTT_PASSWORD "49344dd251a98d07e33ba54d4d2a0640303c6e8c;hmacsha1" -#define MQTT_SUBSCRIBE_TOPIC "QOW7EO9S31/dev1/control" -#define MQTT_PUBLISH_TOPIC "QOW7EO9S31/dev1/event" +#define MQTT_CLIENT_ID "25KCIUIR1Gdev1" +#define MQTT_USR_NAME "25KCIUIR1Gdev1;12010126;R2MUQ;1618721647" +#define MQTT_PASSWORD "bd9755216393179086306766bf7d428dca7d6a1c8a78b305adc281706a5eb963;hmacsha256" +#define MQTT_SUBSCRIBE_TOPIC "25KCIUIR1G/dev1/control" +#define MQTT_PUBLISH_TOPIC "25KCIUIR1G/dev1/event" #endif ``` -如上所示, 只需要按提示依次输入腾讯云端提供的`Product ID`, `Device Name`和`Password`即可, 至于订阅/发布的topic, 如果采用默认的control和event直接回车, 也可自行设置. 脚本会在脚本所在目录下生成一个`tos_mqtt_config.h`的头文件, 开发者将其放置到自己的工程目录下任意位置并在工程中添加头文件引用即可. +如上所示, 需要腾讯云设备信息自行修改`Product ID`, `Device Name`和`Password`，`MQTT_USR_NAME`，`MQTT_PASSWORD`，`MQTT_SUBSCRIBE_TOPIC`，`MQTT_PUBLISH_TOPIC`，订阅/发布的topic, 如果采用默认的control和event如图即可, 也可自行设置. 开发者将其放置到自己的工程目录下任意位置并在工程中添加头文件引用即可. **调用TencentOS tiny提供的接口完成和腾讯云的对接** diff --git a/doc/image/iothub_guide/add_dev.png b/doc/image/iothub_guide/add_dev.png index ea6fd14d..f7f514c6 100644 Binary files a/doc/image/iothub_guide/add_dev.png and b/doc/image/iothub_guide/add_dev.png differ diff --git a/doc/image/iothub_guide/add_prodcut.png b/doc/image/iothub_guide/add_prodcut.png index c91ec51a..b0390b0b 100644 Binary files a/doc/image/iothub_guide/add_prodcut.png and b/doc/image/iothub_guide/add_prodcut.png differ diff --git a/doc/image/iothub_guide/create_new_product.png b/doc/image/iothub_guide/create_new_product.png index 5d8de3de..0b9e37d6 100644 Binary files a/doc/image/iothub_guide/create_new_product.png and b/doc/image/iothub_guide/create_new_product.png differ diff --git a/doc/image/iothub_guide/dev_info.png b/doc/image/iothub_guide/dev_info.png new file mode 100644 index 00000000..429b94c6 Binary files /dev/null and b/doc/image/iothub_guide/dev_info.png differ diff --git a/doc/image/iothub_guide/dev_list.png b/doc/image/iothub_guide/dev_list.png index b285e570..501f85c2 100644 Binary files a/doc/image/iothub_guide/dev_list.png and b/doc/image/iothub_guide/dev_list.png differ diff --git a/doc/image/iothub_guide/new_device.png b/doc/image/iothub_guide/new_device.png index 1801fc9e..f864d7db 100644 Binary files a/doc/image/iothub_guide/new_device.png and b/doc/image/iothub_guide/new_device.png differ diff --git a/doc/image/iothub_guide/product_info.png b/doc/image/iothub_guide/product_info.png index 43de34e8..8dd5504f 100644 Binary files a/doc/image/iothub_guide/product_info.png and b/doc/image/iothub_guide/product_info.png differ diff --git a/doc/image/iothub_guide/rule_set.png b/doc/image/iothub_guide/rule_set.png index 3710a87a..a854318f 100644 Binary files a/doc/image/iothub_guide/rule_set.png and b/doc/image/iothub_guide/rule_set.png differ diff --git a/doc/image/iothub_guide/rule_set_2to1.png b/doc/image/iothub_guide/rule_set_2to1.png index 847a10a7..a9f2dfc3 100644 Binary files a/doc/image/iothub_guide/rule_set_2to1.png and b/doc/image/iothub_guide/rule_set_2to1.png differ diff --git a/doc/image/iothub_guide/topic_list.png b/doc/image/iothub_guide/topic_list.png index d5cd3e4f..4fe1d5f2 100644 Binary files a/doc/image/iothub_guide/topic_list.png and b/doc/image/iothub_guide/topic_list.png differ