MQTT is an open standard application layer protocol for Message Oriented Middleware. MQTT is often used with a Brokerthat relays messages between applications that cannot communicate directly.

Publisherssend MQTT messages to MQTT brokers. Subscriberssubscribe to MQTT brokers for messages. A Brokermay persist messages so they can be delivered even if the Subscriberis not online. Brokersmay also allow messages to be sent to multiple Subscribers.

The MQTT protocol defines a binary protocol used to send and receive messages from and to topics. The body is an opaque binary blob that can contain any data serialized using an encoding chosen by the application.

There are currently two versions of the MQTT protocol in use, version 3.1.1 and version 5.0. Version 5.0 expands on version 3.1.1 by adding support for connection and message properties. This enables advanced routing scenarios at the broker level in particular when using encrypted payloads.

This document defines two possible encodings for the message body: the binary encoded DataSetMessagedefined in 7.2.2and a JSON encoded DataSetMessagedefined in 7.2.2.6.4.7.

MQTT version 3.1.1 does not provide a mechanism for specifying the encoding of the MQTT message which means the Subscribersneed to be configured in advance with knowledge of the expected encoding. As a consequence, Publishersshould only publish NetworkMessagesusing a single encoding to a unique MQTT topic name.

MQTT version 5.0 adds the encoding and the message type information to the message and connection header and therefore allows Subscribers to detect the encoding and the message mapping. No additional information is added to the meta data messages.

MQTT Publisher and Subscriber transport profiles for full and minimal support are defined in OPC 10000-7.

Message security is primarily provided by a TLS connection between the Publisheror Subscriberand the MQTT server; however, this requires that the MQTT server be trusted. For that reason, it may be necessary to provide end-to-end message security. Applications that require end-to-end message security with MQTT need to use the UADP NetworkMessagesand binary message encoding defined in 7.2.2. JSON encoded message bodies need to rely on the security mechanisms provided by MQTT and the MQTT broker.

The syntax of the MQTT transporting protocol URL used in the Addressparameter defined in 6.2.7.3has the following form:

mqtts://<domain name>[:<port>][/<path>]

The protocol prefix mqtts provides transport security. The default port is 8883.

mqtt://<domain name>[:<port>][/<path>]

The protocol prefix without transport security is mqtt. The default port is 1883.

wss://<domain name>[:<port>][/<path>]

The protocol prefix for MQTT over secure Web Sockets is wss. The default port is 443.

MQTT supports the use of Username/Password authentication in the initial CONNECT packet. Aside from password credentials, implementations can use this mechanism to pass any form of secret, such as an authentication token. However, if CONNECT authentication is used, the connection should be secured.

MQTT version 5.0 also supports enhanced authentication, whereby clients can specify the desired SASL authentication method during initial CONNECT and finish the secret exchange with the broker using subsequent AUTH packets, or reauthenticate on an existing connection.

Authentication shall be performed according to the configured AuthenticationProfileUriof the PubSubConnection, DataSetWriterGroup, DataSetWriteror DataSetReaderentities.

If no authentication information is provided in the form of ResourceUriand AuthenticationProfileUri, SASL Anonymous is implied.

If the authentication profile specifies SASL PLAIN authentication, a separate connection for each authentication setting is required.

The MQTT transport mapping for version 3.1.1 does only support the connection property ClientID using a KeyValuePair. Any other configured setting in the connection properties shall be silently discarded.

MQTT version 5.0 allows Publishersand Subscribersto provide MQTT connection properties as part of opening the connection.

The connection properties apply to any connection created as part of the PubSubConnection, or subordinate configuration entities, such as the WriterGroupand the DataSetWriter.

The properties are defined through the KeyValuePairarray in the ConnectionProperties. The NamespaceIndexof the QualifiedNamein the KeyValuePairshall be 0. The Nameof the QualifiedNameis constructed from a prefix “connection” followed by a hyphen and the MQTT property name with the following syntax.

Name = connection-<MQTT property name>

Table 166defines the MQTT standard connection properties.

Table 166– OPC UA MQTT standard connection property configuration

MQTT property name

OPC UA DataTypes

MQTT data types

ClientID

String

UTF-8 Encoded String

Receive Maximum

UInt16

Two Byte Integer

Maximum Packet Size

UInt32

Four Byte Integer

Session Expiry Interval

UInt32

Four Byte Integer

Topic Alias Maximum

UInt16

Two Byte Integer

Request Response Information

Boolean

Byte

Request Problem Information

Boolean

Byte

Any name not in the Table 166is assumed to be a MQTT User Property.

When a field is added to the header as a MQTT User Property the value is encoded as UTF-8 encoded String.If the value is not a String, then it is encoded using the non-reversible OPC UA JSON Data Encodingrules in OPC 10000-6.

The BrokerTransportQualityOfServicevalues map to MQTT publish and subscribe QoS settings as follows:

  • AtMostOnce and BestEffort is mapped to MQTT QoS 0.
  • AtLeastOnce is mapped to MQTT QoS 1.
  • ExactlyOnce is mapped to MQTT QoS 2.

