Supported device types and versions
About the MQTT Sparkplug protocol
Communication line configuration
Communication line parameters
Communication station configuration
I/O tag configuration
Tell commands
Literature
Document revisions
...
The protocol is an implementation of the MQTT 3.1.1 standard (October 2014) and the MQTT 5.0 standard (March 2019). MQTT protocol is a client/server protocol of a subscribe/publish type. It is simple, has little overhead, and is easy to implement. It is used for M2M communication (Machine to Machine) and in the IoT context (Internet of Things). The MQTT server is also called the MQTT broker.
D2000 KOM implements the client part of the protocol. The protocol is implemented on a TCP/IP-TCP and TCP/IP line-TCP Redundant lines. MQTTS (Secure MQTT, MQTT over TLS) is also supported - either directly in the D2000 KOM process (using TLS settings on on TCP/IP-TCP and TCP/IP-TCP lineRedundant lines) or via the tunnelstunnel utility.
For the transfer of LoRaWAN data encapsulated within the MQTT protocol, see LoRaWan protocol description.
The Sparkplug 3.0.0 standard (Sparkplug B MQTT Payload) is also partially supported. Support includes:
- Connecting to the MQTT broker as a Host Application (data consumer, in Payload Type = Sparkplug Host mode):
- reading simple value types
- reading arrays (with support for the Destination column)
- writing simple value types
- reading of template items (UDT)
- reading of dataset items
- support for metric aliases
- compression support (GZIP, DEFLATE)
- browsing - finding a list of metrics
- Connecting to an MQTT broker as an Edge Node (data producer, in Payload Type = Sparkplug Edge Node mode):
- publishing values with simple types
- processing commands (NCMD, DCMD) with simple value types
- processing commands (NCMD, DCMD) with template (UDT) items
- processing commands (NCMD, DCMD) with dataset items
- processing commands (NCMD, DCMD) with arrays
- processing of the NCMD command with the Node Control/Next Server metric (connecting to the next MQTT server, if several are configured on the line)
- processing of the STATE message with the content online=false, which comes from the Primary Host Application (disconnecting from the MQTT server and trying another one, if several are configured on the line - searching for an MQTT server with a connected Primary Host Application)
- support for metric aliases
The communication was tested/deployed with:
- www.TheThings.network cloud
- Loriot.io cloud
- Slovanet cloud (loralink.slovanet.sk)
- Pixii PowerShaper (energy storage solution)
- liveobjects.orange-business.com cloud
- test.mosquitto.org (in both Payload Type = Sparkplug Host and Payload Type = Sparkplug Edge Node modes)
- broker.hivemq.com (in both Payload Type = Sparkplug Host and Payload Type = Sparkplug Edge Node modes)
- ThingsBoard (in Payload Type = Sparkplug Edge Node mode)
- Eclipse™ Sparkplug™ Technology Compatibility Kit (TCK) using version 3.0.0
Note: communication with the cloud liveobjects.orange-business.com via WebSockets (wss://liveobjects.orange-business.com:443/mqtt) was also tested. The program https://github.com/jimparis/unwebsockify.git was used as a WSS wrapper. This program started with the following parameters:
./unwebsockify.py --port 1883 --listen 172.16.0.1 wss://liveobjects.orange-business.com:443/mqtt
The D2000 KOM process was connected to address 172.16.0.1 on port 1883. The WSS wrapper was connected to the defined URL and wrapped the MQTT communication data in a WebSocket envelope.
...
The server responds with a return code that contains information about the success and the maximum QoS that was assigned to the requested topics.
...
If the server does not send a message for longer than the 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.
...
Sparkplug's MQTT protocol defines 3 groups of applications:
- Edge Node - supports 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 Represents a physical or logical device connected to an Edge Node and providing data, process data , or metrics.
- Host Application - represents 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.
...
- If the MQTT server supports Topic aliases, use MQTT Version = MQTT 5.0, and set Topic Alias Maximum to a value greater than the number of stations on the line (for Payload Type = Sparkplug Edge Node) or greater than the number of topics expected from the MQTT broker (for Payload Type = Text only / JSON). On the MQTT broker side, ensure that its Topic Alias Maximum value is greater than the number of topics that will be sent to the D2000 KOM process, so that numeric aliases can be used instead of text topics.
Note: the Topic Alias Maximum value that the MQTT broker sends when connecting as a parameter of the CONNACK message is visible in the communication logs:
09:31:12.086 13-05-2025|D|MQTT> CONNACK Property # 1 Topic Alias Maximum ( 34)
09:31:12.087 13-05-2025|T|MQTT> Recv:<00><0A>
09:31:12.088 13-05-2025|D|MQTT> CONNACK Property value= 10 - Set Subscribe QoS = QoS_0 to not require acknowledgments for PUBLISH messages (unless they are needed for some reason). Additionally, if TLS is also active, this will cause a small packet (e.g., PUBACK for QoS_1) to be encrypted and result in a larger encrypted packet.
- Use aliases for metrics (for for Payload Type = Sparkplug Edge Node): automatically using the Sparkplug Alias Mode=Automatic (HOBJ) parameter or manually using the SAL=alias item in the I/O tag address. If you use manual aliases, use low numbers (aliases 10-127 are encoded as 1 byte).
- For Payload Type = Sparkplug Edge Node: if there are many changes to the output I/O tags, we recommend setting the Batch Size parameter to a larger value than the default (10) and possibly increasing the Delay parameter in the station's time parameters. This will cause fewer messages to be generated (and each will contain multiple metrics), which reduces the overhead required to transmit one metric. If specific I/O tags change frequently, the message may contain several values for the same I/O tag (with timestamps). The disadvantage is the delay in the values.
...
- Communication line category: TCP/IP-TCP or TCP/IP-TCP Redundant.
- Host: IP address of MQTT server (or redundant addresses separated by a comma or semicolon).
Note: In Payload Type = Sparkplug Edge Node mode, the Node Control/Next Server metric is supported, which can be used to command the D2000 KOM process to connect to the next MQTT server (if multiple servers are specified). - Port: the default port number is 1883 or 8883 for the encrypted SSL/TLS variant.
- Line number: unused, set the value to 0.
Note: The default port for the MQTT protocol is 1883 or 8883 for the SSL/TLS version. D2000 KOM contains an implementation of the SSL/TLS protocol variant, alternately t ; it is also possible to configure it by using the stunnel utility http://www.stunnel.org working in a client mode (client = yes). Stunnel running on the same computer as the D2000 KOM should listen to the 1883 local port, and after connecting of the D2000 KOM process to the port, it should encrypt the communication using SLLSSL/TLS and send it to the target MQTT server (typically on port 8883).
Note: when When using an SSL/TLS connection, you must pay attention to the expiration of the certificates used. The expiration date can be found on Linux with the command
openssl x509 -text -in file.crt | grep "After"
Forced disconnection: If all stations on the line are in the simulation mode or the communication is stopped for them, the line will be disconnected (the communication socket will be closed). If the simulation is disabled for at least one station and the communication is not stopped for it (the Parameters tab of the Station type object), the line will be connected again.
Notes on MQTT broker redundancy
If the TCP/IP-TCP line is configured, one TCP connection is created, which can be directed to one of multiple configured IP addresses.
If the TCP/IP-TCP Redundant line is configured, two TCP connections are created (to 2 MQTT brokers), each of which can be directed to one of multiple configured IP addresses. The D2000 KOM process receives values from both MQTT brokers and sends all values of the output I/O tags to both MQTT brokers. The write is considered successful if the value is successfully sent to at least one MQTT broker (in the case of confirmation, if "Subscribe QoS" > QoS_0, if it is confirmed by at least one of the MQTT brokers). Such a configuration allows you to configure a redundant system in which the D2000 KOM connects to two redundant MQTT brokers and the other side to at least one MQTT broker, while the MQTT brokers do not have to form a "cluster", i.e. synchronize messages with each other (so the simple and free Eclipse Mosquitto can also be used - see configuration example).
Forced disconnection: If all stations on the line are in the simulation mode or the communication is stopped for them, the line will be disconnected (the communication socket will be closed). If the simulation is disabled for at least one station and the communication is not stopped for it (the Parameters tab of the Station type object), the line will be connected again.
In Payload Type = Sparkplug Edge Node mode, if communication on the Edge Node station is stopped, the line will be disconnected (even if Device type substations have communication stopped). If communication on the Device station is stopped and the Edge Node station is communicating, the D2000 KOM will send a DDEATH message and after turning on the Device station, it will send a DBIRTH message.
| Kotva | |||
|---|---|---|---|
| |||
| Kotva | |||
|
...
Dialog link configuration line configuration - Protocol parameters tab.
They affect some optional protocol parameters. The following protocol line parameters can be entered:
...
| Parameter | Description | Unit/size | Default value | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Activates detailed debug information about sending and receiving values. | YES/NO | NO | |||||||||
| The version of the MQTT protocol that will be used to connect to the MQTT server. It is possible to use the older MQTT 3.1.1 standard (October 2014) or the newer MQTT 5.0 standard (March 2019). MQTT brokers usually support both standards, the older standard is simpler and more economical; the older standard is simpler and more economical. On the other hand, MQTT 5.0 allows message size reduction by using Topic Aliases. | MQTT 3.1.1 MQTT 5.0 | MQTT 3.1.1 | |||||||||
| User name used in a CONNECT message to connect to the MQTT server. | - | ||||||||||
| Password used in a CONNECT message to connect to the MQTT server. | - | ||||||||||
| The name of one topic or a multiple-topic filter sent within the SUBSCRIBE message. Using the filter, the MQTT client specifies topics , within for which it wants to receive messages. Note:topics Topics are hierarchically sorted, a slash (/) is used as the separator, a plus (+) is used as a one-level mask, and a hash (#) character is used as a mask for multiple levels. Examples of filter: a/b , level1/+ , # , +/+/+/up Note: the change of the Topic Filter parameter will be reflected after restarting the communication - , e.g., due to the breakdown of the TCP connection, as long as all stations on the line are switched off (StOff) and switched on again, or after a restart of the KOM process. In the first two cases, the message UNSUBSCRIBE is sent to the original Topic Filter and then SUBSCRIBE to the new Topic Filter (this can be important in so-called persistent sessions when the Client ID parameter is specified and the MQTT server remembers the state of the client even after the TCP connection is broken). Note: for Payload Type = Sparkplug Host, the filter spBv1.0/# is sufficient to receive all Sparkplug messages. It is also possible to specify an empty filter, as by default, SUBSCRIBE is generated for BIRTH/DATA/DEATH messages derived from station addresses that are in Sparkplug format (group_id/edge_node_id/[device_id]) are sent. Note: for Payload Type = Sparkplug Edge Node, a SUBSCRIBE message is automatically sent to all NCMD/DCMD topics derived from the addresses of Edge Node/Device stations configured on the linkline. Example:
Note: Payload Type = Sparkplug Edge Node, a SUBSCRIBE message is automatically sent to the topic spBv1.0/STATE/<primaryHostApplication> if the Sparkplug Host ID parameter is specified (<primaryHostApplication> is the value of this parameter), so that the D2000 KOM process is informed about the connection/disconnection of the Primary Host Application. If a STATE message about the Primary Host Application disconnection is received (STATE message with online=false) and multiple IP addresses are specified in the line configuration, the D2000 KOM process disconnects from the current MQTT server and tries other MQTT servers until it finds one to which the Primary Host Application is connected (STATE message with online=true). | - | # | |||||||||
| The desired maximum level of validation (QoS) sent within the SUBSCRIBE message. The MQTT server can then send PUBLISH messages with such or lower levels of confirmation (but not higher). PUBLISH messages sent by the MQTT server will be confirmed by the D2000 KOM process according to the level of confirmation specified in them. The higher the level of confirmation, the more messages between the client and the server are exchanged (1 at QoS_0, 2 at QoS_1, and 4 at QoS_2). Note: For Payload Type = Sparkplug Edge Node, QoS_1 is always used. | QoS_0 QoS_1 QoS_2 | QoS_1 | |||||||||
| Unique client identifier (Client Identifier) sent within the CONNECT message. The tested MQTT server (thethings.network) returned an error if the Client ID was blank and Clean Session Flag=NO. Note: Some MQTT brokers (PIXII.COM, Eclipse Mosquitto) identified clients only by Client ID. In practice, this meant that two different D2000 systems that connected to the same broker were considered as one client, and the broker closed an existing connection that it considered old when a new connection was established, or it did not allow a new connection to be created and returned the error Connection Refused, identifier rejected (2). | - | D2000kom | |||||||||
| Parameter Clean Session Flag of the CONNECT message. The NO value means that the server uses the current session state (connection) - e. g. after the collapse and recovery of the TCP connection. This means that all unconfirmed PUBLISH messages with QoS_1 and QoS_2 are resent (optionally also QoS_0, depending on the implementation). | YES/NO | NO | |||||||||
| Level of confirmation (QoS) used to send PUBLISH messages through the D2000 KOM process. Sending the PUBLISH message is the outcome of writing into the output tag with the OUT_VALUE address. The higher the confirmation level, the more messages between the client and server are exchanged (1 for QoS_0, 2 for QoS_1, and 4 for QoS_2)for QoS_2). Note: If Payload Type = Sparkplug Host or Sparkplug Edge Node, this parameter is ignored and QoS_0 is used. | QoS_0 QoS_1 QoS_2 | QoS_0 | |||||||||
| Setting the Retain flag used when sending PUBLISH messages by the D2000 KOM process. Activating the Retain flag causes the last message sent by the D2000 KOM process to be available on the MQTT server to other clients immediately after they are connected, as well as after the D2000 KOM process is disconnected. Note: If Payload Type = Sparkplug Host or Sparkplug Edge Node, this parameter is ignored, and Retain=False is used. | YES/NO | NO | |||||||||
| Parameter Keep Alive sent as part of a CONNECT message. The recommended Keep Alive value is several minutes. The D2000 KOM process sends PING requests according to the settings of the Keep Alive and Ping Interval parameters (whichever interval expires first). | 0-65535 sec | 0 | |||||||||
| If the MQTT server did not send any message during the specified time interval, the D2000 KOM process sends a PING request and waits for a PING response (until time Reply Timeout). A value of 0 turns off sending the PING request messages. The parameter allows detection of TCP connection failure. | 0-3600 sec | 60 | |||||||||
| The setting of message parsing:
| Text only JSON Sparkplug Host Sparkplug Edge Node | Text only | |||||||||
| If Payload Type=JSON, the name of the field with a timestamp. If the field name is not specified or the field is not found, the current time is assigned to the values. For more information on the field name format, see I/O tags with addresses JA=json_address. | - | - | |||||||||
| Mask If Payload Type=JSON, the mask for parsing a value in the JSON field with a timestamp. Special Special masks are:
Note: Whether the time is interpreted as local or UTC with a configured offset depends on the time station parameters settings settings. This rule does not apply when using the special masks listed above, when UTC time with a zero offset is always used. | - | yyyy-mm-dd hh:mi:ss.mss | |||||||||
| Ignoring If Payload Type=JSON, ignoring a missing timestamp - if it is not present in the JSON payload, no warning will be issued. | YES/NO | NO | |||||||||
| Parameter Will Flag of a CONNECT message. A value of Yes means that the server will send a Last Will message to interested parties if the connection to the D2000 KOM process is lost. Note: If Payload Type = Sparkplug Host and the Sparkplug Host ID parameter is not empty, this parameter is ignored and Last Will will be sent (see the description of the Sparkplug Host ID parameter). Note: If Payload Type = Sparkplug Edge Node, this parameter is ignored and Last Will will be sent (see the description of the Sparkplug Host ID parameter). | YES/NO | NO | |||||||||
| The acknowledgment level (QoS) used when sending a Last Will message in the event of a loss of connection to the D2000 KOM process. Note: If Payload Type = Sparkplug Host and the Sparkplug Host ID parameter is not empty, this parameter is ignored, and QoS_1 level will be set (see the description of the Sparkplug Host ID parameter). Note: If Payload Type = Sparkplug Edge Node, this parameter is ignored, and QoS_1 level will be set (see the description of the Sparkplug Host ID parameter). | QoS_0 QoS_1 QoS_2 | QoS_0 | |||||||||
| The setting of the Retain flag used when sending a Last Will message if the connection to the D2000 KOM process is lost. Note: If Payload Type = Sparkplug Host and the Sparkplug Host ID parameter is not empty, this parameter is ignored and Retain is set to YES (see the description of the Sparkplug Host ID parameter). Note: If Payload Type = Sparkplug Edge Node, this parameter is ignored and Retain is set to NO (see the description of the Sparkplug Host ID parameter). | YES/NO | NO | |||||||||
| The topic used to send the Last Will message if the connection to the D2000 KOM process is lost. Note: If Payload Type = Sparkplug Host and the Sparkplug Host ID parameter is not empty, this parameter is ignored (see the description of the Sparkplug Host ID parameter). Note: If Payload Type = Sparkplug Edge Node, this parameter is ignored, and Topic is set according to the Sparkplug standard (see the description of the Sparkplug Host ID parameter). | - | ||||||||||
| Contents of the Last Will report if the connection to the D2000 KOM process is lost. Note: If Payload Type = Sparkplug Host and the Sparkplug Host ID parameter is not empty, this parameter is ignored (see the description of the Sparkplug Host ID parameter). Note: If Payload Type = Sparkplug Edge Node, this parameter is ignored, and Last Will is set according to the Sparkplug standard (see the description of the Sparkplug Host ID parameter). | - | ||||||||||
| If the MQTT server does not respond to the SUBSCRIBE, UNSUBSCRIBE, and PING requests within the required time or the D2000 KOM process fails to read a complete message (and only part of it is read), the D2000 KOM process declares an error, closes the connection, and opens it again. Value 0 turns off the timeout. | sec | 20 | |||||||||
| A timeout of a single reading from a TCP connection. D2000 KOM repeats reading of spontaneous data Max. Wait Retry times and if no data is read, the reading is timeouted and finished (and may be followed by a further reading or writing). By lowering Wait Timeout and Max. Wait Retry parameters, it is possible to achieve a faster writing response of the D2000 KOM process at the expense of a higher CPU load when the MQTT server has no data. | sec | 0.100 | |||||||||
| The number of repetitions of reading from the TCP connection. See the description of the Wait Timeout parameter. | - | 3 | |||||||||
| Payload field encoding. The MQTT protocol does not specify the content of the Payload field; the ISO-8859-1 standard encoding is suitable for both text and binary content, and UTF-8 is suitable if UTF-8 encoded texts are transmitted. Currently supported encodings are:
| - | ISO-8859-1 | |||||||||
MQTT 5.0 Parameters | ||||||||||||
| Number of Topic Aliases that can be sent by the MQTT broker (parameter is sent in the CONNECT message). The value 0 (default) means that Topic Aliases are not used. The parameter is used only for MQTT Version = MQTT 5.0. Topic Aliases are numeric identifiers from the interval <1 ... Topic Alias Maximum>, which are sent by the D2000 KOM and the MQTT Broker instead of text identifiers. Note: In the CONNACK message (response to CONNECT), the MQTT broker optionally sends its value "Topic Alias Maximum", which has the meaning of the number Number of Topic Aliases that can be sent by the MQTT broker (parameter is sent in the CONNECT message). The value 0 (default) means that Topic Aliases are not used. The parameter is used only for MQTT Version = MQTT 5.0. Topic Aliases are numeric identifiers from the interval <1 ... Topic Alias Maximum>, which are sent by the D2000 KOM and the MQTT Broker instead of text identifiers. Note: In the CONNACK message (response to CONNECT), the MQTT broker optionally sends its value "Topic Alias Maximum", which has the meaning of the number of Topic Aliases that can be sent by the D2000 KOM process (e.g. test.mosquitto.org sends the value 10). D2000 KOM uses Topic Aliases only if the value of its configuration parameter Topic Alias Maximum is non-zero. | 0 | 0 - 65535 | D2000 KOM process (e.g. test.mosquitto.org sends the value 10). D2000 KOM uses Topic Aliases only if the value of its configuration parameter Topic Alias Maximum is non-zero. | 0 | 0 - 65535 | ||||||
Sparkplug parameters | ||||||||||||
| For Payload Type = Sparkplug Host: Timeout (in seconds) for the arrival of a missing NDATA/DDATA message(s). NDATA/DDATA messages contain a sequence number (0..255), while the NBIRTH message contains a sequence number of 0 (resets the sequence). If the D2000 KOM detects a gap in the sequence and the missing message(s) do not arrive within the Reorder Timeout, it sends an NCMD command with the metric 'Node Control/Rebirth' to the corresponding station, which causes the corresponding Edge Node to send an NBIRTH message (and DBIRTH messages for all its Devices). This parameter is implemented on the recommendation of the Sparkplug specification. | 05.000 | 0-59.999 | Sparkplug parameters|||||||||
| The parameter activates listings of unknown metrics and topics that do not have their own stations, but end up at a station with the address ".*" (if there is any). The listings will be in the line log as error messages even if the debug on the line is turned off (to facilitate the addition of I/O tags). | YES/NO | NO | |||||||||
| For Payload Type = Sparkplug Host: Activation of parsing of non-standard SparkPlug topics (if Payload Type = Sparkplug Host). | YES/NO | NO | |||||||||
| For Payload Type = Sparkplug Host: Within the metric, it is possible to define a property called Quality of type Int32. According to the Sparkplug standard, it must be one of the values 0=BAD, 192=GOOD, 500=STALE. Any other D2000 Kom process reports as an error. The Ignore Unknown Quality parameter can be used to suppress this error message. | YES/NO | NO | |||||||||
| For Payload Type = Sparkplug Host:The parameter specifies which addresses of the Dataset metric are displayed when browsing:
| - | Columns only | |||||||||
| For Payload Type = Sparkplug Host: Separator of individual levels in Templates used when entering the address of the I/O tag in in Sparkplug mode. | -> | ||||||||||
| If For Payload Type = Sparkplug Host: Identifier of Host Application (D2000 is a Host Application). If For Payload Type = Sparkplug Edge Node: Identifier of Primary Host Application (Identifier of the Host Application that is defined as primary - the most important - for this Edge Node). | - | - | |||||||||
| If Payload Type = Sparkplug Edge Node, the parameter enables Store & Forward functionality for all stations on the line. If communication with the MQTT broker is down, values are stored in memory and sent with the the is_historical flag when communication is restored. | YES/NO | NO | |||||||||
| Adding a textual representation of the value type (e.g., Int32) and a timestamp to the text I/O tag with IN_SP2JS address used to convert the Sparkplug payload to JSON for optional parsing in an ESL script. | YES/NO | NO | |||||||||
...
- Communication protocol "MQTT Client Protocol".
- Polling parameters on the Time parameters tab - recommended value is Delay=0.
- 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 covered by other stations. The processing priority is as follows
:Kotva prio_processing prio_processing - If there is a station with address # on the line, all messages are directed are directed to its I/O tags, and no further search is performed.
- Otherwise, all other stations on the line are searched (except 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 are searched (except 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 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.
For a SparkPlug MQTT server, the Topic has the form 'namespace/group_id/message_type/edge_node_id/[device_id]', where message_type indicates the message type (e.g., DDATA, DBIRTH, DDEATH).
If Payload Type = Sparkplug Host: A regular expression (e.g., spBv1.0/Sparkplug Devices/.*/MyDevice/Sensor2) can be used instead of message_type to cover all message types. It is possible , however, recommended to omit the namespace and message_type parts and write the Topic in the abbreviated form 'form group_id/edge_node_id/[device_id]' (e.g., Sparkplug Devices/MyDevice/Sensor2).
Note: Disabling communication on all stations will cause communication to be disconnected from the MQTT broker.
If Payload Type = Sparkplug Edge Node: One station on the line should correspond to the Edge Node; its address must be in the form group/node (e.g., myGroup/myNode). There may be other stations corresponding to the Device/Sensor on the line, their addresses must be in the form group/node/device (e.g., myGroup/myNode/myDevice1), where group/node is the same as the address of the station corresponding to the Edge Node. According to the Sparkplug standard, these Device/Sensor stations belong to the corresponding Edge Node station (are its substations) and represent devices with which the Edge Node station communicates (e.g., via Modbus protocol).
Note: Disabling communication on the Edge Node station will cause communication to be disconnected from the MQTT broker.
Note: Kotva komunikacna_stanica_pozn komunikacna_stanica_pozn
If Payload Type = Sparkplug Host and the station address is in abbreviated form, the station doesn't process commands (DCMD, NCMD). If it is in the form of a regular expression ('namespace/group_id/.*/edge_node_id/[device_id]'), the station also processes commands (including the command sent by the D2000 KOM process if Send Node Control/Rebirth=YES). Therefore, we recommend specifying the station address in abbreviated form. If it is also necessary to process commands (from other Host Applications), then create another station with an address in the form of a regular expression (e.g., spBv1.0/Sparkplug Devices/DCMD/MyDevice).
If Payload Type = Sparkplug Edge Node, the station processes commands (DCMD, NCMD) and ignores data messages (NDATA, DDATA, NBIRTH, DBIRTH).
...
| Keyword | Full name | Meaning | Unit | Default value | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Subscribe Station Address | If this parameter has the value YES, the Topic related to the station address is also added to the SUBSCRIBE message:
| YES/NO | NO | ||||||||
| Station Will Topic | Will topic of the device. If this parameter is set and a message with the same topic is received, the station will go into a communication error (StHardErr) and the values of the I/O tags will be invalidated. In this way, it is possible to emulate the standard behavior that occurs when there is a communication error with the device (even if the communication between the D2000 Kom process and the MQTT broker is functional). | ||||||||||
| Station Will Payload | Content of the Will message. If this parameter is set and a message with the same topic as defined by the Station Will Topic parameter is received, the Payload must also be the same. If this parameter is an empty string, matching the topic with the Station Will Topic parameter is sufficient. | ||||||||||
| Payload Type | The setting of message parsing (overriding the line parameter Payload Type):
| Default Text only JSON Sparkplug | Default | ||||||||
| Time Field Name | If Payload Type = JSON, the name of the field with a timestamp - overriding the line parameter Time Field Name. | - | - | ||||||||
| Time Mask | Mask for parsing a value in the field with a timestamp - overriding the line parameter Time Mask. Note: Whether the time is interpreted as local or UTC with a configured offset depends on the time station parameters settings. | - | - | ||||||||
Sparkplug parameters | ||||||||||||
| Send Node Control/Rebirth | If Payload Type = Sparkplug Host, when connecting to the MQTT server, a command (NCMD or DCMD) with the metric 'Node Control/Rebirth' is sent to the SparkPlug station. The response should be a message (NBIRTH/DBIRTH) with all current metrics. | YES/NO | YES | ||||||||
| Batch Size | If Payload Type = Sparkplug Edge Node: The parameter specifies the maximum number of values (metrics) that are sent in one message (NDATA/DDATA). The parameter allows for optimization of the number of MQTT messages (more smaller or fewer larger with a delay). Reading values from the station (ReadAllPoints function) will cause the buffered values to be sent even if the configured maximum has not yet been reached (i.e., a larger time delay in the station parameters will cause more values to be buffered). | 1-1000 | 10 | ||||||||
| Store & Forward | The parameter allows you to change the Store & Forward functionality, which is defined for all stations on the line by the Store & Forward line parameter. The value Default means using the settings configured on the line. | Default False True | Default | ||||||||
| Store & Forward Batch Size | If the Store & Forward functionality is active (see Store & Forward parameter), the parameter specifies the maximum number of historical values sent in one message (NDATA/DDATA) after communication is resumed. | 1-1000 | 10 | ||||||||
| Sparkplug Alias Mode | If Payload Type = Sparkplug Edge Node, the parameter specifies the alias usage mode. Aliases are numeric (integer - Int64) identifiers, used optionally in data and command messages (NDATA/DDATA/NCMD/DCMD) instead of text identifiers, due to the message size reduction. If used, they are listed in the NBIRTH/DBIRTH message together with text identifiers. Aliases must be unique within all I/O tags belonging to one station.
| Default (SAL=alias) Automatic (HOBJ) Off | Default (SAL=alias) Automatic (HOBJ) Off | Default (SAL=alias) | |||||||
| Sparkplug-to-JSON Mode | The parameter defines the JSON data format for the measured point with the address IN_SP2JS (Sparkplug payload to JSON conversion). The JSON data is either generated in a compact mode suitable for further machine processing (fields separated by spaces) or in a form suitable for human viewing (multiline format). | Compact Multiline | CompactDefault (SAL=alias) | ||||||||
| Kotva | ||||
|---|---|---|---|---|
|
...
- 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 Host/Edge Node) 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.Kotva sparkplug_address sparkplug_address
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 e.g., Int8, UInt16, DateTime, String, etc). The output I/O tags must be on the station with the the Sparkplug address since the Topic is derived from it when writing.
Note: messages of Messages of STATE type (generated by Host Application clients) with 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 (usually used in Text mode or JSON mode, rarely in Sparkplug mode). Note: values 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 The configuration doesn't need to contain all all three I/O tags. | ||||||||||||||||||||||
| TxtI |
| Topic (Topic) of the received PUBLISH message. | ||||||||||||||||||||
| TxtI |
| Data (Payload) of the received PUBLISH message. | ||||||||||||||||||||
| Ci |
| Identifier of a packet (Packet Identifier) of a 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. On the TCP/IP-TCP line, the identifier is monotonically increasing; on the TCP/IP-TCP Redundant line, values from two monotonically increasing sequences can alternate (so they can also be repeated), so the recommendation given in the following note applies: Note: if If the MQTT server also 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 the 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 For messages received with the a QoS_0 level of validation, no confirmation is sent to the the MQTT server, only ; 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. Note: If the I/O tag with the OUT_TOPIC address does not exist, the station address will be used directly as the Topic (if it is empty, the writing will not be performed). | ||||||||||||||||||||
| TxtO |
| Data (Payload) of the PUBLISH message being sent. Note: sending 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 the 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 tagss Envelope type I/O tags. Writing to an I/O tag with a JSON address is also supported, but it must not have indexes. Examples of correct addresses for writing:
When writing, the generated JSON contains the value itself and optionally a timestamp, if the station protocol parameter Time Field Name or the line parameter Time Field Name is set. | ||||||||||||||||||||
| I/O tags for parsing Sparkplug messages | ||||||||||||||||||||||
TxtI, TxtO, Qi, |
SA=sparkplug_address SAL=alias;SA=sparkplug_address ST=type;SA=sparkplug_address ST=type;SAL=alias;SA=sparkplug_address | If Payload Type = Sparkplug Host/Edge Node, the message is parsed as Sparkplug data (a binary format built on Google Protocol Buffers). Sparkplug data contains metrics that have text identifiers (sparkplug_address) or possibly numeric aliases (alias). Reading template items is possible by specifying sparkplug_address in the format <TemplateName1><Separator><TemplateName2><Separator> ... <Separator><ItemName> where:
Examples of template item addresses: Reading dataset items (equivalent to structured variables in D2000) is possible by specifying sparkplug_address in the format <DatasetName>[<Row>]^<ColumnName> where:
Examples of dataset item addresses: For output I/O tags, the value type can be explicitly (ST=type). Simple types are supported (not template items/dataset items):
If the value type is not specified, the default value depends on the type of I/O tag:
Note: There is no difference between the String and Text types. For Payload Type = Edge Node, it is also possible to specify a numerical alias (SAL=alias) as a natural number (0, 1, 2, ...) for both input and output I/O tags. The alias of the I/O tag within the station must be unique. Aliasing allows you to reduce the size of the transmitted data: in the NBIRTH/DBIRTH message, both the text identifier (sparkplug_address) and the alias are specified for each I/O tag; in the NDATA/DDATA messages, only aliases that are shorter than the text addresses are sent. Alias is only used if Sparkplug Alias Mode = "Default (SAL=alias)".
The Payload of the message contains a timestamp, a value type (type), a written value (encoded according to the specified value type), and a metric name (sparkplug_address) or an alias. | ||||||||||||||||||||
TxtI |
| The I/O tag is used to convert the Sparkplug payload into a JSON representation, which can then be processed, e.g., in an ESL script. Depending on the Convert Datatype/Timestamp to Text parameter, a textual representation of the value type and timestamp is also added. {"metrics":[{"datatype":3,"int_value":7338992,"name":"Corrected Vol Acc Stn","timestamp":1729664005479}],"seq":32,"timestamp":1729664005479} {An example of a more complex value containing properties and a dataset, and also displaying a textual representation of the data type (datatype_txt) and timestamp (timestamp_txt) as a result of the set parameter Convert Datatype/Timestamp to Text: { | ||||||||||||||||||||
...
The list of objects is dynamic, i.e. when a new value arrives in the KOM process, it is updated. Filtering in individual columns (with the exception of of the Time column) is is also supported, ; asterisks can be used in the mask (e.g., *Short*).
Double-clicking on a particular line will insert the value from the Address column into the configuration of the I/O tag from which the MQTT Item Browser window was opened. At the same time, it is also inserted into the clipboard.
The Refresh button clears the list of values in both the CNF and the KOM process and optionally sends the Rebirth command (In the Sparkplug Host mode, if Send Node Control/Rebirth=YES).
The Value column contains the received value.
...
the Address column into the configuration of the I/O tag from which the MQTT Item Browser window was opened. At the same time, it is also inserted into the clipboard.
The Refresh button clears the list of values in both the CNF and the KOM process and optionally sends the Rebirth command (In the Sparkplug Host mode, if Send Node Control/Rebirth=YES).
The Value column contains the received value.
| Kotva | ||||
|---|---|---|---|---|
|
...
| Príkaz | Syntax | Popis |
|---|---|---|
| STCOMMAND | STCOMMAND StationName PUTOLDVAL BeginTime EndTime | For Payload Type = Edge Node: The Tell command reads out historical values of output I/O tags (if the I/O tags or their control objects are archived) and sends them as historical values. Reading works independently of the Store & Forward protocol parameter. Using this command, it is possible to send historical values even for the period when the D2000 KOM was turned off (and therefore the Store & Forward functionality could not work). Example: STCOMMAND B.MQTT_MOSQUITTO_EN.Device1 PUTOLDVAL "30-05-2025 00:00:00" "30-05-2025 00:10:00" |
| Kotva | ||||
|---|---|---|---|---|
|
...
Links
Official website of the MQTT protocol protocol http://mqtt.org
Official website of the MQTT Sparkplug protocol https://sparkplug.eclipse.org
Specifications and Standards
MQTT 3.1.1 specification http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html
ISO/IEC 20922:2016 http://www.iso.org/standard/69499.html
Descriptions of Data Formats and API
www.loriot.io - Application API Data Format https://www.loriot.io/home/documentation.html#docu/app-data-format
www.thethingsnetwork.org - API Reference https://www.thethingsnetwork.org/docs/applications/mqtt/api.html
...
| Info | ||
|---|---|---|
| ||
You can read a blog about the MQTT protocol |
| Kotva | ||||
|---|---|---|---|---|
|
...
- Ver. 1.0 - August 8th, 2017 - document creation.
- Ver. 1.1 - October 15th, 2021 - support LastWill and Retain parameters
- Ver. 1.2 - October 27th, 2021 - support for parsing of JSON messages
- Ver. 1.3 - February 1st, 2022 - support for timestamps in JSON messages
- Ver. 1.4 - October 4th, 2024 - support for MQTT Sparkplug (in Sparkplug Host mode), support for browsing
- Ver. 1.5 - November 8th, 2024 - support for MQTTS (encrypted MQTT, MQTT over TLS)
- Ver. 1.6 - April 25, 2025 - support for MQTT Sparkplug (in Sparkplug Edge Node mode)
- Ver. 1.7 - May 5, 2025 - support for aliases in MQTT Sparkplug mode
- Ver. 1.8 - May 12, 2025 - support for MQTT 5.0
| Info | ||
|---|---|---|
| ||