6 PubSub communication parameters ToC Previous Next

6.3 Message mapping configuration parameters ToC Previous Next

6.3.1 UADP message mapping ToC Previous Next

6.3.1.1 UADP NetworkMessage Writer ToC

6.3.1.1.1 Relationship of Timing parameters ToC

The PublishingInterval, the SamplingOffset the PublishingOffset and the timestamp in the NetworkMessage header shall use the same time base.

If an underlying network provides a synchronized global clock, this clock shall be used as the time base for the Publisher and Subscriber.

The beginning of a PublishingInterval shall be a multiple of the PublishingInterval relative to the start of the time base. The reference start time of the PublishingInterval can be calculated by using the following formula:

Start of periodic execution =

current time + PublishingInterval – (current time / PublishingInterval)

Current time is the number of nanoseconds since the start of epoch used by the reference clock.

PublishingInterval is the duration in nanoseconds.

Start of periodic execution is the number of nanoseconds since the start of epoch which is the next possible start of a PublishingInterval.

Figure 25 shows an example how to select the possible start of a PublishingInterval.

readme_files/image028.png Figure 25 – Start of the periodic publisher execution

The different timing offsets inside a PublishingInterval cycle on Publisher and Subscriber side are shown in Figure 26. The SamplingOffset and PublishingOffset are defined as parameters of the UADP WriterGroup. The ReceiveOffset and the ProcessingOffset are defined as parameters of the UADP DataSetReader in 6.3.1.4.

readme_files/image029.png Figure 26 – Timing offsets in a PublishingInterval

6.3.1.1.2 GroupVersion ToC

The GroupVersion with DataType VersionTime reflects the time of the last layout change of the content of the NetworkMessages published by the WriterGroup. The VersionTime DataType is defined in OPC 10000-4. The GroupVersion changes when one of the following parameters is modified:

  • NetworkMessageContentMask of this WriterGroup;
  • Offset of any DataSetWriter in this WriterGroup;
  • MinorVersion of the DataSet of any DataSetWriter in this WriterGroup;
  • DataSetFieldContentMask of any DataSetWriter in this WriterGroup;
  • DataSetMessageContentMask of any DataSetWriter in this WriterGroup;
  • DataSetWriterId of any DataSetWriter in this WriterGroup. The GroupVersion is valid for all NetworkMessages resulting from this WriterGroup.

6.3.1.1.3 DataSetOrdering ToC

The DataSetOrdering defines the ordering of the DataSetMessages in the NetworkMessages. Possible values for DataSetOrdering are described in Table 80. The default value is Undefined.

The DataSetOrderingType is an enumeration that specifies the possible options for the ordering of DataSetMessages inside and across NetworkMessages. The possible enumeration values are described in Table 80.

Table 80 – DataSetOrderingType values

Name Value Description
Undefined 0 The ordering of DataSetMessages is not specified.
AscendingWriterId 1 DataSetMessages   are ordered ascending by the value of their corresponding DataSetWriterIds.
AscendingWriterIdSingle 2 DataSetMessages   are ordered ascending by the value of their corresponding DataSetWriterIds and only one DataSetMessage is sent per NetworkMessage.

If DataSetOrdering is Undefined any ordering between DataSets and their distribution into NetworkMessages is allowed. Ordering and distribution even may change between each PublishingInterval. If DataSetOrdering is set to AscendingWriterId, the Publisher shall fill up each NetworkMessage with DataSets with an ascending order of the related DataSetWriterIds as long as the accumulated DataSet sizes will not exceed the MaxNetworkMessageSize. The different options are shown in Figure 27.

readme_files/image030.png Figure 27 – DataSetOrdering and MaxNetworkMessageSize

The DataSetOrderingType representation in the AddressSpace is defined in Table 81.

Table 81 – DataSetOrderingType definition

Attribute Value        
BrowseName DataSetOrderingType        
IsAbstract False        
References Node Class BrowseName DataType TypeDefinition Others
Subtype of Enumeration defined in OPC 10000-5          
HasProperty Variable EnumStrings LocalizedText [] PropertyType  
Conformance Units          
PubSub Parameters UADP          

