7 PubSub mappings ToC Previous Next

7.2 Message mappings ToC Previous Next

7.2.2 UADP message mapping ToC Previous Next

7.2.2.1 General ToC

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 message types and data encodings.

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

7.2.2.2 Error handling ToC

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.

7.2.2.3 SequenceNumber in headers ToC

SequenceNumber fields are defined in different headers of the UADP 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 133. The SequenceNumber starts at 0 and shall be incremented by exactly one for each message.

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

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

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

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

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

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

Other results are invalid and the message shall be ignored.

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

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

Table 133 – Values for different sequence number sizes

DataType Name Value Description
UInt16 Formula (New-1-Last) modulo 65536  
  Lower bound 16384 2^14
  Upper bound 49152 2^16-2^14
UInt32 Formula (New-1-Last) modulo 4294967296  
  Lower bound 1073741824 2^30
  Upper bound 3221225472 2^32-2^30

Subscribers shall discard 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.

7.2.2.4 NetworkMessage ToC

7.2.2.4.1 General ToC

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

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.

readme_files/image032.png Figure 29 – UADP NetworkMessage

7.2.2.4.2 NetworkMessage layout ToC

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

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 134 – 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 enabledBit 7: ExtendedFlags1 enabled The 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 Reserved 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: Security enabled      If the SecurityMode is SIGN or SIGNANDENCRYPT, 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      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.2.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.2.4.4. If the ExtendedFlags2 field is not provided, this is the default NetworkMessage type.      001 NetworkMessage with discovery probe defined in 7.2.2.5.4.      010 NetworkMessage with discovery announcement payload defined in 7.2.2.6.4.      011 Reserved      1xx Reserved      Reserved values shall not be used by the sender and the receiver shall skip messages when reserved values are received.   Bit 5: Reserved   Bit 6: Reserved   Bit 7: Reserved for further extended flag fieldsReserved 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.
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 fieldsReserved 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.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 Encrypted The 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: ReservedReserved 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.
   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.4.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-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.

7.2.2.4.3 UADP message security ToC

7.2.2.4.3.1 General ToC

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

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

Name Type Description
SigningKey Byte [SymmetricSignatureAlgorithm Key Length] Signing key part of the key data returned from GetSecurityKeys. The SymmetricSignatureAlgorithm is defined in the SecurityPolicy.
EncryptingKey Byte [SymmetricEncryptionAlgorithm Key Length] Encryption key part of the key data returned from GetSecurityKeys. The SymmetricEncryptionAlgorithm is defined in the SecurityPolicy.
KeyNonce Byte [SymmetricEncryption Nonce Length] Nonce part of the key data returned from GetSecurityKeys.

7.2.2.4.3.2 AES-CTR ToC

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

Table 136 – Layout of the MessageNonce for AES-CTR

Name Type Description
Random Byte [4] The random part of the MessageNonce. This number does not need to be a cryptographically random number, it can be pseudo-random.
SequenceNumber UInt32    Sequence number for the MessageNonce as defined in 7.2.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 135. The layout and content of the counter block is defined in Table 137.

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

Name Type Description
KeyNonce Byte [4] The KeyNonce portion of the key data returned from GetSecurityKeys.
MessageNonce Byte [8]    The first 8 bytes of the 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.

7.2.2.4.4 UADP Chunk NetworkMessage ToC

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 138. The Payload of each NetworkMessage contains the payload defined in Table 139. 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 139. The payload header is disabled for discovery probe and discovery announcement NetworkMessages.

Table 138 – Chunked NetworkMessage payload header

Name Type Description
DataSetWriterId UInt16    DataSetWriterId contained in the NetworkMessage.   The 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 139 – 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.

7.2.2.5 DataSetMessage ToC

7.2.2.5.1 General ToC

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

Different types of DataSetMessage can be combined in on NetworkMessage.

readme_files/image033.png Figure 30 – UADP DataSet payload

