Clause 7specifies the mapping between the PubSubconcepts described in clause 5and the PubSubconfiguration parameters defined in clause 6to concrete message mappings and transport protocol mappings that can be used to implement them.

DataSetMessagemappings, NetworkMessagemappings and transport protocol mappings are combined together to create transport profiles defined in OPC 10000-7. All PubSubapplications shall implement at least one transport profile.

Message mappings specify a specific structure and encoding for NetworkMessages. Such a structure represents the payload for transport protocol mappings like UDP, MQTT or AMQP.

Different mappings are defined for different use cases.

The UADP message mapping uses optimized OPC UA Binary encoding defined in OPC 10000-6and provides message security for OPC UA PubSub. The available protocol mappings are defined in 7.3.

The UADP message mapping defines different optional header fields, variations of field settings and different message types and data encodings.

Some optional fields like timestamps provide information that is not necessary for the processing of the messages on the Subscriberside. Other optional fields like PublisherId, DataSetWriterIdor sizes of DataSetMessagesare typically necessary for the processing of messages in generic Subscribers. If such fields are not present, the Subscribermust know the missing information from the DataSetReaderconfiguration. One scenario is that a Publisheris sending NetworkMessageswith a fixed layout of the payload. In this case the DataSetWriterId, the offset and size of the DataSetMessagesis known from theDataSetReaderconfiguration. The identification is done in this case by the group header with the WriterGroupIdand NetworkMessageNumber.

The flexibility of the optional fields is necessary to support different use cases but it also allows the configuration of invalid combinations. To reduce the number of combinations used in common use cases, Annex Adefines standard UADP header layouts with defined settings for common use cases. Custom configurations can be used but they should be limited to applications that do not fall into these use cases.

A Publishershould support all variations it allows through configuration. The required set of features is defined through profiles in OPC 10000-7.

A Subscribershall be able to process all possible NetworkMessagesand shall be able to skip information the Subscriberis not interested in. The Subscribermay not support all security policies. The capabilities related to processing different DataSetencodings is defined in OPC 10000-7.

The fields in the following protocol definition tables are encoded using the OPC UA Binary encoding rules defined in OPC 10000-6including arrays. If the brackets for an array are not empty, the length field is omitted from the encoding and the length information is provided through additional definitions.

The PubSub communication parameters defined in Clause 6provide the settings for mapping information from the Publisherinto DataSetMessages, settings to send them in NetworkMessagesto the Subscribersand settings to process the DataSetMessageson the Subscriberside.

The error handling for the status codes in DataSetMessageheaders and DataSetMessagefields is defined in 6.2.11and 6.2.4.2. This handling of information flows and status codes assumes that the configuration between Publisherand Subscriberis in sync.

In several combinations of settings for the DataSetMessagesand NetworkMessages, a Subscriberis able to process received messages without further knowledge of the Publisherside configuration. But most Subscribers need at least the DataSetMetaDatato be able to process the received DataSetMessages.

The Publisherside configuration implies two types of contracts necessary for the Subscriber to process messages. The one type of contract is the DataSetMetaDatadescribing the content of a DataSetMessage. The other type of contract provides the communication settings like the DataSetWriterIdor offsets inside NetworkMessages. Both type of contracts provide version information that can be included into the DataSetMessagesand NetworkMessages.

Several settings in the contracts have corresponding flags or version fields in the messages and a Subscribercan detect mismatches between the contract and the received messages.

The error handling depends on the Subscriberapplications. Subscribersthat are configured to process certain DataSetMessagesoften work with a known contract and they will typically drop messages that do not comply with the contract. At the same time they will try to get an update of the contract and will try to adjust its own settings to the updated contract if this is possible. Some changes may need manual reconfiguration of the Subscriber.

But Subscribers may also work without a known contract or may accept some differences between the contract and the actual message layout without dropping messages.

One exception is the security configuration. A Subscribershall drop all messages where the configured SecurityModehas a lower number than the received SecurityMode. E.g. if the Subscriberis configured for SecurityMode SIGNit shall drop messages with NONE. A Subscribermay process messages with a higher SecurityModee.g. it is allowed to process messages with SecurityMode SIGNif it is configured for NONE.

SequenceNumberfields are defined in different headers of the UADP Message Mapping.

A SequenceNumberis a monotonically increasing number assigned to messages headers represented by an unsigned integer of width N which is further specified in Table 133. The SequenceNumber starts at 0 and shall be incremented by exactly one for each message.

Receivers need to be aware of sequence numbers roll over (change from the largest possible value to 0).

To determine whether a received message is newer than the last processed message the following formula shall be used:

(received sequence number -1 – last processed sequence number) modulo 2^N

For the resulting value there is an upper bound and a lower bound depending on the bit width of the sequence number.

Results below the lower bound indicate that the received message is newer than the last processed message and it shall be processed.

Results above the upper bound indicate that the received message is older than (or same as) than the last processed message and it shall be ignored unless reordering of messages is required.

Other results are invalid and the message shall be ignored.

The lower bound is given as 2^(N-2).

The upper bound is given as 2^N – 2^(N-2).

Table 133– Values for different sequence number sizes

DataType

Name

Value

Description

UInt16

Formula

(New-1-Last) modulo 65.536

Lower bound

16.384

2^14

Upper bound

49.152

2^16-2^14

UInt32

Formula

(New-1-Last) modulo 4.294.967.296

Lower bound

1.073.741.824

2^30

Upper bound

3.221.225.472

2^32-2^30

Subscribersshall discard the records they keep for sequence numbers if they do not receive messages for two times the keep alive time to deal with Publishersthat are out of service and were not able to continue from the last used SequenceNumber.

The UADP NetworkMessageheader and other parts of the NetworkMessage are shown in Figure 29.

When using security, the payload and the Paddingfield are encrypted and after that, the whole NetworkMessageis signed if signing and encryption is active. The NetworkMessageshall be signed without being encrypted if only the signing is active.

The UADP NetworkMessagedoes not provide the total message size. It is expected that the message size is known from the transport protocol mapping. If the transport protocol mapping does not provide the size of the payload, an additional size information must be added in front of the UADP NetworkMessagefor that transport protocol.

image032.png

Figure 29– UADP NetworkMessage

The encoding of the UADP NetworkMessageis specified in Table 134.

The NetworkMessageContentMasksetting of the Publishercontrols the flags in the fields UADPFlagsand ExtendedFlags1. The SecurityModesetting of the Publishercontrols the security enabled flag of the ExtendedFlags1. The setting of the flags shall not change until the configuration of the Publisheris changed.

Table 134– UADP NetworkMessage

Name

Type

Description

UADPVersion

Bit[0-3]

Bit range 0-3: Version of the UADP NetworkMessage.

The UADPVersionfor this specification version is 1.

UADPFlags

Bit[4-7]

Bit 4: PublisherIdenabled

If the PublisherId is enabled, the type of PublisherId is indicated in the ExtendedFlags1 field.If the PublisherIdis enabled is false, the ExtendedFlags1 PublisherId Type flags shall be false.

Bit 5: GroupHeaderenabled

Bit 6: PayloadHeaderenabled

Bit 7: ExtendedFlags1 enabledThe bit shall be false, if ExtendedFlags1 is 0.

ExtendedFlags1

Byte

