Subclause 7.3 lists the standard protocols that have been selected for this document and their possible combinations with message mappings.

OPC UA UDP is a simple UDP based protocol that is used to transport UADP NetworkMessages.

A PubSubConnection for UDP shall have a unique Address across all PubSubConnections of an OPC UA Application.

If the Address specifies a domain name then the resolution to an IP address requires access to a domain name resolution service (e.g., the DNS protocol) that maps the domain name onto a usable network address. OPC 10000-7 defines Profiles for different name resolution protocols that Publisher or Subscriber may support.

For OPC UA UDP it is recommended to limit the MaxNetworkMessageSize plus additional headers to a MTU size. The number of frames used for a UADP NetworkMessage influences the probability that UADP NetworkMessages get lost.

Note: The MaxNetworkMessageSize that fits into one MTU is maximum 1472 Byte for IPv4 and 1452 Byte for IPv6. The additional headers have a size of 22 Byte for Ethernet, 20 Byte for IPv4 or 40 Byte for IPv6 and 8 Byte for UDP. This is based on IETF RFC 8200 for IPv6, RFC 791 for IPv4 and RFC 768 for UDP.

For OPC UA UDP the MaxNetworkMessageSize plus additional headers shall be limited to 65535 Byte.

The transport of a UADP NetworkMessage in a UDP packet is defined in Table 195.

Table 195 – UADP message transported over UDP

Name

Description

Frame Header

The frame header.

IP Header

The IP header for the frame contains information like source IP address and destination IP address. IPv4 and IPv6 addresses can be used. The size of the IP header depends on the used version.

UDP Header

The UDP header for the frame contains the source port, destination port, length and checksum. Each field is two byte long. The total size of the UDP header is 8 byte.

UADP NetworkMessage

The UADP NetworkMessage is sent as UDP data.

Frame Footer

The frame footer.

The IANA registered IPv4 multicast address for discovery is 224.0.2.14. It shall only be used for OPC UA discovery purposes. The recommended port for discovery is 4840. Therefore the default DiscoveryAddress has the following form:

opc.udp://224.0.2.14

The default DiscoveryMaxMessageSize for UDP is 4096 bytes.

The transport protocol URL for UDP multicast and broadcast communication is configured on a PubSubConnection for Publisher and Subscriber. The Address parameter for a PubSubConnection is defined in 6.2.7.3.

The Url field in the Address is used as destination address for NetworkMessages sent as UDP datagram. The Address is also used to receive UDP datagrams from the multicast IP address. All DataSetWriters and DataSetReaders that send to and receive from the multicast IP address shall be configured on one PubSubConnection. The Address parameter for WriterGroup datagram TransportSettings shall be null. If an Address is configured on a WriterGroup, the WriterGroup PubSubState shall be Error. The NetworkInterface field in the Address is required if more than one network interface is available.

The syntax of the UDP transport protocol URL used in the Address has the following form:

opc.udp://<address>[:<port>]

The address is either an multicast or broadcast IP address or a registered name like a domain name that can be resolved to a multicast or broadcast IP address.. It is the destination of the UDP datagram.

The IANA registered OPC UA port for UDP communication is 4840. This is the default and recommended port for broadcast and multicast communication. Alternative ports may be used.

It is recommended to use switches with IGMP and MLD support to limit the distribution of multicast traffic to the interested participants.

Note: The Internet Group Management Protocol (IGMP) is a standard protocol used by hosts to report their IP multicast group memberships for IPv4 and needs to be implemented by any host that wishes to receive IP multicast datagrams. IGMP messages are used by multicast routers to learn which multicast groups have members on their attached networks. IGMP messages are also used by switches capable of supporting “IGMP snooping” whereby the switch listens to IGMP messages and only sends the multicast NetworkMessages to ports that have joined the multicast group. The corresponding protocol for IPv6 is the Multicast Listener Discovery (MLD).There are different versions of IGMP and MLD: - IGMP V1 is defined in IETF RFC 1112. - IGMP V2 is defined in IETF RFC 2236. - IGMP V3 is defined in IETF RFC 3376.

- IGMP V3 and MLD V2 are defined in IETF RFC 4604.

IETF RFC 2236 and IETF RFC 3376 discuss host and router requirements for interoperation with older IGMP versions.If OPC UA devices make extensive use of IP multicast for UDP transport, consistent IGMP and MLD usage by OPC UA devices is essential in order to create well-functioning OPC UA Application networks.

OPC UA Applications shall issue an IGMP membership report message (V1, V2 or V3 as appropriate) for IPv4 or a MLD membership report message for IPv6 when enabling a PubSub connection on which they will receive UDP multicast NetworkMessages.

For UDP unicast, the address information for the Subscriber is configured on the PubSubConnection and the address information for the Publisher is configured on the WriterGroup.

