数据上下行格式 支持 neuron方式上报 以下内容描述 MQTT 插件如何上报采集的数据，以及如何通过 MQTT 插件实现读写点位数据。

数据上报 MQTT 插件将采集到的数据以 JSON 形式发布到指定的主题。 上报数据的具体格式由上报数据格式参数指定，有Values-format 格式、Tags-format 格式、ECP-format 格式、Custom 自定义格式多种格式可选。

上报主题 上报主题在北向节点订阅中指定，其默认值为 /things/{MQTT driver name} ，见下图

Values-format 格式 在 Values-format 格式中， 上报的数据由以下字段构成：

timestamp : 数据采集时的 UNIX 时间戳。 node : 被采集的南向节点的名字。 group : 被采集的南向节点的点位组的名字。 values : 存储采集成功的点位值的字典。 errors : 存储采集失败的错误码的字典。 metas : 驱动相关的元数据信息。 以下为使用 values-format 格式的数据样例，采集成功的点位数据值存放在values键中，采集失败的点位错误码存放在errors键中。

json { “timestamp”: 1650006388943, “node”: “modbus”, “group”: “grp”, “values”: { “tag0”: 123 }, “errors”: { “tag1”: 2014 }, “metas”:{} } 注意

当点位采集成功时，返回采集到的数据。当点位采集发生错误时，返回错误码，不再返回数值。

当 MQTT 插件配置项 上报点位错误码 为 False 时，不上报点位错误码。

Tags-format 格式 在 Tags-format 格式中， 上报的数据由以下字段构成：

timestamp : 数据采集时的 UNIX 时间戳。 node : 被采集的南向节点的名字。 group : 被采集的南向节点的点位组的名字。 tags : 点位数据数组，每个元素对应一个点位。 name : 具体的点位名称字段。 value : 具体点位对应的值。 error : 具体点位对应的错误码。 以下为使用 Tags-format 格式的数据样例，其中所有点位数据存放在一个数组中，每个数组元素包含点位的名字，采集成功时的数据值或者采集失败时的错误码。

json { “timestamp”: 1647497389075, “node”: “modbus”, “group”: “grp”, “tags”: [ { “name”: “tag0”, “value”: 123, }, { “name”: “tag1”, “error”: 2014 } ] } 注意

当点位采集成功时，返回采集到的数据。当点位采集发生错误时，返回错误码，不再返回数值。

当 MQTT 插件配置项 上报点位错误码 为 False 时，不上报点位错误码。

ECP-format 格式 在 ECP-format 格式中， 上报的数据由以下字段构成：

timestamp : 数据采集时的 UNIX 时间戳。 node : 被采集的南向节点的名字。 group : 被采集的南向节点的点位组的名字。 tags : 点位数据数组，每个元素对应一个点位。 name : 具体的点位名称字段。 value : 具体点位对应的值。 type : 具体点位对应的数据类型，共包含布尔、整型、浮点型、字符串四种数据类型。 以下为使用 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, } ] } 注意

ECP-format 格式不支持上报点位错误码。 不管 MQTT 插件配置项 上报点位错误码 为 False 或为 True ，都不上报点位错误码。

Custom 自定义格式 在自定义格式中，可以使用内置支持的变量自定义数据上报格式。

custom-format

内置变量 变量名称 说明 ${timestamp} 数据采集时的 UNIX 时间戳。 ${node} 南向采集点位所属的南向驱动名称。 示例：modbus ${group} 南向采集点位所属的南向驱动的采集组的名称。 示例：group ${tags} 南向采集点位有效值的数组集合。 示例：[{“name”: “tag1”, “value”: 123}, {“name”: “tag2”, “value”: 456}] ${tag_values} 南向采集点位有效值的Json集合。 示例：{“tag1”: 123, “tag2”: 456} ${tag_errors} 南向采集点位报错值的数组集合。 示例：[{“name”: “tag3”, “error”: 2014}, {“name”: “tag4”, “error”: 2015}] ${tag_error_values} 南向采集点位报错值的Json集合。 示例：{“tag3”: 2014, “tag4”: 2015} ${static_tags} 订阅采集组时，自定义配置的静态点位的数组集合。 示例： [{“name”: “static_tag1”, “value”: “abc”}, {“name”: “static_tag2”, “value”: “def”}] 详见 静态点位 ${static_tag_values} 订阅采集组时，自定义配置的静态点位的Json集合。 示例： {“static_tag1”: “abc”, “static_tag2”: “def”} 详见 静态点位 注意