The ExtendedFlags1shall be omitted if bit 7 of the UADPFlagsis false.

If the field is omitted, the Subscribershall handle the related bits as false.

Bit range 0-2: PublisherIdType

000 The PublisherIdis of DataType Byte This is the default value if ExtendedFlags1is omitted

001 The PublisherIdis of DataType UInt16

010 The PublisherIdis of DataType UInt32

011 The PublisherIdis of DataType UInt64

100 The PublisherIdis of DataType String

101 Reserved

11x ReservedReserved values shall not be used by the sender and the receiver shall skip messages when reserved values are received.

The PublisherIdType shall be ignored if bit 4 of the UADPFlagsis false.

Bit 3: DataSetClassIdenabled

Bit 4: SecurityHeaderenabled

If this flag is enabled, the NetworkMessage header includes theSecurityHeader, otherwise the SecurityHeaderis omitted.

If the SecurityModein the configuration is SIGNor SIGNANDENCRYPT, this flag shall be set.

Bit 5: Timestampenabled

Bit 6: PicoSeconds enabled

This bit shall be false if the Timestamp bit is false.

Bit 7: ExtendedFlags2 enabled

The bit shall be false, if ExtendedFlags2 is 0.

ExtendedFlags2

Byte

The ExtendedFlags2shall be omitted if bit 7 of the ExtendedFlags1is false.

If the field is omitted, the Subscribershall handle the related bits as false.

Bit 0: Chunk message defined in in 7.2.2.4.4.

Bit 1: PromotedFieldsenabled

If Promoted fields are enabled, the number of DataSetMessagesin the NetworkMessage shall be one.

Bit range 2-4: UADP NetworkMessagetype

000 NetworkMessagewith DataSetMessagepayload defined in 7.2.2.4.4. If the ExtendedFlags2field is not provided, this is the default NetworkMessagetype.

001 NetworkMessagewith discovery probe defined in 7.2.2.5.4.

010 NetworkMessagewith discovery announcement payload defined in 7.2.2.6.4.

011 Reserved

1xxReserved

Reserved values shall not be used by the sender and the receiver shall skip messages when reserved values are received.

Bit 5: Reserved

Bit 6: Reserved

Bit 7: Reserved for further extended flag fields

Reserved bits shall be set to false by the sender and the receiver shall skip messages where the reserved bits are not false.

PublisherId

Byte[*]

The PublisherIdshall be omitted if bit 4 of the UADPFlagsis false.

The Id of the Publisherthat sent the data. Valid DataTypesare UIntegerand String.

The DataType is indicated by bits 0-2 of the ExtendedFlags1.

A Subscribercan skip NetworkMessagesfrom Publishersit does not expect NetworkMessagesfrom.

PublisherIds are only equal if they have the same DataTypes and equal values.

DataSetClassId

Guid

The DataSetClassIdassociated with the DataSetsin the NetworkMessage.

All DataSetMessages in the NetworkMessage shall have the same DataSetClassId.

The DataSetClassIdshall be omitted if bit 3 of the ExtendedFlags1is false.

GroupHeader

The group header shall be omitted if bit 5 of the UADPFlagsis false.

GroupFlags

Byte

Bit 0: WriterGroupIdenabled

Bit 1: GroupVersionenabled

Bit 2: NetworkMessageNumberenabled

Bit 3: SequenceNumberenabled

Bits 4-6: Reserved

Bit 7: Reserved for further extended flag fields

Reserved bits shall be set to false by the sender and the receiver shall skip messages where the reserved bits are not false.

WriterGroupId

UInt16

Unique id for the WriterGroupin the Publisher.

A Subscribercan skip NetworkMessagesfrom WriterGroupsit does not expect NetworkMessagesfrom.

This field shall be omitted if bit 0 of the GroupFlagsis false.

GroupVersion

VersionTime

Version of the header and payload layout configuration of the NetworkMessagessent for the group.

This field shall be omitted if bit 1 of the GroupFlagsis false.

NetworkMessage Number

UInt16

Unique number of a NetworkMessageacross the combination of PublisherIdand WriterGroupIdwithin one PublishingInterval.

The number is needed if the DataSetMessagesfor one group are split into more than one NetworkMessagein a PublishingInterval.

The value 0 is invalid.

This field shall be omitted if bit 2 of the GroupFlagsis false.

SequenceNumber

UInt16

Sequence number for each new NetworkMessageas defined in 7.2.2.3.

This field shall be omitted if bit 3 of the GroupFlagsis false.

PayloadHeader

Byte [*]

The payload header depends on the UADP NetworkMessagetype flags defined in the ExtendedFlags2bit range 2-4. The default is DataSetMessageif the ExtendedFlags2field is not enabled.

The PayloadHeader shall be omitted if bit 6 of the UADPFlagsis false.

The PayloadHeaderis not contained in the payload but it is contained in the unencrypted NetworkMessageheader since it contains information necessary to filter DataSetMessageson the Subscriberside.

If the payload header is not present for DataSetMessages, the Subscribermust know the number and size of DataSetMessagesfrom the DataSetReaderconfiguration. The group header is the default option to provide a reference to this information in the NetworkMessage. In this case the number and size of the DataSetMessagesis known from the DataSetReaderconfiguration for the combination of WriterGroupIdand NetworkMessageNumber.

Timestamp

DateTime

The time the NetworkMessage was created.

The Timestampshall be omitted if bit 5 of ExtendedFlags1is false.

The PublishingInterval, the SamplingOffsetthe PublishingOffsetand the Timestampand PicoSecondsin the NetworkMessageheader shall use the same time base.

PicoSeconds

UInt16

Specifies the number of 10 picosecond (1,0 e-11 seconds) intervals which shall be added to the Timestamp.

The PicoSecondsfield stores the difference between a high-resolution timestamp with a resolution of 10 picoseconds and the Timestamp field value which only has a 100 ns resolution. The PicoSecondsfield shall contain values less than 10 000. The decoder shall treat values greater than or equal to 10 000 as the value ‘9999’.

The PicoSecondsshall be omitted if bit 6 of ExtendedFlags1is false.

PromotedFields

The PromotedFieldsshall be omitted if bit 1 of the ExtendedFlags2is false.

If the PromotedFieldsare provided, the number of DataSetMessagesin the NetworkMessage shall be one.

Size

UInt16

Total size in Bytesof the Fieldscontained in the PromotedFields.

Fields

BaseDataType[ ]

Array of promoted fields. The size, order and DataTypesof the fields depend on the settings in the FieldMetaDataof the DataSetMetaDataassociated with the DataSetMessagecontained in the NetworkMessage.

SecurityHeader

The security header shall be omitted if bit 4 of the ExtendedFlags1is false.

SecurityFlags

Byte

Bit 0: NetworkMessageSigned

Bit 1: NetworkMessageEncryptedThe configuration options for MessageSecurityMode are NONE, SIGN and SIGNANDENCRYPT. Therefore bit 0 shall be true if bit 1 is true.

Bit 2: SecurityFooter enabled

Bit 3: Force key reset

This bit is set if all keys will be made invalid. It is set until the new key is used. The Publisherneeds to give Subscribersa reasonable time to request new keys. The minimum time is five times the KeepAliveTime configured for the corresponding PubSub group.