6.3.1.1.4 NetworkMessageContentMask ToC

The parameter NetworkMessageContentMask defines the optional header fields to be included in the NetworkMessages produced by the WriterGroup. The DataType for the UADP NetworkMessage mapping is UadpNetworkMessageContentMask.

The DataType UadpNetworkMessageContentMask is formally defined in Table 82.

Table 82 – UadpNetworkMessageContentMask values

Value Bit No. Description
PublisherId 0 The PublisherId is included in the NetworkMessages.
GroupHeader 1 The GroupHeader is included in the NetworkMessages.
WriterGroupId 2    The WriterGroupId field is included in the GroupHeader.The flag is only valid if Bit 1 is set.
GroupVersion 3    The GroupVersion field is included in the GroupHeader.The flag is only valid if Bit 1 is set.
NetworkMessageNumber 4    The NetworkMessageNumber field is included in the GroupHeader.   The field is required if more than one NetworkMessage is needed to transfer all DataSets of the group.The flag is only valid if Bit 1 is set.
SequenceNumber 5    The SequenceNumber field is included in the GroupHeader.The flag is only valid if Bit 1 is set.
PayloadHeader 6 The PayloadHeader is included in the NetworkMessages.
Timestamp 7 The sender timestamp is included in the NetworkMessages.
PicoSeconds 8 The sender PicoSeconds portion of the timestamp is included in the NetworkMessages. This flag is ignored if the Timestamp flag is not set.
DataSetClassId 9    The DataSetClassId is included in the NetworkMessages.The NetworkMessage can only contain DataSetMessages with the same DataSetClassId. If DataSetMessages have different DataSetClassIds they must be sent in individual NetworkMessages.
PromotedFields 10 The PromotedFields are included in the NetworkMessages.

The UadpNetworkMessageContentMask representation in the AddressSpace is defined in Table 83.

Table 83 – UadpNetworkMessageContentMask definition

Attribute Value        
BrowseName UadpNetworkMessageContentMask        
IsAbstract False        
References Node Class BrowseName DataType TypeDefinition Others
Subtype of UInt32 defined in OPC 10000-5          
HasProperty Variable OptionSetValues LocalizedText [] PropertyType  
Conformance Units          
PubSub Parameters UADP          

6.3.1.1.5 SamplingOffset ToC Model

The SamplingOffset with the DataType Duration defines the time in milliseconds for the offset of creating the NetworkMessage in the PublishingInterval cycle.

Any negative value indicates that the optional parameter is not configured. In this case the Publisher shall calculate the time before the PublishingOffset that is necessary to create the NetworkMessage in time for sending at the PublishingOffset.

The Duration DataType is a subtype of Double and allows configuration of intervals smaller than a millisecond.

6.3.1.1.6 PublishingOffset ToC Model

The PublishingOffset is an array of DataType Duration that defines the time in milliseconds for the offset in the PublishingInterval cycle of sending the NetworkMessage to the network.

Any negative value indicates that the PublishingOffset is not configured and the timing inside the PublishingInterval is application specific.

The Duration DataType is a subtype of Double and allows configuration of intervals smaller than a millisecond.

Figure 28 depicts how the different variations of PublishingOffset settings affect sending of multiple NetworkMessages.

readme_files/image031.png Figure 28 – PublishingOffset options for multiple NetworkMessages

If all DataSets of a group are transferred with a single NetworkMessage, the scalar value or the first value in the array defines the offset for sending the NetworkMessage relative to the start of the PublishingInterval cycle. If the DataSets of a group are sent in a series of NetworkMessages, the values in the array define the offsets of sending the NetworkMessages relative to the start of the PublishingInterval cycle. If a scalar value is configured, the first NetworkMessage is sent at the offset and the following NetworkMessages are sent immediately after each other. If more NetworkMessages are available for sending than offset values in the array, the offset for the remaining NetworkMessages is extrapolated from the last two offset values in the array.

