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 177 may be used:
Table 177 – 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 UTF8 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 about each Topic level is provided in Table 178.
Table 178 – 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. |
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 the MQTT Broker. The IsCyclic shall be FALSE in this case. The PubSubState value of the Will message shall be Error.
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 179 specifies the mapping between a TransportProfileUri and the encoding.
Table 179 – 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).