This flag is typically set if all keys are invalidated to exclude Subscribers, who no longer have access to the keys.

Bit range 4-7: Reserved

Reserved bits shall be set to false by the the sender and the receiver shall skip messages where the reserved bits are not false.

SecurityTokenId

IntegerId

The ID of the security token that identifies the security key in a SecurityGroup. The relation to the SecurityGroupis done through DataSetWriterIdscontained in the NetworkMessage.

If bit 1 and 2 of the SecurityFlagsare 0, the SecurityTokenIdshall be 0.

NonceLength

Byte

The length of the Nonce used to initialize the encryption algorithm.

If bit 1 and 2 of the SecurityFlagsare 0, the NonceLengthshall be 0.

MessageNonce

Byte [NonceLength]

A number used exactly once for a given security key. For a given security key a unique nonce shall be generated for every NetworkMessage. The rules for constructing the MessageNonceare defined for the UADP Message Security in 7.2.2.4.3.

SecurityFooterSize

UInt16

The size of the SecurityFooter.

The security footer size shall be omitted if bit 2 of the SecurityFlagsis false.

Payload

Byte [*]

The payload depends on the UADP NetworkMessageType flags defined in the ExtendedFlags2bit range 2-4 and on the Chunkflag defined in the.ExtendedFlags2bit 0.

SecurityFooter

Byte [*]

Optional security footer shall be omitted if bit 2 of the SecurityFlagsis false.

The content of the security footer is defined by the SecurityPolicy.

Signature

Byte [*]

The signature of the NetworkMessage.

The security algorithms used and the length of the KeyNoncefor the UADP NetworkMessagedepend on the selected SecurityPolicy. The algorithms are defined by SymmetricEncryptionAlgorithmand SymmetricSignatureAlgorithmin OPC 10000-7.The nonce length is part of the SymmetricEncryptionAlgorithm.

The keys used to encrypt and sign messages are extracted from the key data returned from the GetSecurityKeysmethod (see 8.3.2). This Methodreturns a sequence of key data with a length that depends on the SecurityPolicyUri, which is also returned by the Method. The layout of the key data is defined in Table 135.

Table 135– Layout of the key data for UADP message security

Name

Type

Description

SigningKey

Byte [SymmetricSignatureAlgorithm Key Length]

Signing key part of the key data returned from GetSecurityKeys. The SymmetricSignatureAlgorithm is defined in the SecurityPolicy.

EncryptingKey

Byte [SymmetricEncryptionAlgorithm Key Length]

Encryption key part of the key data returned from GetSecurityKeys. The SymmetricEncryptionAlgorithm is defined in the SecurityPolicy.

KeyNonce

Byte [SymmetricEncryption Nonce Length]

Nonce part of the key data returned from GetSecurityKeys.

The layout of the MessageNonce for AES-CTR mode is defined in Table 136.

Table 136– Layout of the MessageNonce for AES-CTR

Name

Type

Description

Random

Byte [4]

The random part of the MessageNonce. This number does not need to be a cryptographically random number, it can be pseudo-random.

SequenceNumber

UInt32

Sequence number for the MessageNonceas defined in 7.2.2.3.

The sequence number is reset to 1 after the key and SecurityTokenIdare updated in the Publisher.

The message encryption and decryption with AES-CTR mode uses a secret and a counter block. The secret is the EncryptingKeyfrom the key data defined in Table 135. The layout and content of the counter block is defined in Table 137.

Table 137– Layout of the counter block for UADP message security for AES-CTR

Name

Type

Description

KeyNonce

Byte [4]

The KeyNonce portion of the key data returned from GetSecurityKeys.

MessageNonce

Byte [8]

The first 8 bytes of the Noncein the SecurityHeaderof the NetworkMessage.

For AES-CTR mode the length of the SecurityHeader Nonceshall be 8 Bytes.

BlockCounter

Byte [4]

The counter for each encrypted block of the NetworkMessage.

The counter is a 32-bit big endian integer (the opposite of the normal encoding for UInt32 values in OPC UA. This convention comes from the AES-CTR RFC).

The counter starts with 1 at the first block. The counter is incremented by 1 for each block.

AES-CTR mode takes the counter block and encrypts it using the encrypting key. The encrypted key stream is then logically XORed with the data to encrypt or decrypt. The process is repeated for each block in plain text. No padding is added to the end of the plain text. AES-CTR does not change the size of the plain text data and can be applied directly to a memory buffer containing the message.

The signature is calculated on the entire NetworkMessageincluding any encrypted data. The signature algorithm is specified by the SecurityPolicyUriin OPC 10000-7.

When a Subscriberor a Publisherreceives a NetworkMessage, it shall verify the signature before processing the payload. If verification fails, it drops the NetworkMessage.

Other SecurityPolicymay specify different key lengths or cryptography algorithms.

If a NetworkMessagepayload with a DataSetMessageneed to be split across multiple NetworkMessages,the chunks are sent in multiple NetworkMessages. The PayloadHeaderof each NetworkMessagecontains the payload header defined in Table 138. The Payloadof each NetworkMessagecontains the payload defined in Table 139. A chunk NetworkMessagecan only contain chunked payload of one DataSetMessage.

If a NetworkMessagepayload with a discovery announcement message has to be split across multiple NetworkMessagesthe chunks are sent with the payload defined in Table 139. The payload header is disabled for discovery probe and discovery announcement NetworkMessages.

Table 138– Chunked NetworkMessage payload header

Name

Type

Description

DataSetWriterId

UInt16

DataSetWriterId contained in the NetworkMessage.

The DataSetWriterIdidentifies the PublishedDataSetand the DataSetWriterresponsible for sending Messages for the DataSet.

A Subscribercan skip DataSetMessagesfrom DataSetWritersit does not expect DataSetMessagesfrom.

Table 139– Chunked NetworkMessage payload fields

Name

Type

Description

MessageSequenceNumber

UInt16

Sequence number of the payload as defined for the NetworkMessagetype like DataSetMessageSequenceNumberin a DataSetMessage.

NetworkMessagesmay be received out of order. In this case, a chunk for the next payload can be received before the last chunk of the previous payload was received.

If the next sequence number is received by a Subscriberthat can handle only one payload, the chunks of the previous payload are skipped if they are not completely received yet.

ChunkOffset

UInt32

The byte offset position of the chunk in the complete NetworkMessagepayload. The last chunk is detected if ChunkOffsetplus the size of the current chunk equals TotalSize.

All chunks, except for the last one shall have the same size. The size of all chunks other than the last one can be used to calculate the number of expected chunks.

The reassembled NetworkMessagepayload can be processed after all chunks are received.

Depending on the transport protocol mapping, the chunks may be received out of order and the last chunk may be received before all other chunks are received.

TotalSize

UInt32

Total size of the NetworkMessagepayload in bytes.

ChunkData

ByteString

The pieces of the original DataSetMessageor the discovery announcement message are copied into the chunk until the maximum size allowed for a single NetworkMessageis reached minus space for the signature. The data copied into next chunk starts with the byte after the last byte copied into current chunk.

A DataSetMessageor discovery announcement message is completely received when all chunks are received and the message can be processed completely.

The UADP DataSetpayload header and other parts of the NetworkMessage are shown in Figure 30.