7.2.2.5.2 DataSet payload header ToC

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

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

7.2.2.5.3 DataSet payload ToC

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

Table 141 – UADP DataSet payload

Name Type Description
Sizes UInt16 [Count]    List of byte sizes of the DataSetMessages.   The size of the list is defined by the 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.5.4.

7.2.2.5.4 DataSetMessage header ToC

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

readme_files/image034.png Figure 31 – DataSetMessage header structure

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

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 142 – 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.2.5.9.      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      0000 Data Key Frame (see 7.2.2.5.5)            If the DataSetFlags2 field is not provided, this is the default DataSetMessage type.      0001 Data Delta Frame (see 7.2.2.5.6)      0010 Event (see 7.2.2.5.7)      0011 Keep Alive (see 7.2.2.5.8)      01xx Reserved      1xxx Reserved      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 header This bit shall be false if the Timestamp bit is false.   Bit 6: Reserved   Bit 7: Reserved for further extended flag fieldsReserved 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.2.3.The field shall be omitted if Bit 3 of DataSetFlags1 is false.
Timestamp UtcTime    The time the Data was collected.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 ‘9999’.The field shall be omitted if Bit 5 of DataSetFlags2 is false.
Status UInt16    The overall status of the DataSetMessage.   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.
   ConfigurationVersionMajorVersion 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.
   ConfigurationVersionMinorVersion 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.

7.2.2.5.5 Data Key Frame DataSetMessage ToC

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

readme_files/image035.png Figure 32 – Data Key Frame DataSetMessage data

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

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

Table 143 – Data Key Frame DataSetMessage structure

Name Type Description
FieldCount UInt16    Number of fields of the DataSet contained in the DataSetMessage.The FieldCount shall be omitted if RawData field encoding is set in the EncodingFlags defined in 7.2.2.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.2.5.4. The default encoding is Variant if bit 1 and 2 are not set.
Padding Byte [*] Optional padding added if the encoded DataSetMessage is smaller than the ConfiguredSize. The DataSetMessage is padded with bytes with value zero.

7.2.2.5.6 Data Delta Frame DataSetMessage ToC

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

readme_files/image036.png Figure 33 – Data Delta Frame DataSetMessage

The information for a single value in delta frame messages is larger because of the additional index necessary for sending just changed data. The 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 144.

Table 144 – Data Delta Frame DataSetMessage structure

Name Type Description
FieldCount UInt16 Number of fields of the DataSet contained in the DataSetMessage.
DeltaFrameFields Structure [FieldCount] The subset of field values of the DataSet contained in the delta frame.
   FieldIndex UInt16    The index of the Field in the DataSet. The index is based on the field position in the 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.2.5.4. The default encoding is Variant if bit 1 and 2 are not set.
Padding Byte [*] Optional padding added if the encoded DataSetMessage is smaller than the ConfiguredSize. The DataSetMessage is padded with bytes with value zero.

7.2.2.5.7 Event DataSetMessage ToC

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

readme_files/image037.png Figure 34 – Event DataSetMessage

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

Table 145 – Event DataSetMessage structure

Name Type Description
FieldCount UInt16 Number of fields of the 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.2.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.

7.2.2.5.8 KeepAlive message ToC

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

readme_files/image038.png Figure 35 – KeepAlive message

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

7.2.2.5.9 RawData field encoding ToC

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.

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 dimensions, 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 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. 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.
  • 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. 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.

7.2.2.6 Discovery messages ToC

7.2.2.6.1 General ToC

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.

7.2.2.6.2 Discovery scope ToC

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.

7.2.2.6.3 UADP discovery probe NetworkMessage ToC

7.2.2.6.3.1 General ToC

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.

7.2.2.6.3.2 Traffic reduction ToC

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.

7.2.2.6.3.3 Discovery probe header ToC

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

Table 146 – Discovery probe header structure

