Supported device types and versions
Communication line configuration
Communication line parameters
Communication station configuration
I/O tag configuration
Literature
Document revisions
...
The protocol is an implementation of the MQTT 3.1.1 standard (October 2014). MQTT protocol is a client/server protocol of subscribe/publish type. It is simple, has little expense overhead and is easy to implement. It is used for M2M communication (Machine to Machine) and in the IoT context (Internet of Things).
D2000 KOM implements the client part of the protocol. The protocol je implemented on a TCP/IP linkline.
For LoRaWAN transfer of LoRaWAN data transfer encapsulated within the MQTT protocol, see LoRaWan protocol description.
Each PUBLISH message contains a topic (Topic), data (Payload) and level of confirmation (QoS). PUBLISH messages can be sent both by the client and the server. The client clients at the beginning of the communication will use the SUBSCRIBE message to indicate what topics (parameter of Topic Filter protocol) they are interested in.
| Kotva | ||||
|---|---|---|---|---|
|
- QoS_0 - PUBLISH message is not being confirmed, it may be lost
- QoS_1 - PUBLISH message is being confirmed by other side's PUBACK, it may be duplicate
- QoS_2 - PUBLISH message is being confirmed by other side's PUBREC and that which is then confirmed back by the PUBREL message and that one by a final by the PUBCOMP message.
The level of confirmation of the messages sent by the D2000 KOM process is defined by the parameter of protocol parameter Publish QoS protocol . D2000 KOM process considers the writing of the output tag to be successfully terminated finished depending on the QoS:
- QoS_0 - after successful data sending through the data is successfully sent via TCP connection
- QoS_1 - after receiving PUBACK
- QoS_2 - after receiving PUBCOMP
...
The MQTT communication starts with the CONNECT message sent by client (D2000 KOM). Message contains (User Name), Password and other parameters, from which it is possible to set uponly Clean Session Flag and Client ID can be modified (parameter Will Flag is not used, as well as Will QoS and WillRetain Will Retain, parameter Keep Alive is set to 0). Server replies with CONNACK message with a return code that contains information about the connection success informationof connect operation.
Then client sends SUBSCRIBE message with filter of topics (Topic Filter parameter), specifying which are of interest topics it is interest in, and with the required maximum level of confirmation (parameter Subscribe QoS).
The server responds with a return code that contains an information on about the success and maximum QoS that was assigned to the requested topics.
That is followed by a common Then follows a phase of communication, during which both the client and the server send PUBLISH messages (the client with any topic, the server with topics relating to the filter of topics of the received SUBSCRIBE message) and confirm them according to the value of the QoS parameter of the received PUBLISH messages.
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 towards with the MQTT server www.TheThings.network.
...
| Parameter | Description | Unit / size | Default value | ||||||
|---|---|---|---|---|---|---|---|---|---|
| Enabling Activates detailed statements debug information about sending and receiving values. | YES/NO | NO | ||||||
| User name used in CONNECT message to connect to the MQTT server. | - | |||||||
| Password used in 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 a mask for multiple levels. Examples of filter: a/b , level1/+ , # , +/+/+/up | - | # | ||||||
| The desired maximum level of validation (QoS) sent within the SUBSCRIBE message. The MQTT server can then send PUBLISH messages with such or lower level of validation confirmation (but not higher). PUBLISH messages sent by the MQTT server will be validated confirmed by the D2000 KOM process according to the level of validation confirmation specified in them. The higher the level of validation 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. | - | |||||||
| Parameter Clean Session Flag of the CONNECT message. The No value means that the server uses the current session state (connection) - e. g. after collapse and recovery of the TCP connection. This means that all unverified unconfirmed PUBLISH messages are sent with QoS_1 and QoS_2 are resent (and optionally also QoS_0, depending on the implementation). The Yes value means that the session is re-created and any unverified unconfirmed PUBLISH messages are not repeated. | 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 OUT_DATA address. The higher the confirmation level, the more messages between the client and server is sent are exchanged (1 for QoS_0, 2 for QoS_1 and 4 for QoS_2). | QoS_0 QoS_1 QoS_2 | QoS_0 | ||||||
| If the MQTT server did not send a any message during the specified time interval, the D2000 KOM process sends a PING request and waits for a PING response response (until time Reply Timeout). A value of 0 turns off sending the PING request messages. Parameter allows detection of TCP connection collapsefailure. | sec | 60 | ||||||
| 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 retrieve any read a complete message (and only part of it is retrievedread), the D2000 KOM process declares an error, closes the connection, and opens it again. Value 0 turns off the timeout. | sec | 20 | ||||||
| Timeout waiting at of a single reading of from TCP connection. D2000 KOM repeats reading of spontaneous data Max. Wait Retry times and if no data is loadedread, the timeout reading is declared and the reading is completed 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 D2000 KOM process for writing at the expense of a higher CPU load when the MQTT server has no data. | sec | 0.100 | ||||||
| Number of repetitions of reading from TCP connection. See description of the Wait Timeout parameter. | - | 3 |
| Kotva | ||||
|---|---|---|---|---|
|
...
- Communication protocol "MQTT Client Protocol".
- Station address: station address is a particular topic (Topic) or a # character representing # representing all topics. If there is a station with address # on the line, all messages are directed to its I/O tags. Otherwise, the searched KOM looks for a station with the address corresponding to the Topic field in the PUBLISH message is received from the MQTT server.
Note: in the station address, there are not yet supported characters of mask "+" in sense of Topic Filter parameter station address doesn't support wildcard characters "+" corresponding to mask of Topic Filter parameter (yet). - Polling parameters on the Time parameters tab - recommended value is Delay=0.
...
| Type of I/O tag | Address | Description | ||||||
|---|---|---|---|---|---|---|---|---|
| I/O tags for reading data sent by MQTT server through PUBLISH message. Note: values of I/O tags are set by D2000 KOM process in the order IN_TOPIC, IN_DATA and IN_ID. It is not necessary for 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 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 MQTT server sends also messages with the QoS_0 level of validation and the ACK_ID I/O tag is configured, then we recommend to activate activate the option New value when changing time option in the Filter tab, so that repeated writing of the value 0 will cause a generation of new value that differs only with time stamp to be generated with a different time stamp. | ||||||
| I/O tag to confirm a receiving of received data of to 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 value of the IN_ID tag. Not until Only after then 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) to the IN_TOPIC, IN_DATA, and IN_ID (if it has been received in the meantime). In case of the QoS_0 level of validationconfirmation, it is therefore necessary to re-enter repeatedly set the value of 0 into 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_IDare set I/O tags immediately after the PUBLISH message is publishedreceived and processed. Note: for the messages received with the QoS_0 level of validation, no confirmation of is sent to MQTT server is sent, only the values of the next received PUBLISH message received will be published. | ||||||
| I/O tags for sending values to the MQTT server through PUBLISH message. Note: in order for the D2000 KOM process to send the PUBLISH message messages to the MQTT server, both I/O tags must be defined within one station. | ||||||||
| TxtO |
| Topic within of the PUBLISH message being sent. | ||||||
| TxtO |
| Data (Payload) within of the PUBLISH message being sent. Note: sending the message is carried performed out as a response result of writing to the entry into the OUT_DATA point 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). | ||||||
...