Clause 7 specifies the mapping between the PubSub concepts described in clause 5 and the PubSub configuration parameters defined in clause 6 to concrete message mappings and transport protocol mappings that can be used to implement them.
DataSetMessage mappings, NetworkMessage mappings and transport protocol mappings are combined together to create transport profiles defined in OPC 10000-7. All PubSub applications 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.
MessageTypes define the structure and semantics of NetworkMessages. NetworkMessages with different MessageTypes are necessary to support the discovery of Publisher configuration information and the reporting of live data and events.
The defined MessageTypes are listed in Table 150.
Table 150 – PubSub MessageTypes
|
MessageType |
Description |
|
DataSetMessage |
Application data or events supplied by the Publisher as DataSet. |
|
DataSetMetaData |
Discovery message with content and semantics of a DataSetMessage |
|
ApplicationDescription |
Discovery message with OPC UA application description and capabilities of the Publisher. |
|
ServerEndpoints |
Discovery message with the OPC UA server endpoints of the Publisher. |
|
Status |
Discovery message with the current operational status of the PubSubConnection. |
|
PubSubConnection |
Discovery message with the PubSubConnection configured in the Publisher including WriterGroups and DataSetWriters for data and events. |
|
ActionRequest |
Action execution request message sent by the Requestor of the Action to a Responder. |
|
ActionResponse |
Result of an Action execution sent by the Responder of the Action to the Requestor. |
|
ActionMetaData |
Discovery message with Metadata describing the Action request and response for a Requestor. |
|
ActionResponder |
Discovery message with the Responder related PubSubConnection information for Actions configured in the Publisher including WriterGroups and DataSetWriters for Actions. |
Each message mapping defines the structure of each supported MessageType. The mechanism for identifying the MessageType associated with a NetworkMessage is specific to the message mapping. The mapping to UADP messages is defined in 7.2.4.2. The mapping to JSON messages is defined in 7.2.5.2.
The discovery messages are required to send discovery information from the Publishers to the Subscribers that do not have out of band knowledge about available Publishers.
A Message Oriented Middleware where retained messages are supported can use a known addressing schema for queues or topics to provide discovery messages to Subscribers. Such a Topic tree is defined for the MQTT transport protocol mapping in 7.3.5.7. The mapping of MessageTypes for Topics is defined in 7.3.5.7.2.
The UADP message mapping defines also discovery probe messages to request discovery information in a Message Oriented Middleware where retained messages are not available.
SequenceNumber fields are defined in different headers of the UADP or JSON Message Mapping.
A SequenceNumber is a monotonically increasing number assigned to messages headers represented by an unsigned integer of width N which is further specified in Table 151. 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 151 – 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 |
Subscribers shall discard the records they keep for sequence numbers if they do not receive messages for two times the message receive timeout to deal with Publishers or brokers that are out of service and were not able to continue from the last used SequenceNumber.
The UADP message mapping uses optimized OPC UA Binary encoding defined in OPC 10000-6 and 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 DataSetMessage types and data encodings. Available layouts with standard settings and the corresponding URI Strings for UADP are defined in A.2.
Some optional fields like timestamps provide information that is not necessary for the processing of the messages on the Subscriber side. Other optional fields like PublisherId, DataSetWriterId or sizes of DataSetMessages are typically necessary for the processing of messages in generic Subscribers. If such fields are not present, the Subscriber must know the missing information from the DataSetReader configuration. One scenario is that a Publisher is sending NetworkMessages with a fixed layout of the payload. In this case the DataSetWriterId, the offset and size of the DataSetMessages is known from the DataSetReader configuration. The identification is done in this case by the group header with the WriterGroupId and NetworkMessageNumber. The UADP-Periodic-Fixed header layout for this scenario is defined in A.2.1.
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 A defines 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 Publisher should support all variations it allows through configuration. The required set of features is defined through profiles in OPC 10000-7.
A Subscriber shall be able to process all possible NetworkMessages and shall be able to skip information the Subscriber is not interested in. The Subscriber may not support all security policies. The capabilities related to processing different DataSet encodings 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-6 including 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 mapping of MessageTypes to UADP NetworkMessage type and the reference to the detailed definition is listed in Table 152.
Table 152 – UADP MessageType mapping
|
MessageType |
UADP NetworkMessage type |
Specification Reference |
|
DataSetMessage |
DataSetMessage payload |
|
|
DataSetMetaData |
Discovery DataSetMetaData announce |
Defined in 7.2.4.6.4. |
|
ApplicationDescription |
Discovery Application description announce |
Defined in 7.2.4.6.5. |
|
ServerEndpoints |
Discovery Publisher Endpoints announce |
Defined in 7.2.4.6.6. |
|
Status |
Discovery status announce |
Defined in 7.2.4.6.7. |
|
PubSubConnection |
Discovery PubSubConnection configuration announce |
Defined in 7.2.4.6.8. |
|
ActionRequest |
Action request message |
Defined in 7.2.4.5.9 |
|
ActionResponse |
Action response message |
Defined in 7.2.4.5.10 |
|
ActionMetaData |
Discovery ActionMetaData announce |
Defined in 7.2.4.6.11 |
|
ActionResponder |
Discovery ActionResponder configuration announce |
Defined in 7.2.4.6.10 |
The discovery announce messages are required to send discovery information from the Publishers to the Subcribers. The probe messages are used for broker-less transport protocols like UDP or a Message Oriented Middleware where retained messages are not available.
The PubSub communication parameters defined in Clause 6 provide the settings for mapping information from the Publisher into DataSetMessages, settings to send them in NetworkMessages to the Subscribers and settings to process the DataSetMessages on the Subscriber side.
The error handling for the status codes in DataSetMessage headers and DataSetMessage fields is defined in 6.2.11 and 6.2.4.2. This handling of information flows and status codes assumes that the configuration between Publisher and Subscriber is in sync.
In several combinations of settings for the DataSetMessages and NetworkMessages, a Subscriber is able to process received messages without further knowledge of the Publisher side configuration. But most Subscribers need at least the DataSetMetaData to be able to process the received DataSetMessages.
The Publisher side configuration implies two types of contracts necessary for the Subscriber to process messages. The one type of contract is the DataSetMetaData describing the content of a DataSetMessage. The other type of contract provides the communication settings like the DataSetWriterId or offsets inside NetworkMessages. Both type of contracts provide version information that can be included into the DataSetMessages and NetworkMessages.
Several settings in the contracts have corresponding flags or version fields in the messages and a Subscriber can detect mismatches between the contract and the received messages.
The error handling depends on the Subscriber applications. Subscribers that are configured to process certain DataSetMessages often 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 Subscriber shall drop all messages where the configured SecurityMode has a lower number than the received SecurityMode. E.g. if the Subscriber is configured for SecurityMode SIGN it shall drop messages with NONE. A Subscriber may process messages with a higher SecurityMode e.g. it is allowed to process messages with SecurityMode SIGN if it is configured for NONE.
The UADP NetworkMessage header and other parts of the NetworkMessage are shown in Figure 32.
When using security, the payload and the Padding field are encrypted and after that, the whole NetworkMessage is signed if signing and encryption is active. The NetworkMessage shall be signed without being encrypted if only the signing is active.
The UADP NetworkMessage does 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 NetworkMessage for that transport protocol.
Figure 32 – UADP NetworkMessage
The encoding of the UADP NetworkMessage is specified in Table 153.
The NetworkMessageContentMask setting of the Publisher controls the flags in the fields UADPFlags and ExtendedFlags1. The SecurityMode setting of the Publisher controls the security enabled flag of the ExtendedFlags1. The setting of the flags shall not change until the configuration of the Publisher is changed.
Table 153 – UADP NetworkMessage
|
Name |
Type |
Description |
|
UADPVersion |
Bit[0-3] |
Bit range 0-3: Version of the UADP NetworkMessage. The UADPVersion for this specification version is 1. |
|
UADPFlags |
Bit[4-7] |
Bit 4: PublisherId enabled If the PublisherId is enabled, the type of PublisherId is indicated in the ExtendedFlags1 field.If the PublisherId is enabled is false, the ExtendedFlags1 PublisherId Type flags shall be false. Bit 5: GroupHeader enabled Bit 6: PayloadHeader enabled Bit 7: ExtendedFlags1 enabledThe bit shall be false, if ExtendedFlags1 is 0. |
|
ExtendedFlags1 |
Byte |
The ExtendedFlags1 shall be omitted if bit 7 of the UADPFlags is false. If the field is omitted, the Subscriber shall handle the related bits as false. Bit range 0-2: PublisherId Type 000 The PublisherId is of DataType Byte This is the default value if ExtendedFlags1 is omitted 001 The PublisherId is of DataType UInt16 010 The PublisherId is of DataType UInt32 011 The PublisherId is of DataType UInt64 100 The PublisherId is 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 PublisherId Type shall be ignored if bit 4 of the UADPFlags is false. Bit 3: DataSetClassId enabled Bit 4: SecurityHeader enabled If this flag is enabled, the NetworkMessage header includes the SecurityHeader, otherwise the SecurityHeader is omitted. If the SecurityMode in the configuration is SIGN or SIGNANDENCRYPT, this flag shall be set. Bit 5: Timestamp enabled 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 ExtendedFlags2 shall be omitted if bit 7 of the ExtendedFlags1 is false. If the field is omitted, the Subscriber shall handle the related bits as false. Bit 0: Chunk message defined in in 7.2.4.4.4. Bit 1: PromotedFields enabled If Promoted fields are enabled, the number of DataSetMessages in the Network Message shall be one. Bit range 2-4: UADP NetworkMessage type 000 NetworkMessage with DataSetMessage payload defined in 7.2.4.4.4. If the ExtendedFlags2 field is not provided, this is the default NetworkMessage type. 001 NetworkMessage with discovery probe defined in 7.2.4.5.4. 010 NetworkMessage with discovery announcement payload defined in 7.2.4.6. 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: ActionHeader enabled 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 PublisherId shall be omitted if bit 4 of the UADPFlags is false. The Id of the Publisher that sent the data. Valid DataTypes are UInteger and String. The DataType is indicated by bits 0-2 of the ExtendedFlags1. A Subscriber can skip NetworkMessages from Publishers it does not expect NetworkMessages from. PublisherIds are only equal if they have the same DataTypes and equal values. For ActionRequest and ActionResponse messages, the PublisherId of the Responder is used for request and response. |
|
DataSetClassId |
Guid |
The DataSetClassId associated with the DataSets in the NetworkMessage. All DataSetMessages in the NetworkMessage shall have the same DataSetClassId. The DataSetClassId shall be omitted if bit 3 of the ExtendedFlags1 is false. |
|
GroupHeader |
|
The group header shall be omitted if bit 5 of the UADPFlags is false. |
|
GroupFlags |
Byte |
Bit 0: WriterGroupId enabled Bit 1: GroupVersion enabled Bit 2: NetworkMessageNumber enabled Bit 3: SequenceNumber enabled 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 WriterGroup in the Publisher. A Subscriber can skip NetworkMessages from WriterGroups it does not expect NetworkMessages from. This field shall be omitted if bit 0 of the GroupFlags is false. |
|
GroupVersion |
VersionTime |
Version of the header and payload layout configuration of the NetworkMessages sent for the group. This field shall be omitted if bit 1 of the GroupFlags is false. |
|
NetworkMessage Number |
UInt16 |
Unique number of a NetworkMessage across the combination of PublisherId and WriterGroupId within one PublishingInterval. The number is needed if the DataSetMessages for one group are split into more than one NetworkMessage in a PublishingInterval. The value 0 is invalid. This field shall be omitted if bit 2 of the GroupFlags is false. |
|
SequenceNumber |
UInt16 |
Sequence number for each new NetworkMessage as defined in 7.2.3. This field shall be omitted if bit 3 of the GroupFlags is false. |
|
PayloadHeader |
Byte [*] |
The payload header depends on the UADP NetworkMessage type flags defined in the ExtendedFlags2 bit range 2-4. The default is DataSetMessage if the ExtendedFlags2 field is not enabled. The PayloadHeader shall be omitted if bit 6 of the UADPFlags is false. The PayloadHeader is not contained in the payload but it is contained in the unencrypted NetworkMessage header since it contains information necessary to filter DataSetMessages on the Subscriber side. If the payload header is not present for DataSetMessages, the Subscriber must know the number and size of DataSetMessages from the DataSetReader configuration. 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 DataSetMessages is known from the DataSetReader configuration for the combination of WriterGroupId and NetworkMessageNumber. |
|
Timestamp |
DateTime |
The time the NetworkMessage was created. The Timestamp shall be omitted if bit 5 of ExtendedFlags1 is false. The PublishingInterval, the SamplingOffset the PublishingOffset and the Timestamp and PicoSeconds in the NetworkMessage header 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 PicoSeconds field 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 PicoSeconds field shall contain values less than 10 000. The decoder shall treat values greater than or equal to 10 000 as the value ‘9999’. The PicoSeconds shall be omitted if bit 6 of ExtendedFlags1 is false. |
|
PromotedFields |
|
The PromotedFields shall be omitted if bit 1 of the ExtendedFlags2 is false. If the PromotedFields are provided, the number of DataSetMessages in the Network Message shall be one. |
|
Size |
UInt16 |
Total size in Bytes of the Fields contained in the PromotedFields. |
|
Fields |
BaseDataType[ ] |
Array of promoted fields. The size, order and DataTypes of the fields depend on the settings in the FieldMetaData of the DataSetMetaData associated with the DataSetMessage contained in the NetworkMessage. |
|
SecurityHeader |
|
The security header shall be omitted if bit 4 of the ExtendedFlags1 is false. |
|
SecurityFlags |
Byte |
Bit 0: NetworkMessage Signed Bit 1: NetworkMessage EncryptedThe 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 Publisher needs to give Subscribers a 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 SecurityGroup is done through DataSetWriterIds contained in the NetworkMessage. If bit 1 and 2 of the SecurityFlags are 0, the SecurityTokenId shall be 0. |
|
NonceLength |
Byte |
The length of the Nonce used to initialize the encryption algorithm. If bit 1 and 2 of the SecurityFlags are 0, the NonceLength shall 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 MessageNonce are defined for the UADP Message Security in 7.2.4.4.3. |
|
SecurityFooterSize |
UInt16 |
The size of the SecurityFooter. The security footer size shall be omitted if bit 2 of the SecurityFlags is false. |
|
ActionHeader |
|
The Action header shall be omitted if bit 5 of the ExtendedFlags2 is false. The header shall be enabled for ActionRequest and ActionResponse NetworkMessages. The Action execution sequences and execution related request and response message values are defined in 6.2.11.2. |
|
ActionFlags |
Byte |
Bit 0: If enabled, the NetworkMessage is a ActionRequest. If disabled, the NetworkMessage is a ActionResponse Bit 1: ResponseAddress enabled Bit 2: CorrelationData enabled Bit 3: RequestorId enabled Bit 4: TimeoutHint enabled Bits 5-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. |
|
ResponseAddress |
String |
The address used to send the Response messages. This value shall be omitted for Response messages. The handling of the ResponseAddress and default values are defined for the different transport protocol mappings. |
|
CorrelationData |
ByteString |
Data provided by the Requestor in the Request message that is returned to the Requestor in the Response message. |
|
RequestorId |
BaseDataType |
The PublisherId of the Requestor. |
|
TimeoutHint |
Duration |
The timeout used by the Requestor to wait for a Response messages and by the Responder to stop processing the request. This value is mandatory for the Request message. This value is not used for Response messages. |
|
Payload |
Byte [*] |
The payload depends on the UADP NetworkMessage Type flags defined in the ExtendedFlags2 bit range 2-4 and on the Chunk flag defined in the. ExtendedFlags2 bit 0. |
|
SecurityFooter |
Byte [*] |
Optional security footer shall be omitted if bit 2 of the SecurityFlags is 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 KeyNonce for the UADP NetworkMessage depend on the selected SecurityPolicy. The algorithms are defined by SymmetricEncryptionAlgorithm and SymmetricSignatureAlgorithm in 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 GetSecurityKeys method (see 8.3.2). This Method returns 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 154.
Table 154 – 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 155.
Table 155 – 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 MessageNonce as defined in 7.2.3. The sequence number is reset to 1 after the key and SecurityTokenId are updated in the Publisher. |
The message encryption and decryption with AES-CTR mode uses a secret and a counter block. The secret is the EncryptingKey from the key data defined in Table 154. The layout and content of the counter block is defined in Table 156.
Table 156 – 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 Nonce in the SecurityHeader of the NetworkMessage. For AES-CTR mode the length of the SecurityHeader Nonce shall 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 NetworkMessage including any encrypted data. The signature algorithm is specified by the SecurityPolicyUri in OPC 10000-7.
When a Subscriber or a Publisher receives a NetworkMessage, it shall verify the signature before processing the payload. If verification fails, it drops the NetworkMessage.
Other SecurityPolicy may specify different key lengths or cryptography algorithms.
If a NetworkMessage payload with a DataSetMessage need to be split across multiple NetworkMessages, the chunks are sent in multiple NetworkMessages. The PayloadHeader of each NetworkMessage contains the payload header defined in Table 157. The Payload of each NetworkMessage contains the payload defined in Table 158. A chunk NetworkMessage can only contain chunked payload of one DataSetMessage.
If a NetworkMessage payload with a discovery announcement message has to be split across multiple NetworkMessages the chunks are sent with the payload defined in Table 158. The payload header is disabled for discovery probe and discovery announcement NetworkMessages.
Table 157 – Chunked NetworkMessage payload header
|
Name |
Type |
Description |
|
DataSetWriterId |
UInt16 |
DataSetWriterId contained in the NetworkMessage. The DataSetWriterId identifies the PublishedDataSet and the DataSetWriter responsible for sending Messages for the DataSet. A Subscriber can skip DataSetMessages from DataSetWriters it does not expect DataSetMessages from. |
Table 158 – Chunked NetworkMessage payload fields
|
Name |
Type |
Description |
|
MessageSequenceNumber |
UInt16 |
Sequence number of the payload as defined for the NetworkMessage type like DataSetMessageSequenceNumber in a DataSetMessage. NetworkMessages may 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 Subscriber that 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 NetworkMessage payload. The last chunk is detected if ChunkOffset plus 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 NetworkMessage payload 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 NetworkMessage payload in bytes. |
|
ChunkData |
ByteString |
The pieces of the original DataSetMessage or the discovery announcement message are copied into the chunk until the maximum size allowed for a single NetworkMessage is 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 DataSetMessage or discovery announcement message is completely received when all chunks are received and the message can be processed completely. |
The UADP DataSet payload header and other parts of the NetworkMessage are shown in Figure 33.
Different types of DataSetMessage can be combined in on NetworkMessage.
Figure 33 – UADP DataSet payload
The encoding of the UADP DataSet payload header is specified in Table 159. The payload header is unencrypted. This header shall be omitted if bit 6 of the UADPFlags is false.
Table 159 – UADP DataSet payload header
|
Name |
Type |
Description |
|
Count |
Byte |
Number of DataSetMessages contained in the NetworkMessage. The NetworkMessage shall contain at least one DataSetMessage if the NetworkMessage type is DataSetMessage payload. |
|
DataSetWriterIds |
UInt16 [Count] |
List of DataSetWriterIds contained in the NetworkMessage. The size of the list is defined by the Count. The DataSetWriterId identifies the PublishedDataSet and the DataSetWriter responsible for sending Messages for the DataSet. A Subscriber can skip DataSetMessages from DataSetWriters it does not expect DataSetMessages from. |
The DataSet payload is defined in Table 160. The payload is encrypted.
Table 160 – 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 Count in the DataSet payload header. If the payload size exceeds 65535, the DataSetMessages shall be allocated to separate NetworkMessages. If a single DataSetMessage exceeds 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 UADPFlags is false. |
|
DataSetMessages |
DataSetMessage [Count] |
DataSetMessages contained in the NetworkMessage. The size of the list is defined by the Count in the DataSet payload header. The type of encoding used for the DataSetMessages is defined by the DataSetWriter. The encodings for the DataSetMessage are defined in 7.2.4.5.4. |
The DataSetMessage header structure and the relation to other parts in a NetworkMessage is shown in Figure 34.
Figure 34 – DataSetMessage header structure
The encoding of the DataSetMessage header structure is specified in Table 161.
The DataSetFieldContentMask and the DataSetMessageContentMask settings of the DataSetWriter control the flags in the fields DataSetFlags1 and DataSetFlags2. The setting of the flags shall not change until the configuration of the DataSetWriter is changed.
Table 161 – DataSetMessage header structure
|
Name |
Type |
Description |
|
DataSetFlags1 |
Byte |
Bit 0: DataSetMessage is valid. If this bit is set to false, the rest of this DataSetMessage is considered invalid, and shall not be processed by the Subscriber. Bit range 1-2: Field Encoding 00 The DataSet fields are encoded as Variant The Variant can contain a StatusCode instead of the expected DataType if the status of the field is Bad. The Variant can 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.4.5.11. 10 DataValue Field Encoding The DataSet fields are encoded as DataValue. This option is set if the DataSet is 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: DataSetMessageSequenceNumber enabled Bit 4: Status enabled Bit 5: ConfigurationVersionMajorVersion enabled Bit 6: ConfigurationVersionMinorVersion enabled 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 Subscriber shall handle the related bits as false. Bit range 0-3: UADP DataSetMessage type 0000Data Key Frame (see 7.2.4.5.5) If the DataSetFlags2 field is not provided, this is the default DataSetMessage type. 0001Data Delta Frame (see 7.2.4.5.6) 0010Event (see 7.2.4.5.7) 0011Keep Alive (see 7.2.4.5.8) 0101ActionRequest (see 7.2.4.5.9) 0110ActionResponse (see 7.2.4.5.10) 0111Reserved 1xxxReserved Reserved values shall not be used by the sender and the receiver shall skip messages when reserved values are received. Bit 4: Timestamp enabled Bit 5: PicoSeconds included in the DataSetMessage headerThis 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. |
|
DataSetMessageSequenceNumber |
UInt16 |
Sequence number for each new DataSetMessage as defined in 7.2.3. The field shall be omitted if Bit 3 of DataSetFlags1 is false. |
|
Timestamp |
UtcTime |
The time the DataSetMessage was created. The Timestamp shall be omitted if Bit 4 of DataSetFlags2 is false. |
|
PicoSeconds |
UInt16 |
Specifies the number of 10 picoseconds (1,0 e-11 seconds) intervals which shall be added to the Timestamp. The PicoSeconds field 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 PicoSeconds field 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 DataSetFlags2 is false. |
|
Status |
UInt16 |
The overall status of the DataSetMessage. The dependencies to the status of DataSet fields are defined in Table 34. This is the high order 16 bits of the StatusCode DataType representing the numeric value of the Severity and SubCode of the StatusCode DataType. The field shall be omitted if Bit 4 of DataSetFlags1 is false. |
|
ConfigurationVersion MajorVersion |
VersionTime |
The major version of the configuration version of the DataSet used as consistency check with the DataSetMetaData available on the Subscriber side. The field shall be omitted if Bit 5 of DataSetFlags1 is false. |
|
ConfigurationVersion MinorVersion |
VersionTime |
The minor version of the configuration version of the DataSet used as consistency check with the DataSetMetaData available on the Subscriber side. The field shall be omitted if Bit 6 of DataSetFlags1 is false. |
The data key frame DataSetMessage data and related headers are shown in Figure 35.
Figure 35 – Data Key Frame DataSetMessage data
The encoding of the data key frame DataSetMessage structure is specified in Table 162.
If the key frame is a heartbeat DataSetMessage, only the header is encoded but the following structure shall not be encoded into the DataSetMessage. Generic Subscribers can detect heartbeat DataSetMessages if the DataSetMessage size equals the header size. If the DataSetMessage size is not part of the payload header, the DataSetMessage offset configuration is required on Subscriber side to identify a heartbeat DataSetMessage.
Table 162 – Data Key Frame DataSetMessage structure
|
Name |
Type |
Description |
|
FieldCount |
UInt16 |
Number of fields of the DataSet contained in the DataSetMessage. The FieldCount shall be omitted if RawData field encoding is set in the EncodingFlags defined in 7.2.4.5.4. |
|
DataSetFields |
BaseDataType [FieldCount] |
The field values of the DataSet. The field encoding depends on the DataSetFlags1.Field Encoding of the DataSetMessage Header defined in 7.2.4.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 DataSetMessage is padded with bytes with value zero. |
The data delta frame DataSetMessage data and the related headers are shown in Figure 36.
Figure 36 – 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 Publisher shall 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 163.
Table 163 – 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 DataSetMetaData with the configuration version defined in the ConfigurationVersion field. A Publisher shall use an index only once in a DataSetMessage. |
|
FieldValue |
BaseDataType |
The field values of the DataSet. The field encoding depends on the DataSetFlags1.Field Encoding of the DataSetMessage Header defined in 7.2.4.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 DataSetMessage is padded with bytes with value zero. |
The Event DataSetMessage data and the related headers are shown in Figure 37.
Figure 37 – Event DataSetMessage
The encoding of the Event DataSetMessage structure is specified in Table 164.
Table 164 – Event DataSetMessage structure
|
Name |
Type |
Description |
|
FieldCount |
UInt16 |
Number of fields of the DataSet contained in the DataSetMessage. |
|
DataSetFields |
BaseDataType [FieldCount] |
The field values of the DataSet. The fields of Event DataSetMessages shall be encoded as Variant. The Field Encoding DataSetFlags1 of the DataSetMessage header (bit 1 and 2) defined in 7.2.4.5.4 shall be set to false. |
|
Padding |
Byte [*] |
Optional padding added if the encoded DataSetMessage is smaller than the ConfiguredSize. The DataSetMessage is 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 38.
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 Action request DataSetMessage structure is specified in Table 165.
Table 165 – Action request message structure
|
Name |
Type |
Description |
|
ActionTargetId |
UInt16 |
The numeric identifier assigned to the Action target which is unique within one ActionMetaData. It is used to address the Action in combination with the PublisherId and the DataSetWriterId defined by the Responder. |
|
RequestId |
UInt16 |
Request identifier provided by the Requestor in the Request message that is returned to the Requestor in the Response message. |
|
ActionState |
Byte |
Specifies the expected Action state on Responder side. The ActionState enumeration value is encoded as Byte. The details for the use of this value and the relation to other values for a Action execution is defined in 6.2.11.2. |
|
FieldCount |
UInt16 |
Number of fields of the DataSet contained in the DataSetMessage. |
|
DataSetFields |
BaseDataType [FieldCount] |
The field values of the ActionRequest DataSet. The fields of ActionRequest DataSetMessages shall be encoded as Variant or RawData. |
|
Padding |
Byte [*] |
Optional padding added if the encoded DataSetMessage is smaller than the ConfiguredSize. The DataSetMessage is padded with bytes with value zero. |
The encoding of the Action response DataSetMessage structure is specified in Table 166.
Table 166 – Action response message structure
|
Name |
Type |
Description |
|
ActionTargetId |
UInt16 |
The numeric identifier assigned to the Action target which is unique within one ActionMetaData. It is used to address the Action in combination with the PublisherId and the DataSetWriterId defined by the Responder. |
|
RequestId |
UInt16 |
Request identifier provided by the Requestor in the Request message that is returned to the Requestor in the Response message. |
|
ActionState |
Byte |
The current state of this currently running Action. The ActionState enumeration value is encoded as Byte. The details for the use of this value and the relation to other values for a Action execution is defined in 6.2.11.2. |
|
FieldCount |
Uint16 |
Number of fields of the DataSet contained in the DataSetMessage. |
|
DataSetFields |
BaseDataType [FieldCount] |
The field values of the ActionResponse DataSet. The fields of ActionResponse DataSetMessages shall be encoded as Variant or RawData. |
|
Padding |
Byte [*] |
Optional padding added if the encoded DataSetMessage is smaller than the ConfiguredSize. The DataSetMessage is padded with bytes with value zero. |
The encoding of the DataSetMessage fields is handled like a Structure DataType where the DataSet fields are handled like Structure fields and fields with Structure DataType are handled like nested structures but in addition the fields are padded to the maximum size indicated by ArrayDimensions or MaxStringLength. The padding only applies to RawData field encoding.
All restrictions for the encoding of Structure DataTypes also apply to the RawData Field Encoding.
A DataSet field is encoded in the DataType and ValueRank specified in the DataSetMetaData for the DataSet. The following special handling shall be applied to ensure a fixed offset of the fields in the DataSetMessage.
- If the DataType of a DataSet field or a Structure field is String or ByteString and 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 ValueRank is OneDimension (1) or n>1 and the actual size of a dimension in ArrayDimensions is 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 DataSet field or Structure field is a Structure with optional fields, the EncodingMask is 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 DataSet field or Structure field is a Union, the encoding of the selected field is padded with bytes with value zero to the size of the longest Union field, 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.
- If the DataSet field or Structure field is an OptionSet, the length of the two ByteStrings in the OptionSet Structure is defined by highest bit number in the OptionSet definition.
The following restrictions apply to the RawData field encoding.
- Fields shall have MaxStringLength defined in the FieldMetaData if the DataType is String or ByteString. Fields shall have arrayDimensions defined in the FieldMetaData if valueRank has a value of n > 0. This includes Structure fields with such DataTypes or ValueRank.
- DataSet fields and Structure fields shall not have an abstract DataType and shall not allow subtypes.
- DataSet fields and Structure fields shall have a concrete valueRank with values -1 or n > 0.
- DataSet fields and Structure fields shall not have the builtInType NodeId, ExpandedNodeId, QualifiedName, LocalizedText, XmlElement, DiagnosticInfo or DataValue.
- RawField encoding shall only be applied to Data Key Frame DataSetMessages.
- Structure DataTypes shall not have a field that contains the same Structure DataType directly or indirectly.
The DataSetMessage valid bit 0 in DataSetFlags1 shall be set to false if the fields do not fulfil these requirements at the time the DataSetMessage is created.
Discovery announcement messages are sent from the Publisher to the Subscribers and they can be sent through any Message Oriented Middleware and protocol mapping.
Discovery announcement messages are used to inform Subscribers about configuration changes in the Publisher. They are sent by the Publisher in the case of a configuration change. A Publisher can also be configured to send the discovery announcement messages periodically. A Message Oriented Middleware may be able to persist the latest announcement message for Subscribers.
Discovery probe messages are sent from Subscriber to Publisher and they are limited to Message Oriented Middleware and 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 Middleware and the protocol mapping, it may be possible and required for the Subscriber to request discovery announcement messages by sending discovery probe messages. One use case is a non reliable transport where the Subscriber did not receive the message or the Subscriber was not available at the time the Publisher sent 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. Publishers shall use the default PublisherIds as defined in 6.2.7.1 for the following discovery messages.
- OPC UA Application information announcement
- Publisher endpoint announcement
- PubSubConnection configuration announcement
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 PubSubConnection level can use different PublisherIds for different transport protocol mappings. Such PubSubConnection specific PublisherIds could be two Byte PublisherIds for the Ethernet transport protocol mapping. These PublisherIds are known from the payload of the PubSubConnection configuration announcement messages.
The NetworkMessage flags used with the discovery announcement messages shall use the following bit values.
- UADPFlags bits 5 and 6 shall be false, bits 4 and 7 shall be true
- ExtendedFlags1 bits 3, 5 and 6 shall be false, bit 4 and 7 shall be true
- ExtendedFlags2 bit 1 shall be false and the NetworkMessage type shall be discovery announcement
The setting of the flags ensures a known value for the first three bytes plus the PublisherId in the NetworkMessage, except for the Chunk bit 0 in ExtendedFlags2. The actual security settings for the NetworkMessage are indicated by the SecurityHeader.
The encoding of the discovery announcement header structure is specified in Table 167.
Table 167 – Discovery announcement header structure
|
Name |
Type |
Description |
|
AnnouncementType |
Byte |
The following types of discovery announcement messages are defined. 0Reserved 1Publisher Endpoints message (see 7.2.4.6.6) 2DataSetMetaData message (see 7.2.4.6.4) 3DataSetWriter configuration message (see 7.2.4.6.9) 4PubSubConnection configuration message (see 7.2.4.6.8) 5 OPC UA Application information message (see Table 168) 6PubSubConnection configuration message (see 7.2.4.6.8) |
|
SequenceNumber |
UInt16 |
Sequence number, incremented by exactly one, for each discovery announcement sent in the scope of a PublisherId. |
The encoding of the OPC UA Application information announcement message structure is specified in Table 168.
Table 168 – OPC UA Application information announcement message structure
|
Name |
Type |
Description |
|
ApplicationInformationType |
UInt16 |
The following types of application information are defined. 0Reserved 1Application description (see 7.2.4.6.5) 2Status (see 7.2.4.6.7) |
The encoding of the DataSet metadata message structure is specified in Table 169. It contains the current layout and DataSetMetaData for the DataSet.
The ConfigurationVersion in the DataSetMessage header shall match the ConfigurationVersion in the DataSetMetaData.
The Publisher shall send this message without a corresponding discovery probe if the DataSetMetaData changed for the DataSet.
Table 169 – DataSetMetaData announcement message structure
|
Name |
Type |
Description |
|
DataSetWriterId |
UInt16 |
DataSetWriterId of the DataSet described with the MetaData. |
|
MetaData |
DataSetMetaDataType |
The current DataSet metadata for the DataSet related to the DataSetWriterId. The DataSetMetaDataType is defined in 6.2.3.2.3. |
|
statusCode |
StatusCode |
Status code indicating the capability of the Publisher to provide MetaData for the DataSetWriterId. |
The encoding of the OPC UA Application description message fields for ApplicationInformationType equals 1 is specified in Table 170. It contains the ApplicationDescription and the capabilities.
Table 170 – ApplicationInformationType application description fields
|
Name |
Type |
Description |
|
ApplicationDescription |
ApplicationDescription |
ApplicationDescription for the OPC UA Application. The ApplicationDescription DataType is 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. |
The encoding of the available Server Endpoints of a Publisher is specified in Table 171.
Table 171 – Publisher Endpoints announcement message structure
|
Name |
Type |
Description |
|
Endpoints |
EndpointDescription[] |
The OPC UA Server Endpoints of the Publisher. The EndpointDescription is defined in OPC 10000-4. The field is encoded as Array with number of elements encoded as Int32 value. |
|
statusCode |
StatusCode |
Status code indicating the capability of the Publisher to provide Endpoints. |
The encoding of the status message fields for ApplicationInformationType equals 2 is specified in Table 172.
Table 172 – ApplicationInformationType status fields
|
Name |
Type |
Description |
|
IsCyclic |
Boolean |
If TRUE the Publisher periodically updates the status. If FALSE the Middleware is responsible for detecting changes to the status. |
|
Status |
PubSubState |
The current state of the PubSubConnection. This value is mandatory. |
|
NextReportTime |
UtcTime |
When the Publisher expects to send the next update. The field is present if IsCyclic=TRUE. The field is not present if IsCyclic=FALSE. |
|
Timestamp |
UtcTime |
When the message was sent to the Middleware. The field is present if IsCyclic=TRUE. The field is not present if IsCyclic=FALSE. |
IsCyclic is set to FALSE if a PublisherId is used exclusively by a single application and the Message Oriented Middleware can detect when Publishers go offline. In these cases, the Publisher sends updates only when its state changes and the Message Oriented Middleware will send an update with PubSubState Error if the Publisher goes offline.
If IsCyclic is set to TRUE the Publisher only reports while they are Operational. The NextReportTime indicates when the Publisher will send an update. If the Subscriber does not receive updates and the NextReportTime is in the past, the Subscriber assumes the PubSubState Error.
The encoding of the PubSubConnection configuration announcement message structure is specified in Table 173. It contains an array of PubSubConnections configured in the OPC UA Application.
Table 173 – 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 ReaderGroup lists in PubSubConnectionDataType shall be empty. The WriterGroup list shall be contained, if the IncludeWriterGroups is true in the PubSubConnection information probe message. The DataSetWriter lists in the WriterGroups shall be contained, if the IncludeDataSetWriters is true in the PubSubConnection information probe message. The configuration properties shall not be included in the PubSubConnectionDataType, WriterGroupDataType and DataSetWriterDataType. |
The encoding of the DataSetWriter configuration data message structure is specified in Table 174. It contains the current configuration of the WriterGroup and the DataSetWriter for the DataSet.
The Publisher shall send this message without a corresponding discovery probe if the configuration of the WriterGroup changed.
Table 174 – DataSetWriter configuration announcement message structure
|
Name |
Type |
Description |
|
DataSetWriterIds |
UInt16[] |
DataSetWriterIds contained in the configuration information. The field is encoded as Array with number of elements encoded as Int32 value. |
|
DataSetWriterConfig |
WriterGroupDataType |
The current WriterGroup and DataSetWriter settings for the DataSet related to the DataSetWriterId. The WriterGroupDataType is defined in 6.2.6.7. The field DataSetWriters of the WriterGroupDataType shall contain only the entry for the requested or changed DataSetWriters in the WriterGroup. The configuration properties shall not be included in the WriterGroupDataType and DataSetWriterDataType. |
|
statusCodes |
StatusCode[] |
Status codes indicating the capability of the Publisher to provide configuration information for the DataSetWriterIds. The size of the array shall match the size of the DataSetWriterIds array. |
The encoding of the ActionResponder configuration announcement message structure is specified in Table 175. It contains an array of PubSubConnections configured in the OPC UA Application.
Table 175 – ActionResponder configuration announcement message structure
|
Name |
Type |
Description |
|
ActionResponder |
PubSubConnectionDataType [] |
ActionResponder configured for the OPC UA Application. The PubSubConnectionDataType is defined in 6.2.7.5.1. Only DataSetWriters used for Actions are included. All WriterGroups and DataSetWriters not used for Actions shall be excluded. The ReaderGroup lists in PubSubConnectionDataType shall be empty. The WriterGroup list shall be contained, if the IncludeWriterGroups is true in the PubSubConnection information probe message. The DataSetWriter lists in the WriterGroups shall be contained, if the IncludeDataSetWriters is true in the PubSubConnection information probe message. The configuration properties shall not be included in the PubSubConnectionDataType, WriterGroupDataType and DataSetWriterDataType. |
The encoding of the ActionMetaData message structure is specified in Table 176.
The Responder shall send this message without a corresponding discovery probe if the configuration of the Action changed.
Table 176 – ActionMetaData announcement message structure
|
Name |
Type |
Description |
|
DataSetWriterId |
UInt16 |
DataSetWriterId of the Actions described with the MetaData. |
|
ActionTargets |
ActionTargetDataType[] |
The set of Action targets that may be executed. If an Action target is mapped to a Method of an Object in an OPC UA Server, then the related Object and Method are defined by the corresponding entry in the ActionMethods array. The ActionTargetId in the ActionTargetDataType is used to address the Method referenced by the ActionMethodDataType. |
|
Request |
DataSetMetaDataType |
The structure and content of the ActionRequest message. The name of the Action is defined by the Name field in the DataSetMetaDataType. |
|
Response |
DataSetMetaDataType |
The structure and content of the ActionResponse message. The fields Name and ConfigurationVersion of the Request and the Response DataSetMetaDataType shall have equal values. |
|
ActionMethods |
ActionMethodDataType[] |
The optional array of Action sources. If the source information is provided, the array shall match the size and order of the ActionTargets. The namespace URIs for the NamespaceIdex in the NodeIds shall be contained in the Request DataSetMetaData. |
The NetworkMessage flags used with the discovery probe messages shall use the following bit values.
- UADPFlags bits 5 and 6 shall be false, bits 4 and 7 shall be true
- ExtendedFlags1 bits 3, 5 and 6 shall be false, bits 4 and 7 shall be true
- ExtendedFlags2 bit 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 NetworkMessage on the Publisher as receiver. The actual security settings for the NetworkMessage are 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 Subscriber should cache configuration information for PublisherId and DataSetWriterIds of interest.
If a Subscriber requires information from Publishers after 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 Subscriber sent already a probe and the announcement to this probe is used.
A Subscriber shall 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 Subscriber specific.
A Publisher shall delay subsequent announcements for a combination of probe type and identifier like the DataSetWriterId for at least 500 ms. Duplicate probes, that have not yet been responded to, shall be discarded by the Publisher. The maximum delay is Publisher specific.
If the Publisher receives discovery probes for different DataSetWriters in one WriterGroup, the Publisher shall send one aggregated discovery announcement.
The encoding of the discovery probe header structure is specified in Table 177.
Table 177 – Discovery probe header structure
|
Name |
Type |
Description |
|
ProbeType |
Byte |
The following types of discovery probe messages are defined. 0Reserved 1 Publisher information probe message (see 7.2.4.6.12.4) 2FindApplications probe message.The message type does not have additional fields. The PublisherId is set to NULL. |
The encoding of the Publisher information probe message structure is specified in Table 178.
Table 178 – Publisher information probe message structure
|
Name |
Type |
Description |
|
InformationType |
Byte |
The following types of Publisher information probes are defined. 0Reserved No additional fields are defined. The information is provided with the Publisher Endpoints announcement message defined in 7.2.4.6.4. The settings for this InformationType are defined in Table 179. The information is provided with the DataSetMetaData announcement message defined in 7.2.4.6.4. 3 DataSetWriter configuration The settings for this InformationType are defined in Table 179. The information is provided with the DataSetWriter configuration announcement message defined in 7.2.4.6.9. 4 WriterGroup configuration The settings for this InformationType are defined in Table 180 The information is provided with the DataSetWriter configuration announcement message defined in 7.2.4.6.9. 5 PubSubConnections configuration The settings for this InformationType are defined in Table 181 The information is provided with the PubSubConnection configuration announcement message defined in 7.2.4.6.7. |
The additional field for DataSetWriter related InformationType in a Publisher information probe message are specified in Table 179.
Table 179 – DataSetWriter settings for Publisher information probe
|
Name |
Type |
Description |
|
DataSetWriterIds |
UInt16[] |
List of DataSetWriterIds the information is requested for. The field is encoded as Array with number of elements encoded as Int32 value. For DataSetMetaData probes, the Publisher sends one discovery announcement NetworkMessage for each requested DataSetWriterId. For DataSetWriter configuration probes, the DataSetWriters that belong to one WriterGroup are sent together in one DataSetWriter configuration message. If more than one WriterGroup is affected, this results in a DataSetWriter configuration message per WriterGroup. |
The additional fields for WriterGroup related InformationType in a Publisher information probe message are specified in Table 180.
Table 180 – WriterGroup settings for Publisher information probe
|
Name |
Type |
Description |
|
WriterGroupId |
UInt16 |
This option allows a Publisher information probe for a WriterGroup and the contained DataSetWriters if only the WriterGroupId is known from NetworkMessages. For WriterGroup configuration probes, the DataSetWriters that belong to the WriterGroup are sent together in one DataSetWriter configuration message. |
|
IncludeDataSetWriters |
Boolean |
Flag indicating if the DataSetWriter should be contained in the PubSubConnection configuration announcement message. |
The additional fields for PubSubConnection configuration in a Publisher information probe message are specified in Table 181.
Table 181 – 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 PubSubConnection with matching TransportProfileUri shall be returned. If the TransportProfileUris is null or empty, all PubSubConnections are returned. |
|
IncludeWriterGroups |
Boolean |
Flag indicating if the WriterGroups should be contained in the PubSubConnection configuration announcement message. |
|
IncludeDataSetWriters |
Boolean |
Flag indicating if the DataSetWriters should be contained in the PubSubConnection configuration announcement message. This flag is ignored if IncludeWriterGroups is false. Setting this flag increases the size of the PubSubConnection configuration announcement message and it is more likely that max message sizes are exceeded. |
The JSON message mapping uses the OPC UA JSON encoding defined in OPC 10000-6. If an ExtensionObject is encoded, the TypeId shall be the DataType NodeId of the contained structure.
JSON is a format that uses human readable text. It is defined in IETF RFC 8259.
The JSON based message mapping allows OPC UA Applications to interoperate with web and enterprise software that use this format and do not understand OPC UA specific encodings.
The JSON message mapping defines different optional header fields, variations of field settings and different message types. Available layouts with standard settings and the corresponding URI Strings for JSON are defined in A.3.
The mapping of MessageTypes to JSON NetworkMessage MessageTypes and the reference to the detailed definition is listed in Table 182.
Table 182 – JSON NetworkMessage MessageType mapping
|
MessageType |
JSON NetworkMessage MessageType |
Specification Reference |
|
DataSetMessage |
ua-data |
|
|
DataSetMetaData |
ua-metadata |
Defined in 7.2.5.5.2. |
|
ApplicationDescription |
ua-application |
Defined in 7.2.5.5.3. |
|
ServerEndpoints |
ua-endpoints |
Defined in 7.2.5.5.4. |
|
Status |
ua-status |
Defined in 7.2.5.5.5. |
|
PubSubConnection |
ua-connection |
Defined in 7.2.5.5.6. |
|
ActionRequest |
ua-action-request |
Defined in 7.2.5.6.2. |
|
ActionResponse |
ua-action-response |
Defined in 7.2.5.6.3. |
|
ActionMetaData |
ua-action-metadata |
Defined in 7.2.5.5.7. |
|
ActionResponder |
ua-action-responder |
Defined in 7.2.5.5.8. |
Each JSON NetworkMessage can contain one or more JSON DataSetMessages. The JSON NetworkMessage is a JSON object with the fields defined in Table 183.
Table 183 – JSON NetworkMessage definition
|
Name |
Type |
Description |
|
MessageId |
String |
A globally unique identifier for the message. The unique identifier can be created by converting a Guid to a String or through another algorithm that creates a unique string. This value is always present. |
|
MessageType |
String |
This value shall be “ua-data” for NetworkMessages containing DataSetMessages. This value is always present. |
|
PublisherId |
String |
A unique identifier for the Publisher. It identifies the source of the message. The presence of the value depends on the setting in the JsonNetworkMessageContentMask. The source is the PublisherId on a PubSubConnection (see 6.2.7.1). If the PublisherId is a UInteger, the UInteger value is converted to a String without leading zeros. |
|
WriterGroupName |
String |
The name of the WriterGroup which created the NetworkMessage. The presence of the value depends on the setting in the JsonNetworkMessageContentMask. |
|
DataSetClassId |
String |
The DataSetClassId associated with the DataSets in the NetworkMessage. The DataSetClassId is a Guid and shall be converted to a String. The presence of the value depends on the setting in the JsonNetworkMessageContentMask. If specified, all DataSetMessages in the NetworkMessage shall have the same DataSetClassId. The source is the DataSetClassId on the PublishedDataSet (see 6.2.3.3) associated with the DataSetWriters that produced the DataSetMessages. |
|
Messages |
* |
A JSON array of JSON DataSetMessages (see 7.2.5.4) or a JSON object if SingleDataSetMessage is set. This value is always present. |
All fields with a concrete DataType defined are encoded using CompactEncoding OPC UA JSON Data Encoding defined in OPC 10000-6.
The fields in the JSON NetworkMessage are controlled by the NetworkMessageContentMask of the JSON NetworkMessage mapping(see 6.3.2.1.1).
If the NetworkMessageHeader bit of the NetworkMessageContentMask is not set, the NetworkMessage is the contents of the Messages field (e.g. a JSON array of DataSetMessages).
If the DataSetMessageHeader bit of the NetworkMessageContentMask is not set, the content of the Messages field is an array of content from the Payload field for each DataSetMessage (see 7.2.5.4).
If the SingleDataSetMessage bit of the NetworkMessageContentMask is set, the content of the Messages field is a JSON object containing a single DataSetMessage.
If the NetworkMessageHeader and the DataSetMessageHeader bits are not set and SingleDataSetMessage bit is set, the NetworkMessage is a JSON object containing the set of name/value pairs defined for a single DataSet.
If the JSON encoded NetworkMessage size exceeds the Broker limits the message is dropped and a PubSubTransportLimitsExceeded Event is reported.
A DataSetMessage is produced by a DataSetWriter and contains list of name/value pairs which are specified by the PublishedDataSet associated with the DataSetWriter. The contents of the DataSetMessage are formally described by a DataSetMetaData Object. A DataSetMessage is a JSON object with the fields defined in Table 184.
A key frame DataSetMessage or an event based DataSetMessage contains name and value for all fields of the DataSet.
A delta frame DataSetMessage contains only name and value for the changed fields.
DataSetWriters may periodically provide keep-alive messages which are DataSetMessages without any Payload field.
Table 184 – JSON DataSetMessage definition
|
Name |
Type |
Description |
|
DataSetWriterId |
UInt16 |
An identifier for DataSetWriter which created the DataSetMessage. 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 DataSetWriter which created the DataSetMessage. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. |
|
PublisherId |
String |
A unique identifier for the Publisher. It identifies the source of the message. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. The source is the PublisherId on a PubSubConnection (see 6.2.7.1). If the PublisherId is a UInteger, the UInteger value is converted to a String without leading zeros. The value shall be omitted if the NetworkMessage header is present. |
|
WriterGroupName |
String |
The name of the WriterGroup which created the DataSetMessage. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. The value shall be omitted if the WriterGroupName is contained in the NetworkMessage header. |
|
SequenceNumber |
UInt32 |
Sequence number for each new DataSetMessage as defined in 7.2.3. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. For the DataSetMessage MessageType “ua-keepalive”, the sequence number provides the next expected sequence number for the DataSetWriter. |
|
MetaDataVersion |
ConfigurationVersionDataType |
The version of the DataSetMetaData which describes the contents of the Payload. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. |
|
MinorVersion |
VersionTime |
The minor version of the DataSetMetaData which describes the contents of the Payload. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. The value shall be omitted if the MetaDataVersion is contained in the DataSetMessage header. |
|
Timestamp |
DateTime |
The time the DataSetMessage was created. 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 DataSet fields are defined in Table 34. 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 DataType of the field and the flags specified by the DataSetFieldContentMask. For MessageType “ua-event”, only Variant or RawData encoding shall be allowed. If bits for DataValue encoding are set, the Variant encoding shall be used. |
All fields with a concrete DataType are encoded using VerboseEncoding if FieldEncoding1 is FALSE and CompactEncoding if FieldEncoding1 is TRUE. See the OPC UA JSON Data encodings defined in OPC 10000-6.
The fields in the DataSetMessage are specified by the DataSetFieldContentMask in the DataSetWriter parameters.
The format of the field values in the Payload depend on the setting of the DataSetFieldContentMask, the FieldEncoding1 and the FieldEncoding2 flag in the DataSetMessageContentMask. The resulting JSON encoding is defined in Table 111.
If the DataSetFieldContentMask is 0x0 or 0x20 (only the RawData flag is set), the DataSetMessage fields are encoded as Variant. Otherwise the fields are encoded as DataValue. If the KeyFrameCount is 0, the DataSetFieldContentMask shall be 0x0 or 0x20.
If the FieldEncoding1 is FALSE in the DataSetMessageContentMask, the Variant at the top level of a field is encoded as a JSON value containing only the value of the Body field. If this Variant contains an ExtensionObject, the ExtensionObject shall be encoded as a Structure without the UaTypeId field. This also applies to the Variant in a DataValue at the top level of a field.
If the RawData flag is set, the UaType fields of Variants and the UaTypeId fields of ExtensionObjects are always omitted.
If the RawData flag ist set, it is not possible to reverse the data in a DataSetReader in the following cases.
- DataSet fields have an abstract DataType in the DataSetMetaData.
- DataSet field values do not match the DataType specified in the DataSetMetaData if they are Structure DataTypes.
The JSON message mapping defines optional discovery messages. The main purpose is the exchange of additional information not contained in the DataSetMessages like Properties for the DataSet fields.
DataSetMetaData describe the content of DataSetMessages published by a DataSetWriter. More specifically, it specifies the names and data types of the values that shall appear in the Payload of 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 DataSetWriterId and Version fields in a DataSetMessage are used to correlate a DataSetMessage with a DataSetMetaData.
A NetworkMessage with MessageType DataSetMetaData is a JSON object with the fields defined in Table 185.
Table 185 – 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 DataSetWriter which published the DataSetMetaData. This value is mandatory. It is unique within the scope of a Publisher. |
|
WriterGroupName |
String |
The name of the WriterGroup which created the NetworkMessage. This value is mandatory. |
|
DataSetWriterName |
String |
The name of the DataSetWriter. This value is mandatory. |
|
Timestamp |
UtcTime |
When the message was first sent to the middleware. This value is mandatory. |
|
MetaData |
DataSetMetaDataType |
The metadata as defined in 6.2.3.2.3. This value is mandatory. |
All fields with a concrete DataType are encoded using CompactEncoding OPC UA JSON Data Encoding defined in OPC 10000-6.
A NetworkMessage with MessageType ApplicationDescription is a JSON object with the fields defined in Table 186.
Table 186 – JSON ApplicationDescription definition
|
Name |
Type |
Description |
|
MessageId |
String |
A globally unique identifier for the message. This value is mandatory. |
|
MessageType |
String |
This value shall be “ua-application”. This value is mandatory. |
|
PublisherId |
String |
The Publisher that sent the message. This value is mandatory. |
|
Timestamp |
UtcTime |
When the message was first sent to the middleware. This value is mandatory. |
|
Description |
ApplicationDescription |
The ApplicationDescription Structure is described in OPC 10000-4. |
|
ServerCapabilities |
String [] |
The set of Server capabilities supported by the Server associated with the Publisher. The set of allowed Server capabilities are defined in OPC 10000-12. |
A NetworkMessage with MessageType ServerEndpoints is a JSON object with the fields defined in Table 187.
Table 187 – JSON ServerEndpoints definition
|
Name |
Type |
Description |
|
MessageId |
String |
A globally unique identifier for the message. This value is mandatory. |
|
MessageType |
String |
This value shall be “ua-endpoints”. This value is mandatory. |
|
PublisherId |
String |
The Publisher that sent the message. This value is mandatory. |
|
Timestamp |
UtcTime |
When the message was first sent to the middleware. This value is mandatory. |
|
Endpoints |
EndpointDescription [] |
The list of Server Endpoints of the OPC UA Application. The EndpointDescription Structure is described in OPC 10000-4. |
A NetworkMessage with MessageType Status is a JSON object with the fields defined in Table 188.
Table 188 – JSON Status definition
|
Name |
Type |
Description |
|
MessageId |
String |
A globally unique identifier for the message. This value is mandatory. |
|
MessageType |
String |
This value shall be “ua-status”. This value is mandatory. |
|
PublisherId |
String |
The Publisher that sent the message. This value is mandatory. |
|
Timestamp |
UtcTime |
When the message was sent to the Middleware. Mandatory if IsCyclic=TRUE. The field is omitted if IsCyclic=FALSE. |
|
IsCyclic |
Boolean |
If TRUE the Publisher periodically updates the status. If FALSE the Middleware is responsible for detecting changes to the status. |
|
Status |
PubSubState |
The current state of the PubSubConnection. This value is mandatory. |
|
NextReportTime |
UtcTime |
When the Publisher is expected to send the next update. Mandatory if IsCyclic=TRUE. The field is omitted if IsCyclic=FALSE. |
IsCyclic is set to FALSE if a PublisherId is used exclusively by a single application and the Message Oriented Middleware can detect when Publishers go offline. In these cases, the Publisher sends updates only when its state changes and the Message Oriented Middleware will send an update with PubSubState Error if the Publisher goes offline. The status message from the Message Oriented Middleware does not contain the Timestamp.
If IsCyclic is set to TRUE the Publisher only reports when it is Operational. The NextReportTime indicates when the Publisher is expected to send an update. If the Subscriber does not receive updates and the NextReportTime is a reasonable time in the past, the Subscriber assumes the PubSubState Error.
A NetworkMessage with MessageType PubSubConnection is a JSON object with the fields defined in Table 189.
Table 189 – JSON PubSubConnection definition
|
Name |
Type |
Description |
|
MessageId |
String |
A globally unique identifier for the message. This value is mandatory. |
|
MessageType |
String |
This value shall be “ua-connection”. This value is mandatory. |
|
PublisherId |
String |
The Publisher that sent the message. This value is mandatory. |
|
Timestamp |
UtcTime |
When the message was first sent to the Middleware. This value is mandatory. |
|
Connection |
PubSubConnectionDataType |
The PubSubConnectionDataType Structure is defined in 6.2.7.5.1. The ReaderGroup lists and the Address in PubSubConnectionDataType shall be empty. The configuration properties shall not be included in the PubSubConnectionDataType, WriterGroupDataType and DataSetWriterDataType. |
A NetworkMessage with MessageType ActionMetaData is a JSON object with the fields defined in Table 190.
Table 190 – JSON ActionMetaData definition
|
Name |
Type |
Description |
|
MessageId |
String |
A globally unique identifier for the message. This value is mandatory. |
|
MessageType |
String |
This value shall be “ua-action-metadata”. This value is mandatory. |
|
PublisherId |
String |
The Publisher that sent the message. This value is mandatory. |
|
DataSetWriterId |
UInt16 |
An identifier for DataSetWriter which published the metadata. This value is mandatory. It is unique within the scope of a Publisher. |
|
DataSetWriterName |
String |
The name of the DataSetWriter. This value is optional. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. |
|
Timestamp |
UtcTime |
When the message was first sent to the Middleware. This value is mandatory. |
|
ActionTargets |
ActionTargetDataType[] |
The set of Action targets that may be executed. If an Action target is mapped to a Method of an Object in an OPC UA Server, then the related Object and Method are defined by the corresponding entry in the ActionMethods array. The ActionTargetId in the ActionTargetDataType is used to address the Method referenced by the ActionMethodDataType. |
|
Request |
DataSetMetaDataType |
The structure and content of the ActionRequest message. The name of the Action is defined by the Name field in the DataSetMetaDataType. |
|
Response |
DataSetMetaDataType |
The structure and content of the ActionResponse message. The fields Name and ConfigurationVersion of the Request and the Response DataSetMetaDataType shall have equal values. |
|
ActionMethods |
ActionMethodDataType[] |
The optional array of Action sources. If the source information is provided, the array shall match the size and order of the ActionTargets. |
A NetworkMessage with MessageType ActionResponder is a JSON object with the fields defined in Table 190.
Table 191 – JSON ActionResponder definition
|
Name |
Type |
Description |
|
MessageId |
String |
A globally unique identifier for the message. This value is mandatory. |
|
MessageType |
String |
This value shall be “ua-action-responder”. This value is mandatory. |
|
PublisherId |
String |
The Publisher that sent the message. This value is mandatory. |
|
Timestamp |
UtcTime |
When the message was first sent to the Middleware. This value is mandatory. |
|
Connection |
PubSubConnectionDataType |
The PubSubConnectionDataType Structure is defined in 6.2.7.5.1. Only DataSetWriters used for Actions are included. All WriterGroups and DataSetWriters not used for Actions shall be excluded. The ReaderGroup lists in PubSubConnectionDataType shall be empty. The configuration properties shall not be included in the PubSubConnectionDataType, WriterGroupDataType and DataSetWriterDataType. |
Each JSON Action NetworkMessage can contain one or more JSON Request or Response messages. A JSON Action NetworkMessage is a JSON object with the fields defined in Table 192.
Table 192 – JSON Action NetworkMessage definition
|
Name |
Type |
Description |
|
MessageId |
String |
A globally unique identifier for the message. This value is mandatory. |
|
MessageType |
String |
This value shall be “ua-action-request” Request messages or “ua-action-response” for Response messages. This value is mandatory. |
|
PublisherId |
String |
The PublisherId of the Responder for the “ua-action-request” and “ua-action-response” message. This value is mandatory. |
|
Timestamp |
UtcTime |
When the message was first sent to the Middleware. This value is mandatory. |
|
ResponseAddress |
String |
The address used to send the Response messages. The handling of the ResponseAddress and default values are defined for the different transport protocol mappings. This value is mandatory for Request messages. This value shall be omitted for Response message. |
|
CorrelationData |
ByteString |
Data provided by the Requestor in the Request message that is returned to the Requestor in the Response message. The value may be provided in the Request message. The value shall be provided in the Response message if it was included in the Request message. |
|
RequestorId |
String |
The PublisherId of the Requestor for the “ua-action-request” and “ua-action-response” message. This value is mandatory. |
|
TimeoutHint |
Duration |
The timeout used by the Requestor to wait for a Response messages and by the Responder to stop processing the request. This value is mandatory for the Request message. This value is not used for Response messages. |
|
Message |
* |
A JSON array of JSON ActionRequest or JSON ActionResponse messages. This value is mandatory. |
It contains one or more ActionRequest or ActionResponse messages with a layout defined by the Request and Response fields in the ActionMetaData.
The Action execution sequences and execution related request and response message values are defined in 6.2.11.2.
A NetworkMessage with MessageType “ua-action-request” contains a JSON array with ActionRequest messages. A ActionRequest message is a JSON object with the fields defined in Table 193.
Table 193 – JSON ActionRequest definition
|
Name |
Type |
Description |
|
DataSetWriterId |
UInt16 |
An identifier for DataSetWriter in the Responder which creates the Response. This value is mandatory. It is unique within the scope of a Responder. |
|
ActionTargetId |
UInt16 |
The numeric identifier assigned to the Action target which is unique within one ActionMetaData. This value is mandatory. It is used to address the Action target in combination with the PublisherId and the DataSetWriterId. |
|
DataSetWriterName |
String |
The name of the DataSetWriter which created the DataSetMessage. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. |
|
WriterGroupName |
String |
The name of the WriterGroup which created the DataSetMessage. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. The value shall be omitted if the WriterGroupName is contained in the NetworkMessage header. |
|
MetaDataVersion |
ConfigurationVersionDataType |
The version of the ActionMetaData Request which describes the contents of the Payload. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. |
|
MinorVersion |
VersionTime |
The minor version of the ActionMetaData Request which describes the contents of the Payload. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. The value shall be omitted if the MetaDataVersion is contained in the DataSetMessage header. |
|
Timestamp |
DateTime |
The time the Request was created. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. |
|
MessageType |
String |
“ua-action-request” The presence of the value depends on the setting in the JsonDataSetMessageContentMask. |
|
RequestId |
UInt16 |
Data provided by the Requestor in the Request message that is returned to the Requestor in the Response message. |
|
ActionState |
ActionState |
Specifies the expected Action state on Responder side. The details for the use of this value and the relation to other values for a Action execution is defined in 6.2.11.2. |
|
Payload |
Object |
A JSON object containing the name-value pairs specified by the ActionMetaData. The format of the value depends on the DataType of the field and the flags specified by the DataSetFieldContentMask. Only Variant or RawData encoding shall be allowed. If bits for DataValue encoding are set, the Variant encoding shall be used. |
The encoding rules defined in 7.2.5.4 for DataSetMessages also apply to the ActionRequest message. The DataValue encoding shall not be used in ActionRequest message. The RawData flag shall be FALSE for ActionRequest messages.
A NetworkMessage with MessageType “ua-action-response” contains a JSON array with ActionResponse messages. An ActionResponse message is a JSON object with the fields defined in Table 194.
Table 194 – JSON ActionResponse definition
|
Name |
Type |
Description |
|
DataSetWriterId |
UInt16 |
An identifier for DataSetWriter which created the Response. This value is mandatory. It is unique within the scope of a Responder. |
|
ActionTargetId |
UInt16 |
The numeric identifier assigned to the Action target which is unique within one ActionMetaData. This value is mandatory. It is used to address the Action target in combination with the PublisherId and the DataSetWriterId. |
|
DataSetWriterName |
String |
The name of the DataSetWriter which created the DataSetMessage. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. |
|
WriterGroupName |
String |
The name of the WriterGroup which created the DataSetMessage. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. The value shall be omitted if the WriterGroupName is contained in the NetworkMessage header. |
|
MetaDataVersion |
ConfigurationVersionDataType |
The version of the ActionMetaData Response which describes the contents of the Payload. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. |
|
MinorVersion |
VersionTime |
The minor version of the ActionMetaData Response which describes the contents of the Payload. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. The value shall be omitted if the MetaDataVersion is contained in the DataSetMessage header. |
|
Timestamp |
DateTime |
The time the DataSetMessage was created. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. |
|
Status |
StatusCode |
The overall result of the Action Response. The value shall be present. |
|
MessageType |
String |
“ua-action-response”. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. |
|
RequestId |
UInt16 |
Data provided by the Requestor in the Request message that is returned to the Requestor in the Response message. |
|
ActionState |
ActionState |
The current state of this currently running Action. The details for the use of this value and the relation to other values for a Action execution is defined in 6.2.11.2. |
|
Payload |
Object |
A JSON object containing the name-value pairs specified by the ActionMetaData. The format of the value depends on the DataType of the field and the flags specified by the DataSetFieldContentMask. Only Variant or RawData encoding shall be allowed. If bits for DataValue encoding are set, the Variant encoding shall be used. |
The encoding rules defined in 7.2.5.4 for DataSetMessages also apply to the ActionResponse message. The DataValue encoding shall not be used in ActionResponse message. The RawData flag shall be FALSE for ActionResponse messages.
Subclause 7.3 lists the standard protocols that have been selected for this document and their possible combinations with message mappings.
OPC UA UDP is a simple UDP based protocol that is used to transport UADP NetworkMessages.
A PubSubConnection for UDP shall have a unique Address across all PubSubConnections of an OPC UA Application.
If the Address specifies a domain name then the resolution to an IP address requires access to a domain name resolution service (e.g., the DNS protocol) that maps the domain name onto a usable network address. OPC 10000-7 defines Profiles for different name resolution protocols that Publisher or Subscriber may support.
For OPC UA UDP it is recommended to limit the MaxNetworkMessageSize plus additional headers to a MTU size. The number of frames used for a UADP NetworkMessage influences the probability that UADP NetworkMessages get lost.
Note: The MaxNetworkMessageSize that fits into one MTU is maximum 1472 Byte for IPv4 and 1452 Byte for IPv6. The additional headers have a size of 22 Byte for Ethernet, 20 Byte for IPv4 or 40 Byte for IPv6 and 8 Byte for UDP. This is based on IETF RFC 8200 for IPv6, RFC 791 for IPv4 and RFC 768 for UDP.
For OPC UA UDP the MaxNetworkMessageSize plus additional headers shall be limited to 65535 Byte.
The transport of a UADP NetworkMessage in a UDP packet is defined in Table 195.
Table 195 – UADP message transported over UDP
|
Name |
Description |
|
Frame Header |
The frame header. |
|
IP Header |
The IP header for the frame contains information like source IP address and destination IP address. IPv4 and IPv6 addresses can be used. The size of the IP header depends on the used version. |
|
UDP Header |
The UDP header for the frame contains the source port, destination port, length and checksum. Each field is two byte long. The total size of the UDP header is 8 byte. |
|
UADP NetworkMessage |
The UADP NetworkMessage is sent as UDP data. |
|
Frame Footer |
The frame footer. |
The IANA registered IPv4 multicast address for discovery is 224.0.2.14. It shall only be used for OPC UA discovery purposes. The recommended port for discovery is 4840. Therefore the default DiscoveryAddress has the following form:
opc.udp://224.0.2.14
The default DiscoveryMaxMessageSize for UDP is 4096 bytes.
The transport protocol URL for UDP multicast and broadcast communication is configured on a PubSubConnection for Publisher and Subscriber. The Address parameter for a PubSubConnection is defined in 6.2.7.3.
The Url field in the Address is used as destination address for NetworkMessages sent as UDP datagram. The Address is also used to receive UDP datagrams from the multicast IP address. All DataSetWriters and DataSetReaders that send to and receive from the multicast IP address shall be configured on one PubSubConnection. The Address parameter for WriterGroup datagram TransportSettings shall be null. If an Address is configured on a WriterGroup, the WriterGroup PubSubState shall be Error. The NetworkInterface field in the Address is required if more than one network interface is available.
The syntax of the UDP transport protocol URL used in the Address has the following form:
opc.udp://<address>[:<port>]
The address is either an multicast or broadcast IP address or a registered name like a domain name that can be resolved to a multicast or broadcast IP address.. It is the destination of the UDP datagram.
The IANA registered OPC UA port for UDP communication is 4840. This is the default and recommended port for broadcast and multicast communication. Alternative ports may be used.
It is recommended to use switches with IGMP and MLD support to limit the distribution of multicast traffic to the interested participants.
Note: The Internet Group Management Protocol (IGMP) is a standard protocol used by hosts to report their IP multicast group memberships for IPv4 and needs to be implemented by any host that wishes to receive IP multicast datagrams. IGMP messages are used by multicast routers to learn which multicast groups have members on their attached networks. IGMP messages are also used by switches capable of supporting “IGMP snooping” whereby the switch listens to IGMP messages and only sends the multicast NetworkMessages to ports that have joined the multicast group. The corresponding protocol for IPv6 is the Multicast Listener Discovery (MLD).There are different versions of IGMP and MLD: - IGMP V1 is defined in IETF RFC 1112. - IGMP V2 is defined in IETF RFC 2236. - IGMP V3 is defined in IETF RFC 3376.
- IGMP V3 and MLD V2 are defined in IETF RFC 4604.
IETF RFC 2236 and IETF RFC 3376 discuss host and router requirements for interoperation with older IGMP versions.If OPC UA devices make extensive use of IP multicast for UDP transport, consistent IGMP and MLD usage by OPC UA devices is essential in order to create well-functioning OPC UA Application networks.
OPC UA Applications shall issue an IGMP membership report message (V1, V2 or V3 as appropriate) for IPv4 or a MLD membership report message for IPv6 when enabling a PubSub connection on which they will receive UDP multicast NetworkMessages.
For UDP unicast, the address information for the Subscriber is configured on the PubSubConnection and the address information for the Publisher is configured on the WriterGroup.
The receive port for UDP unicast communication is configured on a PubSubConnection. The Address parameter for a PubSubConnection is defined in 6.2.7.3. All NetworkMessages for one port are received through one PubSubConnection. The filtering and assignment of NetworkMessages for the Subscriber is done based on the PublisherId. The hostname for the Url in the PubSubConnection Address parameter is set to ‘localhost’ since the source address is not used for filtering. The NetworkInterface field in the Address is not required and is only configured if the Subscriber should listen only on the configured interface. If the NetworkInterface is null or empty, the Subscriber should listen on all interfaces.
The syntax of the Url field in the PubSubConnection Address parameter has the following form:
opc.udp://localhost[:<port>]
The destination address is configured on the datagram TransportSettings of a WriterGroup. The Address parameter for a WriterGroup datagram TransportSetting is defined in 6.4.1.3.4. The Address parameter for WriterGroup datagram TransportSettings shall be configured. If no Address is configured on a WriterGroup, the WriterGroup PubSubState shall be Error. The NetworkInterface field in the Address is not required and should be null or empty and shall be ignored.
The syntax of Url field in the WriterGroup datagram TransportSettings Address parameter has the following form:
opc.udp://<host>[:<port>]
The host is either an unicast IP address or a registered name like a hostname or domain name that can be resolved to a unicast IP addresses. The IP address and the port are the destination of the UDP datagram.
The syntax is also used for the ResponseAddress in the ActionHeader of ActionRequest messages. If the ResponseAddress is not provided, the sender IP address and port of the ActionRequest is used.
The IANA registered OPC UA port for UDP communication is 4840. This is the default and recommended port for unicast communication. Alternative ports may be used.
The DTLS option is provided mainly for use in high speed device to device communication where hardware may be particularly optimized for DTLS (for either the DTLS handshake and/or the DTLS record layer). This option supports DTLS 1.3, previous versions of DTLS are not supported. Note in DTLS application data (OPC UA PubSub) and handshake messages are multiplexed on the same channel which could have an impact on applications requiring a high level of determinism. Certificates are required for the DTLS Transport, and in order to manage these certificates the DTLS Transport requires the OPC UA GDS CertificateManager. Pull Management or Push Management of certificates shall be supported by any Publisher or Subscriber that supports the DTLS Transport (see Part 12 for more information on the CertificateManager). DTLS makes use of the same Certificates and Trust List that are used for OPC UA Client Server communication, as well as the same procedure for validation of the certificates (see Part 4 “Determining if a Certificate is Trusted” for more information on this). That is, the DefaultApplicationGroup Object is used as the Certificate and TrustList for DTLS communication. A separate certificate group may optionally be used for the DTLS transport. See Part 7 for information on what certificate types may be used for DTLS.
DTLS is not supported for broker-based PubSub transports.
When DTLS Transport is used the DTLS handshake sets up a secure session prior to the PubSub data exchange. In this case either the Subscriber or the Publisher acts as the DTLS Client, with the other one acting as the DTLS Server. Once a DTLS session is established between two endpoints PubSub data is then sent. Different Reader/Writer groups will use the same DTLS session to send data betweent two endpoints. DTLS allows for authentication of just the server or of the client and the server; both cases are supported and can be configured via the VerifyClientCertificate parameter. The high level data flow for a Subscriber acting as the DTLS client is shown in Figure 39 and Figure 40 shows the high level data flow for a Publisher acting as the DTLS client. Note these figures are shown for illustrative purposes, precise details of messages may differ depending on configuration options.
Figure 39 – Subscriber as DTLS Client
Figure 40 – Publisher as DTLS Client
Addressing for DTLS is similar to UADP unicast.
The receive address for DTLS unicast communication is configured on a PubSubConnection. The Address parameter for a PubSubConnection is defined in 6.2.7.3.
The syntax of the URL used in the PubSubConnection Address parameter has the following form:
opc.dtls://localhost:<port>
The send address is configured on the datagram TransportSettings of a WriterGroup. The Address parameter for a datagram TransportSetting is defined in 6.4.1.3.4.
The syntax of the URL used in the datagram TransportSettings Address parameter has the following form:
opc.dtls://<host>:<port>
The host is either a unicast IP address or a registered name like a hostname or domain name that can be resolved to a unicast IP address. The IP address and the port are the destination of the DTLS UDP datagram.
The IANA registered OPC UA port for PubSub over DTLS is 4843. This is the default and recommended port for any PubSub communication using DTLS. Alternative ports may be used.
The DTLS transport does not support multicast of PubSub, and therefore can only be used for unicast communication. If multicast is needed other transports should be used. By definition the DTLS transport is only providing transport security, no notion of user level or application level security is provided. There are other OPC UA mechanisms which provide this, but by itself DTLS does not provide security at the user or application layer.
The DTLS transport supports the ability to use different cipher suites for a given PubSub Connection. This is configured via the ConnectionProperties of the PubSubConnectionDataType structure. A default value is configured in the ConfigurationProperties of the PubSubConfiguration. The properties are defined through the KeyValuePair array in the ConnectionProperties. The NamespaceIndex of the QualifiedName in the KeyValuePair shall be 0 for DTLS standard properties. The Name of the QualifiedName is constructed from a prefix and the DTLS property name with the following syntax. The intended use is for the DTLS client to include a single cipher suite in the handshake, which is the cipher suite to be used for that connection. To facilitate this, the DTLS server may have a list of cipher suites that are accepted if sent by a DTLS client in the handshake.
The NamespaceIndex of the QualifiedName in the KeyValuePair for properties defined in this document shall be 0. The Name of the QualifiedName is the property key from Table 202. The DataType of the Value in the KeyValuePair shall be the DataType defined in Table 202.
Table 202 formally defines the DTLS configuration properties
Table 196 – OPC UA DTLS standard properties
|
Key |
DataTypes |
Description |
|
0:DtlsConnectionSettings |
DtlsPubSubConnectionDataType |
The DTLS configuration for the PubSubConnection or WriterGroup. The DtlsPubSubConnectionDataType is defined in 6.4.1.7.6. |
|
0:DtlsClientCipherSuite |
String |
Cipher suite for the PubSubConnection or WriterGroup. The ClientCipherSuite is defined in 6.4.1.7.1. |
OPC UA Ethernet is a simple Ethernet based protocol using EtherType 0xB62C that is used to transport UADP NetworkMessages as payload of the Ethernet II frame without IP or UDP headers.
The syntax of the Ethernet transporting protocol URL used in the Address parameter defined in 6.2.7.3 has the following form:
opc.eth://<host>[:<VID>[.PCP]]
The host is a MAC address, an IP address or a registered name like a hostname. The format of a MAC address is six groups of hexadecimal digits, separated by hyphens (e.g. 01-23-45-67-89-ab). A system may also accept hostnames and/or IP addresses if it provides means to resolve it to a MAC address (e.g. DNS and Reverse-ARP).
The VID is the VLAN ID as number.
The PCP is the Priority Code Point as one digit number. This optional parameter is typically configured as part of the QoS settings on the network interface and not of the address.
The transport of a UADP NetworkMessage in an Ethernet II frame is defined in Table 197.
Table 197 – UADP message transported over Ethernet
|
Name |
Description |
|
Frame Header |
The frame header with an EtherType of 0xB62C. |
|
UADP NetworkMessage |
The UADP NetworkMessage is sent as Ethernet payload. |
|
Frame Footer |
The frame footer. |
For OPC UA Ethernet the MaxNetworkMessageSize and the DiscoveryMaxMessageSize plus additional headers shall be limited to an Ethernet frame size of 1522 Byte.
Note: The MaxNetworkMessageSize is typically 1500 Byte since the additional headers have a size of 22 Byte and it consists of 6 Byte destination address, 6 Byte source address, 2 Byte EtherType, 4 Byte frame check sequence and optionally 4 Byte VLAN tag. This is based on Q-tagged frames defined in IEEE Std 802.3-2018.
The IANA registered OPC UA EtherType for UADP communication is 0xB62C.
The Advanced Message Queuing Protocol (AMQP) is an open standard application layer protocol for Message Oriented Middleware. AMQP is often used with a Broker that relays messages between applications that cannot communicate directly.
Publishers send AMQP messages to AMQP endpoints. Subscribers listen to AMQP endpoints for incoming messages. If a Broker is involved it may persist messages so they can be delivered even if the subscriber is not online. Brokers may also allow messages to be sent to multiple Subscribers.
The AMQP protocol defines a binary encoding for all messages with a header and a body. The header allows applications to insert additional information as name-value pairs that are serialized using the AMQP binary encoding. The body is an opaque binary blob that can contain any data serialized using an encoding chosen by the application.
This document defines two possible message mappings for the AMQP message body: the UADP message mapping defined in 7.2.3 and a JSON message mapping defined in 7.2.4.6.9. AMQP Brokers have an upper limit on message size. The limit is defined by the AMQP field max-message-size. The mechanism for handling NetworkMessages that exceed the Broker limits depends on the MessageMapping. For MessageMappings that support chunking, the NetworkMessage shall be broken into multiple chunks. The chunk size plus the AMQP header should not exceed the AMQP max-message-size. For MessageMappings that do not support chunking, the NetworkMessages exceeding the maximum size mut be skipped. Diagnostic information for such error scenarios are provided through the Events of the type PubSubTransportLimitsExceedEventType defined in 9.1.13.2 and through the FailedTransmissions counter of the PubSubDiagnosticsWriterGroupType defined in 9.1.11.9.
Security with AMQP is primary provided by a TLS connection between the Publisher or Subscriber and the AMQP Broker, however, this requires that the AMQP Broker be trusted. For that reason, it may be necessary to provide end-to-end security. Applications that require end-to-end security with AMQP need to use the UADP NetworkMessages and binary message encoding defined in 7.2.4.4. JSON encoded message bodies rely on the security mechanisms provided by AMQP and the AMQP Broker.
The syntax of the AMQP transporting protocol URL used in the Address parameter defined in 6.2.7.3 has the following form:
amqps://<domain name>[:<port>][/<path>]
The default port is 5671. The protocol prefix above provides transport security.
amqp://<domain name>[:<port>][/<path>]
The default port is 5672.
The syntax for an AMQP URL over Web Sockets has the following form:
wss://<domain name>[:<port>][/<path>]
The default port is 443.
Authentication shall be performed according to the configured AuthenticationProfileUri of the PubSubConnection, DataSetWriterGroup, DataSetWriter or DataSetReader entities.
If no authentication information is provided in the form of ResourceUri and AuthenticationProfileUri, SASL Anonymous is implied.
If the authentication profile specifies SASL PLAIN authentication, a separate connection for each new Authentication setting is required.
AMQP allows sending properties as part of opening the connection, session establishment and link attach.
The connection properties apply to any connection, session or link created as part of the PubSubConnection, or subordinate configuration entities, such as WriterGroup and DataSetWriter.
The properties are defined through the KeyValuePair array in the ConnectionProperties WriterGroupProperties and DataSetWriterProperties. The NamespaceIndex of the QualifiedName in the KeyValuePair shall be 0 for AMQP standard properties. The Name of the QualifiedName is constructed from a prefix and the AMQP property name with the following syntax.
Name = <target prefix>-<AMQP property name>
The target prefix can have the following values:
- Connection;
- session;
- link.
The Value of the KeyValuePair is converted to an AMQP data type using the rules defined in Table 200. If there is no rule defined for a data type, the property shall not be included.
The connection properties are intended to be used sparingly to optimize interoperability with existing broker endpoints.
A writer negotiates the delivery guarantees for its link using the snd-settle-mode settlement policy (settled, unsettled, mixed) it will use, and the desired rcv-settle-mode (first, second) of the broker.
Vice versa, the reader negotiates delivery guarantees using its rcv-settle-mode (first, second) and the desired snd-settle-mode (settled, unsettled) of the broker.
This matches to the BrokerTransportQualityOfService values as follows:
- AtMostOnce or BestEffort – messages are pre-settled at the sender endpoint and not sent again. Messages may be lost in transit. This is the default setting.
- AtLeastOnce – messages are received and settled at the receiver without waiting for the sender to settle.
- ExactlyOnce – messages are received, the sender settles and then the receiver settles.
If the KeepAliveTime is set on a WriterGroup, a value slightly higher than the configured value of the group should be used as AMQP idle time-out of the AMQP connection ensuring that the connection is disconnected if the keep alive message was not sent by any writer. Otherwise, if no KeepAliveTime is specified, the implementation should set a reasonable default value.
When setting the maximum message sizes for the Link, the MaxNetworkMessageSize of the PubSubGroup shall be used. If this value is 0, the implementation chooses a reasonable maximum.
Other limits are up to the implementation and depend on the capabilities of the OS or on the capabilities of the device the Publisher or Subscriber is running on, and can be made configurable through configuration model extensions or by other means.
The AMQP message header has a number of standard fields which are called properties in the AMQP specification. Table 198 describes how these fields shall be populated when an AMQP message is constructed.
Table 198 – AMQP standard header fields
|
Field Name |
Source |
|
message-id |
A globally unique value per message. |
|
Subject |
Valid values are ua-data or ua-metadata. |
|
Content-type |
The MIME type for the message body. The MIME types are specified in the message body subclauses 7.3.4.8.1 and 7.3.4.8.3. |
The subject defines the type of the message contained in the AMQP body. A value of “ua-data” specifies the body contains a UADP or JSON NetworkMessage. A value of “ua-metadata” specifies a body that contains a UA Binary or JSON encoded DataSetMetaData Message. The content-type specifies the whether the message is binary or JSON data.
The AMQP message header shall include additional fields defined on the WriterGroup or DataSetWriter through the KeyValuePair array in the WriterGroupProperties and DataSetWriterProperties. The NamespaceIndex of the QualifiedName in the KeyValuePair shall be 0 for AMQP standard message properties. The Name of the QualifiedName is constructed from a message prefix and the AMQP property name with the following syntax.
Name = message-<AMQP property name>
Table 199 defines the AMQP standard message properties.
Table 199 – OPC UA AMQP standard header QualifiedName Name mappings
|
AMQP standard property name |
OPC UA DataType |
AMQP data type |
Note |
|
to |
String |
* |
|
|
user-id |
ByteString |
binary |
|
|
reply-to |
String |
string |
|
|
correlation-id |
ByteString |
* |
|
|
absolute-expiry-time |
Duration |
timestamp |
The absolute-expiry-time is calculated by adding the message-absolute-expiry-time (Duration) from the DataSetWriterProperties to the current time of the DataSetMessage creation. |
|
Group-id |
String |
string |
|
|
reply-to-group-id |
String |
string |
|
|
creation-time |
Boolean |
timestamp |
The creation-time is set to the current time of the DataSetMessage creation if the message-creation-time (Boolean) in the DataSetWriterProperties is True, or else if the value is False or if the property is not configured, the AMQP property is not set. |
|
Content-encoding |
String |
symbol |
|
Any name not in the table is assumed to be an application property. In this case the namespace provided as part of the QualifiedName shall be the ApplicationUri.
The AMQP message header shall include additional promoted fields of the DataSet as a list of name-value pairs. DataSet fields with the PromotedField flag set in the FieldMetaData fieldFlags are copied into the AMQP header. The FieldMetaData Structure is defined in 6.2.3.2.4. Promoted fields shall always be included in the header even if the DataSetMessage body is a delta frame and the DataSet field is not included in the delta frame. In this case the last known value is sent in the header.
When a field is added to the header it is converted to an AMQP data type using the rules defined in Table 200. If there is no rule defined for the data type, the field shall not be included.
Table 200 – OPC UA AMQP header field conversion rules
|
OPC UA DataType |
Conversion Rules to AMQP data types. |
|
Boolean |
AMQP ‘boolean’ type. |
|
Sbyte |
AMQP ‘byte’ type. |
|
Byte |
AMQP ‘ubyte’ type. |
|
Int16 |
AMQP ‘short’ type. |
|
UInt16 |
AMQP ‘ushort’ type. |
|
Int32 |
AMQP ‘int’ type. |
|
UInt32 |
AMQP ‘uint’ type. |
|
Int64 |
AMQP ‘long’ type. |
|
UInt64 |
AMQP ‘ulong’ type. |
|
Float |
AMQP ‘float’ type. |
|
Double |
AMQP ‘double’ type. |
|
String |
AMQP ‘string’ type. |
|
ByteString |
AMQP ‘binary’ type. |
|
DateTime |
AMQP ‘timestamp’ type. This conversion may result in loss of precision on some platforms. The rules for dealing with the loss of precision are described in OPC 10000-6. |
|
Guid |
AMQP ‘uuid’ type. |
|
QualifiedName |
The QualifiedName is encoded as an AMQP ‘string’ type with the format <NamespaceUri>’#’<Name>. |
|
LocalizedText |
Not supported and the related field is discarded. |
|
NodeId |
If the NamespaceIndex = 0 the value is encoded as an AMQP ‘string’ type using the format for a NodeId defined in OPC 10000-6. If the NamespaceIndex > 0 the value is converted to an ExpandedNodeId with a NamespaceUri and is encoded as an AMQP ‘string’ type using the format for an ExpandedNodeId defined in OPC 10000-6. |
|
ExpandedNodeId |
If the NamespaceUri is not provided the rules for the NodeId are used. If the NamespaceUri is provided the value is encoded as an AMQP ‘string’ type using the format for an ExpandedNodeId defined in OPC 10000-6. |
|
StatusCode |
AMQP ‘uint’ type. |
|
Variant |
If the value has a supported datatype it uses that conversion; otherwise it is not supported and the related field is discarded. |
|
Structure |
Not supported and the related field is discarded. |
|
Structure with option fields |
Not supported and the related field is discarded. |
|
Array |
Not supported and the related field is discarded. |
|
Union |
Not supported and the related field is discarded. |
The message body is encoded in the AMQP bare-message application-data section as an AMQP ‘binary’ value.
A JSON body is encoded as defined for the JSON message mapping defined in 7.2.4.6.9.
The corresponding MIME type is application/json.
A UADP body is encoded as defined for the UADP message mapping defined in 7.2.3.
The corresponding MIME type is application/opcua+uadp.
If the encoded AMQP message size exceeds the Broker limits it shall be broken into multiple chunks as described in 7.2.4.4.4.
MQTT is an open standard application layer protocol for Message Oriented Middleware. MQTT is often used with a Broker that relays messages between applications that cannot communicate directly.
Publishers send MQTT messages to MQTT brokers. Subscribers subscribe to MQTT brokers for messages. A Broker may persist messages so they can be delivered even if the Subscriber is not online. Brokers may also allow messages to be sent to multiple Subscribers.
The MQTT protocol defines a binary protocol used to send and receive messages from and to topics. The body is an opaque binary blob that can contain any data serialized using an encoding chosen by the application.
There are currently two versions of the MQTT protocol in use, version 3.1.1 and version 5.0. Version 5.0 expands on version 3.1.1 by adding support for connection and message properties. This enables advanced routing scenarios at the broker level in particular when using encrypted payloads.
This document defines two possible encodings for the message body: the binary encoded DataSetMessage defined in 7.2.3 and a JSON encoded DataSetMessage defined in 7.2.4.6.9.
MQTT version 3.1.1 does not provide a mechanism for specifying the encoding of the MQTT message which means the Subscribers need to be configured in advance with knowledge of the expected encoding. As a consequence, Publishers should only publish NetworkMessages using a single encoding to a unique MQTT topic name.
MQTT version 5.0 adds the encoding and the message type information to the message and connection header and therefore allows Subscribers to detect the encoding and the message mapping. No additional information is added to the meta data messages.
MQTT Publisher and Subscriber transport profiles for full and minimal support are defined in OPC 10000-7.
Message security is primarily provided by a TLS connection between the Publisher or Subscriber and the MQTT server; however, this requires that the MQTT server be trusted. For that reason, it may be necessary to provide end-to-end message security. Applications that require end-to-end message security with MQTT need to use the UADP NetworkMessages and binary message encoding defined in 7.2.3. JSON encoded message bodies need to rely on the security mechanisms provided by MQTT and the MQTT broker.
The syntax of the MQTT transporting protocol URL used in the Address parameter defined in 6.2.7.3 has the following form:
mqtts://<domain name>[:<port>][/<path>]
The protocol prefix mqtts provides transport security. The default port is 8883.
mqtt://<domain name>[:<port>][/<path>]
The protocol prefix without transport security is mqtt. The default port is 1883.
wss://<domain name>[:<port>][/<path>]
The protocol prefix for MQTT over secure Web Sockets is wss. The default port is 443.
MQTT supports the use of Username/Password authentication in the initial CONNECT packet. Aside from password credentials, implementations can use this mechanism to pass any form of secret, such as an authentication token. However, if CONNECT authentication is used, the connection should be secured.
MQTT version 5.0 also supports enhanced authentication, whereby clients can specify the desired SASL authentication method during initial CONNECT and finish the secret exchange with the broker using subsequent AUTH packets, or reauthenticate on an existing connection.
Authentication shall be performed according to the configured AuthenticationProfileUri of the PubSubConnection, DataSetWriterGroup, DataSetWriter or DataSetReader entities.
If no authentication information is provided in the form of ResourceUri and AuthenticationProfileUri, SASL Anonymous is implied.
If the authentication profile specifies SASL PLAIN authentication, a separate connection for each authentication setting is required.
The MQTT transport mapping for version 3.1.1 only supports the connection property ClientID using a KeyValuePair. Any other configured setting in the connection properties shall be silently discarded.
If the ClientID is not configured, the PublisherId is used as ClientID. If the PublisherId has a UInteger DataType, the UInteger value is converted to a String for the ClientID.
MQTT version 5.0 allows Publishers and Subscribers to provide MQTT connection properties as part of opening the connection.
The connection properties apply to any connection created as part of the PubSubConnection, or subordinate configuration entities, such as the WriterGroup and the DataSetWriter.
The properties are defined through the KeyValuePair array in the ConnectionProperties. The NamespaceIndex of the QualifiedName in the KeyValuePair shall be 0.
Table 201 formally defines the ConnectionProperties used for MQTT connection configuration.
Table 201 – MQTT ConnectionProperties
|
Key |
DataType |
Description |
|
0:MqttVersion |
String |
Defines the MQTT version to use for the MQTT connection. Possible values are “3.1.1”, “5.0” and “BestAvailable”. The default value is BestAvailable. |
|
0:MqttTopicPrefix |
String |
The <Prefix> part of the Topic convention defined in 7.3.5.7.1. The default value is “opcua” |
For MQTT properties, the Name of the QualifiedName is constructed from a prefix “connection” followed by a hyphen and the MQTT property name with the following syntax.
Name = connection-<MQTT property name>
Table 202 defines the MQTT standard connection properties.
Table 202 – OPC UA MQTT standard connection property configuration
|
MQTT property name |
OPC UA DataTypes |
MQTT data types |
|
ClientID |
String |
UTF-8 Encoded String |
|
Receive Maximum |
UInt16 |
Two Byte Integer |
|
Maximum Packet Size |
UInt32 |
Four Byte Integer |
|
Session Expiry Interval |
UInt32 |
Four Byte Integer |
|
Topic Alias Maximum |
UInt16 |
Two Byte Integer |
|
Request Response Information |
Boolean |
Byte |
|
Request Problem Information |
Boolean |
Byte |
Any name not in the Table 202 is assumed to be a MQTT User Property.
When a field is added to the header as a MQTT User Property the value is encoded as UTF-8 encoded String. If the value is not a String, then it is encoded using the VerboseEncoding OPC UA JSON Data Encoding rules in OPC 10000-6.
The BrokerTransportQualityOfService values map to MQTT publish and subscribe QoS settings as follows:
- AtMostOnce and BestEffort is mapped to MQTT QoS 0.
- AtLeastOnce is mapped to MQTT QoS 1.
- ExactlyOnce is mapped to MQTT QoS 2.
If the KeepAliveTime is set on a WriterGroup, a value slightly higher than the configured value of the group in seconds should be set as MQTT Keep Alive ensuring that the connection is disconnected if the keep alive message was not sent by any writer in the specified time. If multiple WriterGroups are configured, the group with the highest KeepAliveTime setting is used for the calculation.
The implementation chooses packet and message size limits depending on the capabilities of the OS or of the capabilities of the device the application is running on. They can be made configurable through configuration model extensions or by other means.
MQTT messages are sent to Topics which provide context and other information about the message. Topics are hierarchical paths that allow Subscribers to use wildcards to select multiple Topics. Therefore, Topics are most useful when they follow a predictable pattern. This clause defines the Topic conventions for use with the MQTT mapping. All Publishers shall be able to support these conventions.
A Topic has the following general pattern:
<Prefix>/<Encoding>/<MqttMessageType>/<PublisherId>/[<WriterGroup>[/<DataSetWriter>]]
Where Topic levels are:
- <Prefix> is a system defined prefix that provides a scope for the PublisherIds;The default value is ‘opcua’.
- <Encoding> specifies the encoding of messages sent to the Topic (‘json’, ‘uadp’, etc);
- <MqttMessageType> specifies the content of the messages published to the Topic as defined in 7.3.5.7.2;
- <PublisherId> uniquely identifies a Publisher within the scope of the prefix;
- <WriterGroup> is the name of a WriterGroup within the Publisher;
- <DataSetWriter> is the name of a DataSetWriter within the WriterGroup;
The <Prefix> should be one Topic level, however, system designers may break <Prefix> into multiple Topic levels. Note that using multiple Topic levels prevents Subscribers from automatically discovering Publishers in the system unless they are preconfigured with the <Prefix> used for the system.
The possible values for the <Encoding> are ‘json’ or ‘uadp’ based on the message mappings defined in 7.2.3 and 7.2.4.6.9.
When Publishers are configured to publish to an MQTT Broker they shall have PublisherId assigned that can be used as Topic level.
The Topic levels that appear after the <PublisherId> depend on the <MqttMessageType>.
When these Topic conventions are used the wildcards in Table 203 may be used:
Table 203 – Examples of MQTT Wildcards
|
Wildcard |
Notes |
|
opcua/json/status/# |
Subscribes to the status of all Publishers in the “opcua” scope. This allows the Subscriber to detect when Publishers come online or disappear. |
|
opcua/json/metadata/# |
Subscribes to the metadata of all Publishers in the “opcua” scope. This allows the Subscriber to detect changes to metadata. |
|
opcua/json/data/device-one/# |
Subscribes to all data produced by Publisher “device-one” in the “opcua” scope. |
|
opcua/json/data/+/+/diagnostic |
Subscribes to all Publishers that offer a “diagnostic” writer. |
The MQTT Topic syntax places restrictions on what characters may be used in a Topic level. Specifically, Topic levels are any UTF-8 string that:
- Does not start with a $
- Does not include /, + or #
- Does not include non-printable characters or whitespace other than the space character (U+0020).
<MqttMessageType> Topic levels exist for each MessageType defined in 7.2.2. Additional information like requirements for RETAIN for each Topic level is provided in Table 204. The handling of RETAIN messages is defined in 7.3.5.8.
The requirements for topic access permissions are defined in Table 205.
Table 204 – MQTT Topic level MessageType mapping
|
MessageType |
MqttMessageType |
RETAIN |
Required |
Specification Reference |
|
DataSetMessage |
data |
False |
Yes |
Defined in 7.3.5.7.3. A system specific Topic may be used instead The RETAIN false is the default setting. |
|
DataSetMetaData |
metadata |
True |
Yes |
Defined in 7.3.5.7.4. A system specific Topic may be used instead. |
|
ApplicationDescription |
application |
True |
No |
Defined in 7.3.5.7.5. |
|
ServerEndpoints |
endpoints |
True |
No |
Defined in 7.3.5.7.6. |
|
Status |
status |
True |
Yes |
Defined in 7.3.5.7.7. |
|
PubSubConnection |
connection |
True |
Yes |
Defined in 7.3.5.7.8. |
|
ActionRequest |
action-request |
False |
Yes |
Defined in 7.3.5.7.9. A system specific Topic may be used instead |
|
ActionResponse |
action-response |
False |
No |
Defined in 7.3.5.7.10. The ActionResponse topic can be specified by the Requestor. |
|
ActionMetaData |
action-metadata |
True |
Yes |
Defined in 7.3.5.7.12. A system specific Topic may be used instead |
|
ActionResponder |
action-responder |
True |
Yes |
Defined in 7.3.5.7.11. |
Table 205 – MQTT Topic level access permissions
|
MqttMessageType |
Publisher |
Subscriber |
Description |
|
data |
Write |
Read |
Variables and Events from an OPC UA applications acting as Publisher have RolePermissions. Such RolePermissions have no affect after DataSetMessages are sent to the MQTT broker. It is therefore recommended to synchronize Roles used to configure read permissions to the topics with the Roles required to access the information in the Publisher OPC UA application. |
|
metadata |
Write |
Read |
|
|
application |
Write |
Read |
The information published with this message type is similar to discovery information provided with OPC UA Client Server discovery. This information is normally not restricted for read access. |
|
endpoints |
Write |
Read |
|
|
status |
Write |
Read |
|
|
connection |
Write |
Read |
|
|
action-request |
Read |
Write |
Publisher is the Responder and Subscriber is the Requestor. The topic with message type action-request is defined by the Responder with its PublisherId but the Requestors must have write permission to the topic. Only the Responder should be able to read from the topic. |
|
action-response |
Write |
Read |
Publisher is the Responder and Subscriber is the Requestor. If the Responder specifies the response topic it must be ensured that the Responder has Write access to this topic. The Requestor should either use unique random correlation data or should use a private response topic where only the Requestor is able to read from. |
|
action-metadata |
Write |
Read |
|
|
action-responder |
Write |
Read |
|
The data Topic has the form:
<Prefix>/<Encoding>/data/<PublisherId>/<WriterGroup>[/<DataSetWriter>]
The <PublisherId> Topic level is the PublisherId for the application sending the messages.
The <WriterGroup> Topic level is the name of a WriterGroup within the Publisher.
The <DataSetWriter> Topic level is the name of a DataSetWriter within the WriterGroup. If no QueueName is specified at the DataSetWriter level then the QueueName in WriterGroup TransportSettings is used and the DataSetWriter name is not part of the Topic.
The data Topic level is the default if the system owner does not have their own Topic tree. The Topic actually used is specified in the Connection Message as QueueName in the DataSetWriter or WriterGroup TransportSettings.
The messages are instances of the DataSetMessage MessageType (see 7.2.2).
The corresponding PubSubConnection Messag e is sent to the Topic with the same <Prefix>, <Encoding> and <PublisherId>. The PubSubConnection specifies the WriterGroups and DataSetWriters for a Publisher.
The metadata Topic has the form:
<Prefix>/<Encoding>/metadata/<PublisherId>/<WriterGroup>/<DataSetWriter>
The <PublisherId> Topic level is the PublisherId for the application sending the messages.
The <WriterGroup> Topic level is the name of a WriterGroup within the Publisher.
The <DataSetWriter> Topic level the name of a DataSetWriter within the WriterGroup.
The metadata Topic is the default if the system owner does not have their own Topic tree. The Topic actually used is specified in the Connection Message as MetaDataQueueName in the DataSetWriter TransportSettings.
The messages are instances of the DataSetMetaData MessageType (see 7.2.2).
The corresponding PubSubConnection Messag e is sent to the Topic with the same <Prefix>, <Encoding> and <PublisherId>. The PubSubConnection specifies the WriterGroups and DataSetWriters for a Publisher.
The application Topic has the form:
<Prefix>/<Encoding>/application/<PublisherId>
The <PublisherId> Topic level is the PublisherId for the application sending the messages.
The messages are instances of the ApplicationDescription MessageType (see 7.2.2).
The endpoints Topic has the form:
<Prefix>/<Encoding>/endpoints/<PublisherId>
The <PublisherId> Topic level is the PublisherId for the application sending the messages.
The messages are instances of the ServerEndpoints MessageType (see 7.2.2).
The status Topic has the form:
<Prefix>/<Encoding>/status/<PublisherId>
The <PublisherId> Topic level is the PublisherId for the application sending the messages.
The messages are instances of the Status MessageType (see 7.2.2).
A Publisher that is exclusively using a PublisherId shall register a Status message as an MQTT Will message when it creates the connection to the MQTT Broker. This message is sent automatically if the Publisher loses its connection with the MQTT Broker. The IsCyclic shall be FALSE in this case. The PubSubState value of the Will message shall be Error.
If a single MQTT client connection has multiple PubSubConnections (like for different encodings), not more than one PubSubConnection can register a Status message as MQTT Will message. All other PubSubConnections shall use cyclic Status messages.
The connection Topic has the form:
<Prefix>/<Encoding>/connection/<PublisherId>
The <PublisherId> Topic level is the PublisherId for the application sending the messages. This value shall be the same as the PublisherId in PubSubConnection provided in the message.
The PublisherId in the PubSubConnection uniquely identifies the Publisher within the scope defined by the <Prefix>.
The TransportProfileUri in the PubSubConnection specifies the <Encoding> used for all messages for the combination of <Encoding>/<PublisherId>. Table 206 specifies the mapping between a TransportProfileUri and the encoding.
Table 206 – TransportProfileUri encodings
|
URI |
Encoding |
|
http://opcfoundation.org/UA-Profile/Transport/pubsub-mqtt-json |
json |
|
http://opcfoundation.org/UA-Profile/Transport/pubsub-mqtt-uadp |
uadp |
The messages are instances of the PubSubConnection MessageType (see 7.2.2).
The action-request Topic has the form:
<Prefix>/<Encoding>/action-request/<Responder>/<WriterGroup>
The <Responder> Topic level is the PublisherId for the Responder of the Actions.
The <WriterGroup> Topic level is the name of a WriterGroup.
The action-request Topic level is the default if the system owner does not have their own Topic tree. The Topic actually used is specified in the Responder message as QueueName in the WriterGroup TransportSettings.
The messages are instances of the ActionRequest MessageType (see 7.2.2).
The corresponding Responder message is sent to the Topic with the same <Prefix>, <Encoding> and <Responder>. The PubSubConnection specifies the WriterGroups and DataSetWriters for a Responder.
The action-response Topic has the form:
<Prefix>/<Encoding>/action-response/<Responder>/<WriterGroup>
The <Responder> Topic level is the PublisherId for the Responder of the Actions.
The <WriterGroup> Topic level is the name of a WriterGroup.
The action-response Topic level is the default if the ResponseAddress is not provided in the ActionRequest.
The messages are instances of the ActionResponse MessageType (see 7.2.2).
The corresponding Responder message is sent to the Topic with the same <Prefix>, <Encoding> and <Responder>. The PubSubConnection specifies the WriterGroups and DataSetWriters for a Responder.
The action-responder Topic has the form:
<Prefix>/<Encoding>/action-responder/<Responder>
The <Responder> Topic level is the PublisherId for the Responder of the Actions. This value shall be the same as the PublisherId in PubSubConnection provided in the message.
The PublisherId in the PubSubConnection uniquely identifies the Publisher within the scope defined by the <Prefix>. If it is a String, it should be as short as possible since long Topic names degrade performance.
The messages are instances of the PubSubConnection MessageType (see 7.2.2).
The action-metadata Topic has the form:
<Prefix>/<Encoding>/action-metadata/<Responder>/<WriterGroup>/<DataSetWriter>
The <Responder> Topic level is the PublisherId for the Responder of the Action.
The <Group> Topic level is the name of a WriterGroup.
The <Writer> Topic level the name of a DataSetWriter.
The action-metadata Topic is the default if the system owner does not have their own Topic tree. The Topic actually used is specified in the Responder message as MetaDataQueueName in the DataSetWriter TransportSettings.
The messages are instances of the ActionMetaData MessageType (see 7.2.2).
The corresponding PubSubConnection Messag e is sent to the Topic with the same <Prefix>, <Encoding> and <PublisherId>. The PubSubConnection specifies the WriterGroups and DataSetWriters for a Publisher.
The default setting for the MQTT RETAIN flag are defined in Table 204. Table 208 defines an option to change the RETAIN flag setting for DataSetMessages.
A Publisher shall send all RETAIN discovery messages at start up of the Publisher. A Publisher shall update affected RETAIN topics if the Publisher configuration changes. A Publisher shall clear RETAIN topics if the discovery element is deleted from the Publisher configuration like reset the metadata topic if the related DataSetWriter is removed. A Publisher shall subscribe to its own discovery message topics at start-up and clear all topics that do not match the current Publisher configuration.
Publishers using MQTT version 3.1.1 shall clear RETAIN topics when they shut down.
Publishers using MQTT version 5.0 shall set the Message Expiry Interval on RETAIN topics and shall send a new RETAIN message before the interval expires.
The MQTT version 3.1.1 protocol does not support message headers. Any promoted field or additional fields defined on the WriterGroup or DataSetWriter other than RETAIN are not sent as MQTT message properties.
MQTT version 5.0 defines a number of standard message properties. These include properties explicitly defined in the MQTT specification, as well as the MQTT User Property which is a key-value pair of UTF-8 strings. The MQTT User Property is intended to provide a means of transferring application layer name-value tags whose meaning and interpretation are known only by the application programs responsible for sending and receiving them. They are used here to specify PubSub properties not directly supported by the MQTT protocol.
Table 207 describes how these properties shall be populated when a MQTT version 5.0 message is constructed.
Table 207 – OPC UA MQTT message properties
|
MQTT property name |
MQTT property type |
MQTT property value |
|
UAMessageType |
User Property |
Valid values are “ua-<MqttMessageType>” where the MqttMessageTypes are defined in 7.3.5.7.2. |
|
Content Type |
Standard |
The MIME type for the message body. The MIME types are specified in the message body subsections 7.3.5.9.1 and 7.3.5.9.2. |
The MQTT message header shall include additional fields defined on the PubSubConnection, WriterGroup or DataSetWriter through the KeyValuePair array in the WriterGroupProperties and DataSetWriterProperties. The NamespaceIndex of the QualifiedName in the KeyValuePair shall be 0. The Name of the QualifiedName is constructed from a message prefix and the MQTT property name with the following syntax.
Name = <MqttMessageType>-<MQTT property name>
The Name of the key in the KeyValuePair shall have a prefix “message” followed by a hyphen and the MQTT property name.
Table 208 defines the MQTT standard message properties.
Table 208 – OPC UA MQTT standard message property configuration
|
MQTT property name |
OPC UA DataTypes |
MQTT data types |
Description |
|
RETAIN |
Boolean |
RETAIN bit in the header |
RETAIN configuration for DataSetMessages. |
|
Message Expiry Interval |
UInt32 |
Four Byte Integer |
Not available as message property for MQTT 3.1.1. |
Any name not in the Table 208 is assumed to be a MQTT User Property.
When a field is added to the header as a MQTT User Property the value is encoded as UTF-8 encoded String. If the value is not a String, then it is encoded using the VerboseEncoding OPC UA JSON Data Encoding rules in OPC 10000-6. Promoted fields can only be sent for fields which are assumed to be a MQTT User Property and if the NetworkMessage contains only one DataSetMessage. The MQTT message header shall include additional promoted fields of the DataSet as a list of MQTT User Property name-value pairs. DataSet fields with the PromotedField flag set in the FieldMetaData fieldFlags are copied into the MQTT header. The FieldMetaData Structure is defined in 6.2.3.2.4. For a UADP message mapping the promoted fields are also included in the UADP NetworkMessage. Promoted fields shall always be included in the header even if the DataSetMessage body is a delta frame and the DataSet field is not included in the delta frame. In this case the last known value is sent in the header.
A JSON body is encoded as defined for the JSON message mapping defined in 7.2.4.6.9.
When sending a MQTT Version 5.0 message the MQTT ContentType property shall be set to application/json when sending uncompressed JSON messages.
JSON messages can become quite large. In order to save bandwidth and to reduce message size, on MQTT Version 5.0 the MQTT Content Type property allows to select a compression type as encoding for a JSON message.
When sending a gzip (RFC 1952) compressed JSON message on MQTT Version 5.0 the MQTT ContentType property shall be set to application/json+gzip. If a Subscriber receives messages without MQTT ContentType from MQTT Version 3.1.1 Publishers it may require manual configuration.
A UADP body is encoded as defined for the UADP message mapping defined in 7.2.3.
It is expected that the software used to receive UADP NetworkMessage can process the body without needing to know how it was transported.
If the encoded MQTT message size exceeds the Broker limits, it is broken into multiple chunks as described in 7.2.4.4.4.
When sending such message over MQTT Version 5.0 the ContentType property shall be set to application/opcua+uadp.