This clause 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 tranposrt 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.

The UADP message mapping uses optimized UA Binary encoding 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 message types and data encodings.

A Publisher shall 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 UADP NetworkMessage header and other parts of the NetworkMessage are shown in Figure 27.

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.

image030.png

Figure 27 – UADP NetworkMessage

The encoding of the UADP NetworkMessage is specified in Table 73.

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 73 – 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.

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 Reserved

111 Reserved

Bit 3: DataSetClassId enabled

Bit 4: Security enabled

If the SecurityMode is SIGN_1 or SIGNANDENCRYPT_2, this flag is set, message security is enabled and the SecurityHeader is contained in the NetworkMessage header.

If this flag is not set, the SecurityHeader is omitted.

Bit 5: Timestamp enabled

Bit 6: PicoSeconds enabled

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

Bit 1: PromotedFields enabled

Promoted fields can only be sent if the NetworkMessage contains only one DataSetMessage.

Bit range 2-4: UADP NetworkMessage type

000 NetworkMessage with DataSetMessage payload defined in 7.2.2.2.4. If the ExtendedFlags2 field is not provided, this is the default NetworkMessage type.

001 NetworkMessage with discovery request payload defined in 7.2.2.3.4.

010 NetworkMessage with discovery response payload defined in 7.2.2.4.2.

011 Reserved

1xxReserved

Bit 5: Reserved

Bit 6: Reserved

Bit 7: Reserved for further extended flag fields

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.

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

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 the NetworkMessage.

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 0-3. 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.

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 picoseconds (1,0 e-11 seconds) intervals which shall be added to the Timestamp.

The PicoSeconds shall be omitted if bit 6 of ExtendedFlags1 is false.

PromotedFields

The PromotedFields shall be omitted if bit 4 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 Encrypted

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 must 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, that no longer have access to the keys.

Bit range 4-7: Reserved

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.

NonceLength

Byte

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

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

SecurityFooterSize

UInt16

The size of the SecurityFooter.

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

Payload

Byte [*]

The payload depends on the UADP NetworkMessage Type flags defined in the ExtendedFlags2 bit range 2-5.

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 algorithm and nonce length used of the UADP NetworkMessage security depend on the selected SecurityPolicy. They are defined by SymmetricPubSubEncryptionAlgorithm and SymmetricPubSubNonceLength.

The keys used to encrypt and sign messages are returned from the GetSecurityKeys method (see 8.4). This Method returns a sequence of random data with a length that depends on the SecurityPolicyUri, which is also returned by the Method. The layout of the random data is defined in Table 74.

Table 74 – 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 KeyLength]

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

KeyNonce

Byte [SymmetricPubSubNonceLength]

Nonce part of the key data returned from GetSecurityKeys.

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

Table 75 – 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

A strictly monotonically increasing sequence number assigned by the publisher to each NetworkMessage sent for a SecurityTokenId and PublisherId combination.

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

A receiver should ignore older NetworkMessages than the last sequence processed if it does not handle reordering of NetworkMessages. Receivers need to be aware of sequence numbers roll over (change from 4294967295 to 0).

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

(4294967295 + received sequence number – last processed sequence number) modulo 4294967296.

Results below 1073741824 indicate that the received NetworkMessages is newer than the last processed NetworkMessages and the received NetworkMessages is processed.

Results above 3221225472 indicate that the received message is older (or same) than the last processed NetworkMessages and the received NetworkMessages should be ignored if reordering of NetworkMessages is not necessary.

Other results are invalid and the NetworkMessages shall be ignored.

The key lifetime should be selected in a way that a new key is used before a rollover for the SequenceNumber happens.

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

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 74. The layout and content of the counter block is defined in Table 76.

Table 76 – Layout of the counter block for UADP message security

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 0 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 the 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 receives a NetworkMessage, it shall verify the signature first. If verification fails, it drops the NetworkMessage.

