...
The communication was tested/deployed with:
- www.TheThings.Network network cloud
- Loriot.io cloud
- Slovanet cloud (loralink.slovanet.sk)
- Pixii PowerShaper (energy storage solution)
- liveobjects.orange-business.com cloud
...
If the server does not send a message for longer than Ping Interval seconds, the client sends the PING request message, to which the server must respond with the PING response message (within the time specified by the Reply Timeout parameter).
If parameters change on the line, the connection is closed and re-created.
The communication has been tested with the MQTT server www.TheThings.network.
About Sparkplug's MQTT protocol
Sparkplug's MQTT protocol defines 3 groups of applications:
- Edge Node - supports the MQTT protocol and connects to the MQTT server. It sends him data obtained from the Device or its own or aggregated data
- Device/Sensor - represents a physical or logical device connected to an Edge Node and providing data, process data, or metrics
- Host Application - represents a data consumer (SCADA/MES system, Historian, analysis tool) that connects to the MQTT server and receives MQTT data from the Edge Node/Device and, if necessary, commands. D2000 is a Host Application.
MQTT Sparkplug defines the following message types:
- NBIRTH – Birth certificate for Sparkplug Edge Nodes (information about the connection of the Edge Node to the MQTT Server)
- NDEATH – Death certificate for Sparkplug Edge Nodes (information about the loss of the connection between the MQTT Server and the Edge Node)
- DBIRTH – Birth certificate for Devices (information about Device connection to Edge Node)
- DDEATH – Death certificate for Devices (information about the loss of Edge Node connection with Device)
- NDATA – Edge Node data message (data from Edge Node)
- DDATA – Device data message (data from Device)
- NCMD – Edge Node command message (Host Application command for Edge Node)
- DCMD – Device command message (Host Application command for Device)
- STATE – Sparkplug Host Application state message (information from the state of the Host Application for the Edge Node/Device [online/offline]).
MQTT Sparkplug defines a Topic syntax for all message types, which has the form namespace/group_id/message_type/edge_node_id/[device_id], where:
- namespace is a spBv1.0 constant (for Sparkplug B)
- group_id is an arbitrary name of a logical group (e.g. by device type, operation, organizational structure, etc.)
- message_type is the message type
- edge_node_id is the identifier of the Edge Node
- device_id is the identifier of the Device (only if the message is from/for a Device)
Examples:
- spBv1.0/Sparkplug Devices/DDATA/Marvin/Sensor1
- pBv1.0/MIMIC/DDATA/20:19:AB:F4:0E:0D/sensor11
- spBv1.0/SparkplugDevices/NBIRTH/JsonScada
Note: STATE messages have a Topic of the form spBv1.0/STATE/sparkplug_host_id, where sparkplug_host_id is the unique name of the host application.
Examples:
- spBv1.0/STATE/CFGHUB2023
- spBv1.0/STATE/D2Kom
All message types except STATE have a binary Sparkplug payload. The STATE messages have a JSON payload (contains only the items "online" (True/False value) and "timestamp" (time stamp in milliseconds).
The Sparkplug payload contains metrics - each required metric can be configured into a single I/O tag. The metric contains a text identifier (specified in the I/O tag configuration as sparkplug_address), value type, value (simple/array/structured), optionally timestamp, and other attributes. D2000 supports working with simple values and array values - the first field item is stored in the I/O tag; it is possible to configure the Destination Columnfor the I/O tag, in which all array items are stored (or the first N, if the structure does not have enough rows).
Note: if a metric arrives with the is_null flag set, the I/O tag will have the Invalid value.
| Kotva | ||||
|---|---|---|---|---|
|
...
- Communication protocol "MQTT Client Protocol".
- Station address: the station address corresponds to the Topic field in the PUBLISH message received from the MQTT server. The address can be a specific Topic, a regular expression, a # character representing all Topics, or a topic .* representing all Topics that are not suitable for other stations. The processing priority is as follows:
- If there is a station with address # on the line, all messages are directed to its I/O tags and no further search is performed.
- Otherwise, all other stations on the line are searched (with except the exception of the .* address). If the Topic matches the address of a station, the message is directed to that station and no further search is performed.
- Otherwise, all other stations on the line the line are searched (with except the exception of the .* address), and their address is evaluated as a regular expression. If the Topic matches the station address, the message is directed to that station and no further search is performed.
Stations are searched in descending order (by station address), so more specific terms go first (e.g., status/battery before status/batt.*) - Finally, if there is a station with a .* address, the message is addressed to it.
- Polling parameters on the Time parameters tab - recommended value is Delay=0.
...
- Text mode: The original implementation of the MQTT protocol contained only input text I/O tags with the addresses IN_TOPIC, IN_DATA, and optionally a pair of I/O tags with the addresses IN_ID and ACK_ID. The first two I/O tags were used to publish the received Topic and Payload (which then needed to be parsed in the script), the second two points were used to publish the packet identifier and confirm the processing of the packet. Thus, it was possible to ensure that for data sent with QoS > QoS_0, confirmation was sent only after data processing in the script.
Output I/O tags with the addresses OUT_TOPIC and OUT_VALUE are used for writing. - JSON mode: An extension for processing Payload with JSON data (Payload Type=JSON) was implemented with the help of input I/O tags with addresses JA=json_address. The D2000 KOM process directly parses the JSON payload and sets the values of I/O tagswith JSON addresses. I/O tags with addresses IN_TOPIC, IN_DATA, IN_ID, and ACK_ID may not exist at all.
Output I/O tags with the addresses OUT_TOPIC and OUT_VALUE are used for writing. - Sparkplug mode: An extension for Payload processing with Sparkplug data (Payload Type=Sparkplug) has been implemented using input I/O tags with addresses SA=sparkplug_address. The D2000 KOM process directly parses the Sparkplug payload and sets the values of I/O tags with the Sparkplug addresses. I/O tags with addresses IN_TOPIC, IN_DATA, IN_ID and ACK_ID may not exist at all.
Writing simple values is possible using output I/O tags with addresses ST=type;SA=sparkplug_address, where type is the Sparkplug definition of a data type (eg Int8, UInt16, DateTime, String, etc).
Note: STATE type messages that have a JSON payload can be parsed using I/O tags with a JSON address (typically an I/O tag of Di type with an address of JA=online).
| Type of I/O tag | Address | Description | ||||||
|---|---|---|---|---|---|---|---|---|
| I/O tags for reading data sent by the MQTT server through a PUBLISH message. Note: values of I/O tags are set by the D2000 KOM process in the order IN_TOPIC, IN_DATA, and IN_ID. It is not necessary for the configuration to contain all three I/O tags. | ||||||||
| TxtI |
| Topic (Topic) of received PUBLISH message. | ||||||
| TxtI |
| Data (Payload) of received PUBLISH message. | ||||||
| Ci |
| Identifier of a packet (Packet Identifier) of PUBLISH message that depends on the level of validation (QoS). For messages sent with QoS_0, the identifier is zero, for QoS_1 and QoS_2, it is a positive 16-bit number. Note: if the MQTT server sends also messages with the QoS_0 level of validation and the ACK_ID I/O tag is configured, then we recommend activating the option New value when changing time in the Filter tab, so that repeated writing of the value 0 will cause a new value that differs only in a timestamp to be generated. | ||||||
| I/O tag to confirm the received data to the MQTT server. | ||||||||
| Co |
| If an output I/O tag with ACK_ID address is defined, the D2000 KOM expects confirmation of the processing of each message by writing a copy of the value of the IN_ID tag. Only after, it sets values from the next received PUBLISH message (if it was received in the meantime) into the IN_TOPIC, IN_DATA, and IN_ID I/O tags (in this order). In the case of the QoS_0 level of confirmation, it is, therefore, necessary to repeatedly set the value of the I/O tag ACK_ID to 0. If the I/O tag ACK_ID does not exist, the values are written into the IN_TOPIC, IN_DATA, and IN_ID I/O tags immediately after the PUBLISH message is received and processed. Note: for the messages received with the QoS_0 level of validation, no confirmation is sent to the MQTT server, only the values of the received PUBLISH message will be published. | ||||||
| I/O tags for sending values to the MQTT server through a PUBLISH message. Note: in order for the D2000 KOM process to send the PUBLISH messages to the MQTT server, both I/O tags must be defined within one station. | ||||||||
| TxtO |
| The topic of the PUBLISH message being sent. | ||||||
| TxtO |
| Data (Payload) of the PUBLISH message being sent. Note: sending the message is performed out as a result of writing to the OUT_VALUE I/O tag (i.e. if the Topic does not change then it is sufficient to set the OUT_TOPIC point once - e.g. by using default value). | ||||||
| I/O tags for parsing JSON messages | ||||||||
TxtI, TxtO, Qi, |
| If Payload Type=JSON, the message is parsed as JSON data. The json_address value specifies the name of the JSON field whose value is to be assigned to the I/O tag. For other examples, see the description of the LoRaWAN protocol's Envelope type I/O tags. | ||||||
| I/O tags for parsing Sparkplug messages | ||||||||
TxtI, TxtO, Qi, |
SA=sparkplug_address Output I/O tags: | If Payload Type=Sparkplug, the message is parsed as Sparkplug data (a binary format built on Google Protocol Buffers). Sparkplug data contains metrics that have text identifiers. The value type must be specified for output I/O tags. Simple types are supported:
| ||||||
...