The receive port for UDP unicast communication is configured on a PubSubConnection. The Address parameter for a PubSubConnection is defined in 6.2.7.3. All NetworkMessages for one port are received through one PubSubConnection. The filtering and assignment of NetworkMessages for the Subscriber is done based on the PublisherId. The hostname for the Url in the PubSubConnection Address parameter is set to ‘localhost’ since the source address is not used for filtering. The NetworkInterface field in the Address is not required and is only configured if the Subscriber should listen only on the configured interface. If the NetworkInterface is null or empty, the Subscriber should listen on all interfaces.

The syntax of the Url field in the PubSubConnection Address parameter has the following form:

opc.udp://localhost[:<port>]

The destination address is configured on the datagram TransportSettings of a WriterGroup. The Address parameter for a WriterGroup datagram TransportSetting is defined in 6.4.1.3.4. The Address parameter for WriterGroup datagram TransportSettings shall be configured. If no Address is configured on a WriterGroup, the WriterGroup PubSubState shall be Error. The NetworkInterface field in the Address is not required and should be null or empty and shall be ignored.

The syntax of Url field in the WriterGroup datagram TransportSettings Address parameter has the following form:

opc.udp://<host>[:<port>]

The host is either an unicast IP address or a registered name like a hostname or domain name that can be resolved to a unicast IP addresses. The IP address and the port are the destination of the UDP datagram.

The syntax is also used for the ResponseAddress in the ActionHeader of ActionRequest messages. If the ResponseAddress is not provided, the sender IP address and port of the ActionRequest is used.

The IANA registered OPC UA port for UDP communication is 4840. This is the default and recommended port for unicast communication. Alternative ports may be used.

The DTLS option is provided mainly for use in high speed device to device communication where hardware may be particularly optimized for DTLS (for either the DTLS handshake and/or the DTLS record layer). This option supports DTLS 1.3, previous versions of DTLS are not supported. Note in DTLS application data (OPC UA PubSub) and handshake messages are multiplexed on the same channel which could have an impact on applications requiring a high level of determinism. Certificates are required for the DTLS Transport, and in order to manage these certificates the DTLS Transport requires the OPC UA GDS CertificateManager. Pull Management or Push Management of certificates shall be supported by any Publisher or Subscriber that supports the DTLS Transport (see Part 12 for more information on the CertificateManager). DTLS makes use of the same Certificates and Trust List that are used for OPC UA Client Server communication, as well as the same procedure for validation of the certificates (see Part 4 “Determining if a Certificate is Trusted” for more information on this). That is, the DefaultApplicationGroup Object is used as the Certificate and TrustList for DTLS communication. A separate certificate group may optionally be used for the DTLS transport. See Part 7 for information on what certificate types may be used for DTLS.

DTLS is not supported for broker-based PubSub transports.

When DTLS Transport is used the DTLS handshake sets up a secure session prior to the PubSub data exchange. In this case either the Subscriber or the Publisher acts as the DTLS Client, with the other one acting as the DTLS Server. Once a DTLS session is established between two endpoints PubSub data is then sent. Different Reader/Writer groups will use the same DTLS session to send data betweent two endpoints. DTLS allows for authentication of just the server or of the client and the server; both cases are supported and can be configured via the VerifyClientCertificate parameter. The high level data flow for a Subscriber acting as the DTLS client is shown in Figure 39 and Figure 40 shows the high level data flow for a Publisher acting as the DTLS client. Note these figures are shown for illustrative purposes, precise details of messages may differ depending on configuration options.

image042.png

Figure 39 – Subscriber as DTLS Client

image043.png

Figure 40 – Publisher as DTLS Client

Addressing for DTLS is similar to UADP unicast.

The receive address for DTLS unicast communication is configured on a PubSubConnection. The Address parameter for a PubSubConnection is defined in 6.2.7.3.

The syntax of the URL used in the PubSubConnection Address parameter has the following form:

opc.dtls://localhost:<port>

The send address is configured on the datagram TransportSettings of a WriterGroup. The Address parameter for a datagram TransportSetting is defined in 6.4.1.3.4.

The syntax of the URL used in the datagram TransportSettings Address parameter has the following form:

opc.dtls://<host>:<port>

The host is either a unicast IP address or a registered name like a hostname or domain name that can be resolved to a unicast IP address. The IP address and the port are the destination of the DTLS UDP datagram.

The IANA registered OPC UA port for PubSub over DTLS is 4843. This is the default and recommended port for any PubSub communication using DTLS. Alternative ports may be used.

The DTLS transport does not support multicast of PubSub, and therefore can only be used for unicast communication. If multicast is needed other transports should be used. By definition the DTLS transport is only providing transport security, no notion of user level or application level security is provided. There are other OPC UA mechanisms which provide this, but by itself DTLS does not provide security at the user or application layer.