Different types of DataSetMessagecan be combined in on NetworkMessage.

image033.png

Figure 30– UADP DataSet payload

The encoding of the UADP DataSet payload header is specified in Table 140. The payload header is unencrypted. This header shall be omitted if bit 6 of the UADPFlagsis false.

Table 140– UADP DataSet payload header

Name

Type

Description

Count

Byte

Number of DataSetMessagescontained in the NetworkMessage. The NetworkMessageshall contain at least one DataSetMessageif the NetworkMessagetype is DataSetMessagepayload.

DataSetWriterIds

UInt16 [Count]

List of DataSetWriterIdscontained in the NetworkMessage. The size of the list is defined by the Count.

The DataSetWriterIdidentifies the PublishedDataSetand the DataSetWriterresponsible for sending Messages for the DataSet.

A Subscribercan skip DataSetMessagesfrom DataSetWritersit does not expect DataSetMessagesfrom.

The DataSetpayload is defined in Table 141. The payload is encrypted.

Table 141– UADP DataSet payload

Name

Type

Description

Sizes

UInt16 [Count]

List of byte sizes of the DataSetMessages.

The size of the list is defined by the Countin the DataSetpayload header.

If the payload size exceeds 65535, the DataSetMessagesshall be allocated to separate NetworkMessages. If a single DataSetMessageexceeds the payload size it shall be split into Chunk NetworkMessages.

This field shall be omitted if count is one or if bit 6 of the UADPFlagsis false.

DataSetMessages

DataSetMessage [Count]

DataSetMessagescontained in the NetworkMessage. The size of the list is defined by the Countin the DataSetpayload header.

The type of encoding used for the DataSetMessagesis defined by the DataSetWriter.

The encodings for the DataSetMessageare defined in 7.2.2.5.4.

The DataSetMessage header structure and the relation to other parts in a NetworkMessageis shown in Figure 31.

image034.png

Figure 31– DataSetMessageheader structure

The encoding of the DataSetMessage header structure is specified in Table 142.

The DataSetFieldContentMaskand the DataSetMessageContentMasksettings of the DataSetWritercontrol the flags in the fields DataSetFlags1and DataSetFlags2. The setting of the flags shall not change until the configuration of the DataSetWriteris changed.

Table 142– DataSetMessageheader structure

Name

Type

Description

DataSetFlags1

Byte

Bit 0: DataSetMessage is valid.

If this bit is set to false, the rest of this DataSetMessageis considered invalid, and shall not be processed by the Subscriber.

Bit range 1-2: Field Encoding

00 The DataSetfields are encoded as Variant The Variantcan contain a StatusCodeinstead of the expected DataTypeif the status of the field is Bad. The Variantcan contain a DataValue with the value and the statusCode if the status of the field is Uncertain.

01 RawData Field Encoding

The RawData field encoding is defined in 7.2.2.5.9.

10 DataValue Field Encoding

The DataSetfields are encoded as DataValue. This option is set if the DataSetis configured to send more than the Value.

11 Reserved

Reserved values shall not be used by the sender and the receiver shall skip messages when reserved values are received.

Bit 3: DataSetMessageSequenceNumberenabled

Bit 4: Statusenabled

Bit 5: ConfigurationVersionMajorVersionenabled

Bit 6: ConfigurationVersionMinorVersionenabled

Bit 7: DataSetFlags2 enabled

The bit shall be false, if DataSetFlags2 is 0.

DataSetFlags2

Byte

The DataSetFlags2 shall be omitted if bit 7 of the DataSetFlags1 is false.

If the field is omitted, the Subscribershall handle the related bits as false.

Bit range 0-3: UADP DataSetMessage type

0000Data Key Frame (see 7.2.2.5.5)

If the DataSetFlags2field is not provided, this is the default DataSetMessage type.

0001Data Delta Frame (see 7.2.2.5.6)

0010Event (see 7.2.2.5.7)

0011Keep Alive (see 7.2.2.5.8)

01xxReserved

1xxxReserved

Reserved values shall not be used by the sender and the receiver shall skip messages when reserved values are received.

Bit 4: Timestampenabled

Bit 5: PicoSecondsincluded in the DataSetMessageheaderThis bit shall be false if the Timestamp bit is false.

Bit 6: Reserved

Bit 7: Reserved for further extended flag fields

Reserved bits shall be set to false by the Publisher and Subscribers shall skip messages where the reserved bits are not false.

DataSetMessage‌SequenceNumber

UInt16

Sequence number for each new DataSetMessageas defined in 7.2.2.3.

The field shall be omitted if Bit 3 of DataSetFlags1is false.

Timestamp

UtcTime

The time the DataSetMessagewas created.

The Timestampshall be omitted if Bit 4 of DataSetFlags2is false.

PicoSeconds

UInt16

Specifies the number of 10 picoseconds (1,0 e-11 seconds) intervals which shall be added to the Timestamp.

The PicoSecondsfield stores the difference between a high-resolution timestamp with a resolution of 10 picoseconds and the Timestamp field value which only has a 100 ns resolution. The PicoSecondsfield shall contain values less than 10 000. The decoder shall treat values greater than or equal to 10 000 as the value ‘9.999’.

The field shall be omitted if Bit 5 of DataSetFlags2is false.

Status

UInt16

The overall status of the DataSetMessage. The dependencies to the status of DataSetfields are defined in Table 26.

This is the high order 16 bits of the StatusCode DataTyperepresenting the numeric value of the Severityand SubCodeof the StatusCode DataType.

The field shall be omitted if Bit 4 of DataSetFlags1is false.

ConfigurationVersion

MajorVersion

VersionTime

The major version of the configuration version of the DataSet used as consistency check with the DataSetMetaDataavailable on the Subscriberside.

The field shall be omitted if Bit 5 of DataSetFlags1is false.

ConfigurationVersion

MinorVersion

VersionTime

The minor version of the configuration version of the DataSet used as consistency check with the DataSetMetaDataavailable on the Subscriberside.

The field shall be omitted if Bit 6 of DataSetFlags1is false.

The data key frame DataSetMessage data and related headers are shown in Figure 32.

image035.png

Figure 32– Data Key Frame DataSetMessagedata

The encoding of the data key frame DataSetMessage structure is specified in Table 143.

If the key frame is a heartbeatDataSetMessage, only the header is encoded but the following structure shall not be encoded into the DataSetMessage.

Table 143– Data Key Frame DataSetMessage structure

Name

Type

Description

FieldCount

UInt16

Number of fields of the DataSetcontained in the DataSetMessage.

The FieldCountshall be omitted if RawDatafield encoding is set in the EncodingFlagsdefined in 7.2.2.5.4.

DataSetFields

BaseDataType [FieldCount]

The field values of the DataSet.

The field encoding depends on the DataSetFlags1.Field Encodingof the DataSetMessageHeader defined in 7.2.2.5.4. The default encoding is Variantif bit 1 and 2 are not set.

Padding

Byte [*]

Optional padding added if the encoded DataSetMessage is smaller than the ConfiguredSize. The DataSetMessageis padded with bytes with value zero.

The data delta frame DataSetMessage data and the related headers are shown in Figure 33.

image036.png

Figure 33– Data Delta Frame DataSetMessage

