UA Part 14: PubSub - 7.3.5.7 Topics

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).

7.3.5.7.2 MessageType mapping

<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

7.3.5.7.3 data Topic level

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.

7.3.5.7.4 metadata Topic level

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).

7.3.5.7.5 application Topic level

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).

7.3.5.7.6 endpoints Topic level

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).

7.3.5.7.7 status Topic level

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.

7.3.5.7.8 connection Topic level

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).

7.3.5.7.9 action-request Topic level

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.

7.3.5.7.10 action-response Topic level

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).

7.3.5.7.11 action-responder Topic level

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).

7.3.5.7.12 action-metadata Topic level

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).