The DTLS transport supports the ability to use different cipher suites for a given PubSub Connection. This is configured via the ConnectionProperties of the PubSubConnectionDataType structure. A default value is configured in the ConfigurationProperties of the PubSubConfiguration. The properties are defined through the KeyValuePair array in the ConnectionProperties. The NamespaceIndex of the QualifiedName in the KeyValuePair shall be 0 for DTLS standard properties. The Name of the QualifiedName is constructed from a prefix and the DTLS property name with the following syntax. The intended use is for the DTLS client to include a single cipher suite in the handshake, which is the cipher suite to be used for that connection. To facilitate this, the DTLS server may have a list of cipher suites that are accepted if sent by a DTLS client in the handshake.

The NamespaceIndex of the QualifiedName in the KeyValuePair for properties defined in this document shall be 0. The Name of the QualifiedName is the property key from Table 202. The DataType of the Value in the KeyValuePair shall be the DataType defined in Table 202.

Table 202 formally defines the DTLS configuration properties

Table 196 – OPC UA DTLS standard properties

Key

DataTypes

Description

0:DtlsConnectionSettings

DtlsPubSubConnectionDataType

The DTLS configuration for the PubSubConnection or WriterGroup. The DtlsPubSubConnectionDataType is defined in 6.4.1.7.6.

0:DtlsClientCipherSuite

String

Cipher suite for the PubSubConnection or WriterGroup.

The ClientCipherSuite is defined in 6.4.1.7.1.

OPC UA Ethernet is a simple Ethernet based protocol using EtherType 0xB62C that is used to transport UADP NetworkMessages as payload of the Ethernet II frame without IP or UDP headers.

The syntax of the Ethernet transporting protocol URL used in the Address parameter defined in 6.2.7.3 has the following form:

opc.eth://<host>[:<VID>[.PCP]]

The host is a MAC address, an IP address or a registered name like a hostname. The format of a MAC address is six groups of hexadecimal digits, separated by hyphens (e.g. 01-23-45-67-89-ab). A system may also accept hostnames and/or IP addresses if it provides means to resolve it to a MAC address (e.g. DNS and Reverse-ARP).

The VID is the VLAN ID as number.

The PCP is the Priority Code Point as one digit number. This optional parameter is typically configured as part of the QoS settings on the network interface and not of the address.

The transport of a UADP NetworkMessage in an Ethernet II frame is defined in Table 197.

Table 197 – UADP message transported over Ethernet

Name

Description

Frame Header

The frame header with an EtherType of 0xB62C.

UADP NetworkMessage

The UADP NetworkMessage is sent as Ethernet payload.

Frame Footer

The frame footer.

For OPC UA Ethernet the MaxNetworkMessageSize and the DiscoveryMaxMessageSize plus additional headers shall be limited to an Ethernet frame size of 1522 Byte.

Note: The MaxNetworkMessageSize is typically 1500 Byte since the additional headers have a size of 22 Byte and it consists of 6 Byte destination address, 6 Byte source address, 2 Byte EtherType, 4 Byte frame check sequence and optionally 4 Byte VLAN tag. This is based on Q-tagged frames defined in IEEE Std 802.3-2018.

The IANA registered OPC UA EtherType for UADP communication is 0xB62C.

The Advanced Message Queuing Protocol (AMQP) is an open standard application layer protocol for Message Oriented Middleware. AMQP is often used with a Broker that relays messages between applications that cannot communicate directly.

Publishers send AMQP messages to AMQP endpoints. Subscribers listen to AMQP endpoints for incoming messages. If a Broker is involved it may persist messages so they can be delivered even if the subscriber is not online. Brokers may also allow messages to be sent to multiple Subscribers.

The AMQP protocol defines a binary encoding for all messages with a header and a body. The header allows applications to insert additional information as name-value pairs that are serialized using the AMQP binary encoding. The body is an opaque binary blob that can contain any data serialized using an encoding chosen by the application.

This document defines two possible message mappings for the AMQP message body: the UADP message mapping defined in 7.2.3 and a JSON message mapping defined in 7.2.4.6.9. AMQP Brokers have an upper limit on message size. The limit is defined by the AMQP field max-message-size. The mechanism for handling NetworkMessages that exceed the Broker limits depends on the MessageMapping. For MessageMappings that support chunking, the NetworkMessage shall be broken into multiple chunks. The chunk size plus the AMQP header should not exceed the AMQP max-message-size. For MessageMappings that do not support chunking, the NetworkMessages exceeding the maximum size mut be skipped. Diagnostic information for such error scenarios are provided through the Events of the type PubSubTransportLimitsExceedEventType defined in 9.1.13.2 and through the FailedTransmissions counter of the PubSubDiagnosticsWriterGroupType defined in 9.1.11.9.

Security with AMQP is primary provided by a TLS connection between the Publisher or Subscriber and the AMQP Broker, however, this requires that the AMQP Broker be trusted. For that reason, it may be necessary to provide end-to-end security. Applications that require end-to-end security with AMQP need to use the UADP NetworkMessages and binary message encoding defined in 7.2.4.4. JSON encoded message bodies rely on the security mechanisms provided by AMQP and the AMQP Broker.