The information for a single value in delta frame messages is larger because of the additional index necessary for sending just changed data. The Publishershall send a key frame message if the delta frame message is larger than a key frame message.

The encoding of the data delta frame DataSetMessage structure is specified in Table 144.

Table 144– Data Delta Frame DataSetMessage structure

Name

Type

Description

FieldCount

UInt16

Number of fields of the DataSet contained in the DataSetMessage.

DeltaFrameFields

Structure [FieldCount]

The subset of field values of the DataSet contained in the delta frame.

FieldIndex

UInt16

The index of the Field in the DataSet. The index is based on the field position in the DataSetMetaDatawith the configuration version defined in the ConfigurationVersionfield.

A Publishershall use an index only once in a DataSetMessage.

FieldValue

BaseDataType

The field values of the DataSet.

The field encoding depends on the DataSetFlags1.Field Encodingof the DataSetMessageHeader defined in 7.2.2.5.4. The default encoding is Variant if bit 1 and 2 are not set.

Padding

Byte [*]

Optional padding added if the encoded DataSetMessage is smaller than the ConfiguredSize. The DataSetMessageis padded with bytes with value zero.

The Event DataSetMessage data and the related headers are shown in Figure 34.

image037.png

Figure 34– Event DataSetMessage

The encoding of the Event DataSetMessage structure is specified in Table 145.

Table 145– Event DataSetMessage structure

Name

Type

Description

FieldCount

UInt16

Number of fields of the DataSetcontained in the DataSetMessage.

DataSetFields

BaseDataType [FieldCount]

The field values of the DataSet.

The fields of Event DataSetMessagesshall be encoded as Variant.

The Field Encoding DataSetFlags1of the DataSetMessageheader (bit 1 and 2) defined in 7.2.2.5.4shall be set to false.

Padding

Byte [*]

Optional padding added if the encoded DataSetMessage is smaller than the ConfiguredSize. The DataSetMessageis padded with bytes with value zero.

The keep-alive message does not add any additional fields. The message and the related headers are shown in Figure 35.

image038.png

Figure 35– KeepAlive message

If the sequence number is contained in the header, the sequence number provides the next expected sequence number for the DataSetWriter.

The encoding of the DataSetMessagefields is handled like a Structure DataTypewhere the DataSetfields are handled like Structurefields and fields with Structure DataTypeare handled like nested structures but in addition the fields are padded to the maximum size indicated by ArrayDimensionsor MaxStringLength.

All restrictions for the encoding of Structure DataTypesalso apply to the RawData Field Encoding.

A DataSetfield is encoded in the DataTypeand ValueRankspecified in the DataSetMetaDatafor the DataSet. The following special handling shall be applied to ensure a fixed offset of the fields in the DataSetMessage.

  • If theDataTypeof a DataSetfield or a Structurefield is Stringor ByteStringand the actual size is smaller than the maximum possible size indicated by the MaxStringLength, the field shall be padded with bytes with value zero.
  • If the ValueRankis OneDimension(1) or n>1 and the actual size of a dimension in ArrayDimensionsis smaller than the maximum possible size indicated by the dimensions, the field shall be padded with bytes with value zero for each dimension.
  • If the DataSetfield or Structurefield is a Structurewith optional fields, the EncodingMaskis encoded followed by all fields. Any optional field that is not present is encoded as padding with bytes with value zero. The size of the padding equals to the size needed to encode the field if it were present.
  • If the DataSetfield or Structurefield is a Union, the encoding of the selected field is padded with bytes with value zero to the size of the longest Unionfield, when encoded using the rules in this chapter. The case when no field is selected is treated as if there was an encoded field whose encoded size is zero.

The following restrictions apply to the RawDatafield encoding.

The DataSetMessagevalid bit 0 in DataSetFlags1shall be set to false if the fields do not fulfil these requirements at the time the DataSetMessageis created.

Discovery announcement messages are sent from the Publisherto the Subscribersand they can be sent through any Message Oriented Middlewareand protocol mapping.

Discovery announcement messages are used to inform Subscribersabout configuration changes in the Publisher. They are sent by the Publisherin the case of a configuration change. A Publisher can also be configured to send the discovery announcement messages periodically. A Message Oriented Middlewaremay be able to persist the latest announcement message for Subscribers.

Discovery probe messages are sent from Subscriberto Publisherand they are limited to Message Oriented Middlewareand protocol mappings that support such a back channel. A discovery probe is typically answered with one or more discovery announcement messages.

Depending on the used Message Oriented Middlewareand the protocol mapping, it may be possible and required for the Subscriberto request discovery announcement messages by sending discovery probe messages. One use case is a non reliable transport where the Subscriberdid not receive the message or the Subscriberwas not available at the time the Publishersent the discovery announcement. Another use case is the collection of initial knowledge about a Publisher. Some discovery announcement messages may only be sent as result of a discovery probe message.

Discovery in a global scope requires unique PublisherIds. Publishersshall use the default PublisherIdsas defined in 6.2.7.1for the following discovery messages.

These messages use the standard discovery address if defined for the transport protocol mapping like the IANA registered IPv4 multicast address for UDP.

Other announcements below PubSubConnectionlevel can use different PublisherIdsfor different transport protocol mappings. Such PubSubConnectionspecific PublisherIdscould be two Byte PublisherIdsfor the Ethernettransport protocol mapping. These PublisherIdsare known from the payload of the PubSubConnectionconfiguration announcement messages.

The NetworkMessage flags used with the discovery probe messages shall use the following bit values.

  • UADPFlagsbits 5 and 6 shall be false, bits 4 and 7 shall be true
  • ExtendedFlags1bits 3, 5 and 6 shall be false, bits 4 and 7 shall be true
  • ExtendedFlags2bit 2 shall be true, all other bits shall be false

The setting of the flags ensures a known value for the first three bytes plus the PublisherId in the NetworkMessageon the Publisheras receiver. The actual security settings for the NetworkMessageare indicated by the SecurityHeader.

A variety of rules are used to reduce the amount of traffic on the network in the case of multicast or broadcast communication.

A Subscribershould cache configuration information for PublisherIdand DataSetWriterIdsof interest.

If a Subscriberrequires information from Publishersafter a startup or version change detection, discovery probes shall be randomly delayed in the range of 100 ms to 500 ms. The probe shall be skipped if the information is already received during this time or another Subscribersent already a probe and the announcement to this probe is used.

A Subscribershall wait for a announcement at least 500 ms. As long as not all announcements are received, the Subscriber requests the missing information. It should double the time period between following probes until all needed announcements are received or denied. The maximum period is Subscriberspecific.

A Publishershall delay subsequent announcements for a combination of probe type and identifier like the DataSetWriterIdfor at least 500 ms. Duplicate probes, that have not yet been responded to, shall be discarded by the Publisher. The maximum delay is Publisherspecific.

If the Publisherreceives discovery probes for different DataSetWritersin one WriterGroup, the Publishershall send one aggregated discovery announcement.

The encoding of the discovery probeheader structure is specified in Table 146.

Table 146– Discovery probeheader structure

Name

Type

Description

ProbeType

Byte

The following types of discovery probe messages are defined.

0Reserved

1 Publisherinformation probe message (see 7.2.2.6.3.4)

2FindApplications probe message.The message type does not have additional fields. The PublisherIdis set to NULL.