Other SecurityPolicy may specify different key lengths or cryptography algorithms.

If a NetworkMessage payload like a DataSetMessage or a discovery response message has to be split across multiple NetworkMessages the chunks are sent with the payload header defined in Table 77 and the payload defined in Table 78. A chunk NetworkMessage can only contain chunked payload of one DataSetMessage.

Table 77 – 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.

The DataSetWriterId shall be set to 0 for discovery response messages.

Table 78 – 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 Subscribers 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 received if ChunkOffset plus the size of the current chunk equals TotalSize.

The reassembled NetworkMessage payload can be processed after all chunks are received.

TotalSize

UInt32

Total size of the NetworkMessage payload in bytes.

ChunkData

ByteString

The pieces of the original DataSetMessage, 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 is completely received when all chunks are received and the DataSetMessage can be processed completely.

The UADP DataSet payload header and other parts of the NetworkMessage are shown in Figure 28.

Different types of DataSetMessage can be combined in on NetworkMessage.

image031.png

Figure 28 – UADP DataSet Payload

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

Table 79 – UADP DataSet Payload Header

Name

Type

Description

Count

Byte

Number of DataSetMessages contained in the NetworkMessage. The NetworkMessage shall contain at least one DataSetMessages 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 80. The payload is encrypted.

Table 80 – 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.2.3.4.

The DataSetMessage header structure and the relation to other parts in a NetworkMessage is shown in Figure 29.

image032.png

Figure 29 – DataSetMessage Header Structure

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

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 81 – 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 DataSet fields are encoded in the DataTypes specified in the DataSetMetaData for the DataSet.

The encoding 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.

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

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

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

If the DataSetFlags2 field is not provided, this is the default DataSetMessage type.

0001Data Delta Frame (see 7.2.2.3.6)

0010Event (see 7.2.2.3.7)

0011Keep Alive (see 7.2.2.3.8)

01xxReserved

1xxxReserved

Bit 4: Timestamp enabled

Bit 5: PicoSeconds included in the DataSetMessage header

Bit 6: Reserved

Bit 7: Reserved for further extended flag fields

DataSetMessage‌SequenceNumber

UInt16

A strictly monotonically increasing sequence number assigned by the publisher to each DataSetMessage sent.

A receiver should ignore older DataSetMessage than the last sequence processed if it does not handle reordering of DataSetMessages. Receivers need to be aware of sequence numbers roll over (change from 65535 to 0).

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

(65535 + received sequence number – last processed sequence number) modulo 65536

Results below 16384 indicate that the received DataSetMessage is newer than the last processed DataSetMessage and the received DataSetMessage is processed.

Results above 49162 indicate that the received message is older (or same) than the last processed DataSetMessage and the received DataSetMessage should be ignored if reordering of DataSetMessages is not necessary.

Other results are invalid and the DataSetMessage shall be ignored.

The field shall be omitted if Bit 2 of DataSetFlags1 is false.

Timestamp

UtcTime

The time the Data was collected.

The Timestamp shall be omitted if Bit 3 of DataSetFlags1 is false.

PicoSeconds

UInt16

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

The field shall be omitted if Bit 4 of DataSetFlags2 is false.

Status

UInt16

The overall status of the DataSet.

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

image033.png

Figure 30 – Data Key Frame DataSetMessage Data

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

Table 82 – 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.2.3.4.

DataSetFields

BaseDataType[]

The field values of the DataSet.

The field encoding depends on the EncodingFlags of the DataSetMessage Header defined in 7.2.2.3.4. The default encoding is Variant if bit 0 and 1 are not set.

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

image034.png

Figure 31 – 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 83.

Table 83 – Data Delta Frame DataSetMessage Structure

Name

Type

Description

FieldCount

UInt16

Number of fields of the DataSet contained in the DataSetMessage.

DeltaFrameFields

Structure[]

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.

FieldValue

BaseDataType

The field values of the DataSet.