The syntax of the AMQP transporting protocol URL used in the Address parameter defined in 6.2.7.3 has the following form:

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

The default port is 5671. The protocol prefix above provides transport security.

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

The default port is 5672.

The syntax for an AMQP URL over Web Sockets has the following form:

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

The default port is 443.

Authentication shall be performed according to the configured AuthenticationProfileUri of the PubSubConnection, DataSetWriterGroup, DataSetWriter or DataSetReader entities.

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

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

AMQP allows sending properties as part of opening the connection, session establishment and link attach.

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

The properties are defined through the KeyValuePair array in the ConnectionProperties WriterGroupProperties and DataSetWriterProperties. The NamespaceIndex of the QualifiedName in the KeyValuePair shall be 0 for AMQP standard properties. The Name of the QualifiedName is constructed from a prefix and the AMQP property name with the following syntax.

Name = <target prefix>-<AMQP property name>

The target prefix can have the following values:

  • Connection;
  • session;
  • link.

The Value of the KeyValuePair is converted to an AMQP data type using the rules defined in Table 200. If there is no rule defined for a data type, the property shall not be included.

The connection properties are intended to be used sparingly to optimize interoperability with existing broker endpoints.

A writer negotiates the delivery guarantees for its link using the snd-settle-mode settlement policy (settled, unsettled, mixed) it will use, and the desired rcv-settle-mode (first, second) of the broker.

Vice versa, the reader negotiates delivery guarantees using its rcv-settle-mode (first, second) and the desired snd-settle-mode (settled, unsettled) of the broker.

This matches to the BrokerTransportQualityOfService values as follows:

If the KeepAliveTime is set on a WriterGroup, a value slightly higher than the configured value of the group should be used as AMQP idle time-out of the AMQP connection ensuring that the connection is disconnected if the keep alive message was not sent by any writer. Otherwise, if no KeepAliveTime is specified, the implementation should set a reasonable default value.

When setting the maximum message sizes for the Link, the MaxNetworkMessageSize of the PubSubGroup shall be used. If this value is 0, the implementation chooses a reasonable maximum.

Other limits are up to the implementation and depend on the capabilities of the OS or on the capabilities of the device the Publisher or Subscriber is running on, and can be made configurable through configuration model extensions or by other means.

The AMQP message header has a number of standard fields which are called properties in the AMQP specification. Table 198 describes how these fields shall be populated when an AMQP message is constructed.

Table 198 – AMQP standard header fields

Field Name

Source

message-id

A globally unique value per message.

Subject

Valid values are ua-data or ua-metadata.

Content-type

The MIME type for the message body.

The MIME types are specified in the message body subclauses 7.3.4.8.1 and 7.3.4.8.3.

The subject defines the type of the message contained in the AMQP body. A value of “ua-data” specifies the body contains a UADP or JSON NetworkMessage. A value of “ua-metadata” specifies a body that contains a UA Binary or JSON encoded DataSetMetaData Message. The content-type specifies the whether the message is binary or JSON data.

The AMQP message header shall include additional fields defined on the WriterGroup or DataSetWriter through the KeyValuePair array in the WriterGroupProperties and DataSetWriterProperties. The NamespaceIndex of the QualifiedName in the KeyValuePair shall be 0 for AMQP standard message properties. The Name of the QualifiedName is constructed from a message prefix and the AMQP property name with the following syntax.

Name = message-<AMQP property name>

Table 199 defines the AMQP standard message properties.

Table 199 – OPC UA AMQP standard header QualifiedName Name mappings

AMQP standard property name

OPC UA DataType

AMQP data type

Note

to

String

*

user-id

ByteString

binary

reply-to

String

string

correlation-id

ByteString

*

absolute-expiry-time

Duration

timestamp

The absolute-expiry-time is calculated by adding the message-absolute-expiry-time (Duration) from the DataSetWriterProperties to the current time of the DataSetMessage creation.

Group-id

String

string

reply-to-group-id

String

string

creation-time

Boolean

timestamp

The creation-time is set to the current time of the DataSetMessage creation if the message-creation-time (Boolean) in the DataSetWriterProperties is True, or else if the value is False or if the property is not configured, the AMQP property is not set.

Content-encoding

String

symbol

Any name not in the table is assumed to be an application property. In this case the namespace provided as part of the QualifiedName shall be the ApplicationUri.

The AMQP message header shall include additional promoted fields of the DataSet as a list of name-value pairs. DataSet fields with the PromotedField flag set in the FieldMetaData fieldFlags are copied into the AMQP header. The FieldMetaData Structure is defined in 6.2.3.2.4. Promoted fields shall always be included in the header even if the DataSetMessage body is a delta frame and the DataSet field is not included in the delta frame. In this case the last known value is sent in the header.

