...
- reading simple value types
- reading arrays (with support for the Destination column)
- writing simple value types
Work with templates Reading of template items (UDT) is not supported.
The communication was tested/deployed with:
...
| Parameter | Description | Unit / size | Default value | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Activates detailed debug information about sending and receiving values. | YES/NO | NO | ||||||||
| 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 which it wants to receive messages. Note: topics are hierarchically sorted, a slash (/) is used as the separator, a plus (+) is used as a one-level mask, 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, the filter spBv1.0/# is sufficient to receive all Sparkplug messages. | - | # | ||||||||
| 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). | 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). | 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. | 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 | 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 for parsing a value in the field with a timestamp. Special masks are:
Note: Whether the time is interpreted as local or UTC with a configured offset depends on the time station parameters settings. | - | yyyy-mm-dd hh:mi:ss.mss | ||||||||
| 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 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). | 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 and the Sparkplug Host ID parameter is not empty, this parameter is ignored and QoS_1 level will be sent (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 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). | 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 and the Sparkplug Host ID parameter is not empty, this parameter is ignored (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 and the Sparkplug Host ID parameter is not empty, this parameter is ignored (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 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 | ||||||||
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 | ||||||||
| Activation of parsing of non-standard SparkPlug topics. | YES/NO | NO | ||||||||
| Separator of individual levels in Templates used when entering the address of the I/O tag in Sparkplug mode. | -> | |||||||||
| Identifier of Host Application. If specified, the D2000 KOM process will send a STATE message according to the MQTT Sparkplug standard after connecting to the MQTT server. With this message it announces that it is alive (equivalent to the NBIRTH and DBIRTH messages sent by Edge Nodes and Devices). At the same time, it sets the Will Topic/Will Message in the CONNECT message according to the Sparkplug standard, with Identifier of Host Application. If specified, the D2000 KOM process will send a STATE message according to the MQTT Sparkplug standard after connecting to the MQTT server. With this message it announces that it is alive (equivalent to the NBIRTH and DBIRTH messages sent by Edge Nodes and Devices). At the same time, it sets the Will Topic/Will Message in the CONNECT message according to the Sparkplug standard, with Will QoS=QoS_1, Will Retain=YES, Clean Session Flag=YES. If the identifier is not specified, the D2000 KOM does not send the STATE message (and the Will parameters are configurable). | - | - | ||||||||
...
- 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.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 Int8, UInt16, DateTime, String, etc). The output I/O tags must be on the station with the Sparkplug address since the Topic is derived from it when writing.
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: I/O tags: 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 (sparkplug_address). Reading template items is possible by specifying sparkplug_address in the format <TemplateName1><Separator><TemplateName2><Separator> ... <Separator><ItemName> where:
Examples of template item addresses: The value type must be specified for output I/O tags. Simple types are supported (not template items):
The PUBLISH message created during writing contains a Topic derived from the station address. The message type depends on the station address - whether it is Edge Node (NCMD) or Device/Sensor (DCMD). The Payload contains a timestamp, a value type (type), a written value (encoded according to the specified value type), and a metric name (sparkplug_address). | ||||||
...