The field encoding depends on the EncodingFlags of the DataSetMessage Header defined in 7.2.2.3.4. The default encoding is Variant if bit 2 and 3 are not set.

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

image035.png

Figure 32 – Event DataSetMessage

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

Table 84 – Event DataSetMessage Structure

Name

Type

Description

FieldCount

UInt16

Number of fields of the DataSet contained in the DataSetMessage.

DataSetFields

BaseDataType[]

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.2.3.4 shall be set to false.

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

image036.png

Figure 33 – KeepAlive Message

The sequence number contains the next expected sequence number for the DataSetWriter.

The NetworkMessage flags used with the discovery request 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 five fields 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 requests shall be randomly delayed in the range of 100-500 ms. The request shall be skipped if the information is already received during this time or another Subscriber sent already a request and the response to this request is used.

Discovery requests for different DataSetWriters in one WriterGroup shall be aggregated into one discovery response.

A Publisher shall delay subsequent responses for a combination of request type and identifier like the DataSetWriterId for at least 500 ms. Duplicate requests, that have not yet been responded to, shall be discarded by the Publisher.

A Subscriber shall wait for a response at least 500 ms. As long as not all responses are received, the Subscriber requests the missing information. It shall double the time period between follwing requests until all needed response are received or denied.

The encoding of the discovery request header structure is specified in Table 85.

Table 85 – Discovery Request Header Structure

Name

Type

Description

RequestType

Byte

The following types of discovery request messages are defined.

0Reserved

1 Publisher information request message (see 7.2.2.4.1.4)

The encoding of the Publisher information request message structure is specified in Table 86.

Table 86 – Publisher Information Request Message Structure

Name

Type

Description

InformationType

Byte

The following types of Publisher information requests are defined.

0Reserved

1 Publisher Server Endpoints

2 DataSetMetaData

3 DataSetWriter configuration

DataSetWriterIds

UInt16[]

List of DataSetWriterIds the information is requested for.

If the request is not related to DataSet, the array shall be null.

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

The setting of the flags ensures a known value for the first five fields in the NetworkMessage for Publishers expected by the Subscriber. The actual security settings for the NetworkMessage are indicated by the SecurityHeader.

The encoding of the discovery response header structure is specified in Table 87.

Table 87 – Discovery Response Header Structure

Name

Type

Description

ResponseType

Byte

The following types of discovery response messages are defined.

0Reserved

1Publisher Endpoint message (see 7.2.2.4.2.3)

2DataSet Metadata message (see 7.2.2.4.2.4)

3DataSetWriter configuration message (see 7.2.2.4.2.5)

SequenceNumber

UInt16

A strictly monotonically increasing sequence number assigned to each discovery response sent in the scope of a PublisherId.

The encoding of the available Endpoints of a Publisher is specified in Table 88.

Table 88 – Publisher Endpoints Message Structure

Name

Type

Description

Endpoints

EndpointDescription[]

The OPC UA Server Endpoints of the Publisher. The EndpointDescription is defined in OPC 10000-4.

statusCode

StatusCode

Status code indicating the capability of the Publisher to provide Endpoints.

The encoding of the DataSet metadata message structure is specified in Table 89. 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 request if the DataSetMetaData changed for the DataSet.

Table 89 – DataSetMetaData 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.2.1.2.

statusCode

StatusCode

Status code indicating the capability of the Publisher to provide MetaData for the DataSetWriterId.

The encoding of the DataSetWriter configuration data message structure is specified in Table 90. It contains the current configuration of the WriterGroup and the DataSetWriter for the DataSet.

The Publisher shall send this message without a corresponding discovery request if the configuration of the WriterGroup changed.

Table 90 – DataSetWriter Configuration Message Structure

Name

Type

Description

DataSetWriterIds

UInt16[]

DataSetWriterIds contained in the configuration information.

DataSetWriterConfig

WriterGroupDataType