The encoding of the Publisher information probe message structure is specified in Table 147.

Table 147– Publisher information probe message structure

Name

Type

Description

InformationType

Byte

The following types of Publisherinformation probes are defined.

0Reserved

1 Publisher Server Endpoints

No additional fields are defined.

The information is provided with the Publisher Endpoints announcement message defined in 7.2.2.6.4.3.

2 DataSetMetaData

The settings for this InformationTypeare defined in Table 148.

The information is provided with the DataSetMetaData announcement message defined in 7.2.2.6.4.4.

3 DataSetWriterconfiguration

The settings for this InformationTypeare defined in Table 148.

The information is provided with the DataSetWriterconfiguration announcement message defined in 7.2.2.6.4.5.

4 WriterGroupconfiguration

The settings for this InformationTypeare defined in Table 149

The information is provided with the DataSetWriterconfiguration announcement message defined in 7.2.2.6.4.5.

5 PubSubConnectionsconfiguration

The settings for this InformationTypeare defined in Table 150

The information is provided with the PubSubConnection configuration announcement message defined in 7.2.2.6.4.6.

The additional field for DataSetWriterrelated InformationTypein a Publisherinformation probe message are specified in Table 148.

Table 148– DataSetWriter settings for Publisher information probe

Name

Type

Description

DataSetWriterIds

UInt16[]

List of DataSetWriterIdsthe information is requested for.

The field is encoded as Arraywith number of elements encoded as Int32value.

For DataSetMetaDataprobes, the Publishersends one discovery announcement NetworkMessagefor each requested DataSetWriterId.

For DataSetWriterconfiguration probes, the DataSetWritersthat belong to one WriterGroupare sent together in one DataSetWriterconfiguration message. If more than one WriterGroupis affected, this results in a DataSetWriterconfiguration message per WriterGroup.

The additional fields for WriterGrouprelated InformationTypein a Publisherinformation probe message are specified in Table 149.

Table 149– WriterGroup settings for Publisher information probe

Name

Type

Description

WriterGroupId

UInt16

This option allows a Publisherinformation probe for a WriterGroup and the contained DataSetWriters if only the WriterGroupIdis known from NetworkMessages.

For WriterGroupconfiguration probes, the DataSetWritersthat belong to the WriterGroupare sent together in one DataSetWriterconfiguration message.

IncludeDataSetWriters

Boolean

Flag indicating if the DataSetWritershould be contained in the PubSubConnectionconfiguration announcementmessage.

The additional fields for PubSubConnectionconfiguration in a Publisherinformation probe message are specified in Table 150.

Table 150– PubSubConnections settings for Publisher information probe

Name

Type

Description

TransportProfileUris

String []

Filter criteria for the PubSubConnections to return in the PubSubConnection configuration announce message.

If TransportProfileUris are set, only PubSubConnectionwith matching TransportProfileUrishall be returned.

If the TransportProfileUris is null or empty, all PubSubConnectionsare returned.

IncludeWriterGroups

Boolean

Flag indicating if the WriterGroupsshould be contained in the PubSubConnectionconfiguration announcementmessage.

IncludeDataSetWriters

Boolean

Flag indicating if the DataSetWritersshould be contained in the PubSubConnectionconfiguration announcementmessage.

This flag is ignored if IncludeWriterGroupsis false.

Setting this flag increases the size of the PubSubConnectionconfiguration announcementmessage and it is more likely that max message sizes are exceeded.

The NetworkMessage flags used with the discovery announcement messages shall use the following bit values.

The setting of the flags ensures a known value for the first three bytes plus the PublisherId in the NetworkMessage, except for the Chunkbit 0 in ExtendedFlags2. The actual security settings for the NetworkMessageare indicated by the SecurityHeader.

The encoding of the discovery announcementheader structure is specified in Table 151.

Table 151– Discovery announcementheader structure

Name

Type

Description

AnnouncementType

Byte

The following types of discovery announcement messages are defined.

0Reserved

1Publisher Endpoints message (see 7.2.2.6.4.3)

2DataSetMetaData message (see 7.2.2.6.4.4)

3DataSetWriter configuration message (see 7.2.2.6.4.5)

4PubSubConnection configuration message (see 7.2.2.6.4.6)

5 OPC UA Application information message (see 7.2.2.6.4.7)

SequenceNumber

UInt16

Sequence number, incremented by exactly one, for each discovery announcement sent in the scope of a PublisherId.

The encoding of the available Endpointsof a Publisheris specified in Table 152.

Table 152– Publisher Endpoints announcement message structure

Name

Type

Description

Endpoints

EndpointDescription[]

The OPC UA Server Endpointsof the Publisher. The EndpointDescriptionis defined in OPC 10000-4.

The field is encoded as Arraywith number of elements encoded as Int32value.

statusCode

StatusCode

Status code indicating the capability of the Publisherto provide Endpoints.

The encoding of the DataSetmetadata message structure is specified in Table 153. It contains the current layout and DataSetMetaDatafor the DataSet.

The ConfigurationVersionin the DataSetMessage header shall match the ConfigurationVersionin the DataSetMetaData.

The Publishershall send this message without a corresponding discovery probe if the DataSetMetaDatachanged for the DataSet.

Table 153– DataSetMetaData announcement message structure

Name

Type

Description

DataSetWriterId

UInt16

DataSetWriterIdof the DataSetdescribed with the MetaData.

MetaData

DataSetMetaDataType

The current DataSetmetadata for the DataSetrelated to the DataSetWriterId. The DataSetMetaDataTypeis defined in 6.2.3.2.2.

statusCode

StatusCode

Status code indicating the capability of the Publisherto provide MetaDatafor the DataSetWriterId.

The encoding of the DataSetWriterconfiguration data message structure is specified in Table 154. It contains the current configuration of the WriterGroupand the DataSetWriterfor the DataSet.

The Publishershall send this message without a corresponding discovery probe if the configuration of the WriterGroupchanged.

Table 154– DataSetWriter configuration announcement message structure

Name

Type

Description

DataSetWriterIds

UInt16[]

DataSetWriterIdscontained in the configuration information.

The field is encoded as Arraywith number of elements encoded as Int32value.

DataSetWriterConfig

WriterGroupDataType

The current WriterGroupand DataSetWritersettings for the DataSetrelated to the DataSetWriterId. The WriterGroupDataTypeis defined in 6.2.6.7.

The field DataSetWritersof the WriterGroupDataTypeshall contain only the entry for the requested or changed DataSetWritersin the WriterGroup.

The configuration properties shall not be included in the WriterGroupDataTypeand DataSetWriterDataType.

statusCodes

StatusCode[]

Status codes indicating the capability of the Publisherto provide configuration information for the DataSetWriterIds. The size of the array shall match the size of the DataSetWriterIdsarray.

The encoding of the PubSubConnectionconfiguration announcementmessage structure is specified in Table 155. It contains an array of PubSubConnectionsconfigured in the OPC UA Application.

Table 155– PubSubConnection configuration announcement message structure

Name

Type

Description

PubSubConnections

PubSubConnectionDataType []

PubSubConnections configured for the OPC UA Application.

The PubSubConnectionDataType is defined in 6.2.7.5.1.

The ReaderGrouplists in PubSubConnectionDataTypeshall be empty.