${tags} 和 ${tag_values} 是采集数据点的2种不同格式，${tags} 是数组格式，${tag_values} 是Json格式。一般在构建自定义数据上报格式时，使用 ${tags} 或 ${tag_values} 中的一种即可。

${static_tags} 和 ${static_tag_values}、${tag_errors}和${tag_error_values} 同理，使用其中一种即可。

MQTT 插件配置项 上报点位错误码 为 False 时，即使配置了${tag_errors} 和或 ${tag_error_values}，也不上报点位错误码信息。

上表中示例部分，原始南向驱动modbus1采集组group1下，包含4个点位，其中tag1和tag2的点位采集数据正常，tag3和tag4的点位采集数据异常。在北向节点订阅时，自定义配置的静态点位为static_tag1和static_tag2，其值分别为abc和def。

以上配置，以 Values-format 数据格式上报时，内容如下：

json { “timestamp”: 1650006388943, “node”: “modbus1”, “group”: “group1”, “values”: {“tag1”: 123, “tag2”: 456, “static_tag1”: “abc”, “static_tag2”: “def”}, “errors”: {“tag3”: 2014, “tag4”: 2015}, “metas”:{} } 以下示例通过设定不同的 Custom 配置，将上面 Json 报文输出为不同的数据上报格式。

示例一 将数据点位转换为数组格式，并自定义Json 键名。

json { “timestamp”: “${timestamp}”, “node”: “${node}”, “group”: “${group}”, “custom_tag_name”: “${tags}”, “custom_tag_errors”: “${tag_errors}”, } 实际输出结果如下：

json { “timestamp”: 1650006388943, “node”: “modbus1”, “group”: “group1”, “custom_tag_name”: [{“name”: “tag1”, “value”: 123}, {“name”: “tag2”, “value”: 456}], “custom_tag_errors”: [{“name”: “tag3”, “error”: 2014}, {“name”: “tag4”, “error”: 2015}] } 示例二 通过自定义数据格式，添加全局静态点位。该静态点位在所有驱动采集组上报数据时，均会携带。如 edgex 部署在一个物理网关上，可将网关的SN号、IP地址、位置信息等信息，添加到所有驱动采集组中。

json { “timestamp”: “${timestamp}”, “node”: “${node}”, “group”: “${group}”, “values”: “${tag_values}”, “gateway_info”: { “ip”: “192.168.1.100”, “sn”: “SN123456789”, “location”: “shanghai” } } 实际输出结果如下：

json { “timestamp”: 1650006388943, “node”: “modbus1”, “group”: “group1”, “values”: {“tag1”: 123, “tag2”: 456}, “gateway_info”: { “ip”: “192.168.1.100”, “sn”: “SN123456789”, “location”: “shanghai” } } 示例三 将采集数据点位、静态点位、驱动、采集组信息放入 Json 子节点中，可自定义 Json 节点名称。目前自定义数据结构做多支持三层子层级。

json { “timestamp”: “${timestamp}”, “data”: { “child_node”: { “node”: “${node}”, “group”: “${group}”, “tag_values”: “${tag_values}”, “static_tag_values”: “${static_tag_values}”, “tag_error_values”: “${tag_error_values}” } } } 数据上报的格式为：

json { “timestamp”: 1650006388943, “data”: { “child_node”: { “node”: “modbus”, “group”: “group”, “tag_values”: {“tag1”: 123, “tag2”: 456}, “static_tag_values”: {“static_tag1”: “abc”, “static_tag2”: “def”}, “tag_error_values”: {“tag3”: 2014, “tag4”: 2015} } } } 静态点位 静态点位功能，支持在南向驱动数据上报时，由用户在北向应用组列表页面手动配置静态点位，在数据上报时，将静态点位数据一并上报。

static-tags

静态点位配置，需输入标准JSON格式内容，每个静态点位均为JSON对象中的键值对。静态点位将根据配置的数据上报格式（Values-format、Tags-format、ECP-format）与采集组数据一并上报。

json { “location”: “sh”, “sn_number”: “123456” } 每个南向采集组，可分别配置不同静态点位。表示该采集组代表的物理设备，具有哪些静态属性信息。

静态点位功能支持布尔、整型、浮点型、字符串四种数据类型。复杂数据类型，如数组、结构体等，将以字符串形式上报。

如果添加的静态点位，为 edgex 实例中所有采集组共用，既可以勾选所有采集组，添加静态点位，也可以在 Custom 自定义格式中，统一添加静态点位，参考 自定义格式：示例二。

注意

静态点位命名，不能和南向驱动采集的点位名称相同。

