Upstream/Downstream Data Format

The following contents describe how the Neuron MQTT plugin publishes collected data, and how to read or write data through MQTT using the plugin.

Note that {node_name} in all the following MQTT topics refers to the actual MQTT northbound application name, {driver_name} refers to some southbound node name, and {group_name} refers to some south node group name.

Data Upload

The Neuron MQTT plugin publishes collected data in JSON to some user-designated topics. The exact format of the data reported is controlled by the Upload Format parameter. There are two formats, tags-format and values-format.

Upload Topic

Before Neuron version 2.4.0, the upload topic is specified by the upload-topic parameter, and the default one set through the dashboard is /neuron/{node_name}/upload.

Since Neuron version 2.4.0, the upload-topic parameter is removed. And the upload topic is specified in the group subscription request instead with default as /neuron/{node_name}/{driver_name}/{group_name}.

Tags Format

In tags-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 tags-format, where tag data are stored in an array. Each element has the name of the tag, and the tag value or error code if something went wrong.

json

  1. {
  2. "timestamp": 1647497389075,
  3. "node": "modbus",
  4. "group": "grp",
  5. "tags": [
  6. {
  7. "name": "tag0",
  8. "value": 123,
  9. },
  10. {
  11. "name": "tag1",
  12. "error": 2014
  13. }
  14. ]
  15. }

Values Format

In values-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
  • values: dictionary storing tags with successfully collected values
  • errors: dictionary storing tags with encountered error codes

The following example data is in values-format, where tag values collected successfully are stored in a dictionary, while error codes in another.

json

  1. {
  2. "timestamp": 1650006388943,
  3. "node": "modbus",
  4. "group": "grp",
  5. "values":
  6. {
  7. "tag0": 123
  8. },
  9. "errors":
  10. {
  11. "tag1": 2014
  12. }
  13. }

TIP

Tag value is returned only when the tag is read successfully. If something goes wrong when reading a tag, the error code is returned.

Read Tag

Request

You can read a group of tags by sending requests in JSON to the MQTT topic /neuron/{node_name}/read/req.

Body

The read request body should have the following fields:

  • uuid: a unique identifier, which will be echoed back in the response to help identify the corresponding request
  • node: the name of a southbound node
  • group: the name of a group to read

Below is an example read request:

json

  1. {
  2. "uuid": "bca54fe7-a2b1-43e2-a4b4-1da715d28eab",
  3. "node": "modbus",
  4. "group": "grp"
  5. }

Response

Read response will be published to the MQTT topic /neuron/{node_name}/read/resp.

Body

The read response body has the following fields:

  • uuid: the same unique identifier which is set by the corresponding request
  • tags: tags data array, same as that in tags format

Below is an example read response:

json

  1. {
  2. "uuid": "bca54fe7-a2b1-43e2-a4b4-1da715d28eab",
  3. "tags": [
  4. {
  5. "name": "tag0",
  6. "value": 4,
  7. },
  8. {
  9. "name": "tag1",
  10. "error": 2014
  11. }
  12. ]
  13. }

TIP

Tag value is returned only when the tag is read successfully. If something goes wrong when reading a tag, the error code is returned.

Write Tag

Request

You could write a tag by sending requests in JSON to the MQTT topic designated by the Write Request Topic parameter.

TIP

Before Neuron version 2.4.5, the write request topic was hard-coded to /neuron/{node_name}/write/req.

Body

Write one tag

The write request body should have the following fields:

  • uuid: a unique identifier, which will be echoed back in the response to help identify the corresponding request
  • node: the name of a southbound node
  • group: the name of a group
  • tag: the name of a tag
  • value: the value to write

Below is an example of write request:

json

  1. {
  2. "uuid": "cd32be1b-c8b1-3257-94af-77f847b1ed3e",
  3. "node": "modbus",
  4. "group": "grp",
  5. "tag": "tag0",
  6. "value": 1234
  7. }

Write multiple tags

Since Neuron version 2.6.0, write requests also support writing multiple tags at a time. To write multiple tags at a time, the request body should have the following fields:

  • uuid : a unique identifier, which will be echoed back in the response to help identify the corresponding request.
  • node : the name of a southbound node.
  • group : the name of a group.
  • tags : tags data array where each element corresponds to one tag in the group.

Below is an example write request:

json

  1. {
  2. "uuid": "cd32be1b-c8b1-3257-94af-77f847b1ed3e",
  3. "node": "modbus",
  4. "group": "grp",
  5. "tags": [
  6. {
  7. "tag": "tag0",
  8. "value": 1234
  9. },
  10. {
  11. "tag": "tag1",
  12. "value": 5678
  13. }
  14. ]
  15. }

Response

Write response will be published to the MQTT topic designated by the Write Response Topic parameter.

TIP

Before Neuron version 2.4.5, the write response topic was hard-coded to /neuron/{node_name}/write/resp.

Body

The write response body has the following fields:

  • uuid: the same unique identifier which is set by the corresponding request.
  • error: error code if something bad happens, 0 represents success.

Below is an example of write response:

json

  1. {
  2. "uuid": "cd32be1b-c8b1-3257-94af-77f847b1ed3e",
  3. "error": 0
  4. }