The current WriterGroup and DataSetWriter settings for the DataSet related to the DataSetWriterId. The WriterGroupDataType is defined in 6.2.5.6.

The field DataSetWriters of the WriterGroupDataType shall contain only the entry for the requested or changed DataSetWriters in the WriterGroup.

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.

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

The JSON based message mapping allows OPC UA Applications to interoperate with web and enterprise software that use this format.

Each JSON NetworkMessage contains one or more JSON DataSetMessages. The JSON NetworkMessage is a JSON object with the fields defined in Table 91.

Table 91 – JSON 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-data”.

This value is mandatory.

PublisherId

String

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

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

The source is the PublisherId on a PubSubConnection (see 6.2.6.1).

DataSetClassId

String

The DataSetClassId associated with the DataSets in the NetworkMessage.

This value is optional. 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.2.2) associated with the DataSetWriters that produced the DataSetMessages.

Messages

*

A JSON array of JSON DataSetMessages (see 7.2.3.3).

This value is mandatory.

All fields with a concrete DataType defined are encoded using reversible 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.3.3).

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 DataSetMetData Objects. A DataSetMessage is a JSON object with the fields defined in Table 92.

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

Table 92 – JSON DataSetMessage Definition

Name

Type

Description

DataSetWriterId

String

An identifier for DataSetWriter which created the DataSetMessage.

This value is mandatory.

It is unique within the scope of a Publisher.

SequenceNumber

UInt32

A strictly monotonically increasing sequence number assigned to the DataSetMessage by the DataSetWriter.

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

MetaDataVersion

ConfigurationVersionDataType

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

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

Timestamp

DateTime

A timestamp which applies to all values contained in the DataSetMessage.

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

Status

StatusCode

A status code which applies to all values contained in the DataSetMessage.

This value is optional. 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 DataSetMessageContentMask.

All fields with a concrete DataType are encoded using reversible OPC UA JSON Data Encoding defined in OPC 10000-6.

The fields in the DataSetMessage are specified by the DataSetFieldContentMask in the DataSetWriter parameters.

DataSetFieldContentMask specifies the format of the field values in the Payload according to the following rules:

The JSON message mapping defines only one optional discovery message for the exchange of the DataSetMetaData. The main purpose is the exchange of additional information not contained in the DataSetMessages like Properties for the DataSet fields.

DataSetMetaData describe the content a DataSet 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 DataSetMetaData is a JSON object with the fields defined in Table 93.

Table 93 – 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.

MetaData

DataSetMetaDataType

The metadata as defined in 6.2.2.1.2.

This value is mandatory.

All fields with a concrete DataType are encoded using reversible OPC UA JSON Data Encoding defined in OPC 10000-6.

This clause lists the standard protocols that have been selected for this specification and their possible combinations with message mappings.

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

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

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

The host is either an IP address or a registered name like a hostname or domain name. IP addresses can be unicast, multicast or broadcast addresses. 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, multicast and unicast communication. Alternative ports may be used.

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

Table 94 – 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. 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.

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.

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

It is recommended to use switches with IGMP support to limit the distribution of multicast traffic to the interested participants. OPC UA Applications shall issue an IGMP membership report.

Note: The Internet Group Management Protocol (IGMP) is a standard protocol used by hosts to report their IP multicast group memberships and must 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.There are three versions of IGMP: - IGMP V1 is defined in RFC1112. - IGMP V2 is defined in RFC2236. - IGMP V3 is defined in RFC3376.RFC2236 and RFC3376 discuss host and router requirements for interoperation with older IGMP versions.Since OPC UA devices make extensive use of IP multicast for UDP transport, consistent IGMP usage by OPC UA devices is essential in order to create well-functioning OPC UA Application networks.

IGMP Membership Report MessagesOPC UA devices shall issue a Membership Report message (V1, V2 or V3 as appropriate) when opening a UDP connection on which they will receive multicast NetworkMessages.

