1.79 Mqtt - Driver for Data Exchange with MQTT Protocol Brokers

Driver Use

The Mqtt driver is used to exchange data between the Asix system and the MQTT protocol brokers. Version 3.1.1 of the MQTT protocol is supported.

The MQTT protocol is designed for transmission for devices that do not require high bandwidth. This protocol is used for machine-to-machine connections, on the Internet of Things (IoT), in mobile devices and where savings in bandwidth and energy are required.

Declaration of Transmission Channel

Declaration of the transmission channel operating according to the MQTT protocol requires adding the channel  to the Current  data module with the following parameters:

Standard tab:

Name: logical name of the transmission channel

Driver: Mqtt

Tab Mqtt / Channel parameters:

MQTT broker address          - address of the MQTT protocol broker. Uncrip connection (tcp: // address prefix) and encrypted (ssl: // address prefix) are supported.

Sample addresses:

tcp: //iot.eclipse.org: 1883

ssl: //iot.eclipse.org: 8883

Parameters of the Channel

Channel parameters declared on the tabs: Channel parameters and Channel parameters 2:

R   Client ID

Meaning                                 - the unique client name of the MQTT protocol; some brokers allow the name to be empty.

R   Certification authority file

Meaning                                 - file in pem format.

R   Authorization

User Name                      - name of the broker's user,

Password                          - user password.

R   Quality of service

Meaning                                 - possible values:

0 - Send without confirmation

1 - Send with confirmation (default value)

2 - Providing confirmation of sending

Note to options. If a large number of transmissions is performed, especially sending data to a broker, use the level 0, because it is much more efficient than levels: 1 and 2.

R   Table separator

Meaning                           - separator of elements of the board; applies to data transfer in text mode.

The default value                    - comma.

R   Decimal separator

Meaning                                 - applies to data transfer in text mode.

The default value                    - period.

Declaration of Variables

The MQTT driver requires for each variable to specify the address of the data packet to be retrieved from the MQTT broker and the way of interpreting this data packet. In the further part of the documentation, the address of the data packet will be called Topic. The data in the package can be binary coded, text-based or in Json format.

·        Binary-encoded data

Data received from the broker is treated as a binary representation of the Asix application variable. The number of bytes of the data packet can not be less than the size of the variable. Redundant bytes are ignored.

The address of the binary-encoded data has the following form:

bin: Topic + ValueNo + TimestampNo

ValueNo and TimestampNo elements are optional.

Data of packet data is read from the zero byte, unless ValueNo is given in address - which means offset in bytes.

If TimestampNo is specified in the address , it means that the data of the time stamp is offset in bytes. The time stamp must be of 4 bytes and include Unix time - the number of seconds since the beginning of 1970 UTC. If TimestampNo is not given, the time of reception of the data package from the MQTT broker will be a time stamp.

Only numeric variables are supported in binary coding. Text and table variables are not supported. The recording  is supported only if the address does not use the phrase ValueNo and TimestampNo.

Examples of addresses:

bin:machine1/measurement1 - read the data packet machine1/ measurement1 and use it from byte 0 as the variable value;

bin:machine1/measurement1+10 - read the machine data packet1/measurement1 and use it from byte 10 as the variable value;

bin:machine1/measure1+0+4 - read the data packet machine1/measure1 and use it from byte 0 as the variable value and from byte 4 as the variable time stamp.

·        Text-encoded data

Data received from the broker is treated as a textual representation of the Asix application variable.

As a decimal separator, the dot is used by default. As an array element separator, a comma is used by default. The separator characters can be changed in the channel options. The number of array elements can not be less than the number of array variable elements.

Numeric, text and table variables are supported. Transfer of time stamp is not supported. As a time stamp, the time of receipt of a data packet from the MQTT broker is assumed.

The address of the text-coded data has the following form:

text:Topic

By default, it is assumed that the text uses ANSI encoding. Alternatively, you can use the prefix 'text/utf8' for text that uses UTF8 encoding or 'text/utf16' for text that uses UTF16 encoding.

Example of the scalar variable address:

text:machine1/measurement1 - read the data package machine1/measurement1 and treat it as a textual representation of the variable value.

Examples of the array variable address:

text:machine1/measurements - read the data package machine1/measurement1 and treat it as a textual representation of array of numbers and use the array as the variable values. 

·        Data encoded in Json format

Data received from the broker is treated as an object or array saved in JSON format.The indicated element of an object or array is retrieved as a value or a variable time stamp.

The data address encoded in the Json format has the following form:

json:topic+ValuePath+TimestampPath

Json is the default data format and the prefix "json:" may be omitted.

ValuePath means the location of the data fragment that should be used as the value of the variable. If it is omitted, the data packet should contain an array and the Asix application variable must also be an array.

TimestampPath means the location of the data fragment that should be used as a variable time stamp. The path to the time stamp is optional and if not specified, the time of reception of the data packet from the MQTT broker is taken as the time stamp.

If the path to the variable value is not found, then the variable will have the quality bad. Similarly, when null is specified as the variable value. For table variables, the bad quality can also be an empty array. The number of array elements can not be less than the number of array variable elements.

Examples of variable addresses:

json:machine1/measurement1+value - read the data packet Machine1/Measurement1 and treat it as a representation of the object, retrieve the value of the field value and treat it as a variable value. For numeric variables, the value field should contain a number, text variables should contain text, and for table variables should contain an array of numbers.

json:machine1/measurement1+value+time - as above, additionally the value of the time field is retrieved and treated as a variable time stamp. The time stamp must be given in the ISO 8061 or Unix format.

json:machine1/measurements+values.temp1 - read the data packet machine1/measurements and treat it as the representation of the object, retrieve from the object the value ​​of temp1 of the values field and treat it as a variable value.

json:machine1/measurements+values​​[12] - read the data packet machine1/measurements and treat it as the representation of the object, retrieve the element number 12 of the array from the values field and treat it as a variable value.

json:machine1/measurements+[12] - read the data packet machine1/measurements and treat it as a representation of the array, retrieve the item number 12 of the array and treat it as a variable value.

json:machine1/measurements – read the data package machine1/measurements, treat it as a representation of an array and use it as a variable value. This address can only refer to an array variable.