When a field is added to the header it is converted to an AMQP data type using the rules defined in Table 200. If there is no rule defined for the data type, the field shall not be included.

Table 200 – OPC UA AMQP header field conversion rules

OPC UA DataType

Conversion Rules to AMQP data types.

Boolean

AMQP ‘boolean’ type.

Sbyte

AMQP ‘byte’ type.

Byte

AMQP ‘ubyte’ type.

Int16

AMQP ‘short’ type.

UInt16

AMQP ‘ushort’ type.

Int32

AMQP ‘int’ type.

UInt32

AMQP ‘uint’ type.

Int64

AMQP ‘long’ type.

UInt64

AMQP ‘ulong’ type.

Float

AMQP ‘float’ type.

Double

AMQP ‘double’ type.

String

AMQP ‘string’ type.

ByteString

AMQP ‘binary’ type.

DateTime

AMQP ‘timestamp’ type.

This conversion may result in loss of precision on some platforms.

The rules for dealing with the loss of precision are described in OPC 10000-6.

Guid

AMQP ‘uuid’ type.

QualifiedName

The QualifiedName is encoded as an AMQP ‘string’ type with the format <NamespaceUri>’#’<Name>.

LocalizedText

Not supported and the related field is discarded.

NodeId

If the NamespaceIndex = 0 the value is encoded as an AMQP ‘string’ type using the format for a NodeId defined in OPC 10000-6.

If the NamespaceIndex > 0 the value is converted to an ExpandedNodeId with a NamespaceUri and is encoded as an AMQP ‘string’ type using the format for an ExpandedNodeId defined in OPC 10000-6.

ExpandedNodeId

If the NamespaceUri is not provided the rules for the NodeId are used.

If the NamespaceUri is provided the value is encoded as an AMQP ‘string’ type using the format for an ExpandedNodeId defined in OPC 10000-6.

StatusCode

AMQP ‘uint’ type.

Variant

If the value has a supported datatype it uses that conversion; otherwise it is not supported and the related field is discarded.

Structure

Not supported and the related field is discarded.

Structure with option fields

Not supported and the related field is discarded.

Array

Not supported and the related field is discarded.

Union

Not supported and the related field is discarded.

The message body is encoded in the AMQP bare-message application-data section as an AMQP ‘binary’ value.

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

The corresponding MIME type is application/json.

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

The corresponding MIME type is application/opcua+uadp.

If the encoded AMQP message size exceeds the Broker limits it shall be broken into multiple chunks as described in 7.2.4.4.4.

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

Publishers send MQTT messages to MQTT brokers. Subscribers subscribe to MQTT brokers for messages. A Broker may persist messages so they can be delivered even if the Subscriber is not online. Brokers may 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 DataSetMessage defined in 7.2.3 and a JSON encoded DataSetMessage defined in 7.2.4.6.9.

MQTT version 3.1.1 does not provide a mechanism for specifying the encoding of the MQTT message which means the Subscribers need to be configured in advance with knowledge of the expected encoding. As a consequence, Publishers should only publish NetworkMessages using 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 Publisher or Subscriber and 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 NetworkMessages and binary message encoding defined in 7.2.3. 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 Address parameter defined in 6.2.7.3 has 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 AuthenticationProfileUri of the PubSubConnection, DataSetWriterGroup, DataSetWriter or DataSetReader entities.

If no authentication information is provided in the form of ResourceUri and 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 only supports the connection property ClientID using a KeyValuePair. Any other configured setting in the connection properties shall be silently discarded.

If the ClientID is not configured, the PublisherId is used as ClientID. If the PublisherId has a UInteger DataType, the UInteger value is converted to a String for the ClientID.

MQTT version 5.0 allows Publishers and Subscribers to 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 WriterGroup and the DataSetWriter.

The properties are defined through the KeyValuePair array in the ConnectionProperties. The NamespaceIndex of the QualifiedName in the KeyValuePair shall be 0.

Table 201 formally defines the ConnectionProperties used for MQTT connection configuration.

Table 201 – MQTT ConnectionProperties

Key

DataType

Description

0:MqttVersion

String

Defines the MQTT version to use for the MQTT connection. Possible values are “3.1.1”, “5.0” and “BestAvailable”.

The default value is BestAvailable.

0:MqttTopicPrefix

String

The <Prefix> part of the Topic convention defined in 7.3.5.7.1.

The default value is “opcua”

For MQTT properties, the Name of the QualifiedName is constructed from a prefix “connection” followed by a hyphen and the MQTT property name with the following syntax.

Name = connection-<MQTT property name>

Table 202 defines the MQTT standard connection properties.

Table 202 – 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 202 is 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 VerboseEncoding OPC UA JSON Data Encoding rules in OPC 10000-6.

The BrokerTransportQualityOfService values 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 KeepAliveTime is 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 WriterGroups are configured, the group with the highest KeepAliveTime setting 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.