OPC UA Ethernet is a simple Ethernet based protocol using EtherType B62C 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.6.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.

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

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

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 specification defines two possible message mappings for the AMQP message body, the UADP message mapping defined in 7.2.2 and a JSON message mapping defined in 7.2.3. AMQP Brokers have an upper limit on message size. The mechanism for handling NetworkMessage that exceed the Broker limits depend on the encoding.

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.2.2. 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.6.3 has the following form:

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

The default port is 5671.

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 98. If there is no rule defined for a data type, the property shall not be included.

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

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

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

This matches to the BrokerTransportQualityOfService values as follows:

If the KeepAliveTime is set on a WriterGroup, a value slightly higher than the configured value of the group should be used as idle timeout of the 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 or 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. Table 96 describes how these fields shall be populated when an AMQP message is constructed.

Table 96 – AMQP Standard Header Fields

Field Name

Source

message-id

A globally unique value created by the DataSetWriter.

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 subsections 7.3.4.8.1 and 7.3.4.8.2.

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 97 defines the AMQP standard message properties.

Table 97 - OPC UA AMQP Standard Header QualifiedName Name mappings

AMQP standard property name

OPC UA DataType

AMQP data type

to

String

*

user-id

ByteString

binary

reply-to

String

string

correlation-id

ByteString

*

absolute-expiry-time

DateTime

timestamp

group-id

String

string

reply-to-group-id

String

string

creation-time

DateTime

timestamp

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 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.2.1.3. 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 98. If there is no rule defined for the data type, the field shall not be included.

Table 98 – 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 is = 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.

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

The corresponding MIME type is application/json.

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

The corresponding MIME type is application/opcua+uadp.

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

It is recommended that the MetaDataQueueName as described in 6.4.2.3.6 is configured as a sub-topic of the related QueueName with the name $Metadata.

The Message Queue Telemetry Transport (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.

This specification defines two possible encodings for the message body: the binary encoded DataSetMessage defined in 7.2.2 and a JSON encoded DataSetMessage defined in 7.2.3. MQTT does not provide a mechanism for specifying the encoding of the MQTT message which means the Subscribers shall be configured in advance with knowledge of the expected encoding. Publishers should only publish NetworkMessages using a single encoding to a unique MQTT topic name.

Security with MQTT is primary 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 security. Applications that require end-to-end security with MQTT need to use the UADP NetworkMessages and binary message encoding defined in 7.2.2. JSON encoded message bodies must rely on the security mechanisms provided by MQTT and the MQTT server.

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

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

The default port is 8883.

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

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

The default port is 443.

The current MQTT transport mapping only supports simple Username/Password authentication.

The current MQTT transport mapping does not support the concept of connection properties and any configured setting in the connection properties shall be silently discarded.

Implementations should attempt to reconnect to existing sessions (CleanSession=0) and attempt to resume message transfer at the specified QoS level.

The BrokerTransportQualityOfService values map to MQTT publish and subscribe QoS settings as follows:

  • AtMostOnce_1 is mapped to MQTT QoS 0.
  • AtLeastOnce_2 is mapped to MQTT QoS 1.
  • ExactlyOnce_3 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.

The implmentation choses packet and message size limits depending on the capabilities of the OS or or the capabilities of the device the application is running on. They can be made configurable through configuration model extensions or by other means.

The current MQTT transport mapping does not support message headers. Any promoted field or additional fields defined on the WriterGroup or DataSetWriter shall be silently discarded. Implementations shall not set the MQTT RETAIN flag, except for meta data messages published to the MetaDataQueueName as described in 6.4.2.3.6.

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

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

It is expected that the software used to receive UADP 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.2.2.4.

It is recommended that the MetaDataQueueName as described in 6.4.2.3.6 is configured as a sub-topic of the related QueueName with the name $Metadata. The MQTT RETAIN flag shall be set for metadata messages.