Merge pull request #535 from hxy7yx/v2.11-2

[v2.11]mqtt support ECP-format and Upload Tag Error Code
emqx · Dec 19, 2024 · fab76fd · fab76fd
2 parents 7f0d4c5 + 163425b
commit fab76fd
Show file tree

Hide file tree

Showing 4 changed files with 95 additions and 2 deletions.
diff --git a/en_US/configuration/north-apps/mqtt/api.md b/en_US/configuration/north-apps/mqtt/api.md
@@ -73,6 +73,52 @@ The following example data is in *values-format*, where tag values collected suc
 Tag value is returned only when the tag is read successfully. If something goes wrong when reading a tag, the error code is returned.
 :::
 
+### ECP Format
+
+In *ECP-format*, the upload data has the following fields:
+* `timestamp`: the Unix timestamp when the data was collected
+* `node`: name of the south node from which data was collected
+* `group`: name of the south node group that the tags belong to
+* `tags`: tags data array where each element corresponds to one tag in the group
+
+The following example data is in *ECP-format*, where tag data are stored in an array. Each element has the name of the tag, the tag type and the tag value, excluding tags where collection failed.
+
+Data classes are divided into four types: Boolean, Integer, Float, and String.
+* type = 1 Boolean
+* type = 2 Integer
+* type = 3 Float
+* type = 4 String
+
+```json
+{
+  "timestamp": 1647497389075,
+  "node": "modbus",
+  "group": "grp",
+  "tags": [
+    {
+      "name": "tag_boolean",
+      "value": true,
+      "type": 1,
+    },
+    {
+      "name": "tag_int32_",
+      "value": 123,
+      "type": 2,
+    },
+    {
+      "name": "tag_float",
+      "value": 1.23,
+      "type": 3,
+    },
+    {
+      "name": "tag_string",
+      "value": "abcd",
+      "type": 4,
+    }
+  ]
+}
+```
+
 ## Read Tag
 
 ### Request

diff --git a/en_US/configuration/north-apps/mqtt/overview.md b/en_US/configuration/north-apps/mqtt/overview.md
@@ -26,7 +26,8 @@ See the table below for the configuration parameters.
 | **MQTT Version**                | The version of MQTT protocol. The default is v3.1.1.          |
 | **Client ID**                   | MQTT client id for communication, a required field.          |
 | **QoS Level**                   | MQTT QoS level for message delivery, optional, default QoS 0. (since 2.4.0) |
-| **Upload Format**               | JSON format of reported data, a required field: <br /><br /> - *values-format*, data are split into `values` and `errors` sub-objects. <br />- *tags-format*, tag data are put in a single array. <br /><br />For data communication format, see [Upstream/Downstream Data Format](./api.md#write-tag) |
+| **Upload Format**               | JSON format of reported data, a required field: <br /><br /> - *values-format*, data are split into `values` and `errors` sub-objects. <br />- *tags-format*, tag data are put in a single array. <br /><br />For data communication format, see [Upstream/Downstream Data Format](./api.md#write-tag) <br />· *ECP-format*：Add tag types on the basis of *tags-format*.|
+| **Upload Tag Error Code**     | When data tag collection reports an error, report the tag error code. Default enabled.           |
 | **Write Request Topic**         | MQTT topic to which the plugin subscribes for write requests. For data communication format, see [Upstream/Downstream Data Format](./api.md#write-tag) (since 2.4.5). If tracing is enabled, configure the user properties `traceparent` and `tracestate` according to the W3C standard. |
 | **Write Response Topic**        | MQTT topic to which the plugin sends write responses. (since 2.4.5) |
 | **Driver Status Report**         | Reports status of all the southbound nodes to the specified topic. |

diff --git a/zh_CN/configuration/north-apps/mqtt/api.md b/zh_CN/configuration/north-apps/mqtt/api.md
@@ -76,6 +76,51 @@ Neuron MQTT 插件将采集到的数据以 JSON 形式发布到指定的主题
 当点位采集成功时，返回采集到的数据。当点位采集发生错误时，返回错误码，不再返回数值。
 :::
 
+### ECP 格式
+
+在 *ECP-format* 格式中， 上报的数据由以下字段构成：
+* `timestamp` : 数据采集时的 UNIX 时间戳。
+* `node` : 被采集的南向节点的名字。
+* `group` : 被采集的南向节点的点位组的名字。
+* `tags` : 点位数据数组，每个元素对应一个点位。
+
+以下为使用 *ECP-format* 格式的数据样例，其中所有点位数据存放在一个数组中，每个数组元素包含点位的名字，点位的数据类型和采集成功时的数据值，不包含采集失败的点位。
+数据类分为布尔、整型、浮点型、字符串四种。
+* type = 1 布尔
+* type = 2 整型
+* type = 3 浮点型
+* type = 4 字符串
+
+```json
+{
+  "timestamp": 1647497389075,
+  "node": "modbus",
+  "group": "grp",
+  "tags": [
+    {
+      "name": "tag_boolean",
+      "value": true,
+      "type": 1,
+    },
+    {
+      "name": "tag_int32_",
+      "value": 123,
+      "type": 2,
+    },
+    {
+      "name": "tag_float",
+      "value": 1.23,
+      "type": 3,
+    },
+    {
+      "name": "tag_string",
+      "value": "abcd",
+      "type": 4,
+    }
+  ]
+}
+```
+
 ## 读 Tags
 
 ### 请求

diff --git a/zh_CN/configuration/north-apps/mqtt/overview.md b/zh_CN/configuration/north-apps/mqtt/overview.md
@@ -23,7 +23,8 @@ Neuron 支持 MQTT 插件作为其数据汇聚上报的方式之一，Neuron MQT
 | **MQTT 版本**      | MQTT 协议的版本，默认为 v3.1.1。             |
 | **客户端 ID**      | MQTT 通信的客户端 id，必填。                                 |
 | **QoS 等级**       | MQTT 通信的服务质量等级，可选，默认为 QoS 0 。               |
-| **上报数据格式**   | 上报数据的 JSON 格式：<br />· *values-format*：数据被分成 `values` 和 `errors` 的子对象。<br />· *tags-format*：数据被放在一个数组中。关于通信数据格式，见 [数据上下行格式](./api.md#数据上报) |
+| **上报数据格式**   | 上报数据的 JSON 格式：<br />· *values-format*：数据被分成 `values` 和 `errors` 的子对象。<br />· *tags-format*：数据被放在一个数组中。关于通信数据格式，见 [数据上下行格式](./api.md#数据上报) <br />· *ECP-format*：在 *tags-format* 的基础上增加数据类型。|
+| **上报点位错误码**     | 点位采集报错时，上报点位错误码。默认开启。           |
 | **写请求主题**     | 接收点位写入请求的 MQTT 主题。关于通信数据格式，见 [数据上下行格式](./api.md#写-tag)。如开启链路追踪，请按 W3C 标准配置用户属性 `traceparent` 和 `tracestate`。|
 | **写响应主题**     | 发送点位写入响应的 MQTT 主题。                           |
 | **驱动状态上报**   | 上报所有南向驱动状态到指定的 MQTT 主题。                  |