MQTT messages are sent to Topics which provide context and other information about the message. Topics are hierarchical paths that allow Subscribers to use wildcards to select multiple Topics. Therefore, Topics are most useful when they follow a predictable pattern. This clause defines the Topic conventions for use with the MQTT mapping. All Publishers shall be able to support these conventions.

A Topic has the following general pattern:

<Prefix>/<Encoding>/<MqttMessageType>/<PublisherId>/[<WriterGroup>[/<DataSetWriter>]]

Where Topic levels are:

  • <Prefix> is a system defined prefix that provides a scope for the PublisherIds;The default value is ‘opcua’.
  • <Encoding> specifies the encoding of messages sent to the Topic (‘json’, ‘uadp’, etc);
  • <MqttMessageType> specifies the content of the messages published to the Topic as defined in 7.3.5.7.2;
  • <PublisherId> uniquely identifies a Publisher within the scope of the prefix;
  • <WriterGroup> is the name of a WriterGroup within the Publisher;
  • <DataSetWriter> is the name of a DataSetWriter within the WriterGroup;

The <Prefix> should be one Topic level, however, system designers may break <Prefix> into multiple Topic levels. Note that using multiple Topic levels prevents Subscribers from automatically discovering Publishers in the system unless they are preconfigured with the <Prefix> used for the system.

The possible values for the <Encoding> are ‘json’ or ‘uadp’ based on the message mappings defined in 7.2.3 and 7.2.4.6.9.

When Publishers are configured to publish to an MQTT Broker they shall have PublisherId assigned that can be used as Topic level.

The Topic levels that appear after the <PublisherId> depend on the <MqttMessageType>.

When these Topic conventions are used the wildcards in Table 203 may be used:

Table 203 – Examples of MQTT Wildcards

Wildcard

Notes

opcua/json/status/#

Subscribes to the status of all Publishers in the “opcua” scope.

This allows the Subscriber to detect when Publishers come online or disappear.

opcua/json/metadata/#

Subscribes to the metadata of all Publishers in the “opcua” scope.

This allows the Subscriber to detect changes to metadata.

opcua/json/data/device-one/#

Subscribes to all data produced by Publisher “device-one” in the “opcua” scope.

opcua/json/data/+/+/diagnostic

Subscribes to all Publishers that offer a “diagnostic” writer.

The MQTT Topic syntax places restrictions on what characters may be used in a Topic level. Specifically, Topic levels are any UTF-8 string that:

  • Does not start with a $
  • Does not include /, + or #
  • Does not include non-printable characters or whitespace other than the space character (U+0020).

<MqttMessageType> Topic levels exist for each MessageType defined in 7.2.2. Additional information like requirements for RETAIN for each Topic level is provided in Table 204. The handling of RETAIN messages is defined in 7.3.5.8.

The requirements for topic access permissions are defined in Table 205.

Table 204 – MQTT Topic level MessageType mapping

MessageType

MqttMessageType

RETAIN

Required

Specification Reference

DataSetMessage

data

False

Yes

Defined in 7.3.5.7.3.

A system specific Topic may be used instead

The RETAIN false is the default setting.

DataSetMetaData

metadata

True

Yes

Defined in 7.3.5.7.4.

A system specific Topic may be used instead.

ApplicationDescription

application

True

No

Defined in 7.3.5.7.5.

ServerEndpoints

endpoints

True

No

Defined in 7.3.5.7.6.

Status

status

True

Yes

Defined in 7.3.5.7.7.

PubSubConnection

connection

True

Yes

Defined in 7.3.5.7.8.

ActionRequest

action-request

False

Yes

Defined in 7.3.5.7.9.

A system specific Topic may be used instead

ActionResponse

action-response

False

No

Defined in 7.3.5.7.10.

The ActionResponse topic can be specified by the Requestor.

ActionMetaData

action-metadata

True

Yes

Defined in 7.3.5.7.12.

A system specific Topic may be used instead

ActionResponder

action-responder

True

Yes

Defined in 7.3.5.7.11.

Table 205 – MQTT Topic level access permissions

MqttMessageType

Publisher

Subscriber

Description

data

Write

Read

Variables and Events from an OPC UA applications acting as Publisher have RolePermissions. Such RolePermissions have no affect after DataSetMessages are sent to the MQTT broker. It is therefore recommended to synchronize Roles used to configure read permissions to the topics with the Roles required to access the information in the Publisher OPC UA application.

metadata

Write

Read

application

Write

Read

The information published with this message type is similar to discovery information provided with OPC UA Client Server discovery. This information is normally not restricted for read access.

endpoints

Write

Read

status

Write

Read

connection

Write

Read

action-request

Read

Write

Publisher is the Responder and Subscriber is the Requestor.

The topic with message type action-request is defined by the Responder with its PublisherId but the Requestors must have write permission to the topic.