如命名相同，则如果选择Values-format上报数据时，静态点位数据将覆盖南向驱动采集的点位数据.

如果选择Tags-format、ECP-format或Custom上报数据时，静态点位数据将和南向驱动采集的点位数据一起重复上报。

读 Tags 请求 通过发送 JSON 形式的请求到 MQTT 主题 /things/{node_name}/read/req，您可以读取一组点位数据。

请求体 读请求体由以下字段构成：

uuid : 唯一的标志，会在响应中原样返回用以区分对应的请求。 node : 某个南向节点名字。 group : 南向节点的某个组的名字。 以下为一个读请求样例：

json { “uuid”: “bca54fe7-a2b1-43e2-a4b4-1da715d28eab”, “node”: “modbus”, “group”: “grp” } 响应 读响应会发布到 MQTT 主题 /things/{node_name}/read/resp 。

响应体 读响应体由以下字段构成：

uuid : 对应请求中所设置的唯一标志。 tags : 点位数据数组，和 tags 格式中的表示方法一样。 以下为一个读响应样例：

json { “uuid”: “bca54fe7-a2b1-43e2-a4b4-1da715d28eab”, “tags”: [ { “name”: “tag0”, “value”: 4, }, { “name”: “tag1”, “error”: 2014 } ] } TIP

当点位采集成功时，返回采集到的数据。当点位采集发生错误时，返回错误码，不再返回数值。

写 Tag 请求 通过发送 JSON 形式的请求到写请求主题参数指定的 MQTT 主题，您可以写一个点位数据。可在 MQTT 参数配置中配置写请求的主题，默认为为 /things/{random_str}/write/req。

请求体 写一个 Tag 写请求体由以下字段构成：

uuid : 唯一的标志，会在响应中原样返回用以区分对应的请求。 node : 某个南向节点名字。 group : 南向节点的某个组的名字。 tag : 要写入的点位名字。 value : 要写入的数据值。 以下为一个写请求样例：

json { “uuid”: “cd32be1b-c8b1-3257-94af-77f847b1ed3e”, “node”: “modbus”, “group”: “grp”, “tag”: “tag0”, “value”: 1234 } 写多个 Tag edgex 提供了对多点位写入的支持。要在一次请求中可以写入多个点位数据, 写请求体应由以下字段构成：

uuid : 唯一的标志，会在响应中原样返回用以区分对应的请求。 node : 某个南向节点名字。 group : 南向节点的某个组的名字。 tags : 点位数据数组，每个元素对应一个点位。 以下为一个写请求样例：

json { “uuid”: “cd32be1b-c8b1-3257-94af-77f847b1ed3e”, “node”: “modbus”, “group”: “grp”, “tags”: [ { “tag”: “tag0”, “value”: 1234 }, { “tag”: “tag1”, “value”: 5678 } ] } 响应 写响应会发布到配置的写响应主题（Write Response Topic）。若未配置，默认在写请求主题后追加 /resp。

响应体 写响应体由以下字段构成：

uuid : 对应请求中所设置的唯一标志。 success : 布尔值，true 代表成功，false 代表失败。 message : （可选）失败时的错误信息。

以下为一个写响应样例：

json { “uuid”: “cd32be1b-c8b1-3257-94af-77f847b1ed3e”, “success”: true } 驱动状态上报 上报所有南向驱动状态到指定的 MQTT 主题。

状态上报主题 上报主题在北向节点配置中指定，其默认值为 /things/{random_str}/state/update

状态上报间隔 状态上报间隔在北向节点配置中指定，指每条消息之间间隔的秒数，其默认值为 1，允许的范围为 1-3600。

上报消息格式 上报的数据由以下字段构成：

timestamp : 数据采集时的 UNIX 时间戳。 states : 节点状态信息的数组。 以下是一个驱动状态上报消息样例。

json { “timestamp”: 1658134132237, “states”: [ { “node”: “modbus-tcp”, “link”: 1, “running”: 3 }, { “node”: “modbus-rtu”, “link”: 1, “running”: 3 } ] }

设备状态通知 当设备上线或离线时，MQTT 插件会发布状态消息。支持 LWT（遗嘱消息）。

状态主题 可在配置中指定状态主题（Status Topic）。默认值为 {topic}/status。支持变量替换。

状态载荷 可在配置中指定上线（Online Payload）和离线（Offline Payload）的 JSON 模板。

默认载荷格式： json { “status”: “online”, // 或 “offline” “timestamp”: 1658134132237, “device_id”: “device1” }

变量替换 在主题（Topic）和载荷（Payload）配置中，支持以下变量替换：