Merge pull request #264 from emqx/master

Merge back docs

README-CN.md

@@ -54,6 +54,9 @@ Kuiper 可以运行在各类物联网的边缘使用场景中，比如工业物
 - [Kuiper 5分钟快速入门](docs/zh_CN/quick_start_docker.md)
 - [EdgeX 规则引擎教程](docs/zh_CN/edgex/edgex_rule_engine_tutorial.md)
 
+## Slack
+加入我们的 [Slack](https://join.slack.com/t/emqx/shared_invite/zt-7xrracuf-GGdbNB1pARtaZKvv6IfTvw)，然后加入 [kuiper](https://emqx.slack.com/archives/C0138SZP23Y) 频道。
+
 ## 性能测试结果
 
 ### MQTT 吞吐量测试支持

README.md

@@ -54,6 +54,9 @@ It can be run at various IoT edge use scenarios, such as real-time processing of
 - [Kuiper 5 minutes quick start](docs/en_US/quick_start_docker.md)
 - [EdgeX rule engine tutorial](docs/en_US/edgex/edgex_rule_engine_tutorial.md)
 
+## Slack channels
+Join our [Slack](https://join.slack.com/t/emqx/shared_invite/zt-7xrracuf-GGdbNB1pARtaZKvv6IfTvw), and then join [kuiper](https://emqx.slack.com/archives/C0138SZP23Y) channel.
+
 ## Performance test result
 
 ### MQTT throughput test

docs/en_US/edgex/edgex_rule_engine_command.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-This document describes how to use Kuiper rule engine to control devices with anlysis result. To make the tutorial simple,  the doc uses [device-virtual](https://github.com/edgexfoundry/device-virtual-go) sample,  it analyzes the data sent from device-virtual services, and then control the device according to the analysis result produced by Kuiper rule engine.
+This document describes how to use Kuiper rule engine to control devices with analysis result. To make the tutorial simple,  the doc uses [device-virtual](https://github.com/edgexfoundry/device-virtual-go) sample,  it analyzes the data sent from device-virtual services, and then control the device according to the analysis result produced by Kuiper rule engine.
 
 ### Scenarios
 
@@ -145,7 +145,7 @@ curl -X POST \
 
 The 2nd rule is monitoring `Random-Integer-Device` device, and if the average value for `int8` with every 20 seconds is larger than 0, then send a command to `Random-Boolean-Device` device service to turn off random generation of bool value.
 
-- The average value for uint8 is caculated every 20 seconds, and if the average value is larger than 0, then send a control command to `Random-Boolean-Device` service.
+- The average value for uint8 is calculated every 20 seconds, and if the average value is larger than 0, then send a control command to `Random-Boolean-Device` service.
 
 ```shell
 curl -X POST \

docs/en_US/rules/overview.md

@@ -62,7 +62,7 @@ Each action can define its own properties. There are several common properties:
 | concurrency | int: 1   | Specify how many instances of the sink will be run. If the value is bigger than 1, the order of the messages may not be retained. |
 | bufferLength | int: 1024   | Specify how many messages can be buffered in memory. If the buffered messages exceed the limit, the sink will block message receiving until the buffered messages have been sent out so that the buffered size is less than the limit. |
 | runAsync        | bool:false   | Whether the sink will run asynchronously for better performance. If it is true, the sink result order is not promised.  |
-| retryInterval   | int:1000   | Specify how many milliseconds will the sink retry to send data out if the previous send failed  |
+| retryInterval   | int:1000   | Specify how many milliseconds will the sink retry to send data out if the previous send failed. If the specified value <= 0, then it will not retry. |
 | cacheLength     | int:10240   | Specify how many messages can be cached. The cached messages will be resent to external system until the data sent out successfully. The cached message will be sent in order except in runAsync or concurrent mode. The cached message will be saved to disk in fixed intervals.  |
 | cacheSaveInterval  | int:1000   | Specify the interval to save cached message to the disk. Notice that, if the rule is closed in plan, all the cached messages will be saved at close. A larger value can reduce the saving overhead but may lose more cache messages when the system is interrupted in error.  |
 | omitIfEmpty | bool: false | If the configuration item is set to true, when SELECT result is empty, then the result will not feed to sink operator. |

docs/zh_CN/edgex/edgex_rule_engine_command.md

@@ -0,0 +1,215 @@
+# 使用 EdgeX Kuiper 规则引擎控制设备
+
+## 概述
+
+该文章描述了如何在 EdgeX 中使用 Kuiper 规则引擎，根据分析结果来实现对设备的控制。为了便于理解，该文章使用 [device-virtual](https://github.com/edgexfoundry/device-virtual-go)示例，它对device-virtual服务发送的数据进行分析，然后根据由Kuiper规则引擎生成的分析结果来控制设备 。
+
+### 场景
+
+在本文中，将创建并运行以下两条规则。
+
+1. 监视`Random-UnsignedInteger-Device`设备的规则，如果`uint8`值大于 `20`，则向`Random-Boolean-Device`设备发送命令，并开启布尔值的随机生成 。
+2. 监视`Random-Integer-Device`设备的规则，如果每20秒 `int8`的平均值大于0，则向`Random-Boolean-Device` 设备服务发送命令以关闭 布尔值的随机生成。
+
+该场景不含任何真实的业务逻辑，而只是为了演示EdgeX Kuiper规则引擎的功能。 您可以根据我们的演示制定合理的业务规则。
+
+## 预备知识
+
+本文档将不涉及EdgeX和EMQ X Kuiper的基本操作，因此读者应具有以下基本知识：
+
+- 请通过[此链接](https://docs.edgexfoundry.org/1.2/) 以了解EdgeX的基础知识，最好完成[快速入门](https://docs.edgexfoundry.org/1.2/getting-started/quick-start/)。
+- 请阅读[EdgeX Kuiper规则引擎入门教程](https://github.com/emqx/kuiper/blob/master/docs/en_US/edgex/edgex_rule_engine_tutorial.md)：您最好阅读此入门教程，并开始在EdgeX中试用规则引擎。
+- [Go模板](https://golang.org/pkg/text/template/)：EMQ X Kuiper使用Go模板从分析结果中提取数据。 了解Go模板可以帮助您从分析结果中提取所需的数据。
+
+## 开始使用
+
+请务必遵循文档 [EdgeX Kuiper规则引擎入门教程](https://github.com/emqx/kuiper/blob/master/docs/en_US/edgex/edgex_rule_engine_tutorial.md)，确保教程能够成功运行。
+
+### 创建EdgeX流
+
+在创建规则之前，应创建一个流，该流可以使用来自EdgeX应用程序服务的流数据。 如果您已经完成 [EdgeX Kuiper规则引擎入门教程](https://github.com/emqx/kuiper/blob/master/docs/en_US/edgex/edgex_rule_engine_tutorial.md)，则不需要此步骤。
+
+```shell
+curl -X POST \
+  http://$kuiper_docker:48075/streams \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "sql": "create stream demo() WITH (FORMAT=\"JSON\", TYPE=\"edgex\")"
+}'
+```
+
+由于这两个规则都会向设备`Random-UnsignedInteger-Device`发送控制命令，通过运行命令`curl http://localhost:48082/api/v1/device/name/Random-Boolean-Device | jq`可以获取该设备的可用命令列表。它将打印类似的输出，如下所示。
+
+```json
+{
+  "id": "9b051411-ca20-4556-bd3e-7f52475764ff",
+  "name": "Random-Boolean-Device",
+  "adminState": "UNLOCKED",
+  "operatingState": "ENABLED",
+  "labels": [
+    "device-virtual-example"
+  ],
+  "commands": [
+    {
+      "created": 1589052044139,
+      "modified": 1589052044139,
+      "id": "28d88bb3-e280-46f7-949f-37cc411757f5",
+      "name": "Bool",
+      "get": {
+        "path": "/api/v1/device/{deviceId}/Bool",
+        "responses": [
+          {
+            "code": "200",
+            "expectedValues": [
+              "Bool"
+            ]
+          },
+          {
+            "code": "503",
+            "description": "service unavailable"
+          }
+        ],
+        "url": "http://edgex-core-command:48082/api/v1/device/bcd18c02-b187-4f29-8265-8312dc5d794d/command/d6d3007d-c4ce-472f-a117-820b5410e498"
+      },
+      "put": {
+        "path": "/api/v1/device/{deviceId}/Bool",
+        "responses": [
+          {
+            "code": "200"
+          },
+          {
+            "code": "503",
+            "description": "service unavailable"
+          }
+        ],
+        "url": "http://edgex-core-command:48082/api/v1/device/bcd18c02-b187-4f29-8265-8312dc5d794d/command/d6d3007d-c4ce-472f-a117-820b5410e498",
+        "parameterNames": [
+          "Bool",
+          "EnableRandomization_Bool"
+        ]
+      }
+    }
+  ]
+}
+```
+
+从输出中，您能看出有两个命令，第二个命令用于更新设备的配置。 此设备有两个参数：
+
+- `Bool`：当其他服务想要获取设备数据时，设置返回值。 仅当`EnableRandomization_Bool`设置为false时，才使用该参数。
+- `EnableRandomization_Bool`：是否启用`Bool`的随机生成。 如果将此值设置为true，则将忽略第一个参数。
+
+因此，示例控制命令将类似于如下命令：
+
+```shell
+curl -X PUT \
+  http://edgex-core-command:48082/api/v1/device/c1459444-79bd-46c8-8b37-d6e1418f2a3a/command/fe202437-236d-41c5-845e-3e6013b928cd \
+  -H 'Content-Type: application/json' \
+  -d '{"Bool":"true", "EnableRandomization_Bool": "true"}'
+```
+
+### 创建规则
+
+#### 第一条规则
+
+第一条规则是监视`Random-UnsignedInteger-Device`设备的规则，如果`uint8`值大于“ 20”，则向`Random-Boolean-Device`设备发送命令，并开启布尔值的随机生成 。 以下是规则定义，请注意：
+
+- 当uint8的值大于20时将触发该动作。由于uint8的值不用于向`Random-Boolean-Device`发送控制命令，因此在`rest`操作的`dataTemplate`属性中不使用`uint8`值。
+
+```shell
+curl -X POST \
+  http://$kuiper_server:48075/rules \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "id": "rule1",
+  "sql": "SELECT uint8 FROM demo WHERE uint8 > 20",
+  "actions": [
+    {
+      "rest": {
+        "url": "http://edgex-core-command:48082/api/v1/device/bcd18c02-b187-4f29-8265-8312dc5d794d/command/d6d3007d-c4ce-472f-a117-820b5410e498",
+        "method": "put",
+        "retryInterval": -1,
+        "dataTemplate": "{\"Bool\":\"true\", \"EnableRandomization_Bool\": \"true\"}",
+        "sendSingle": true
+      }
+    },
+    {
+      "log":{}
+    }
+  ]
+}'
+```
+
+#### 第二条规则
+
+第二条规则监视`Random-Integer-Device`设备，如果每20秒 `int8`的平均值大于0，则向`Random-Boolean-Device` 设备服务发送命令以关闭 布尔值的随机生成。
+
+- uint8的平均值每20秒计算一次，如果平均值大于0，则向 `Random-Boolean-Device` 服务发送控制命令。
+
+```shell
+curl -X POST \
+  http://$kuiper_server:48075/rules \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "id": "rule2",
+  "sql": "SELECT avg(int8) AS avg_int8 FROM demo WHERE int8 != nil GROUP BY  TUMBLINGWINDOW(ss, 20) HAVING avg(int8) > 0",
+  "actions": [
+    {
+      "rest": {
+        "url": "http://edgex-core-command:48082/api/v1/device/bcd18c02-b187-4f29-8265-8312dc5d794d/command/d6d3007d-c4ce-472f-a117-820b5410e498",
+        "method": "put",
+        "retryInterval": -1,
+        "dataTemplate": "{\"Bool\":\"false\", \"EnableRandomization_Bool\": \"false\"}",
+        "sendSingle": true
+      }
+    },
+    {
+      "log":{}
+    }
+  ]
+}'
+```
+
+现在创建了两个规则，您可以查看edgex-kuiper的日志以获取规则执行结果。
+
+```shell
+# docker logs edgex-kuiper
+```
+
+## 如何从分析结果中提取数据？
+
+由于分析结果也需要发送到command rest服务，如何从分析结果中提取数据？通过SQL过滤数据的示例如下所示：
+
+```sql
+SELECT int8, "true" AS randomization FROM demo WHERE uint8 > 20
+```
+
+SQL的输出内容如下：
+
+```json
+[{"int8":-75, "randomization":"true"}]
+```
+
+当从字段`int8`读取`value`字段，从字段`randomization`读取`EnableRandomization_Bool`时，假设服务需要以下数据格式：
+
+```shell
+curl -X PUT \
+  http://edgex-core-command:48082/api/v1/device/${deviceId}/command/xyz \
+  -H 'Content-Type: application/json' \
+  -d '{"value":-75, "EnableRandomization_Bool": "true"}'
+```
+
+Kuiper使用[Go模板](https://golang.org/pkg/text/template/) 从分析结果中提取数据，并且`dataTemplate` 内容如下：
+
+```
+"dataTemplate": "{\"value\": {{.int8}}, \"EnableRandomization_Bool\": \"{{.randomization}}\"}"
+```
+
+在某些情况下，您可能需要迭代返回的数组值，或使用if条件设置不同的值，然后参考[此链接](https://golang.org/pkg/text/template/#hdr-Actions)写入更复杂的数据模板表达式。
+
+## 补充阅读材料
+
+如果您想了解EMQ X Kuiper的更多特性，请阅读下面的参考资料：
+
+- [Kuiper Github 代码库](https://github.com/emqx/kuiper/)
+- [Kuiper 参考指南](https://github.com/emqx/kuiper/blob/edgex/docs/en_US/reference.md)
+

docs/zh_CN/rules/overview.md

@@ -52,7 +52,7 @@
 | concurrency | int: 1   | 设置运行的线程数。该参数值大于1时，消息发出的顺序可能无法保证。 |
 | bufferLength | int: 1024   | 设置可缓存消息数目。若缓存消息数超过此限制，sink将阻塞消息接收，直到缓存消息被消费使得缓存消息数目小于限制为止。|
 | runAsync        | bool:false   | 设置是否异步运行输出操作以提升性能。请注意，异步运行的情况下，输出结果顺序不能保证。  |
-| retryInterval   | int:1000   | 设置信息发送失败后重试等待时间，单位为毫秒|
+| retryInterval   | int:1000   | 设置信息发送失败后重试等待时间，单位为毫秒。如果该值的设置 <= 0，那么不会尝试重新发送。 |
 | cacheLength     | int:10240   | 设置最大消息缓存数量。缓存的消息会一直保留直到消息发送成功。缓存消息将按顺序发送，除非运行在异步或者并发模式下。缓存消息会定期存储到磁盘中。  |
 | cacheSaveInterval  | int:1000   | 设置缓存存储间隔时间，单位为毫秒。需要注意的是，当规则关闭时，缓存会自动存储。该值越大，则缓存保存开销越小，但系统意外退出时缓存丢失的风险变大。 |
 | omitIfEmpty | bool: false | Omit the output if the select result is empty. |