Only the Responder should be able to read from the topic.

action-response

Write

Read

Publisher is the Responder and Subscriber is the Requestor.

If the Responder specifies the response topic it must be ensured that the Responder has Write access to this topic.

The Requestor should either use unique random correlation data or should use a private response topic where only the Requestor is able to read from.

action-metadata

Write

Read

action-responder

Write

Read

The data Topic has the form:

<Prefix>/<Encoding>/data/<PublisherId>/<WriterGroup>[/<DataSetWriter>]

The <PublisherId> Topic level is the PublisherId for the application sending the messages.

The <WriterGroup> Topic level is the name of a WriterGroup within the Publisher.

The <DataSetWriter> Topic level is the name of a DataSetWriter within the WriterGroup. If no QueueName is specified at the DataSetWriter level then the QueueName in WriterGroup TransportSettings is used and the DataSetWriter name is not part of the Topic.

The data Topic level is the default if the system owner does not have their own Topic tree. The Topic actually used is specified in the Connection Message as QueueName in the DataSetWriter or WriterGroup TransportSettings.

The messages are instances of the DataSetMessage MessageType (see 7.2.2).

The corresponding PubSubConnection Messag e is sent to the Topic with the same <Prefix>, <Encoding> and <PublisherId>. The PubSubConnection specifies the WriterGroups and DataSetWriters for a Publisher.

The metadata Topic has the form:

<Prefix>/<Encoding>/metadata/<PublisherId>/<WriterGroup>/<DataSetWriter>

The <PublisherId> Topic level is the PublisherId for the application sending the messages.

The <WriterGroup> Topic level is the name of a WriterGroup within the Publisher.

The <DataSetWriter> Topic level the name of a DataSetWriter within the WriterGroup.

The metadata Topic is the default if the system owner does not have their own Topic tree. The Topic actually used is specified in the Connection Message as MetaDataQueueName in the DataSetWriter TransportSettings.

The messages are instances of the DataSetMetaData MessageType (see 7.2.2).

The corresponding PubSubConnection Messag e is sent to the Topic with the same <Prefix>, <Encoding> and <PublisherId>. The PubSubConnection specifies the WriterGroups and DataSetWriters for a Publisher.

The application Topic has the form:

<Prefix>/<Encoding>/application/<PublisherId>

The <PublisherId> Topic level is the PublisherId for the application sending the messages.

The messages are instances of the ApplicationDescription MessageType (see 7.2.2).

The endpoints Topic has the form:

<Prefix>/<Encoding>/endpoints/<PublisherId>

The <PublisherId> Topic level is the PublisherId for the application sending the messages.

The messages are instances of the ServerEndpoints MessageType (see 7.2.2).

The status Topic has the form:

<Prefix>/<Encoding>/status/<PublisherId>

The <PublisherId> Topic level is the PublisherId for the application sending the messages.

The messages are instances of the Status MessageType (see 7.2.2).

A Publisher that is exclusively using a PublisherId shall register a Status message as an MQTT Will message when it creates the connection to the MQTT Broker. This message is sent automatically if the Publisher loses its connection with the MQTT Broker. The IsCyclic shall be FALSE in this case. The PubSubState value of the Will message shall be Error.

If a single MQTT client connection has multiple PubSubConnections (like for different encodings), not more than one PubSubConnection can register a Status message as MQTT Will message. All other PubSubConnections shall use cyclic Status messages.

The connection Topic has the form:

<Prefix>/<Encoding>/connection/<PublisherId>

The <PublisherId> Topic level is the PublisherId for the application sending the messages. This value shall be the same as the PublisherId in PubSubConnection provided in the message.

The PublisherId in the PubSubConnection uniquely identifies the Publisher within the scope defined by the <Prefix>.

The TransportProfileUri in the PubSubConnection specifies the <Encoding> used for all messages for the combination of <Encoding>/<PublisherId>. Table 206 specifies the mapping between a TransportProfileUri and the encoding.

Table 206 – TransportProfileUri encodings

URI

Encoding

http://opcfoundation.org/UA-Profile/Transport/pubsub-mqtt-json

json

http://opcfoundation.org/UA-Profile/Transport/pubsub-mqtt-uadp

uadp

The messages are instances of the PubSubConnection MessageType (see 7.2.2).

The action-request Topic has the form:

<Prefix>/<Encoding>/action-request/<Responder>/<WriterGroup>

The <Responder> Topic level is the PublisherId for the Responder of the Actions.

The <WriterGroup> Topic level is the name of a WriterGroup.

The action-request Topic level is the default if the system owner does not have their own Topic tree. The Topic actually used is specified in the Responder message as QueueName in the WriterGroup TransportSettings.

The messages are instances of the ActionRequest MessageType (see 7.2.2).

The corresponding Responder message is sent to the Topic with the same <Prefix>, <Encoding> and <Responder>. The PubSubConnection specifies the WriterGroups and DataSetWriters for a Responder.