The WriterGrouplist shall be contained, if the IncludeWriterGroupsis true in the PubSubConnection information probe message.

The DataSetWriterlists in the WriterGroupsshall be contained, if the IncludeDataSetWriters is true in the PubSubConnection information probe message.

The configuration properties shall not be included in the PubSubConnectionDataType, WriterGroupDataTypeand DataSetWriterDataType.

The encoding of the OPC UA Applicationinformation announcementmessage structure is specified in Table 156.

Table 156– OPC UA Applicationinformation announcement message structure

Name

Type

Description

ApplicationInformationType

UInt16

The following types of application information are defined.

0Reserved

1Application description (see Table 157)

The encoding of the OPC UA Applicationdescription message fields for ApplicationInformationType1 is specified in Table 157. It contains the ApplicationDescriptionand the capabilities.

Table 157– ApplicationInformationType application description fields

Name

Type

Description

ApplicationDescription

ApplicationDescription

ApplicationDescriptionfor the OPC UA Application. The ApplicationDescription DataTypeis defined in OPC 10000-4.

capabilities

String[]

The list of capability identifiers for the application. The allowed capability identifiers are defined in OPC 10000-12.

JSON is a format that uses human readable text. It is defined in IETF RFC 8254.

The JSON based message mapping allows OPC UA Applicationsto interoperate with web and enterprise software that use this format and do not understand OPC UA specific encodings.

Each JSON NetworkMessagecontains one or more JSON DataSetMessages. The JSON NetworkMessageis a JSON object with the fields defined in Table 158.

Table 158– JSON NetworkMessage definition

Name

Type

Description

MessageId

String

A globally unique identifier for the message. The unique identifier can be created by converting a Guidto a Stringor through another algorithm that creates a unique string.

This value is mandatory.

MessageType

String

This value shall be “ua-data”.

This value is mandatory.

PublisherId

String

A unique identifier for the Publisher. It identifies the source of the message.

This value is optional. The presence of the value depends on the setting in the JsonNetworkMessageContentMask.

The source is the PublisherIdon a PubSubConnection(see 6.2.7.1).

If the PublisherIdis a UInteger, the UIntegervalue is converted to a Stringwithout leading zeros.

DataSetClassId

String

The DataSetClassIdassociated with the DataSetsin the NetworkMessage. The DataSetClassIdis a Guidand shall be converted to a String.

This value is optional. The presence of the value depends on the setting in the JsonNetworkMessageContentMask.

If specified, all DataSetMessagesin the NetworkMessageshall have the same DataSetClassId.

The source is the DataSetClassIdon the PublishedDataSet(see 6.2.3.3) associated with the DataSetWritersthat produced the DataSetMessages.

Messages

*

A JSON array of JSON DataSetMessages (see 7.2.3.3).

This value is mandatory.

All fields with a concrete DataTypedefined are encoded using reversible OPC UA JSON Data Encodingdefined in OPC 10000-6.

The fields in the JSON NetworkMessageare controlled by the NetworkMessageContentMaskof the JSON NetworkMessagemapping(see 6.3.2.1.1).

If the NetworkMessageHeaderbit of the NetworkMessageContentMaskis not set, the NetworkMessageis the contents of the Messagesfield (e.g. a JSON array of DataSetMessages).

If the DataSetMessageHeaderbit of the NetworkMessageContentMaskis not set, the content of the Messagesfield is an array of content from the Payloadfield for each DataSetMessage(see 7.2.3.3).

If the SingleDataSetMessagebit of the NetworkMessageContentMaskis set, the content of the Messagesfield is a JSON object containing a single DataSetMessage.

If theNetworkMessageHeaderand theDataSetMessageHeaderbits are not setandSingleDataSetMessage bit is set, the NetworkMessageis a JSON object containing the set of name/value pairs defined for a single DataSet.

If the JSON encoded NetworkMessagesize exceeds the Brokerlimits the message is dropped and a PubSubTransportLimitsExceeded Eventis reported.

A DataSetMessageis produced by a DataSetWriterand contains list of name/value pairs which are specified by the PublishedDataSet associated with theDataSetWriter. The contents of the DataSetMessageare formally described by a DataSetMetaData Object. A DataSetMessageis a JSON object with the fields defined in Table 159.

A key frame DataSetMessageor an event based DataSetMessagecontains name and value for all fields of the DataSet.

A delta frame DataSetMessagecontains only name and value for the changed fields.

DataSetWriters may periodically provide keep-alive messages which are DataSetMessages without any Payloadfield.

Table 159– JSON DataSetMessage definition

Name

Type

Description

DataSetWriterId

UInt16

An identifier for DataSetWriterwhich created the DataSetMessage.

This value is optional. The presence of the value depends on the setting in the JsonDataSetMessageContentMask.

It is unique within the scope of a Publisher.

DataSetWriterName

String

The name of the DataSetWriterwhich created the DataSetMessage.

The value is optional. The presence of the value depends on the setting in the JsonDataSetMessageContentMask.

SequenceNumber

UInt32

Sequence number, incremented by exactly one, assigned to the DataSetMessage by the DataSetWriter.

This value is optional. The presence of the value depends on the setting in the JsonDataSetMessageContentMask.

Subscribersshall discard the records they keep for sequence numbers if they do not receive messages with the expected SequenceNumberfor two times the keep alive time to deal with Publishersor brokers that are out of service and were not able to continue from the last used SequenceNumber.

MetaDataVersion

ConfigurationVersionDataType

The version of the DataSetMetaData which describes the contents of the Payload.

This value is optional. The presence of the value depends on the setting in the JsonDataSetMessageContentMask.

Timestamp

DateTime

The time the DataSetMessagewas created.

This value is optional. The presence of the value depends on the setting in the JsonDataSetMessageContentMask.

Status

StatusCode

The overall status of the DataSetMessage.The dependencies to the status of DataSetfields are defined in Table 26.

This value is optional. The presence of the value depends on the setting in the JsonDataSetMessageContentMask.

MessageType

String

Possible values are “ua-keyframe”, “ua-deltaframe”, “ua-event” and “ua-keepalive”. The presence of the value depends on the setting in the JsonDataSetMessageContentMask.

Payload

Object

A JSON object containing the name-value pairs specified by the PublishedDataSet.

The format of the value depends on the DataTypeof the field and the flags specified by the DataSetFieldContentMask.

All fields with a concrete DataTypeare encoded using reversible OPC UA JSON Data Encodingdefined in OPC 10000-6.

The fields in the DataSetMessageare specified by the DataSetFieldContentMaskin the DataSetWriterparameters.

The format of the field values in the Payloaddepend on the setting of the ReversibleFieldEncodingflag in the DataSetMessageContentMask.

The JSON message mapping defines only one optional discovery message for the exchange of the DataSetMetaData. The main purpose is the exchange of additional information not contained in the DataSetMessageslike Propertiesfor the DataSetfields.

DataSetMetaDatadescribe the content a DataSetpublished by a DataSetWriter. More specifically, it specifies the names and data types of the values that shall appear in the Payloadof a DataSetMessage.

When the DataSetMetaData of a DataSet changes, the DataSetWriter may be configured to publish the updated value through the mechanism defined by the transport protocol mapping.