Name Type Description
ProbeType Byte    The following types of discovery probe messages are defined.   0 Reserved   1 Publisher information probe message (see 7.2.2.6.3.4)2 FindApplications probe message. The message type does not have additional fields. The PublisherId is set to NULL.

7.2.2.6.3.4 Publisher information probe message ToC

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

Table 147 – Publisher information probe message structure

Name Type Description
InformationType Byte    The following types of Publisher information probes are defined.   0 Reserved   1 Publisher Server Endpoints      No additional fields are defined.      The information is provided with the Publisher Endpoints announcement message defined in 7.2.2.6.4.3.   2 DataSetMetaData      The settings for this InformationType are defined in Table 148.      The information is provided with the DataSetMetaData announcement message defined in 7.2.2.6.4.4.   3 DataSetWriter configuration      The settings for this InformationType are defined in Table 148.      The information is provided with the DataSetWriter configuration announcement message defined in 7.2.2.6.4.5.   4 WriterGroup configuration      The settings for this InformationType are defined in Table 149      The information is provided with the DataSetWriter configuration announcement message defined in 7.2.2.6.4.5.   5 PubSubConnections configuration      The settings for this InformationType are defined in Table 150   The information is provided with the PubSubConnection configuration announcement message defined in 7.2.2.6.4.6.

The additional field for DataSetWriter related InformationType in a Publisher information probe message are specified in Table 148.

Table 148 – 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 149.

Table 149 – 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 150.

Table 150 – PubSubConnections settings for Publisher information probe

Name Type Description
TransportProfileUris String []    Filter criteria for the PubSubConnections to return in the PubSubConnection configuration announce message.   If TransportProfileUris are set, only 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.

7.2.2.6.4 UADP discovery announcement NetworkMessage ToC

7.2.2.6.4.1 General ToC

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.

7.2.2.6.4.2 Discovery announcement header ToC

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

Table 151 – Discovery announcement header structure

Name Type Description
AnnouncementType Byte    The following types of discovery announcement messages are defined.   0 Reserved   1 Publisher Endpoints message (see 7.2.2.6.4.3)   2 DataSetMetaData message (see 7.2.2.6.4.4)   3 DataSetWriter configuration message (see 7.2.2.6.4.5)   4 PubSubConnection configuration message (see 7.2.2.6.4.6)5 OPC UA Application information message (see 7.2.2.6.4.7)
SequenceNumber UInt16 Sequence number, incremented by exactly one, for each discovery announcement sent in the scope of a PublisherId.

7.2.2.6.4.3 Publisher Endpoints announcement message ToC

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

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

7.2.2.6.4.4 DataSetMetaData announcement message ToC

The encoding of the DataSet metadata message structure is specified in Table 153. 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 153 – 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.2.
statusCode StatusCode Status code indicating the capability of the Publisher to provide MetaData for the DataSetWriterId.

7.2.2.6.4.5 DataSetWriter configuration announcement message ToC

The encoding of the DataSetWriter configuration data message structure is specified in Table 154. 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 154 – 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.
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.

7.2.2.6.4.6 PubSubConnection configuration announcement message ToC

The encoding of the PubSubConnection configuration announcement message structure is specified in Table 155. It contains an array of PubSubConnections configured in the OPC UA Application.

Table 155 – PubSubConnection configuration announcement message structure

Name Type Description
PubSubConnections PubSubConnectionDataType []    PubSubConnections configured for the OPC UA Application.    The PubSubConnectionDataType is defined in 6.2.7.5.1.   The 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.

7.2.2.6.4.7 OPC UA Application information announcement message ToC

The encoding of the OPC UA Application information announcement message structure is specified in Table 156.

Table 156 – OPC UA Application information announcement message structure

Name Type Description
ApplicationInformationType UInt16    The following types of application information are defined.   0 Reserved1 Application description (see Table 157)

The encoding of the OPC UA Application description message fields for ApplicationInformationType 1 is specified in Table 157. It contains the ApplicationDescription and the capabilities.

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

Previous Next