The action-response Topic has the form:

<Prefix>/<Encoding>/action-response/<Responder>/<WriterGroup>

The <Responder> Topic level is the PublisherId for the Responder of the Actions.

The <WriterGroup> Topic level is the name of a WriterGroup.

The action-response Topic level is the default if the ResponseAddress is not provided in the ActionRequest.

The messages are instances of the ActionResponse MessageType (see 7.2.2).

The corresponding Responder message is sent to the Topic with the same <Prefix>, <Encoding> and <Responder>. The PubSubConnection specifies the WriterGroups and DataSetWriters for a Responder.

The action-responder Topic has the form:

<Prefix>/<Encoding>/action-responder/<Responder>

The <Responder> Topic level is the PublisherId for the Responder of the Actions. This value shall be the same as the PublisherId in PubSubConnection provided in the message.

The PublisherId in the PubSubConnection uniquely identifies the Publisher within the scope defined by the <Prefix>. If it is a String, it should be as short as possible since long Topic names degrade performance.

The messages are instances of the PubSubConnection MessageType (see 7.2.2).

The action-metadata Topic has the form:

<Prefix>/<Encoding>/action-metadata/<Responder>/<WriterGroup>/<DataSetWriter>

The <Responder> Topic level is the PublisherId for the Responder of the Action.

The <Group> Topic level is the name of a WriterGroup.

The <Writer> Topic level the name of a DataSetWriter.

The action-metadata Topic is the default if the system owner does not have their own Topic tree. The Topic actually used is specified in the Responder message as MetaDataQueueName in the DataSetWriter TransportSettings.

The messages are instances of the ActionMetaData MessageType (see 7.2.2).

The corresponding PubSubConnection Messag e is sent to the Topic with the same <Prefix>, <Encoding> and <PublisherId>. The PubSubConnection specifies the WriterGroups and DataSetWriters for a Publisher.

The default setting for the MQTT RETAIN flag are defined in Table 204. Table 208 defines an option to change the RETAIN flag setting for DataSetMessages.

A Publisher shall send all RETAIN discovery messages at start up of the Publisher. A Publisher shall update affected RETAIN topics if the Publisher configuration changes. A Publisher shall clear RETAIN topics if the discovery element is deleted from the Publisher configuration like reset the metadata topic if the related DataSetWriter is removed. A Publisher shall subscribe to its own discovery message topics at start-up and clear all topics that do not match the current Publisher configuration.

Publishers using MQTT version 3.1.1 shall clear RETAIN topics when they shut down.

Publishers using MQTT version 5.0 shall set the Message Expiry Interval on RETAIN topics and shall send a new RETAIN message before the interval expires.

The MQTT version 3.1.1 protocol does not support message headers. Any promoted field or additional fields defined on the WriterGroup or DataSetWriter other 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 PubSub properties not directly supported by the MQTT protocol.

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

Table 207 – OPC UA MQTT message properties

MQTT property name

MQTT property type

MQTT property value

UAMessageType

User Property

Valid values are “ua-<MqttMessageType>” where the MqttMessageTypes are defined in 7.3.5.7.2.

Content Type

Standard

The MIME type for the message body.

The MIME types are specified in the message body subsections 7.3.5.9.1 and 7.3.5.9.2.

The MQTT message header shall include additional fields defined on the PubSubConnection, WriterGroup or DataSetWriter through the KeyValuePair array in the WriterGroupProperties and DataSetWriterProperties. The NamespaceIndex of the QualifiedName in the KeyValuePair shall be 0. The Name of the QualifiedName is constructed from a message prefix and the MQTT property name with the following syntax.

Name = <MqttMessageType>-<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 208 defines the MQTT standard message properties.

Table 208 – OPC UA MQTT standard message property configuration

MQTT property name

OPC UA DataTypes

MQTT data types

Description

RETAIN

Boolean

RETAIN bit in the header

RETAIN configuration for DataSetMessages.

Message Expiry Interval

UInt32

Four Byte Integer

Not available as message property for MQTT 3.1.1.

Any name not in the Table 208 is 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 VerboseEncoding OPC UA JSON Data Encoding rules 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 DataSet as a list of MQTT User Property name-value pairs. DataSet fields with the PromotedField flag set in the FieldMetaData fieldFlags are copied into the MQTT header. The FieldMetaData Structure is defined in 6.2.3.2.4. 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 the DataSetMessage body is a delta frame and the DataSet field is not included in the delta frame. In this case the last known value is sent in the header.

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

When sending a MQTT Version 5.0 message the MQTT ContentType property 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 Content Type 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. If a Subscriber receives messages without MQTT ContentType from MQTT Version 3.1.1 Publishers it may require manual configuration.

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

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

If the encoded MQTT message size exceeds the Broker limits, it is broken into multiple chunks as described in 7.2.4.4.4.

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