API

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 topic. 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 which default to /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 a array. Each element has the name of the tag, and the tag value or error code if something went wrong.

  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.

  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 tags

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:

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

Response

Read response will be publish 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:

  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

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 write request:

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

Response

Write response will be published to the MQTT topic /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 write response:

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