Skip to main content

22 MQTT

Introduction

MQTT (short for MQ Telemetry Transport) is an open OASIS and ISO standard (ISO/IEC PRF 20922) lightweight, publish-subscribe network protocol that transports messages between devices. The protocol usually runs over TCP/IP, although its variant, MQTT-SN, is used over other transports such as UDP or Bluetooth. It is designed for connections with remote locations where a small code footprint is required or the network bandwidth is limited.

The broker acts as a post office, MQTT doesn’t use the address of the intended recipient but uses the subject line called “Topic”, and anyone who wants a copy of that message will subscribe to that topic. Multiple clients can receive the message from a single broker (one-to-many capability). Similarly, multiple publishers can publish topics to a single subscriber (many to one).

Each client can both produce and receive data by both publishing and subscribing, i.e. the devices can publish sensor data and still be able to receive the configuration information or control commands. This helps in both sharing data and managing and controlling devices.

With MQTT broker architecture the devices and applications become decoupled and more secure. MQTT might use Transport Layer Security (TLS) encryption with a user name, password-protected connections, and optional certifications that require clients to provide a certificate file that matches the server’s. The clients are unaware of each other's IP address.

The broker can store the data in the form of retained messages so that new subscribers to the topic can get the last value straight away.

The main advantages of an MQTT broker are:

  • Eliminates vulnerable and insecure client connections
  • Can easily scale from a single device to thousands
  • Manages and tracks all client connection states, including security credentials and certificates
  • Reduced network strain without compromising the security (cellular or satellite network)

Each connection to the broker can specify a quality of service measure. These are classified in increasing order of overhead:

  • At most once - the message is sent only once and the client and broker take no additional steps to acknowledge delivery (fire and forget).
  • At least once - the message is re-tried by the sender multiple times until acknowledgement is received (acknowledged delivery).

  • Exactly once - the sender and receiver engage in a two-level handshake to ensure only one copy of the message is received (assured delivery).

Using WCC Lite as an MQTT Client

MQTT serves as an alternative for protocols conforming to IEC standards, for example, to send data to a cloud infrastructure that supports MQTT instead of IEC-60870-5-104.

WCC Lite supports MQTT messaging compatible with MQTT v3.1 standard (starting from version v1.4.0). Such messaging is possible via mapping of Redis and MQTT data therefore data can be transmitted from any protocol that is supported by WCC Lite.

All standard functions, except for data encryption, are supported. Encrypted messages are not supported yet, therefore to ensure security a user would have to use a VPN service. A user can choose from three different Quality of Service levels, select if messages are to be retained, authenticate users and optionally send Last Will messages.

To configure WCC Lite a user can fill in the needed parameters in Excel configuration. These parameters are shown in the two tables below.

Table. MQTT parameters for the Devices tab

Parameter

Type

Description

Required

Default value

(when not specified)

Range

Min

Max

name

string

User-friendly device name

Yes


device_alias

string

Device alias to be used in the configuration

Yes


enable boolean

Enabling/disabling of a device

No 0 0 1
protocol

string

Selection of protocol

Yes
MQTT
ip

string

MQTT broker IP address/Domain name selection

Yes


port integer

MQTT broker port selection

No 1883

enable_threshold boolean

A parameter to determine if identical values should not be sent multiple times in a row.

No 1 0 1
mqtt_qos integer

MQTT Quality of Service for the message as in standard

No 0 0 2
mqtt_retain boolean

Selecting if the MQTT broker should retain the last received messages

No 0 0 1
username

string

MQTT user name

Yes


password

string

MQTT user password Yes


auth

string

Selecting if TLS should be used No

tls
ca_certificate

string

Certificate authority file for TLS connection

Yes

(If auth=tls)




client_certificate

string

Client certificate file for TLS connection

Yes

(If auth=tls)




client_key

string

The private key that corresponds to the client certificate for TLS connection

Yes

(If auth=tls)




use_last_will boolean

Selecting if MQTT should use the Last Will and Testament functionality

(Default: False)

No 0 0 1
last_will_topic

string

Topic to which an MQTT message would be sent if the device abruptly disconnected the message broker

Yes

(If use_last_will=True)




last_will_message

string

Message to be sent over MQTT if the device abruptly disconnected message broker

No


last_will_qos 

integer

MQTT Quality of Service selection as in standard

No 0 0 2

last_will_retain

boolean

Selecting if the MQTT broker should retain the last will message

No 0 0 1

client_id

string

User-friendly name for client ID

No


To map the signal to send through the MQTT client, it should have its device_alias and signal_alias mapped to source_device_alias and source_signal_alias respectively.

Table. MQTT parameters for the Signals tab

Parameter

Type

Description

Required

Default value

(when not specified)

Range

Min

Max

signal_name string

User-friendly signal name

Yes

 



device_alias string

Device alias from a Devices tab

Yes


signal_alias string

Unique signal name to be used

Yes


source_device_alias string

device_alias of a source device

Yes


source_signal_alias string

signal_alias of a source signal

Yes


enable boolean

Enabling/disabling of an individual signal

No 1 0 1
log  integer

Allow signal to be logged. Log signal with 1 and no logging with 0.

No 0



topic string

Topic name to override the value built by default

No


periodic_update_ms integer

Signal value is published periodically according to the value set.

No - - -

MQTT data format

The format of a MQTT message is a bit different than Redis messages. Redis messages are supported as CSV strings: value, timestamp, flags (where value can be float, integer or nan; timestamp - Unix timestamp in milliseconds; flags contain additional information about a measurement). MQTT messages are supported as value, timestamp, and quality (where value can be float, integer or nan; timestamp - Unix timestamp in milliseconds; quality shows if a value is to be considered valid). Quality parts of a string are always equal to 1 except for Redis messages containing invalid (IV), non-topic (NT) and/or overflow (OV) flags.

As mentioned, the MQTT client acts as an adapter between Redis and MQTT, therefore data from the topic in Redis is written to a topic in MQTT. Therefore mqtt-client has to know the mapping table before starting. This table is saved at /etc/elseta-mqtt.json. Every Redis topic name is constructed as tag/[device_alias]/[signal_alias]/[direction]. Prefix tag/ is always used before the rest of the argument. device_alias and signal_alias represent columns in Excel configuration. Direction can have one of four possible values - rout, out, in, rin; all of which depend on the direction data is sent or acquired protocol-wise. The same Redis topic structure is preserved in MQTT by default making it easier to find matching signals, however, as no recalculation is done by MQTT and only PUBLISH messages are now supported, only Redis signals within direction have their MQTT mappings.

A user can create and select his topic name in Excel configuration, in the topic column. As no recalculation is done by MQTT and only PUBLISH messages are now supported, only Redis signals within in direction have their MQTT mappings.

Debugging a MQTT protocol

If the configuration for MQTT is set up, a handler for the protocol will start automatically. If the configuration is missing parameters or contains errors, the protocol will not start. It is done intentionally to decrease unnecessary memory usage.

MQTT Client command line debugging options

mqtt-client


-h [ –help ] Display help information
-c [ –config ] Configuration file location (default - /etc/elseta-mqtt.conf) 
-V [ –version ] Show version
-d<debug level> [ –debug ] Set debugging level 
-r [ –redis ] Show REDIS output
-m [ –mqtt ] Show MQTT output

If the MQTT Client does not work properly (e.g. no communication between devices, data is corrupted, etc.), a user can launch a debug session from the command line interface and find out why the link is not functioning properly.

To launch a debugging session, a user should stop mqtt-client process and run mqtt-client command with respective flags as was shown above.