The DataSetWriterIdand Versionfields in a DataSetMessage are used to correlate a DataSetMessagewith a DataSetMetaData.

A DataSetMetaDatais a JSON object with the fields defined in Table 160.

Table 160– JSON DataSetMetaData definition

Name

Type

Description

MessageId

String

A globally unique identifier for the message.

This value is mandatory.

MessageType

String

This value shall be “ua-metadata”.

This value is mandatory.

PublisherId

String

A unique identifier for the Publisher. It identifies the source of the message.

This value is mandatory.

DataSetWriterId

UInt16

An identifier for DataSetWriterwhich published the DataSetMetaData.

This value is mandatory.

It is unique within the scope of a Publisher.

MetaData

DataSetMetaDataType

The metadata as defined in 6.2.3.2.2.

This value is mandatory.

DataSetWriterName

String

The name of the DataSetWriter.

All fields with a concrete DataTypeare encoded using reversible OPC UA JSON Data Encodingdefined in OPC 10000-6.

Subclause 7.3lists 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 PubSubConnectionfor UDP shall have a unique Addressacross all PubSubConnectionsof an OPC UA Application.

For OPC UA UDP it is recommended to limit the MaxNetworkMessageSizeplus additional headers to a MTU size. The number of frames used for a UADP NetworkMessageinfluences the probability that UADP NetworkMessagesget 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 MaxNetworkMessageSizeplus additional headers shall be limited to 65535 Byte.

The transport of a UADP NetworkMessagein a UDP packet is defined in Table 161.

Table 161– 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 DiscoveryAddresshas the following form:

opc.udp://224.0.2.14

The default DiscoveryMaxMessageSizefor UDP is 4096 bytes.

The transport protocol URL for UDP multicast and broadcast communication is configured on a PubSubConnectionfor Publisherand Subscriber. The Addressparameter for a PubSubConnectionis defined in 6.2.7.3.

The Urlfield in the Addressis used as destination address for NetworkMessagessent as UDP datagram. The Addressis also used to receive UDP datagrams from the multicast IP address. All DataSetWritersand DataSetReadersthat send to and receive from the multicast IP address shall be configured on one PubSubConnection. The Addressparameter forWriterGroupdatagram TransportSettingsshall be null. If an Addressis configured on a WriterGroup, the WriterGroup PubSubStateshall be Error. The NetworkInterfacefield in the Addressis required if more than one network interface is available.

The syntax of the UDP transport protocol URL used in the Addresshas 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 NetworkMessagesto 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 Applicationnetworks.

OPC UA Applicationsshall 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 Subscriberis configured on the PubSubConnectionand the address information for the Publisheris configured on the WriterGroup.

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

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

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

The destination address is configured on the datagram TransportSettingsof a WriterGroup. The Addressparameter for a WriterGroupdatagram TransportSettingis defined in 6.4.1.3.4. The Addressparameter forWriterGroupdatagram TransportSettingsshall be configured. If no Addressis configured on a WriterGroup, the WriterGroup PubSubStateshall be Error. The NetworkInterfacefield in the Addressis not required and should be null or empty and shall be ignored.

The syntax of Url field in the WriterGroupdatagram TransportSettings Addressparameter 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 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.

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

The syntax of the Ethernet transporting protocol URL used in the Addressparameter defined in 6.2.7.3has 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 NetworkMessagein an Ethernet II frame is defined in Table 162.

Table 162– 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 MaxNetworkMessageSizeand the DiscoveryMaxMessageSizeplus additional headers shall be limited to an Ethernet frame size of 1522 Byte.

Note: The MaxNetworkMessageSizeis 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 Brokerthat relays messages between applications that cannot communicate directly.

Publisherssend AMQP messages to AMQP endpoints. Subscribers listen to AMQP endpoints for incoming messages. If a Brokeris involved it may persist messages so they can be delivered even if the subscriber is not online. Brokersmay 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.2and a JSON message mapping defined in 7.2.2.6.4.7. AMQP Brokers have an upper limit on message size. The limit is defined by the AMQP field max-message-size. The mechanism for handling NetworkMessagesthat exceed the Brokerlimits depends on the MessageMapping. For MessageMappingsthat support chunking, the NetworkMessageshall be broken into multiple chunks. The chunk size plus the AMQP header should not exceed the AMQP max-message-size. For MessageMappingsthat do not support chunking, the NetworkMessagesexceeding the maximum size mut be skipped. Diagnostic information for such error scenarios are provided through the Eventsof the type PubSubTransportLimitsExceedEventTypedefined in 9.1.13.2and through the FailedTransmissionscounter of the PubSubDiagnosticsWriterGroupTypedefined in 9.1.11.9.

Security with AMQP is primary provided by a TLS connection between the Publisheror Subscriberand the AMQP Broker, however, this requires that the AMQP Brokerbe 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 NetworkMessagesand binary message encoding defined in 7.2.2.3. 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 Addressparameter defined in 6.2.7.3has 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 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 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 WriterGroupand DataSetWriter.

The properties are defined through the KeyValuePairarray in the ConnectionProperties WriterGroupPropertiesand DataSetWriterProperties. The NamespaceIndexof the QualifiedNamein the KeyValuePairshall be 0 for AMQP standard properties. The Nameof the QualifiedNameis 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 Valueof the KeyValuePairis converted to an AMQP data type using the rules defined in Table 165. 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 BrokerTransportQualityOfServicevalues as follows:

If the KeepAliveTimeis 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 KeepAliveTimeis specified, the implementation should set a reasonable default value.

When setting the maximum message sizes for the Link, the MaxNetworkMessageSizeof the PubSubGroupshall 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 Publisheror Subscriberis 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 163describes how these fields shall be populated when an AMQP message is constructed.

Table 163– 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.1and 7.3.4.8.3.

The subjectdefines 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 WriterGroupor DataSetWriterthrough the KeyValuePairarray in the WriterGroupPropertiesand DataSetWriterProperties. The NamespaceIndexof the QualifiedNamein the KeyValuePairshall be 0 for AMQP standard message properties. The Nameof the QualifiedNameis constructed from a message prefix and the AMQP property name with the following syntax.

Name = message-<AMQP property name>

Table 164defines the AMQP standard message properties.

Table 164– 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 DataSetWriterPropertiesto the current time of the DataSetMessagecreation.

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 DataSetMessagecreation if the message-creation-time (Boolean) in the DataSetWriterPropertiesis 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 QualifiedNameshall be the ApplicationUri.

The AMQP message header shall include additional promoted fields of the DataSetas a list of name-value pairs. DataSetfields with the PromotedFieldflag set in the FieldMetaData fieldFlagsare copied into the AMQP header. The FieldMetaData Structureis defined in 6.2.3.2.3. Promoted fields shall always be included in the header even if the DataSetMessagebody 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 a field is added to the header it is converted to an AMQP data type using the rules defined in Table 165. If there is no rule defined for the data type, the field shall not be included.

Table 165– 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.2.6.4.7.

The corresponding MIME type is application/json.

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

The corresponding MIME type is application/opcua+uadp.

If the encoded AMQP message size exceeds the Brokerlimits it shall be broken into multiple chunks as described in 7.2.2.4.4.

It is recommended to create the MetaDataQueueNameas described in 6.4.2.5.5by appending the text “$Metadata” to the related QueueName.

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.