The PublishingInterval, the SamplingOffset the PublishingOffset and the timestamp in the NetworkMessage header shall use the same time base.

6.3.1.1.7 UadpWriterGroupMessageDataType structure ToC Model

This Structure DataType is used to represent the UADP NetworkMessage mapping specific WriterGroup parameters. It is a subtype of WriterGroupMessageDataType defined in 6.2.6.7.3.

The UadpWriterGroupMessageDataType is formally defined in Table 84.

Table 84 – UadpWriterGroupMessageDataType structure

Name Type Description
UadpWriterGroupMessageDataType Structure Subtype of WriterGroupMessageDataType defined in 6.2.6.7.3
   groupVersion VersionTime Defined in 6.3.1.1.2.
   dataSetOrdering DataSetOrderingType Defined in 6.3.1.1.3.
   networkMessageContentMask UadpNetworkMessageContentMask Defined in 6.3.1.1.4.
   samplingOffset Duration Defined in 6.3.1.1.5.
   publishingOffset Duration[] Defined in 6.3.1.1.6.

Its representation in the AddressSpace is defined in Table 85.

Table 85 – UadpWriterGroupMessageDataType definition

Attributes Value
BrowseName UadpWriterGroupMessageDataType
IsAbstract False
Subtype of WriterGroupMessageDataType defined in 6.2.6.7.3.  
Conformance Units  
PubSub Parameters UADP  

6.3.1.2 UADP ReaderGroup Parameters ToC

There are no UADP specific message mapping parameters defined for the ReaderGroup.

6.3.1.3 UADP DataSetMessage Writer ToC

6.3.1.3.1 General ToC

The configuration of the DataSetWriters in a WriterGroup can result in a fixed NetworkMessage layout where all DataSets have a static position between NetworkMessages.

In this case the parameters NetworkMessageNumber and DataSetOffset provide information about the static position of the DataSetMessage in a NetworkMessage Subscribers can rely on. If the value of one of the two parameters is 0, the position is not guaranteed to be static.

NOTE A Publisher can only provide valid values for the parameters NetworkMessageNumber and DataSetOffset if the message mapping allows keeping the value for these Properties constant unless the configuration of the WriterGroup is changed.

6.3.1.3.2 DataSetMessageContentMask ToC

The DataSetMessageContentMask defines the flags for the content of the DataSetMessage header. The UADP message mapping specific flags are defined by the UadpDataSetMessageContentMask DataType.

The UadpDataSetMessageContentMask DataType is formally defined in Table 86.

Table 86 – UadpDataSetMessageContentMask Values

Value Bit No. Description
Timestamp 0 If this flag is set, a timestamp shall be included in the DataSetMessage header.
PicoSeconds 1 If this flag is set, a PicoSeconds timestamp field shall be included in the DataSetMessage header. This flag is ignored if the Timestamp flag is not set.
Status 2 If this flag is set, the DataSetMessage status is included in the DataSetMessage header. The rules for creating the DataSetMessage status are defined in Table 26.
MajorVersion 3 If this flag is set, the ConfigurationVersion.MajorVersion is included in the DataSetMessage header.
MinorVersion 4 If this flag is set, the ConfigurationVersion.MinorVersion is included in the DataSetMessage header.
SequenceNumber 5 If this flag is set, the DataSetMessageSequenceNumber is included in the DataSetMessage header.

The UadpDataSetMessageContentMask representation in the AddressSpace is defined in Table 87.

Table 87 – UadpDataSetMessageContentMask definition

Attribute Value        
BrowseName UadpDataSetMessageContentMask        
IsAbstract False        
References Node Class BrowseName DataType TypeDefinition Others
Subtype of UInt32 defined in OPC 10000-5          
HasProperty Variable OptionSetValues LocalizedText [] PropertyType  
Conformance Units          
PubSub Parameters UADP          

6.3.1.3.3 ConfiguredSize ToC Model

