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 collectednode
: name of the south node from which data was collectedgroup
: name of the south node group that the tags belong totags
: 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.
{
"timestamp": 1647497389075,
"node": "modbus",
"group": "grp",
"tags": [
{
"name": "tag0",
"value": 123,
},
{
"name": "tag1",
"error": 2014
}
]
}
Values Format
In values-format, the upload data has the following fields:
timestamp
: the Unix timestamp when the data was collectednode
: name of the south node from which data was collectedgroup
: name of the south node group that the tags belong tovalues
: dictionary storing tags with successfully collected valueserrors
: 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.
{
"timestamp": 1650006388943,
"node": "modbus",
"group": "grp",
"values":
{
"tag0": 123
},
"errors":
{
"tag1": 2014
}
}
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 requestnode
: the name of a southbound nodegroup
: the name of a group to read
Below is an example read request:
{
"uuid": "bca54fe7-a2b1-43e2-a4b4-1da715d28eab",
"node": "modbus",
"group": "grp"
}
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 requesttags
: tags data array, same as that in tags format
Below is an example read response:
{
"uuid": "bca54fe7-a2b1-43e2-a4b4-1da715d28eab",
"tags": [
{
"name": "tag0",
"value": 4,
},
{
"name": "tag1",
"error": 2014
}
]
}
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 requestnode
: the name of a southbound nodegroup
: the name of a grouptag
: the name of a tagvalue
: the value to write
Below is an example of write request:
{
"uuid": "cd32be1b-c8b1-3257-94af-77f847b1ed3e",
"node": "modbus",
"group": "grp",
"tag": "tag0",
"value": 1234
}
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:
{
"uuid": "cd32be1b-c8b1-3257-94af-77f847b1ed3e",
"node": "modbus",
"group": "grp",
"tags": [
{
"tag": "tag0",
"value": 1234
},
{
"tag": "tag1",
"value": 5678
}
]
}
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:
{
"uuid": "cd32be1b-c8b1-3257-94af-77f847b1ed3e",
"error": 0
}