If the KeepAliveTimeis set on a WriterGroup, a value slightly higher than the configured value of the group in seconds should be set as MQTT Keep Alive ensuring that the connection is disconnected if the keep alive message was not sent by any writer in the specified time. If multiple WriterGroupsare configured, the group with the highest KeepAliveTimesetting is used for the calculation.

The implementation chooses packet and message size limits depending on the capabilities of the OS or of the capabilities of the device the application is running on. They can be made configurable through configuration model extensions or by other means.

The default setting for the MQTT RETAIN flag is false, except for metadata messages published to the MetaDataQueueNameas described in 6.4.2.5.6.

The MQTT version 3.1.1 protocol does not support message headers. Any promoted field or additional fields defined on the WriterGroupor DataSetWriterother than RETAIN are not sent as MQTT message properties.

MQTT version 5.0 defines a number of standard message properties. These include properties explicitly defined in the MQTT specification, as well as the MQTT User Property which is a key-value pair of UTF-8 strings. The MQTT User Property is intended to provide a means of transferring application layer name-value tags whose meaning and interpretation are known only by the application programs responsible for sending and receiving them. They are used here to specify PubSubproperties not directly supported by the MQTT protocol.

Table 167describes how these properties shall be populated when a MQTT version 5.0 message is constructed.

Table 167– OPC UA MQTT message properties

MQTT property name

MQTT property type

MQTT property value

UAMessageType

User Property

Valid values are ua-data or ua-metadata.

Content Type

Standard

The MIME type for the message body.

The MIME types are specified in the message body subsections 7.3.5.8.2and 7.3.5.8.3.

The MQTT message header shall include additional fields defined on the WriterGroupor DataSetWriter through theKeyValuePair array in theWriterGroupProperties andDataSetWriterProperties. TheNamespaceIndex of theQualifiedName in theKeyValuePair shall be 0. The Nameof the QualifiedNameis constructed from a message prefix and the MQTT property name with the following syntax.

Name = message-<MQTT property name>

The Name of the key in the KeyValuePair shall have a prefix “message” followed by a hyphen and the MQTT property name.

Table 168defines the MQTT standard message properties.

Table 168– OPC UA MQTT standard message property configuration

MQTT property name

OPC UA DataTypes

MQTT data types

Description

RETAIN

Boolean

RETAIN bit in the header

Response Topic

String

UTF-8 Encoded String

Not available as message property for MQTT 3.1.1.

Correlation Data

ByteString

Binary Data

Not available as message property for MQTT 3.1.1.

Message Expiry Interval

UInt32

Four Byte Integer

Not available as message property for MQTT 3.1.1.

Content Type

String

UTF-8 Encoded String

Configuration option for the MIME.type of the message body for MQTT 3.1.1 and 5.0.

Not available as message property for MQTT 3.1.1.

Any name not in the Table 168is assumed to be a MQTT User Property.

When a field is added to the header as a MQTT User Property the value is encoded as UTF-8 encoded String.If the value is not a String, then it is encoded using the non-reversible OPC UA JSON Data Encodingrules in OPC 10000-6. Promoted fields can only be sent for fields which are assumed to be a MQTT User Property and if the NetworkMessage contains only one DataSetMessage. The MQTT message header shall include additional promoted fields of the DataSetas a list of MQTT User Property name-value pairs. DataSetfields with the PromotedFieldflag set in the FieldMetaData fieldFlags are copied into the MQTT header. TheFieldMetaData Structure is defined in 6.2.3.2.3. For a UADP message mapping the promoted fields are also included in the UADP NetworkMessage. Promoted fields shall always be included in the header even if theDataSetMessage body is a delta frame and the DataSetfield is not included in the delta frame. In this case the last known value is sent in the header.

When sending a MQTT Version 5.0 message the UAMessageTypeproperty shall be set to uadata for data messages or ua-metadata for metadata messages.

A JSON body is encoded as defined for the JSON message mapping defined in 7.2.2.6.4.7.

When sending a MQTT Version 5.0 message the MQTT ContentTypeproperty shall be set to application/json when sending uncompressed JSON messages.

JSON messages can become quite large. In order to save bandwidth and to reduce message size, on MQTT Version 5.0 the MQTT ContentType property allows to select a compression type as encoding for a JSON message.

When sending a gzip (RFC 1952) compressed JSON message on MQTT Version 5.0 the MQTT ContentType property shall be set to application/json+gzip.

A UADP body is encoded as defined for the UADP message mapping defined in 7.2.2.

It is expected that the software used to receive UADP NetworkMessagecan process the body without needing to know how it was transported.

If the encoded MQTT message size exceeds the Brokerlimits, it is broken into multiple chunks as described in 7.2.2.4.4.

When sending such message over MQTT Version 5.0 the ContentTypeproperty shall be set to application/opcua+uadp.

It is recommended that the MetaDataQueueNameas described in 6.4.2.5.5is configured as a sub-topic of the related QueueNamewith the name “$Metadata”. The MQTT RETAIN flag shall be set for metadata messages.