The parameter ConfiguredSize with the DataType UInt16 defines the fixed size in bytes a DataSetMessage uses inside a NetworkMessage. The default value is 0 and it indicates a dynamic length. If a DataSetMessage would be smaller in size (e.g. because of the current values that are encoded) the DataSetMessage is padded with bytes with value zero. In case it would be larger, the Publisher shall set bit 0 of the DataSetFlags1 to false to indicate that the DataSetMessage is not valid.

NOTE The parameter ConfiguredSize can be used for different reasons. One reason is the reservation of space inside a NetworkMessage by setting ConfiguredSize to a higher value than the assigned DataSet actually requires. Modifications (e.g. extensions) of the DataSet would then not change the required bandwidth on the network which reduces the risk of side effects. Another reason would be to maintain predictable network behaviour even when using a volatile field DataTypes like String or ByteString.

6.3.1.3.4 NetworkMessageNumber ToC Model

The parameter NetworkMessageNumber with the DataType UInt16 is the number of the NetworkMessage inside a PublishingInterval in which this DataSetMessage is published. The default value is 0 and indicates that the number of the NetworkMessage is not fixed.

The NetworkMessage shall have a fixed layout if the PayloadHeader flag in the NetworkMessageContentMask is false.

If the NetworkMessage layout is fixed and all DataSetMessages of a WriterGroup fit into one single NetworkMessage, the value of NetworkMessageNumber shall be 1. If the DataSetMessages of a WriterGroup are distributed or chunked over more than one NetworkMessage, the first NetworkMessage in a PublishingInterval shall be generated with the value 1, the following NetworkMessages shall be generated with incrementing NetworkMessageNumbers. To avoid a roll-over the number of NetworkMessages generated from one WriterGroup within one PublishingInterval is limited to 65535.

6.3.1.3.5 DataSetOffset ToC Model

The parameter DataSetOffset with the DataType UInt16 is the offset in bytes inside a NetworkMessage at which the DataSetMessage is located, relative to the beginning of the NetworkMessage.

The default value 0 indicates that the position of the DataSetMessage in a NetworkMessage is not fixed. If the DataSetWriter is disabled and the DataSetOffset is not 0, the valid flag of the DataSetFlags1 in the DataSetMessage header at the offset shall be false.

This parameter should be set if the PayloadHeader flag in the NetworkMessageContentMask is false and therefore the NetworkMessage has a fixed layout.

6.3.1.3.6 UadpDataSetWriterMessageDataType structure ToC Model

This Structure DataType is used to represent UADP DataSetMessage mapping specific DataSetWriter parameters. It is a subtype of the DataSetWriterMessageDataType defined in 6.2.4.5.3.

The UadpDataSetWriterMessageDataType is formally defined in Table 88.

Table 88 – UadpDataSetWriterMessageDataType structure

Name Type Description
UadpDataSetWriterMessageDataType Structure Subtype of DataSetWriterMessageDataType defined in 6.2.4.5.3
   dataSetMessageContentMask UadpDataSetMessageContentMask Defined in 6.3.1.3.2.
   configuredSize UInt16 Defined in 6.3.1.3.3.
   networkMessageNumber UInt16 Defined in 6.3.1.3.4.
   dataSetOffset UInt16 Defined in 6.3.1.3.5.

Its representation in the AddressSpace is defined in Table 89.

Table 89 – UadpDataSetWriterMessageDataType definition

Attributes Value
BrowseName UadpDataSetWriterMessageDataType
IsAbstract False
Subtype of DataSetWriterMessageDataType defined in 6.2.4.5.3.  
Conformance Units  
PubSub Parameters UADP  

6.3.1.4 UADP DataSetMessage Reader ToC Model

6.3.1.4.1 GroupVersion ToC Model

The parameter GroupVersion with DataType VersionTime defines the expected value in the field GroupVersion in the header of the NetworkMessage. The default value 0 is defined as null value, and means this parameter shall be ignored.

6.3.1.4.2 NetworkMessageNumber ToC Model

The parameter NetworkMessageNumber with DataType UInt16 is the number of the NetworkMessage inside a PublishingInterval in which this DataSetMessage is published. The default value 0 is defined as null value, and means this parameter shall be ignored.

The NetworkMessage shall have a fixed layout if the PayloadHeader flag in the NetworkMessageContentMask is false.

6.3.1.4.3 DataSetOffset ToC Model

The parameter DataSetOffset with DataType UInt16 defines the offset in bytes for the DataSetMessage inside the corresponding NetworkMessage relative to the beginning of the NetworkMessage. The default value 0 is defined as null value, and means that the position of the DataSetMessage in a NetworkMessage is not fixed.

This parameter should be set if the PayloadHeader flag in the NetworkMessageContentMask is false and therefore the NetworkMessage has a fixed layout.

6.3.1.4.4 DataSetClassId ToC Model

The parameter DataSetClassId with DataType Guid defines a DataSet class related filter. If the value is null, the DataSetClassId filter is not applied.

6.3.1.4.5 NetworkMessageContentMask ToC Model

The NetworkMessageContentMask with DataType UadpNetworkMessageContentMask indicates the optional header fields included in the received NetworkMessages.

The UadpNetworkMessageContentMask DataType is defined in 6.3.1.1.4.

6.3.1.4.6 DataSetMessageContentMask ToC Model

The DataSetMessageContentMask with the DataType UadpDataSetMessageContentMask indicates the optional header fields included in the DataSetMessages.

The UadpDataSetMessageContentMask DataType is defined in 6.3.1.3.2.

6.3.1.4.7 PublishingInterval ToC Model

The PublishingInterval with DataType Duration indicates the rate the Publisher sends NetworkMessages related to the DataSet. The start time for the periodic execution of the Subscriber shall be calculated according to 6.3.1.1.1.

6.3.1.4.8 ReceiveOffset ToC Model

The ReceiveOffset with DataType Duration defines the time in milliseconds for the offset in the PublishingInterval cycle for the expected receive time of the NetworkMessage for the DataSet from the network.

Any negative value indicates that the ReceiveOffset is not configured and the timing inside the PublishingInterval is not defined.

6.3.1.4.9 ProcessingOffset ToC Model

The ProcessingOffset with DataType Duration defines the time in milliseconds for the offset in the PublishingInterval cycle when the received DataSet need to be processed by the application in the Subscriber.

The different timing offsets inside a PublishingInterval cycle on the Publisher and Subscriber sides are shown in Figure 26.

Any negative value indicates that the ProcessingOffset is not configured and the timing inside the PublishingInterval is application specific.

6.3.1.4.10 UadpDataSetReaderMessageDataType ToC Model

This Structure DataType is used to represent UADP message mapping specific DataSetReader parameters. It is a subtype of the DataSetReaderMessageDataType defined in 6.2.9.13.3.

The UadpDataSetReaderMessageDataType is formally defined in Table 90.

Table 90 – UadpDataSetReaderMessageDataType structure

Name Type Description
UadpDataSetReaderMessageDataType Structure Subtype of DataSetReaderMessageDataType defined in 6.2.9.13.3.
   groupVersion VersionTime Defined in 6.3.1.4.1.
   networkMessageNumber UInt16 Defined in 6.3.1.4.2.
   dataSetOffset UInt16 Defined in 6.3.1.4.3.
   dataSetClassId Guid Defined in 6.3.1.4.4.
   networkMessageContentMask UadpNetworkMessageContentMask Defined in 6.3.1.4.5.
   dataSetMessageContentMask UadpDataSetMessageContentMask Defined in 6.3.1.4.6.
   publishingInterval Duration Defined in 6.3.1.4.7.
   receiveOffset Duration Defined in 6.3.1.4.8.
   processingOffset Duration Defined in 6.3.1.4.9.

Its representation in the AddressSpace is defined in Table 91.

Table 91 – UadpDataSetReaderMessageDataType definition

Attributes Value
BrowseName UadpDataSetReaderMessageDataType
IsAbstract False
Subtype of DataSetReaderMessageDataType defined in 6.2.9.13.3.  
Conformance Units  
PubSub Parameters UADP  

Previous Next