Figure1_

 

 

 

Figure3_

 

     OPC UA Specification

OPC 10000-14

 

OPC Unified Architecture

Part 14: PubSub

 

 

Release 1.04

2018-02-06

 

 

 

 

 

 

 


 

Specification Type:

Industry Standard Specification

Comments:

 

 

 

 

Document
Number

OPC 10000-14

 

 

Title:

OPC Unified Architecture

Part 14 :PubSub

Date:

2018-02-06

 

 

 

 

Version:

Release 1.04

Software:

MS-Word

 

 

Source:

OPC 10000-14 - UA Specification Part 14 - PubSub 1.04.docx

 

 

 

 

Author:

OPC Foundation

Status:

Release

 

 

 

 


 

 

 

CONTENTS

FIGURES. iv

TABLES. v

1       Scope. 1

2       Normative references. 1

3       Terms, definitions and conventions. 2

3.1        Terms and definitions. 2

3.2        Abbreviations and symbols. 3

4       Overview. 3

4.1        Fields of application. 3

4.2        Abstraction layers. 4

4.3        Decoupling by use of middleware. 4

4.4        Synergy of models. 5

5       PubSub Concepts. 6

5.1        Introduction. 6

5.2        DataSet 7

5.2.1          General 7

5.2.2          DataSetClass. 8

5.2.3          DataSetMetaData. 8

5.3        Messages. 9

5.3.1          General 9

5.3.2          DataSetMessage field. 9

5.3.3          DataSetMessage. 10

5.3.4          NetworkMessage. 10

5.3.5          Message Security. 10

5.3.6          Transport Security. 11

5.3.7          SecurityGroup. 11

5.4        Entities. 11

5.4.1          Publisher 11

5.4.2          Subscriber 14

5.4.3          Security Key Service. 15

5.4.4          Message Oriented Middleware. 18

6       PubSub Communication Parameters. 22

6.1        Overview. 22

6.2        Common Configuration Parameters. 23

6.2.1          PubSubState State Machine. 23

6.2.2          PublishedDataSet Parameters. 24

6.2.3          DataSetWriter Parameters. 30

6.2.4          Shared PubSubGroup Parameters. 34

6.2.5          WriterGroup Parameters. 35

6.2.6          PubSubConnection Parameters. 37

6.2.7          ReaderGroup Parameters. 39

6.2.8          DataSetReader Parameters. 40

6.2.9          SubscribedDataSet Parameters. 43

6.2.10        Information flow and status handling. 45

6.2.11        PubSubConfigurationDataType. 46

6.3        Message Mapping Configuration Parameters. 47

6.3.1          UADP Message Mapping. 47

6.3.2          JSON Message Mapping. 54

6.4        Transport Protocol Mapping Configuration Parameters. 56

6.4.1          Datagram Transport Protocol 56

6.4.2          Broker Transport Protocol 57

7       PubSub Mappings. 62

7.1        General 62

7.2        Message Mappings. 62

7.2.1          General 62

7.2.2          UADP Message Mapping. 62

7.2.3          JSON Message Mapping. 76

7.3        Transport Protocol Mappings. 79

7.3.1          General 79

7.3.2          OPC UA UDP. 79

7.3.3          OPC UA Ethernet 80

7.3.4          AMQP. 80

7.3.5          MQTT. 85

8       PubSub Security Key Service Model 87

8.1        Overview. 87

8.2        PublishSubscribe Object 87

8.3        PubSubKeyServiceType. 88

8.4        GetSecurityKeys Method. 88

8.5        GetSecurityGroup Method. 90

8.6        SecurityGroupType. 90

8.7        SecurityGroupFolderType. 91

8.8        AddSecurityGroup Method. 91

8.9        RemoveSecurityGroup Method. 92

9       PubSub Configuration Model 93

9.1        Common Configuration Model 93

9.1.1          General 93

9.1.2          Configuration behaviours. 95

9.1.3          Types for the PublishSubscribe Object 96

9.1.4          Published DataSet Model 100

9.1.5          Connection Model 113

9.1.6          Group Model 116

9.1.7          DataSetWriter Model 122

9.1.8          DataSetReader Model 124

9.1.9          Subscribed DataSet Model 128

9.1.10        PubSub Status Object 130

9.1.11        PubSub Diagnostics Objects. 131

9.1.12        PubSub Status Events. 138

9.2        Message Mapping Configuration Model 139

9.2.1          UADP Message Mapping. 139

9.2.2          JSON Message Mapping. 141

9.3        Transport Protocol Mapping Configuration Model 142

9.3.1          Datagram Transport Protocol Mapping. 142

9.3.2          Broker Transport Protocol Mapping. 143

Annex A (normative)  Common Types. 146

A.1        DataType Schema Header Structures. 146

A.1.1          DataTypeSchemaHeader 146

A.1.2          DataTypeDescription. 146

A.1.3          StructureDescription. 147

A.1.4          EnumDescription. 147

A.1.5          SimpleTypeDescription. 147

A.2        UABinaryFileDataType. 148

A.3        NetworkAddress Model 148

A.3.1          NetworkAddressType. 148

A.3.2          NetworkAddressUrlType. 149

Annex B (informative) Client Server vs. Publish Subscribe. 150

B.1        Overview. 150

B.2        Client Server Subscriptions. 150

B.3        Publish-Subscribe. 151

B.4        Synergy of models. 152

 

FIGURES

 

Figure 1 – Publish Subscribe Model Overview.......................................... 4

Figure 2 – Publisher and Subscriber entities............................................. 6

Figure 3 – DataSet in the process of publishing........................................ 7

Figure 4 – OPC UA PubSub Message Layers........................................... 9

Figure 5 – Publisher details................................................................. 12

Figure 6 – Publisher message sending sequence..................................... 13

Figure 7 – Subscriber details............................................................... 14

Figure 8 – Subscriber message reception sequence................................. 15

Figure 9 – SecurityGroup Management Sequence.................................... 16

Figure 10 – Handshake used to pull keys from SKS................................. 17

Figure 11 – Handshake used to push keys to Publishers and Subscribers.... 17

Figure 12 – Handshake with a Security Key Service................................. 18

Figure 13 – PubSub using network infrastructure..................................... 19

Figure 14 – UDP Multicast Overview..................................................... 19

Figure 15 – PubSub using broker.......................................................... 20

Figure 16 – Broker Overview............................................................... 21

Figure 17 – PubSub Component Overview............................................. 22

Figure 18 – PubSub Mapping Specific Parameters Overview...................... 23

Figure 19 – PubSub Component State Dependencies............................... 24

Figure 20 – PubSubState State Machine................................................ 24

Figure 21 – PubSub Information Flow dependency to field representation..... 32

Figure 22 – PubSub Information Flow.................................................... 45

Figure 23 – Start of the periodic publisher execution................................ 47

Figure 24 – Timing offsets in a PublishingInterval.................................... 48

Figure 25 – DataSetOrdering and MaxNetworkMessageSize...................... 49

Figure 26 – PublishingOffset options for multiple NetworkMessages............ 51

Figure 27 – UADP NetworkMessage...................................................... 63

Figure 28 – UADP DataSet Payload...................................................... 68

Figure 29 – DataSetMessage Header Structure....................................... 69

Figure 30 – Data Key Frame DataSetMessage Data................................. 71

Figure 31 – Data Delta Frame DataSetMessage...................................... 72

Figure 32 – Event DataSetMessage...................................................... 73

Figure 33 – KeepAlive Message........................................................... 74

Figure 34 – PublishSubscribe Object Types Overview.............................. 87

Figure 35 – PubSub Configuration Model Overview.................................. 93

Figure 36 – PubSub Example Objects.................................................... 94

Figure 37 – PubSub Information Flow.................................................... 94

Figure 38 – PublishSubscribe Object Types Overview.............................. 96

Figure 39 – Published DataSet Overview.............................................. 100

Figure 40 – PubSubConnectionType Overview...................................... 114

Figure 41 – PubSubGroupType Overview............................................. 117

Figure 42 – DataSet Writer Model Overview.......................................... 123

Figure 43 – DataSet Reader Model Overview........................................ 125

Figure 44 – PubSub Diagnostics Overview............................................ 132

Figure 45 – PubSubDiagnosticsCounterType......................................... 132

Figure B.46 – Subscriptions in OPC UA Client Server Model.................... 151

Figure B.47 – Publish Subscribe Model Overview................................... 152

 

TABLES

 

Table 1 – PubSubState Values............................................................. 23

Table 2 – PubSubState State Machine................................................... 24

Table 3 – DataSetMetaDataType Structure............................................. 25

Table 4 – DataSetMetaDataType Definition............................................ 25

Table 5 – FieldMetaData Structure........................................................ 25

Table 6 – DataSetFieldFlags Values...................................................... 26

Table 7 – DataSetFieldFlags Definition.................................................. 27

Table 8 – ConfigurationVersionDataType Structure.................................. 27

Table 9 – PublishedDataSetDataType Structure...................................... 28

Table 10 – PublishedDataSetSourceDataType Definition........................... 28

Table 11 – PublishedVariableDataType Structure.................................... 29

Table 12 – PublishedDataItemsDataType Structure.................................. 29

Table 13 – PublishedEventsDataType Structure...................................... 30

Table 14 – DataSetFieldContentMask Values.......................................... 31

Table 15 – DataSetFieldContentMask Definition...................................... 31

Table 16 – DataSetMessage field representation options.......................... 32

Table 17 – DataSetWriterDataType Structure.......................................... 33

Table 18 – DataSetWriterTransportDataType Definition............................ 33

Table 19 – DataSetWriterMessageDataType Structure.............................. 33

Table 20 – PubSubGroupDataType Structure.......................................... 35

Table 21 – PubSubGroupDataType Definition......................................... 35

Table 22 – WriterGroupDataType Structure............................................ 36

Table 23 – WriterGroupDataType Definition............................................ 36

Table 24 – WriterGroupTransportDataType Definition............................... 37

Table 25 – WriterGroupMessageDataType Structure................................ 37

Table 26 – PubSubConnectionDataType Structure................................... 38

Table 27 – ConnectionTransportDataType Definition................................ 38

Table 28 – NetworkAddressDataType Structure....................................... 38

Table 29 – NetworkAddressDataType Definition...................................... 39

Table 30 – NetworkAddressUrlDataType Structure................................... 39

Table 31 – NetworkAddressUrlDataType Definition.................................. 39

Table 32 – ReaderGroupDataType Structure........................................... 39

Table 33 – ReaderGroupDataType Definition.......................................... 40

Table 34 – ReaderGroupTransportDataType Definition............................. 40

Table 35 – ReaderGroupMessageDataType Structure.............................. 40

Table 36 – DataSetReaderDataType Structure........................................ 42

Table 37 – DataSetReaderTransportDataType Structure........................... 42

Table 38 – DataSetReaderTransportDataType Definition........................... 42

Table 39 – DataSetReaderMessageDataType Structure............................ 42

Table 40 – DataSetReaderMessageDataType Definition............................ 43

Table 41 – SubscribedDataSetDataType Structure................................... 43

Table 42 – SubscribedDataSetDataType Definition.................................. 43

Table 43 – TargetVariablesDataType Structure....................................... 43

Table 44 – FieldTargetDataType Structure............................................. 44

Table 45 – OverrideValueHandling Values.............................................. 44

Table 46 – SubscribedDataSetMirrorDataType Structure........................... 45

Table 47 – Source to message input mapping......................................... 46

Table 48 – Message output to target mapping......................................... 46

Table 49 – PubSubConfigurationDataType Structure................................ 46

Table 50 – PubSubConfiguration File Content......................................... 47

Table 51 – DataSetOrderingType Values............................................... 48

Table 52 – UadpNetworkMessageContentMask Values............................. 50

Table 53 – UadpNetworkMessageContentMask Definition......................... 50

Table 54 – UadpWriterGroupMessageDataType Structure......................... 51

Table 55 – UadpDataSetMessageContentMask Values............................. 52

Table 56 – UadpDataSetMessageContentMask Definition.......................... 52

Table 57 – UadpDataSetWriterMessageDataType Structure....................... 53

Table 58 – UadpDataSetReaderMessageDataType Structure..................... 54

Table 59 – JsonNetworkMessageContentMask Values.............................. 54

Table 60 – JsonNetworkMessageContentMask Definition.......................... 55

Table 61 – JsonWriterGroupMessageDataType Structure.......................... 55

Table 62 – JsonDataSetMessageContentMask Values.............................. 55

Table 63 – JsonDataSetMessageContentMask Definition.......................... 55

Table 64 – JsonDataSetWriterMessageDataType Structure....................... 56

Table 65 – JsonDataSetReaderMessageDataType Structure...................... 56

Table 66 – DatagramConnectionTransportDataType Structure................... 56

Table 67 – DatagramWriterGroupTransportDataType Structure.................. 57

Table 68 – BrokerConnectionTransportDataType Structure........................ 58

Table 69 – BrokerTransportQualityOfService Values................................ 58

Table 70 – BrokerWriterGroupTransportDataType Structure...................... 59

Table 71 – BrokerDataSetWriterTransportDataType Structure.................... 60

Table 72 – BrokerDataSetReaderTransportDataType Structure.................. 61

Table 73 – UADP NetworkMessage....................................................... 64

Table 74 – Layout of the key data for UADP message security................... 66

Table 75 – Layout of the MessageNonce for AES-CTR............................. 66

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

Table 77 – Chunked NetworkMessage Payload Header............................. 67

Table 78 – Chunked NetworkMessage Payload Fields.............................. 67

Table 79 – UADP DataSet Payload Header............................................ 68

Table 80 – UADP DataSet Payload....................................................... 68

Table 81 – DataSetMessage Header Structure........................................ 70

Table 82 – Data Key Frame DataSetMessage Structure............................ 71

Table 83 – Data Delta Frame DataSetMessage Structure.......................... 72

Table 84 – Event DataSetMessage Structure.......................................... 73

Table 85 – Discovery Request Header Structure...................................... 75

Table 86 – Publisher Information Request Message Structure.................... 75

Table 87 – Discovery Response Header Structure................................... 75

Table 88 – Publisher Endpoints Message Structure.................................. 76

Table 89 – DataSetMetaData Message Structure..................................... 76

Table 90 – DataSetWriter Configuration Message Structure....................... 76

Table 91 – JSON NetworkMessage Definition......................................... 77

Table 92 – JSON DataSetMessage Definition......................................... 78

Table 93 – JSON DataSetMetaData Definition......................................... 79

Table 94 – UADP message transported over UDP.................................... 79

Table 95 – UADP message transported over Ethernet.............................. 80

Table 96 – AMQP Standard Header Fields............................................. 82

Table 97 - OPC UA AMQP Standard Header QualifiedName Name mappings 83

Table 98 – OPC UA AMQP Header Field Conversion Rules....................... 84

Table 99 – PublishSubscribe Object Definition........................................ 88

Table 100 – PubSubKeyServiceType Definition....................................... 88

Table 101 – SecurityGroupType Definition.............................................. 90

Table 102 – SecurityGroupFolderType Definition..................................... 91

Table 103 – PublishSubscribeType Definition.......................................... 96

Table 104 – HasPubSubConnection ReferenceType................................. 99

Table 105 – PublishedDataSetType Definition....................................... 101

Table 106 – ExtensionFieldsType Definition.......................................... 102

Table 107 – Well-Known Extension Field Names.................................... 102

Table 108 – DataSetToWriter ReferenceType........................................ 103

Table 109 – PublishedDataItemsType Definition.................................... 104

Table 110 – PublishedEventsType Definition......................................... 106

Table 111 – DataSetFolderType Definition............................................ 108

Table 112 – PubSubConnectionType Definition..................................... 114

Table 113 – ConnectionTransportType Definition................................... 116

Table 114 – PubSubGroupType Definition............................................ 117

Table 115 – WriterGroupType Definition............................................... 118

Table 116 – HasDataSetWriter ReferenceType...................................... 120

Table 117 – WriterGroupTransportType Definition.................................. 120

Table 118 – WriterGroupMessageType Definition................................... 120

Table 119 – ReaderGroupType Definition............................................. 120

Table 120 – HasDataSetReader ReferenceType.................................... 122

Table 121 – ReaderGroupTransportType Definition................................ 122

Table 122 – ReaderGroupMessageType Definition................................. 122

Table 123 – DataSetWriterType Definition............................................ 123

Table 124 – DataSetWriterTransportType Definition............................... 124

Table 125 – DataSetWriterMessageType Definition................................ 124

Table 126 – DataSetReaderType Definition........................................... 125

Table 127 – DataSetReaderTransportType Definition.............................. 126

Table 128 – DataSetReaderMessageType Definition............................... 126

Table 129 – SubscribedDataSetType Definition..................................... 128

Table 130 – TargetVariablesType Definition.......................................... 128

Table 131 – SubscribedDataSetMirrorType Definition............................. 130

Table 132 – PubSubStatusType Definition............................................ 130

Table 133 – Status Object Definition.................................................... 131

Table 134 – PubSubDiagnosticsType................................................... 132

Table 135 – Counters for PubSubDiagnosticsType................................. 133

Table 136 – DiagnosticsLevel Values................................................... 134

Table 137 – PubSubDiagnosticsCounterType........................................ 134

Table 138 – PubSubDiagnosticsCounterClassification Values................... 135

Table 139 – PubSubDiagnosticsRootType............................................ 135

Table 140 – LiveValues for PubSubDiagnosticsRootType........................ 135

Table 141 – PubSubDiagnosticsConnectionType................................... 135

Table 142 – LiveValues for PubSubDiagnosticsConnectionType............... 136

Table 143 – PubSubDiagnosticsWriterGroupType.................................. 136

Table 144 – Counters for PubSubDiagnosticsWriterGroupType................. 136

Table 145 – LiveValues for PubSubDiagnosticsWriterGroupType.............. 136

Table 146 – PubSubDiagnosticsReaderGroupType................................. 136

Table 147 – Counters for PubSubDiagnosticsReaderGroupType............... 137

Table 148 – LiveValues for PubSubDiagnosticsReaderGroupType............. 137

Table 149 – PubSubDiagnosticsDataSetWriterType................................ 137

Table 150 – Counters for PubSubDiagnosticsDataSetWriterType.............. 137

Table 151 – LiveValues for PubSubDiagnosticsDataSetWriterType............ 137

Table 152 – PubSubDiagnosticsDataSetReaderType.............................. 138

Table 153 – Counters for PubSubDiagnosticsDataSetReaderType............. 138

Table 154 – LiveValues for PubSubDiagnosticsDataSetReaderType.......... 138

Table 155 – PubSubStatusEventType Definition.................................... 138

Table 156 – PubSubTransportLimitsExceedEventType Definition.............. 139

Table 157 – PubSubCommunicationFailureEventType Definition............... 139

Table 158 – UadpWriterGroupMessageType Definition............................ 140

Table 159 – UadpDataSetWriterMessageType Definition......................... 140

Table 160 – UadpDataSetReaderMessageType Definition....................... 141

Table 161 – JsonWriterGroupMessageType Definition............................ 141

Table 162 – JsonDataSetWriterMessageType Definition.......................... 142

Table 163 – JsonDataSetReaderMessageType Definition........................ 142

Table 164 – DatagramConnectionTransportType Definition...................... 142

Table 165 – DatagramWriterGroupTransportType Definition..................... 143

Table 166 – BrokerConnectionTransportType Definition.......................... 143

Table 167 – BrokerWriterGroupTransportType Definition......................... 143

Table 168 – BrokerDataSetWriterTransportType Definition....................... 144

Table 169 – Broker Writer Well-Known Extension Field Names................. 144

Table 170 – BrokerDataSetReaderTransportType Definition..................... 144

Table A.1 – DataTypeSchemaHeader Structure..................................... 146

Table A.2 – DataTypeSchemaHeader Definition..................................... 146

Table A.3 – DataTypeDescription Structure........................................... 146

Table A.4 – DataTypeDescription Definition.......................................... 147

Table A.5 – StructureDescription Structure........................................... 147

Table A.6 – StructureDescription Definition........................................... 147

Table A.7 – EnumDescription Structure................................................ 147

Table A.8 – EnumDescription Definition............................................... 147

Table A.9 – SimpleTypeDescription Structure........................................ 148

Table A.10 – UABinaryFileDataType Structure....................................... 148

Table A.11 – UABinaryFileDataType Definition...................................... 148

Table A.12 – NetworkAddressType Definition........................................ 149

Table A.13 – NetworkAddressUrlType Definition.................................... 149

 


OPC Foundation

____________

 

UNIFIED ARCHITECTURE –

FOREWORD

This specification is the specification for developers of OPC UA applications. The specification is a result of an analysis and design process to develop a standard interface to facilitate the development of applications by multiple vendors that shall inter-operate seamlessly together.

Copyright © 2014-2018, OPC Foundation, Inc.

AGREEMENT OF USE

COPYRIGHT RESTRICTIONS

Any unauthorized use of this specification may violate copyright laws, trademark laws, and communications regulations and statutes. This document contains information which is protected by copyright. All Rights Reserved. No part of this work covered by copyright herein may be reproduced or used in any form or by any means--graphic, electronic, or mechanical, including photocopying, recording, taping, or information storage and retrieval systems--without permission of the copyright owner.

OPC Foundation members and non-members are prohibited from copying and redistributing this specification. All copies must be obtained on an individual basis, directly from the OPC Foundation Web site
HTUhttp://www.opcfoundation.orgUTH.

PATENTS

The attention of adopters is directed to the possibility that compliance with or adoption of OPC specifications may require use of an invention covered by patent rights. OPC shall not be responsible for identifying patents for which a license may be required by any OPC specification, or for conducting legal inquiries into the legal validity or scope of those patents that are brought to its attention. OPC specifications are prospective and advisory only. Prospective users are responsible for protecting themselves against liability for infringement of patents.

WARRANTY AND LIABILITY DISCLAIMERS

WHILE THIS PUBLICATION IS BELIEVED TO BE ACCURATE, IT IS PROVIDED "AS IS" AND MAY CONTAIN ERRORS OR MISPRINTS. THE OPC FOUDATION MAKES NO WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, WITH REGARD TO THIS PUBLICATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTY OF TITLE OR OWNERSHIP, IMPLIED WARRANTY OF MERCHANTABILITY OR WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE OR USE. IN NO EVENT SHALL THE OPC FOUNDATION BE LIABLE FOR ERRORS CONTAINED HEREIN OR FOR DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, RELIANCE OR COVER DAMAGES, INCLUDING LOSS OF PROFITS, REVENUE, DATA OR USE, INCURRED BY ANY USER OR ANY THIRD PARTY IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS MATERIAL, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

The entire risk as to the quality and performance of software developed using this specification is borne by you.

RESTRICTED RIGHTS LEGEND

This Specification is provided with Restricted Rights. Use, duplication or disclosure by the U.S. government is subject to restrictions as set forth in (a) this Agreement pursuant to DFARs 227.7202-3(a); (b) subparagraph (c)(1)(i) of the Rights in Technical Data and Computer Software clause at DFARs 252.227-7013; or (c) the Commercial Computer Software Restricted Rights clause at FAR 52.227-19 subdivision (c)(1) and (2), as applicable. Contractor / manufacturer are the OPC Foundation,. 16101 N. 82nd Street, Suite 3B, Scottsdale, AZ, 85260-1830

COMPLIANCE

The OPC Foundation shall at all times be the sole entity that may authorize developers, suppliers and sellers of hardware and software to use certification marks, trademarks or other special designations to indicate compliance with these materials. Products developed using this specification may claim compliance or conformance with this specification if and only if the software satisfactorily meets the certification requirements set by the OPC Foundation. Products that do not meet these requirements may claim only that the product was based on this specification and must not claim compliance or conformance with this specification.

Trademarks

Most computer and software brand names have trademarks or registered trademarks. The individual trademarks have not been listed here.

GENERAL PROVISIONS

Should any provision of this Agreement be held to be void, invalid, unenforceable or illegal by a court, the validity and enforceability of the other provisions shall not be affected thereby.

This Agreement shall be governed by and construed under the laws of the State of Minnesota, excluding its choice or law rules.

This Agreement embodies the entire understanding between the parties with respect to, and supersedes any prior understanding or agreement (oral or written) relating to, this specification.

ISSUE REPORTING

The OPC Foundation strives to maintain the highest quality standards for its published specifications, hence they undergo constant review and refinement. Readers are encouraged to report any issues and view any existing errata here: HTUhttp://www.opcfoundation.org/errataUTH

 

 


OPC Unified Architecture Specification

 

Part 14: PubSub

 

 

 

1       Scope

This specification defines the OPC Unified Architecture (OPC UA) PubSub communication model. It defines an OPC UA publish subscribe pattern which complements the client server pattern defined by the Services in OPC 10000-4. See The following documents, in whole or in part, are normatively referenced in this document and are indispensable for its application. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments and errata) applies.

OPC 10000-1 for an overview of the two models and their distinct uses.

PubSub allows distributing data and events from an OPC UA information source to interested observers inside a device network as well as in IT and analytics cloud systems.

The specification consists of

·      a general introduction of the PubSub concepts,

·      a definition of the PubSub configuration parameters,

·      mapping of PubSub concepts and configuration parameters to messages and transport protocols,

·      and a PubSub configuration model.

Not all OPC UA Applications will need to implement all defined message and transport protocol mappings. OPC 10000-7 defines the Profile that dictate which mappings need to be implemented in order to be compliant with a particular Profile.

2       Normative references

The following documents, in whole or in part, are normatively referenced in this document and are indispensable for its application. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments and errata) applies.

OPC 10000-1, OPC Unified Architecture - Part 1: Overview and Concepts

http://www.opcfoundation.org/UA/Part1/

OPC 10000-2, OPC Unified Architecture - Part 2: Security Model

http://www.opcfoundation.org/UA/Part2/

OPC 10000-3, OPC Unified Architecture - Part 3: Address Space Model

http://www.opcfoundation.org/UA/Part3/

OPC 10000-4, OPC UA Specification - Part 4: Services

http://www.opcfoundation.org/UA/Part4/

OPC 10000-5, OPC Unified Architecture - Part 5: Information Model

http://www.opcfoundation.org/UA/Part5/

OPC 10000-6, OPC Unified Architecture - Part 6: Mappings

http://www.opcfoundation.org/UA/Part6/

OPC 10000-7, OPC Unified Architecture - Part 7: Profiles

http://www.opcfoundation.org/UA/Part7/

OPC 10000-8, OPC Unified Architecture - Part 8: Data Access

http://www.opcfoundation.org/UA/Part8/

OPC 10000-12, OPC Unified Architecture - Part 12: Discovery and Global Services

http://www.opcfoundation.org/UA/Part12/

ISO/IEC 19464:2014: Advanced Message Queuing Protocol (AMQP) v1.0

ISO/IEC 20922:2016: Message Queuing Telemetry Transport (MQTT) v3.1.1

RFC 7159: The JavaScript Object Notation (JSON) Data Interchange Format

http://www.ietf.org/rfc/rfc7159.txt

3       Terms, definitions and conventions

3.1       Terms and definitions

For the purposes of this document, the terms and definitions given in The following documents, in whole or in part, are normatively referenced in this document and are indispensable for its application. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments and errata) applies.

OPC 10000-1, OPC 10000-3, and OPC 10000-4, as well as the following apply.

3.1.1         

DataSetClass

template declaring the content of a DataSet

Note 1 to entry:   A DataSetClass is used to type DataSets for use in several Publishers and for filtering in Subscribers.

3.1.2         

DataSetMetaData

describes the content and semantic of a DataSet

3.1.3         

DataSetReader

entity receiving DataSetMessages from a Message Oriented Middleware

Note 1 to entry:   A DataSetReader is the component that extracts a DataSetMessage from a NetworkMessage received from the Message Oriented Middleware and decodes the DataSetMessage to a DataSet for further processing in the Subscriber.

3.1.4         

DataSetWriter

entity creating DataSetMessages from DataSets and publishing them through a Message Oriented Middleware

Note 1 to entry:   A DataSetWriter encodes a DataSet to a DataSetMessage and includes the DataSetMessage into a NetworkMessage for publishing through a Message Oriented Middleware.

3.1.5         

PublishedDataSet

configuration of application-data to be published as DataSet

Note 1 to entry: A PublishedDataSet can be a list of monitored Variables or an Event selection.

3.1.6         

SecurityGroup

grouping of security settings and security keys used to access messages from a Publisher

Note 1 to entry:   A SecurityGroup is an abstraction that represents the security settings and security keys that can be used to access messages from a Publisher. A SecurityGroup is identified with a unique identifier called the SecurityGroupId. The SecurityGroupId is unique within the Security Key Service.

3.1.7         

SubscribedDataSet

configuration for dispatching of received DataSets

Note 1 to entry: A SubscribedDataSet can be a mapping of DataSet fields to Variables in the Subscriber AddressSpace.

3.2       Abbreviations and symbols

AMQP Advanced Message Queuing Protocol

AS      Authorization Service

CA      Certificate Authority

CRL    Certificate Revocation List

CTL    Certificate Trust List

HMI    Human Machine Interface

IGMP  Internet Group Management Protocol

MIME  Multipurpose Internet Mail Extensions

MQTT MQ Telemetry Transport

MTU   Maximum Transmission Unit

PCP    Priority Code Point

QoS    Quality of Service

SKS    Security Key Service

STS    Security Token Service

UA      Unified Architecture

UADP  UA Datagram Protocol

UDP    User Datagram Protocol

URI     Uniform Resource Identifier

URL    Uniform Resource Locator

VID     VLAN Identifier

4       Overview

4.1       Fields of application

In PubSub the participating OPC UA Applications with their roles as Publishers and Subscribers are decoupled. The number of Subscribers receiving data from a Publisher does not influence the Publisher. This makes PubSub suitable for applications where location independence and/or scalability are required.

The following are some example uses for PubSub:

·      Configurable peer to peer communication between controllers and between controllers and HMIs. The peers are not directly connected and do not even need to know about the existence of each other. The data exchange often requires a fixed time-window; it may be point-to-point connection or data distribution to many receivers.

·      Asynchronous workflows. For example, an order processing application can place an order on a message queue or an enterprise service bus. From there it can be processed by one or more workers.

·      Logging to multiple systems. For example, sensors or actuators can write logs to a monitoring system, an HMI, an archive application for later querying, and so on.

·      OPC UA Servers representing services or devices can stream data to applications hosted in the cloud. For example, backend servers, big data analytics for system optimization and predictive maintenance.

4.2       Abstraction layers

PubSub is designed to be flexible and is not bound to a particular messaging system. All components and activities are first described abstractly in this clause and do not represent a specification for implementation. The concrete communication parameters are specified in 6. The concrete transport protocol mappings and message mappings are later specified in 7.

Defined with these abstraction layers, PubSub can be used to transport different types of information through networks with different characteristics as illustrated with two examples:

·      PubSub with UDP transport and binary encoded messages may be well-suited in production environments for frequent transmission of small amounts of data. It also allows data exchange in one-to-one and one-to-many configurations.

·      The use of established standard messaging protocols (e.g. AMQP or MQTT) with JSON data encoding supports the cloud integration path and readily allows handling of the information in modern stream and batch analytics systems.

4.3       Decoupling by use of middleware

In PubSub the participating OPC UA Applications can assume the roles Publisher and Subscriber. Publishers are the sources of data, while Subscribers consume that data. Communication in PubSub is message-based. Publishers send messages to a Message Oriented Middleware, without knowledge of what, if any, Subscribers there may be. Similarly, Subscribers express interest in specific types of data, and process messages that contain this data, without knowledge of what Publishers there are.

Message Oriented Middleware is software or hardware infrastructure that supports sending and receiving messages between distributed systems. The implementation of this distribution depends on the Message Oriented Middleware.

Figure 1 illustrates that Publishers and Subscribers only interact with the Message Oriented Middleware which provides the means to forward the data to one or more receivers.

Figure4_

Figure 1 – Publish Subscribe Model Overview

To cover a large number of use cases, OPC UA PubSub supports two largely different Message Oriented Middleware variants. These are:

·      A broker-less form, where the Message Oriented Middleware is the network infrastructure that is able to route datagram-based messages. Subscribers and Publishers use datagram protocols like UDP.

·      A broker-based form, where the core component of the Message Oriented Middleware is a message Broker. Subscribers and Publishers use standard messaging protocols like AMQP or MQTT to communicate with the Broker. All messages are published to specific queues (e.g. topics, nodes) that the Broker exposes and Subscribers can listen to these queues. The Broker may translate messages from the formal messaging protocol of the Publisher to the formal messaging protocol of the Subscriber.

4.4       Synergy of models

PubSub and Client Server are both based on the OPC UA Information Model. PubSub therefore can easily be integrated into OPC UA Servers and OPC UA Clients. Quite typically, a Publisher will be an OPC UA Server (the owner of information) and a Subscriber is often an OPC UA Client. Above all, the PubSub Information Model for configuration (see 6.2.2) promotes the configuration of Publishers and Subscribers using the OPC UA Client Server model.

Nevertheless, the PubSub communication does not require such a role dependency. I.e., OPC UA Clients can be Publishers and OPC UA Servers can be Subscribers. In fact, there is no necessity for Publishers or Subscribers to be either an OPC UA Server or an OPC UA Client to participate in PubSub communications.

5      PubSub Concepts

5.1   Introduction

This clause describes the general OPC UA PubSub concepts.

The DataSet constitutes the payload of messages provided by the Publisher and consumed by the Subscriber. The DataSet is described in 5.2. The mapping to messages is described in 5.3. The participating entities like Publisher and Subscriber are described in 5.4.

The abstract communication parameters are described in clause 6.

The mapping of this model to concrete message and transport protocol mappings is defined in clause 7.

The OPC UA Information Model for PubSub configuration in clause 9 specifies the standard Objects in an OPC UA AddressSpace used to create, modify and expose an OPC UA PubSub configuration.

Figure 2 provides an overview of the Publisher and Subscriber entities. It illustrates the flow of messages from a Publisher to one or more Subscribers. The PubSub communication model supports many other scenarios; for example, a Publisher may send a DataSet to multiple Message Oriented Middleware and a Subscriber may receive messages from multiple Publishers.

Figure5_

Figure 2 – Publisher and Subscriber entities

Publishers and Subscribers are loosely coupled. They often will not even know each other. Their primary relation is the shared understanding of specific types of data (DataSets), the publish characteristics of messages that include these data, and the Message Oriented Middleware.

The “messages” in Figure 2 represent NetworkMessages. Each NetworkMessage includes header information (e.g. identification and security data) and one or more DataSetMessages (the payload). The DataSetMessages may be signed and encrypted in accordance with the configured message security. A Security Key Server is responsible for the distribution of the security keys needed for message security.

Each DataSetMessage is created from a DataSet. A component of a Publisher called DataSetWriter generates a continuous sequence of DataSetMessages. Syntax and semantics of DataSets are described by DataSetMetaData. The selection of information for a DataSet in the Publisher and the data acquisition parameters are called PublishedDataSet. DataSet, DataSetMetaData and PublishedDataSet are detailed in 5.2.

Note 1: The PubSub directory is an optional entity that allows Publishers to advertise their PublishedDataSets and their communication parameters. This directory functionality is planned for a future release of this specification.

5.2   DataSet

5.2.1        General

A DataSet can be thought of as a list of name and value pairs representing an Event or a list of Variable Values.

A DataSet can be created from an Event or from a sample of Variable Values. The configuration of this application-data collector is called PublishedDataSet. DataSet fields can be defined to represent any information, for example, they could be internal Variables in the Publisher, Events from the Publisher or collected by the Publisher, network data, or data from sub-devices.

DataSetMetaData described in 5.2.3 defines the structure and content of a DataSet.

For publishing, a DataSet will be encoded into a DataSetMessage. One or more DataSetMessages are combined to form the payload of a NetworkMessage.

Figure 3 illustrates the use of DataSets for publishing.

Figure6_

Figure 3 – DataSet in the process of publishing

A PublishedDataSet is similar to either an Event MonitoredItem or a list of data MonitoredItems in the Client Server Subscription model. Similar to an Event MonitoredItem, a PublishedDataSet can select a list of Event fields. Similar to data MonitoredItems, the PublishedDataSet can contain a list of Variables.

A DataSet does not define the mechanism to encode, secure and transport it. A DataSetWriter handles the creation of a DataSetMessage for a DataSet. The DataSetWriter contains settings for the encoding and transport of a DataSetMessage. Most of these settings depend on the selected Message Oriented Middleware.

The configuration of DataSets and the way the data is obtained for publishing can be configured using the PubSub configuration model defined in clause 8.2 or with vendor specific configuration tools.

5.2.2        DataSetClass

DataSets can be individual for a Publisher or they can be derived from a DataSetClass. Such a DataSetClass acts as template declaring the content of a DataSet. The DataSetClass is identified by a globally unique id – the DataSetClassId (see 6.2.2.2).

The DataSetMetaData is identical for all PublishedDataSets that are configured based on this DataSetClass. The DataSetClassId shall be in the corresponding field of the DataSetMetaData.

When all DataSetMessages of a NetworkMessage are created from DataSets that are instances of the same DataSetClass, the DataSetClassId of this class can be provided in the NetworkMessage header.

5.2.3        DataSetMetaData

DataSetMetaData describes the content and semantic of a DataSet. The structure description includes overall DataSet attributes (e.g. name and version) and a set of fields with their name and data type. The order of the fields in the DataSetMetaData shall match the order of values in the published DataSetMessages.

The DataSetMetaDataType is defined in 6.2.2.1.2.

Example description (simplified, in pseudo-language):

Name:     “Temperature-Sensor Measurement”

Fields:   [1] Name=DeviceName, Type=String

          [2] Name=Temperature, Type=Float, Unit=Celsius, Range={1,100}

Subscribers use the DataSetMetaData for decoding the values of a DataSetMessage to a DataSet. Subscribers may use name and data type for further processing or display of the published data.

Each DataSetMessage also includes the version of the DataSetMetaData that it complies with. This allows Subscribers to verify if they have the corresponding DataSetMetaData. The related ConfigurationVersionDataType is defined in 6.2.2.1.5.

DataSetMetaData may be specific to a single PublishedDataSet or identical for all PublishedDataSets that are configured based on a DataSetClass (see 5.2.2).

There are multiple options for Subscribers to get the initial DataSetMetaData:

·      The Subscriber is an OPC UA Client and is able to get the necessary configuration information from the PubSub configuration model (see 9.1.4.2.1) provided by the Publisher, from a configuration server or from a directory server.

·      The Subscriber supports the OPC UA configuration Methods defined in the PubSub configuration model.

·      The Subscriber receives the DataSetMetaData as NetworkMessage from the Publisher. This may require an option for the Subscriber to request this NetworkMessage from the Publisher.

·      The Subscriber is configured with product specific configuration means.

There are multiple options to exchange the DataSetMetaData between Publisher and Subscriber if the configuration changes.

·      The DataSetMetaData is sent as a NetworkMessage from the Publisher to the Subscriber before DataSetMessages with changed content are sent. The used Message Oriented Middleware should ensure reliable delivery of the message. The mapping for the Message Oriented Middleware defines a way for the Subscriber to request the DataSetMetaData. The Subscriber goes to an error state if it has not received the new DataSetMetaData that matches the ConfigurationVersion of the received DataSetMessage.

·      The Subscriber is automatically updated via the OPC UA configuration Methods defined in the PubSub configuration model when the DataSet in the Publisher is updated.

·      The Subscriber is an OPC UA Client and is able to obtain the update from the Publisher or a configuration server via the information exposed by the PubSub configuration model.

·      The Subscriber is updated with product specific configuration means when the DataSet in the Publisher is changed.

5.3   Messages

5.3.1        General

The term message is used with various intentions in the messaging world. It sometimes only refers to the payload (the application data) and sometimes to the network packet that also includes protocol-, security-, or encoding-specific data. To avoid confusion, this specification formally defines the term DataSetMessage to mean the application data (the payload) supplied by the Publisher and the term NetworkMessage to mean the message handed off and received from a specific Message Oriented Middleware. DataSetMessages are embedded in NetworkMessages. Figure 4 shows the relationship of these message types.

Figure7_

Figure 4 – OPC UA PubSub Message Layers

The transport protocol-specific headers and definitions are described in 7.3.

Following is an abstract definition of DataSetMessage and NetworkMessage. The concrete structure depends on the message mapping and is described in 7.2.

5.3.2        DataSetMessage field

A DataSetMessage field is the representation of a DataSet field in a DataSetMessage.

A DataSet field contains the actual value as well as additional information about the value like status and timestamp.

A DataSet field can be represented as a DataValue, as a Variant or as a RawData in the DataSetMessage field. The representation depends on the DataSetFieldContentMask defined in 6.2.3.2.

The representation as a DataValue is used if value, status and timestamp should be included in the DataSetMessage.

The representation as Variant is used if value or bad status should be included in the DataSetMessage.

The representation as RawData is the most efficient format and is used if a common status and timestamp per DataSet is sufficient.

5.3.3        DataSetMessage

A DataSetMessage is created from a DataSet. It consists of a header and the encoded fields of the DataSet.

Depending on the configured DataSetMessageContentMask, a DataSetMessage may exist in different forms and with varying detail. DataSetMessages do not contain any information about the data acquisition or information source in the Publisher.

Additional header information includes:

DataSetWriterId      Identifies the DataSetWriter and indirectly the PublishedDataSet.

Sequence number   A number that is incremented for each DataSetMessage. Can be used to verify the ordering and to detect missing messages.

Timestamp             A timestamp describing when the data in this DataSetMessage was obtained.

Version                 Version information about the configuration of the DataSetMetaData.

Status                   Status information about the data in this DataSetMessage.

Keep alive             When no DataSetMessages are sent for a configured time period, a keep alive DataSetMessage is sent to signal the Subscribers that the Publisher is still alive.

Some encodings differentiate between key frame DataSetMessages and delta frame DataSetMessages. A key frame DataSetMessage includes values for all fields of the DataSet. A delta frame DataSetMessage only contains the subset that changed since the previous DataSetMessage.

A key frame DataSetMessage is sent after a configured number of DataSetMessages.

5.3.4        NetworkMessage

The NetworkMessage is a container for DataSetMessages and includes information shared between DataSetMessages. This information consists of:

PublisherId            Identifies the Publisher.

Security data          Only available for encodings that support message security. The relevant information is specified in the message mapping.

Promoted fields      Selected fields out of the DataSet also sent in the header.

Payload                 One or more DataSetMessages.

The payload, consisting of the DataSetMessages will be encrypted in accordance with the configured message security. Individual fields of a DataSetMessage can be marked as being “promoted fields”. Such fields are intended for filtering or routing and therefore are never encrypted. How and where the values for promoted fields are inserted depends on the NetworkMessage format and the used protocol. The NetworkMessage header is not encrypted to enable efficient filtering.

5.3.5        Message Security

Message security in PubSub concerns integrity and confidentiality of the published message payload. The level of security can be:

·      No security

·      Signing but no encryption

·      Signing and encryption

Message security is end-to-end security (from Publisher to Subscriber) and requires common knowledge of the cryptographic keys necessary to sign and encrypt on the Publisher side as well as validate signature and decrypt on the Subscriber side.

The keys used for message security are managed in the context of a SecurityGroup. The basic concepts of a SecurityGroup are described in 5.3.7.

This standard defines a general distribution framework for cryptographic keys. This framework is introduced in 5.4.3.

All parameters that are relevant for message security are described in 6.2.4. These parameters are independent of any Broker level transport security.

The message security for PubSub is independent of the transport protocol mapping and is completely defined by OPC UA.

5.3.6        Transport Security

The transport security is specific to the transport protocol mapping.

When using a broker-based middleware (see 5.4.4.2.2), confidentiality and integrity can be ensured with the transport security between Publishers and the Broker as well as Subscribers and the Broker. The Broker level security in addition requires all Publishers and Subscribers to have credentials that grant them access to a Broker resource.

Transport security may be hop-by-hop security with some risk of man-in-the-middle attacks. It also requires trusting the Broker since the Broker can read the messages. Combining transport security with message security reduces this risk.

5.3.7        SecurityGroup

A SecurityGroup is an abstraction that represents the message security settings and security keys for a subset of NetworkMessages exchanged between Publishers and Subscribers. The security keys are used to encrypt and decrypt NetworkMessages and to generate and check signatures on a NetworkMessage.

A Security Key Service (SKS) manages SecurityGroups and maintains a mapping between Roles and their access Permissions for a SecurityGroup. This mapping defines if a Publisher or Subscriber has access to the security keys of a SecurityGroup. The SKS is described in more detail in 5.4.3.

A SecurityGroup is identified with a unique identifier called the SecurityGroupId. It is unique within the SKS. A Publisher for its PublishedDataSets must know the SecurityGroupId. For Subscribers the SecurityGroupId is distributed as metadata together with the DataSetMetaData. The metadata for a SecurityGroupId includes the EndpointDescription of the responsible SKS. Publishers and Subscribers use the EndpointDescription to access the SKS and the SecurityGroupId to obtain the security keys for a SecurityGroup.

5.4   Entities

5.4.1        Publisher

5.4.1.1         General

The Publisher is the PubSub entity that sends NetworkMessages to a Message Oriented Middleware. It represents a certain information source, for example, a control device, a manufacturing process, a weather station, or a stock exchange.

Commonly, a Publisher is also an OPC UA Server. For the abstract PubSub concepts, however, it is an arbitrary entity and should not be assumed to be an individual or even a specific network node (an IP or a MAC address) or a specific application. Figure 5 illustrates a Publisher with data collection, encoding and message sending.

Figure8_

Figure 5 – Publisher details

A single Publisher may support multiple PublishedDataSets and multiple DataSetWriters to one or more Message Oriented Middleware. A DataSetWriter is a logical component of a Publisher. See 5.4.1.2 for further information about the DataSet writing process.

If the Publisher is an OPC UA Server, it can expose the Publisher configuration in its AddressSpace. This information may be created through product specific configuration tools or through the OPC UA defined Methods. The OPC UA Information Model for PubSub configuration is specified in clause 9.

5.4.1.2         Message sending

Figure 6 illustrates the process inside a Publisher when creating and sending messages and the parameters required to accomplish it. The components, like DataSet collection or DataSetWriter should be considered abstract. They may not exist in every Publisher as independent entities. However, comparable processes have to exist to generate the OPC UA PubSub messages.

Figure9_

 

Figure 6 – Publisher message sending sequence

The sending process is guided by different parameters for different logical steps. The parameters define for example when and how often to trigger the sending sequence and the encoding and security of the messages. The PubSub communication parameters are defined in 6.

The first step is the collection of data (DataSet) to be published. The configuration for such a collection is called PublishedDataSet. The PublishedDataSet also defines the DataSetMetaData. Collection is a generic expression for various different options, like monitoring of Variables in an OPC UA Server AddressSpace, processing OPC UA Events, or for example reading data from network packets. In the end, the collection process produces values for the individual fields of a DataSet.

In the next step, a DataSetWriter takes the DataSet and creates a DataSetMessage. DataSetMessages from DataSetWriters in one WriterGroup can be inserted into a single NetworkMessage. The creation of a DataSetMessage is guided by the following parameters:

·      The DataSetFieldContentMask (see 6.2.3.2) controls which attributes of a value shall be encoded.

·      The DataSetMessageContentMask (see 6.3.1.2.2) controls which header fields shall be encoded.

·      The KeyFrameCount controls whether a key frame or a delta frame DataSetMessage is to be created.

The resulting DataSetMessage is passed on to the next step together with the DataSetWriterId (see 6.2.3.1), the DataSetClassId (see 6.2.2.2), the ConfigurationVersion of the DataSetMetaData (see 6.2.2.1.5), and a list of values that match the configured propagated fields.

Next is the creation of the NetworkMessage. It uses the data provided from the previous step together with the PublisherId (see 6.2.6.1) defined on the WriterGroup. The structure of this message is protocol specific. If the SecurityMode (see 6.2.4.2) requires message security, the SecurityGroupId (see 6.2.4.3) is used to fetch the SecurityPolicy and the security keys from the SKS (see 5.4.3). This information is used to encrypt and/or sign the NetworkMessage as required by the SecurityMode.

The final step is delivery of the NetworkMessage to the Message Oriented Middleware through the configured Address.

5.4.2        Subscriber

5.4.2.1         General

Subscribers are the consumers of NetworkMessages from the Message Oriented Middleware. They may be OPC UA Clients, OPC UA Servers or applications that are neither Client nor Server but only understand the structure of OPC UA PubSub messages. Figure 7 illustrates a Subscriber with filtering, decoding and dispatching of NetworkMessages.

Figure10_

Figure 7 – Subscriber details

To determine for which DataSetMessages and on which Message Oriented Middleware to subscribe, the Subscriber has to be configured and/or use discovery mechanisms.

Subscribers shall be prepared to receive messages that they do not understand or are irrelevant. Each NetworkMessage provides unencrypted data in the NetworkMessage header to support identifying and filtering of relevant Publishers, DataSetMessages, DataSetClasses or other relevant message content (see 5.3).

If a NetworkMessage is signed or signed and encrypted, the Subscriber will need the proper security keys (see 5.3.5) to verify the signature and decrypt the relevant DataSetMessages.

Once a DataSetMessage has been selected as relevant, it will be forwarded to the corresponding DataSetReader for decoding into a DataSet. See 5.4.2.2 for further information about this DataSet reading process. The resulting DataSet is then further processed or dispatched in the Subscriber.

If the Subscriber is an OPC UA Server, it can expose the reader configuration in its AddressSpace. This information may be created through product specific configuration tools or through the OPC UA defined configuration model. The OPC UA Information Model for PubSub configuration is specified in clause 9.

5.4.2.2         Message reception

Figure 8 illustrates the process inside a Subscriber when receiving, decoding and interpreting messages and the parameter model required for accomplishing it. As for the Publisher, the components should be considered abstract.

Figure11_

 

Figure 8 – Subscriber message reception sequence

The Subscriber has to select the required Message Oriented Middleware and establish a connection to it using the provided Address. Such a connection may simply be a multi-cast address when using OPC UA UDP or a connection to a message Broker when using MQTT or AMQP. Once subscribed, the Subscriber will start listening. The sequence starts when a NetworkMessage is received. The Subscriber may have configured filters (like a PublisherId, DataSetWriterId or a DataSetClassId) so that it can drop all messages that do not match the filter.

Once a NetworkMessage has been accepted, it has to be decrypted and decoded. The security parameters are the same as for the Publisher.

Each DataSetMessage of interest is passed on to a DataSetReader. Here, the DataSetMetaData is used to decode the DataSetMessage content to a DataSet. The DataSetMetaData in particular provides the complete field syntax including the name, data type, and other relevant Properties like engineering units. Version information that exists in both the DataSetMessage and the DataSetMetaData allows the Subscriber to detect version changes. If a major change occurs, the Subscriber needs to get an updated DataSetMetaData.

Any further processing is application-specific. For example, an additional dispatching step may map the received values to Nodes in the Subscribers OPC UA AddressSpace. The configuration for such a dispatching is called SubscribedDataSet.

5.4.3        Security Key Service

5.4.3.1         General

A Security Key Service (SKS) provides keys for message security that can be used by the Publisher to sign and encrypt NetworkMessages and by the Subscriber to verify the signature of NetworkMessages and to decrypt them.

The SKS is responsible for managing the keys used to publish or consume PubSub NetworkMessages. Separate keys are associated with each SecurityGroupId in the system. The GetSecurityKeys Method exposed by the SKS shall be called to receive necessary key material for a SecurityGroupId. GetSecurityKeys can return more than one key. In this case the next key can be used when the current key is outdated without calling GetSecurityKeys for every key needed. The PubSubKeyServiceType defined in 8.2 specifies the GetSecurityKeys Method.

The GetSecurityKeys Method can be implemented by a Publisher or by a central SKS. In both cases, the well-known NodeIds for the PublishSubscribe Object and the related GetSecurityKeys Method are used to call the GetSecurityKeys Method. The PublishSubscribe Object is defined in 8.4.

The SetSecurityKeys Method is typically used by a central SKS to push the security keys for a SecurityGroup into a Publisher or Subscriber. The Method is exposed by Publishers or Subscribers that have no OPC UA Client functionality. The Method is part of the PublishSubscribeType defined in 9.1.3.2.

5.4.3.2         SecurityGroup Management

The SKS is the entity with knowledge of SecurityGroups and it maintains a mapping between Roles and SecurityGroups. The related User Authorization model is defined in OPC 10000-3. The User Authorization model defines the mapping of identities to Roles and the mechanism to set Permissions for Roles on a Node. The Permissions on a SecurityGroup Object is used to determine if a Role has access to the keys for the SecurityGroup.

An example for setting up a SecurityGroup and the configuration of affected Publishers and Subscribers is shown in Figure 9.

Figure12_

Figure 9 – SecurityGroup Management Sequence

To secure NetworkMessages, the NetworkMessages must be secured with keys provided in the context of a SecurityGroup. A SecurityGroup is created on a SKS using the Method AddSecurityGroup.

To limit access to the SecurityGroup and therefore to the security keys, Permissions must be set on the SecurityGroup Object. This requires the management of Roles and Permissions in the SKS.

To set the SecurityGroup relation on the Publishers and Subscribers, the SecurityGroupId and the SKS EndpointDescriptions are configured in a PubSub groups.

5.4.3.3         Key Acquisition Handshakes

The Publisher or Subscriber use keys provided by an SKS to secure messages exchanged via the Message Oriented Middleware. The handshake to pull the keys from a SKS is shown in Figure 10. The handshake to push the keys from a SKS to Publishers and Subscribers is shown in Figure 11.

Figure13_

Figure 10 – Handshake used to pull keys from SKS

To pull keys, the Publisher or Subscriber creates an encrypted connection and provides credentials that allow it access to the SecurityGroup. Then it passes the identifier of the SecurityGroup to the GetSecurityKeys Method that verifies the identity and returns the keys used to secure messages for the PubSubGroup. The GetSecurityKeys Method is defined in 8.4.

The access to the GetSecurityKeys Method may use SessionlessInvoke Service calls. These calls typically use an Access Token that is retrieved from an Authorization Service. Both concepts are defined in OPC 10000-4.

Figure14_

Figure 11 – Handshake used to push keys to Publishers and Subscribers

To push keys, the SKS creates an encrypted connection to a Publisher or Subscriber and provides credentials that allow it to provide keys for a SecurityGroup. Then it passes the identifier of the SecurityGroup and the keys used to secure messages for the SecurityGroup to the SetSecurityKeys Method. The SetSecurityKeys Method is defined in 9.1.3.3.

5.4.3.4         Authorization Services and Security Key Service

Access to the SKS can be managed by an Authorization Service as shown in Figure 12.

Figure15_

Figure 12 – Handshake with a Security Key Service

The SKS is a Server that exposes a Method called GetSecurityKeys. The Access Token is used to determine if the calling application is allowed to access the keys. One way to do this would be to check the Permissions assigned to the SecurityGroup Object identified by the GetSecurityKeys Method arguments. Publishers and Subscribers can request keys if the Access Token they provide is mapped to Roles that have been granted Permission to Browse the SecurityGroup Object.

5.4.4        Message Oriented Middleware

5.4.4.1         General

Message Oriented Middleware as used in this specification is any infrastructure supporting sending and receiving NetworkMessages between distributed applications. OPC UA does not define a Message Oriented Middleware, rather it uses protocols that allow connecting, sending and receiving data. The transport protocol mappings for PubSub are described in 7.3.

This part describes two general types of Message Oriented Middleware to cover a large number of use cases. The two types, broker-less and broker-based middleware are described in 5.4.4.2 and 5.4.4.3.

5.4.4.2         Broker-less Middleware

5.4.4.2.1          General

With this option, OPC UA PubSub relies on the network infrastructure to deliver NetworkMessages to one or more receivers. Network devices – like network routers, switches, or bridges – are typically used for this purpose.

One example is a switched network and the use of UDP with unicast or multicast messages shown in Figure 13.

Figure16_

Figure 13 – PubSub using network infrastructure

Advantages of this model include:

·        Only requires standard network equipment and no additional software components like a Broker.

·        Message delivery is assumed to be direct without software intermediaries and therefore provides reduced latency and overhead.

·        UDP protocol supports multiple subscribers using multicast addressing.

5.4.4.2.2          Broker-less model with OPC UA UDP

Figure 14 depicts the applications, entities and messages involved in peer to peer communication using UDP as a protocol that does not require a Broker.

Figure17_

Figure 14 – UDP Multicast Overview

The PublishSubscribe Object contains a connection Object for each address like an IP multicast address. The connection can have one or more groups with DataSetWriters. A group can publish DataSets at the defined publishing interval.

In each publishing interval, a DataSet is collected for a PublishedDataSet which can be a list of sampled data items in the Publisher OPC UA Address Space. For each DataSet a DataSetMessage is created. The DataSetMessages are sent in a NetworkMessage to the IP multicast address.

OPC UA Applications like HMI applications would use the values of the DataSetMessage that they are interested in.

An OPC UA Application that maps data fields from UADP DataSetMessages to internal Variables can be configured through the DataSetReader Object and dispatcher in the Subscriber. The configuration of a DataSetReader defines how to decode the DataSetMessage to a DataSet. The SubscribedDataSet defines which field in the DataSet is mapped to which Variable in the OPC UA Application.

With OPC UA UDP there is no guarantee of timeliness, delivery, ordering, or duplicate protection. The sequence numbers in DataSetMessages provide a solution for ordering and duplicate detection. The reliability is improved by the option to send the complete DataSet in every DataSetMessage or with the option to repeat NetworkMessages.

Other transport protocol mappings used with the broker-less model could provide guarantee of timeliness, delivery, ordering, or duplicate protection.

5.4.4.3         Broker-based Middleware

5.4.4.3.1          General

This option assumes a messaging Broker in the middle as shown in Figure 15. No application is speaking directly to other applications. All the communication is passed through the Broker. The Broker routes the NetworkMessages to the right applications based on business criteria ("queue name", "routing key", "topic" etc.) rather than on physical topology (IP addresses, host names).

Figure18_

Figure 15 – PubSub using broker

Advantages of this model (partly depending on used Broker and its configuration) include:

·        Publisher and Subscriber do not have to be directly addressable. They can be anywhere as long as they have access to the Broker.

·        Fan out can be handled to a very large list of Subscribers, multiple networks or even chained Brokers or scalable Brokers.

·        Publisher and Subscriber lifetimes do not have to overlap. The Publisher application can push NetworkMessages to the Broker and terminate. The NetworkMessages will be available for the Subscriber application later.

·        Publisher and Subscriber can use different messaging protocols to communicate with the Broker.

In addition, the Broker model is to some extent resistant to the application failure. So, if the application is buggy and prone to failure, the NetworkMessages that are already in the Broker will be retained even if the application fails.

5.4.4.3.2          Broker-based model

Figure 16 depicts the applications, entities and messages involved in typical communication scenarios with a Broker. It requires use of messaging protocols that a Broker understands, like AMQP defined in ISO/IEC 19464:2014 or MQTT defined in ISO/IEC 20922:2016. In this model the Message Oriented Middleware will be a Broker that relays NetworkMessages from Publishers to Subscribers. The Broker may also be able to queue messages and send the same message to multiple Subscribers.

Note that the Broker functionality is outside the scope of this specification. In terms of the messaging protocols, the Broker is a messaging server (the OPC UA Publisher and the OPC UA Subscriber are messaging clients). The messaging protocols define how to connect to a messaging server and what fields in a message influence the Broker functionality.

Figure19_

Figure 16 – Broker Overview

An OPC UA Publisher that publishes data may be configured through the PubSub configuration model. It contains a connection Object per Broker. The Broker is configured through an URL in the connection. The connection can have one or more groups which identity specific queues or topics. Each group may have one or more DataSetWriters that format a DataSet as required for the messaging protocol. A DataSet can be collected from a list of Event fields and/or selected Variables. Such a configuration is called PublishedDataSet.

Each DataSet is sent as a separate DataSetMessage serialized with a format that depends on the DataSetWriter. One DataSetMessage format is the JSON message mapping which represents the DataSet in a format which Subscribers can understand without knowledge of OPC UA. Another DataSetMessage format is the UADP message mapping.

Message confidentiality and integrity with the Broker based communication model can be ensured at two levels:

·      transport security between Publishers or Subscribers and the Broker or

·      message security as end-to-end security between Publisher and Subscriber.

The Broker level security requires all Publishers and Subscribers to have credentials that grant them access to the necessary queue or topic. In addition, all communication with the Broker uses transport level security to ensure confidentiality. The security parameters are specified on the connection and group.

The message security provided by the Publisher is only defined for the UADP message mapping.

6       PubSub Communication Parameters

6.1       Overview

PubSub defines different configuration parameters for the various PubSub components. They define the behaviour of Publisher and Subscriber. The parameters are grouped by component and are partitioned into ‘common’, ’message mapping’, and ‘transport protocol mapping’.

The common parameters are defined in 6.2. The parameters for the different message mappings are defined in 6.3. The parameters for the different transport protocol mappings are defined in 6.4.

The application of communication parameters for concrete message and transport protocol mappings is defined in clause 7.

Configuration of these parameters can be performed through the OPC UA Information Model for PubSub configuration defined in clause 9 or through vendor-specific mechanisms. The parameter groupings in this clause define the parameters and also define Structures used to represent the parameters of the groupings. These Structures are used in the PubSub configuration model described in clause 9 but they can also be used for offline configuration or vendor-specific configuration mechanisms.

Figure 17 depicts the different components and their relation to each other. The WriterGroup, DataSetWriter and PublishedDataSet components define the data acquisition for the DataSets, the message generation and the sending on the Publisher side. These parameters need to be known on the Subscriber side to configure DataSetReaders and to filter and process DataSetMessages.

Figure20_

Figure 17 – PubSub Component Overview

The figure shows the following components:

·      PublishedDataSet contains the DataSetMetaData describing the content of the DataSets produced by the PublishedDataSet and the corresponding data acquisition parameters.

·      DataSetWriter parameters are necessary for creating DataSetMessages. Each DataSetWriter is bound to a single PublishedDataSet. A PublishedDataSet can have multiple DataSetWriters.

·      WriterGroup parameters are necessary for creating a NetworkMessage. Each writer group can have one or more DataSetWriters. Some of these parameters are used for creating the DataSetMessages. They are grouped here since they are the same for all DataSetMessages in a single NetworkMessage.

·      PubSubConnection parameters represent settings needed for the transport protocol. One connection can have a number of writer groups and reader groups.

·      ReaderGroup is used to group a list of DataSetReaders and contains a few shared settings for them. It is not symmetric to a WriterGroup and it is not related to a particular NetworkMessage. The NetworkMessage related filter settings are on the DataSetReaders.

·      DataSetReader parameters represent settings for filtering of received NetworkMessages and DataSetMessages as well as settings for decoding of the DataSetMessages of interest.

·      SubscribedDataSet parameters define the processing of the decoded DataSet in the Subscriber for one DataSetReader.

·      PublishSubscribe is the overall management of the PubSub groupings. It contains a list of PublishedDataSets and a list of PubSubConnections.

The different PubSub mapping specific parameter groupings are shown in Figure 18.

Figure21_

Figure 18 – PubSub Mapping Specific Parameters Overview

Transport protocol mapping specific parameters may be defined for the PubSubConnection, the WriterGroup or the DataSetWriter.

Message mapping specific parameters are defined for the NetworkMessages on the WriterGroup and for the DataSetMessages on the DataSetWriter.

6.2       Common Configuration Parameters

6.2.1        PubSubState State Machine

The PubSubState is used to expose and control the operation of a PubSub component. It is an enumeration of the possible states. The enumeration values are described in Table 1.

Table 1 – PubSubState Values

Value

Description

Disabled_0

The PubSub component is configured but currently disabled.

Paused_1

The PubSub component is enabled but currently paused by a parent component. The parent component is either Disabled_0 or Paused_1.

Operational_2

The PubSub component is operational.

Error_3

The PubSub component is in an error state.

 

Figure 19 depicts the PubSub components that have a PubSub state and their parent-child relationship. State changes of children are based on changes of the parent state. The root of the hierarchy is the PublishSubscribe component.

Figure22_

Figure 19 – PubSub Component State Dependencies

Figure 20 describes the formal state machine with the possible transitions.

Figure23_

Figure 20 – PubSubState State Machine

Table 2 formally defines the transitions of the state machine.

Table 2 – PubSubState State Machine

Source State

Target State

Trigger Description

Disabled_0

Paused_1

The component was successfully enabled but the parent component is in the state Disabled_0 or Paused_1.

Disabled_0

Operational_2

The component was successfully enabled.

Paused_1

Disabled_0

The component was successfully disabled.

Paused_1

Operational_2

The state of the parent component changed to Operational_2.

Operational_2

Disabled_0

The component was successfully disabled.

Operational_2

Paused_1

The state of the parent component changed to Disabled_0 or Paused_1.

Operational_2

Error_3

There is a pending error situation for the related PubSub component.

Error_3

Disabled_0

The component was successfully disabled.

Error_3

Paused_1

The state of the parent component changed to Disabled_0 or Paused_1.

Error_3

Operational_2

The error situation was resolved for the related PubSub component.

 

6.2.2        PublishedDataSet Parameters

6.2.2.1         DataSetMetaData

6.2.2.1.1          General

DataSetMetaData describe the content and semantic of a DataSet. The order of the fields in the DataSetMetaData shall match the order of DataSet fields when they are included in the published DataSetMessages. The DataSetMetaDataType is defined in 6.2.2.1.2.

6.2.2.1.2          DataSetMetaDataType

This Structure DataType is a subtype of DataTypeSchemaHeader and is used to provide the metadata for a DataSet. The DataSetMetaDataType is formally defined in Table 3.

The DataTypeSchemaHeader provides OPC UA DataType definitions used in the DataSetMetaData. The DataTypeSchemaHeader is defined in A.1.1.

Table 3 – DataSetMetaDataType Structure

Name

Type

Description

DataSetMetaDataType

Structure

 

     name

String

Name of the DataSet.

     description

LocalizedText

Description of the DataSet.

The default value is a null LocalizedText.

     fields

FieldMetaData[]

The metadata for the fields in the DataSet.

The FieldMetaData DataType is defined in 6.2.2.1.3.

     dataSetClassId

Guid

This field provides the globally unique identifier of the class of DataSet if the DataSet is based on a DataSetClass. In this case, this field shall match the DataSetClassId of the concrete DataSet configuration.

If the DataSets are not created from a class, this field is null.

     configurationVersion

Configuration‌VersionDataType

The configuration version for the current configuration of the DataSet.

 

Its representation in the AddressSpace is defined in Table 4.

Table 4 – DataSetMetaDataType Definition

Attributes

Value

BrowseName

DataSetMetaDataType

IsAbstract

False

Subtype of DataTypeSchemaHeader defined in A.1.1.

 

6.2.2.1.3          FieldMetaData

This Structure DataType is used to provide the metadata for a field in a DataSet. The FieldMetaData is formally defined in Table 5.

Table 5 – FieldMetaData Structure

Name

Type

Description

FieldMetaData

Structure

 

     name

String

Name of the field.

The name shall be unique in the DataSet.

     description

LocalizedText

Description of the field.

The default value shall be a null LocalizedText.

     fieldFlags

DataSetFieldFlags

Flags for the field.

     builtInType

Byte

The built-in data type of the field. The possible built-in type values are defined in OPC 10000-6.

All data types are transferred in DataSetMessages as one of the built-in data types. In most cases the identifier of the DataType NodeId matches the built-in type. The following special cases must be handled in addition:

(1) Abstract types always have the built-in type Variant since they can result in different concrete types in a DataSetMessage. The dataType field may provide additional restrictions e.g. if the abstract type is Number. Abstract types shall not be used if the field is represented as RawData set by the DataSetFieldContentMask defined in 6.2.3.1.

(2) Enumeration DataTypes are encoded as Int32. The Enumeration strings are defined through a DataType referenced through the dataType field.

(3) Structure and Union DataTypes are encoded as ExtensionObject. The encoding rules are defined through a DataType referenced through the dataType field.

(4) DataTypes derived from built-in types have the BuiltInType of the corresponding base DataType. The concrete subtype is defined through the dataType field.

(5) OptionSet DataTypes are either encoded as one of the concrete UInteger DataTypes or as an instance of an OptionSetType in an ExtensionObject.

     dataType

NodeId

The NodeId of the DataType of this field.

If the DataType is an Enumeration or an OptionSet, the semantic of the Enumeration DataType is provided through the enumDataTypes field of the DataSetMetaData.

If the DataType is a Structure or Union, the encoding and decoding description of the Structure DataType is provided through the structureDataTypes field of the DataSetMetaData.

     valueRank

Int32

Indicates whether the dataType is an array and how many dimensions the array has.

It may have the following values:

n > 1: the dataType is an array with the specified number of dimensions.

OneDimension (1): The dataType is an array with one dimension.

OneOrMoreDimensions (0): The dataType is an array with one or more dimensions.

Scalar (1): The dataType is not an array.

Any (2): The dataType can be a scalar or an array with any number of dimensions.

ScalarOrOneDimension (3): The dataType can be a scalar or a one dimensional array.

NOTE All DataTypes are considered to be scalar, even if they have array-like semantics like ByteString and String.

     arrayDimensions

UInt32[]

This field specifies the maximum supported length of each dimension. If the maximum is unknown the value shall be 0.

The number of elements shall be equal to the value of the valueRank field. This field shall be null if valueRank ≤ 0.

The maximum number of elements of an array transferred on the wire is 2147483647 (max Int32). It is the total number of elements in all dimensions based on the UA Binary encoding rules for arrays.

     maxStringLength

UInt32

If the dataType field is a String or ByteString then this field specifies the maximum supported length. If the maximum is unknown the value shall be 0.

If the dataType field is not a String or ByteString the value shall be 0.

If the valueRank is greater than 0 this field applies to each element of the array.

     dataSetFieldId

Guid

The unique ID for the field in the DataSet. The ID is generated when the field is added to the list. A change of the position of the field in the list shall not change the ID.

     properties

KeyValuePair[]

List of Property values providing additional semantic for the field.

If at least one Property value changes, the MajorVersion of the ConfigurationVersion shall be updated.

If the Property is EngineeringUnits, the unit of the Field Value shall match the unit of the FieldMetaData.

The KeyValuePair DataType is defined in OPC 10000-5. For this field the key in the KeyValuePair structure is the BrowseName of the Property and the value in the KeyValuePair structure is the Value of the Property.

 

6.2.2.1.4          DataSetFieldFlags

This DataType defines flags for DataSet fields.

The DataSetFieldFlags is formally defined in Table 6.

Table 6 – DataSetFieldFlags Values

Value

Bit No.

Description

PromotedField

0

The flag indicates if the field is promoted to the NetworkMessages or transport protocol header.

Setting this flag increases the size of the NetworkMessages since information from the DataSetMessage body is also promoted to the header.

Depending on the used security, the header including the field may be unencrypted.

Promoted fields are always included in the header even if the DataSetMessage payload is a delta frame and the DataSet field is not included in the delta frame. In this case the last sent value is sent in the header.

The order of the fields in the DataSetMetaData promoted to the header shall match the order of the fields in the header unless the header includes field names.

 

The DataSetFieldFlags representation in the AddressSpace is defined in Table 7.

Table 7 – DataSetFieldFlags Definition

Attributes

Value

BrowseName

DataSetFieldFlags

IsAbstract

False

References

NodeClass

BrowseName

DataType

Subtype of UInt16 defined in OPC 10000-5.

HasProperty

Variable

OptionSetValues

LocalizedText [ ]

 

6.2.2.1.5          ConfigurationVersionDataType

This Structure DataType is used to indicate configuration changes in the information published for a DataSet. The ConfigurationVersionDataType is formally defined in Table 8.

Table 8 – ConfigurationVersionDataType Structure

Name

Type

Description

ConfigurationVersionDataType

Structure

 

     majorVersion

VersionTime

The MajorVersion reflects the time of the last major change of the DataSet content. The VersionTime DataType is defined in OPC 10000-4.

To assure interoperability, the Subscriber has to use DataSetMetaData for decoding with a MajorVersion that matches the MajorVersion in DataSetMessages sent by the Publisher.

Removing fields from the DataSet content, reordering fields, adding fields in between other fields or a DataType change in fields shall result in an update of the MajorVersion.

If at least one Property value of a DataSetMetaData field changes, the MajorVersion shall be updated.

There can be situations where older configurations of a Publisher are loaded and changed with product specific configuration tools. In this case the MajorVersion shall be updated if the configuration tool is not able to verify if the change only extends the configuration and does not change the existing content.

Additional criteria for changing MajorVersion or MinorVersion are defined in this specification.

     minorVersion

VersionTime

The MinorVersion reflects the time of the last change.

Only the MinorVersion shall be updated if fields are added at the end of the DataSet content.

If the MajorVersion version is updated, the MinorVersion is updated to the same value as MajorVersion.

 

6.2.2.2         DataSetClassId

DataSetMetaData may be specific to a single Publisher and a single selection of information or universal e.g. defined by a standard organisation or by a plant operator as a DataSetClass. DataSets that conform to such a DataSetClass are identified with a DataSetClassId.

The DataSetClassId is the globally unique identifier (Guid) of a DataSetClass. It is included in the DataSetMetaData. The NetworkMessageContentMask controls the availability of the DataSetClassId in the NetworkMessage.

6.2.2.3         ExtensionFields

The ExtensionFields parameter allows the configuration of fields with values to be included in the DataSet when the existing AddressSpace of the Publisher does not provide the necessary information. The ExtensionFields are represented as array of KeyValuePair Structures.

6.2.2.4         PublishedDataSetDataType

This Structure DataType represents the PublishedDataSet parameters. The PublishedDataSetDataType is formally defined in Table 9.

Table 9 – PublishedDataSetDataType Structure

Name

Type

Description

PublishedDataSetDataType

Structure

 

     name

String

Name of the PublishedDataSet.

The name of the PublishedDataSet shall be unique in the Publisher.

     dataSetFolder

String[]

Optional path of the DataSet folder used to group PublishedDataSets where each entry in the String array represents one level in a DataSet folder hierarchy.

If no grouping is needed the parameter is a null String array.

     dataSetMetaData

DataSetMetaDataType

Defined in 6.2.2.1.

     extensionFields

KeyValuePair[]

Defined in 6.2.2.3.

     dataSetSource

PublishedDataSetSourceDataType

Defined in 6.2.2.5.

 

6.2.2.5         PublishedDataSetSourceDataType

The PublishedDataSetSourceDataType Structure is an abstract base type without fields for the definition of the PublishedDataSet source. Its representation in the AddressSpace is defined in Table 10.

Table 10 – PublishedDataSetSourceDataType Definition

Attributes

Value

BrowseName

PublishedDataSetSourceDataType

IsAbstract

True

References

NodeClass

BrowseName

IsAbstract

Description

Subtype of Structure defined in OPC 10000-5.

HasSubtype

DataType

PublishedDataItemsDataType

FALSE

Defined in 6.2.2.6.2.

HasSubtype

DataType

PublishedEventsDataType

FALSE

Defined in 6.2.2.7.4.

 

6.2.2.6         Published Data Items

6.2.2.6.1          PublishedData

The parameter PublishedData defines the content of a DataSet created from Variable Values and therefore the content of the DataSetMessage sent by a DataSetWriter. The sources of the DataSet fields are defined through an array of PublishedVariableDataType.

The index into the array has an important role for Subscribers and for configuration tools. It is used as a handle to reference the Value in DataSetMessages received by Subscribers. The index may change after configuration changes. Changes are indicated by the ConfigurationVersion of the DataSet and applications working with the index shall always check the ConfigurationVersion before using the index.

If an entry of the PublishedData references one of the ExtensionFields, the substituteValue shall contain the QualifiedName of the ExtensionFields entry. All other fields of this PublishedVariableDataType array element shall be null.

The DataType PublishedVariableDataType represents the configuration information for one Variable. The PublishedVariableDataType is formally defined in Table 11.

Table 11 – PublishedVariableDataType Structure

Name

Type

Description

PublishedVariableDataType

Structure

 

     publishedVariable

NodeId

The NodeId of the published Variable.

Some transport protocols require knowledge on the message receiver side about the DataType, ValueRank and ArrayDimensions to be able to decode the message content. This information is provided through the DataSetMetaData provided for the DataSet.

     attributeId

IntegerId

Id of the Attribute to publish e.g. the Value Attribute. This shall be a valid Attribute id.

The Attributes are defined in OPC 10000-3. The IntegerId DataType is defined in OPC 10000-4. The IntegerIds for the Attributes are defined in OPC 10000-6.

     samplingIntervalHint

Duration

A recommended rate of acquiring new values for change or deadband evaluation. A Publisher should use this value as hint for setting the internal sampling rate.

The value 0 indicates that the Server should use the fastest practical rate.

The value -1 indicates that the default sampling interval defined by the PublishingInterval of the WriterGroup is requested. Any negative number is interpreted as -1.

     deadbandType

UInt32

A value that defines the Deadband type and behaviour.

    Value                  Description

    None_0               No Deadband calculation should be applied.

    Absolute_1          AbsoluteDeadband (This type is specified in                               OPC 10000-4)

    Percent_2            PercentDeadband (This type is specified in                               OPC 10000-8).

     deadbandValue

Double

The deadband value for the corresponding DeadbandType. The meaning of the value depends on DeadbandType.

     indexRange

NumericRange

This parameter is used to identify a single element of an array, or a single range of indexes for arrays. The NumericRange type and the logic for IndexRange are defined in OPC 10000-4.

 

     substituteValue

BaseDataType

The value that is included in the DataSet if the StatusCode of the DataValue is Bad. In this case the StatusCode is set to

Uncertain_SubstituteValue.

This Value shall match the DataType of the PublishedVariable since DataSetWriters may depend on a valid Value with the right DataType that matches the ConfigurationVersion.

If the SubstituteValue is Null, the StatusCode of the DataValue is processed.

The handling of the SubstituteValue is defined in 6.2.10.

     metaDataProperties

QualifiedName [ ]

This parameter specifies an array of Properties to be included in the FieldMetaData created for this Variable.

It shall be used to populate the properties element of the resulting field in the DataSetMetaData.

 

6.2.2.6.2          PublishedDataItemsDataType

This Structure DataType is used to represent PublishedDataItems specific parameters. It is a subtype of the PublishedDataSetSourceDataType defined in 6.2.2.5.

The PublishedDataItemsDataType is formally defined in Table 12.

Table 12 – PublishedDataItemsDataType Structure

Name

Type

Description

PublishedDataItemsDataType

Structure

 

     publishedData

PublishedVariableDataType[]

Defined in 6.2.2.6.1.

 

6.2.2.7         Published Events

6.2.2.7.1          EventNotifier

The parameter EventNotifier defines the NodeId of the Object in the event notifier tree of the OPC UA Server from which Events are collected.

6.2.2.7.2          SelectedFields

The parameter SelectedFields defines the selection of Event fields contained in the DataSet generated for an Event and sent through the DataSetWriter. The SimpleAttributeOperand DataType is defined in OPC 10000-4. The DataType of the selected Event field in the EventType defines the DataType of the DataSet field. Event fields can be null or the field value can be a StatusCode. The encoding of Event based DataSetMessages shall be able to handle these cases. ExtensionFields defined for the instance of the PublishedEventsType can be included in the SelectedFields by specifying the PublishedEventsType NodeId as typeId in the SimpleAttributeOperand and the BrowseName of the extension field in the browsePath of the SimpleAttributeOperand.

The index into the list of entries in the SelectedFields has an important role for Subscribers. It is used as handle to reference the Event field in DataSetMessages received by Subscribers. The index may change after configuration changes. Changes are indicated by the ConfigurationVersion and applications working with the index shall always check the ConfigurationVersion before using the index. If a change of the SelectedFields adds additional fields, the MinorVersion of the ConfigurationVersion shall be updated. If a change of the SelectedFields removes fields, the MajorVersion of the ConfigurationVersion shall be updated. The ConfigurationVersionDataType and the rules for setting the version are defined in 6.2.2.1.5.

6.2.2.7.3          Filter

The parameter Filter defines the filter applied to the Events. It allows the reduction of the DataSets generated from Events through a filter. The ContentFilter DataType is defined in OPC 10000-4.

6.2.2.7.4          PublishedEventsDataType

This Structure DataType is used to represent PublishedEvents specific parameters. It is a subtype of the PublishedDataSetSourceDataType defined in 6.2.2.5.

The PublishedEventsDataType is formally defined in Table 13.

Table 13 – PublishedEventsDataType Structure

Name

Type

Description

PublishedEventsDataType

Structure

 

     eventNotifier

NodeId

Defined in 6.2.2.7.1.

     selectedFields

SimpleAttributeOperand[]

Defined in 6.2.2.7.2.

     filter

ContentFilter

Defined in 6.2.2.7.3.

 

6.2.3        DataSetWriter Parameters

6.2.3.1         DataSetWriterId

The DataSetWriterId with DataType UInt16 defines the unique ID of the DataSetWriter for a PublishedDataSet. It is used to select DataSetMessages for a PublishedDataSet on the Subscriber side.

It shall be unique across all DataSetWriters for a PublisherId.

All values, except for 0, are valid DataSetWriterIds. The value 0 is defined as null value.

6.2.3.2         DataSetFieldContentMask

A DataSet field consists of a value and related metadata. In most cases the value comes with status and timestamp information.

This DataType defines flags to include DataSet field related information like status and timestamp in addition to the value in the DataSetMessage.

The DataSetFieldContentMask is formally defined in Table 14.

The handling of bad status for different field representations is defined in Figure 21 and Table 16.

Table 14 – DataSetFieldContentMask Values

Value

Bit No.

Description

DataSet fields can be represented as RawData, Variant or DataValue as described in 5.3.2.

If none of the flags are set, the fields are represented as Variant.

If the RawData flag is set, the fields are represented as RawData and all other bits are ignored.

If one of the bits 0 to 4 is set, the fields are represented as DataValue.

StatusCode

0

The DataValue structure field StatusCode is included in the DataSetMessages.

If this flag is set, the fields are represented as DataValue.

SourceTimestamp

1

The DataValue structure field SourceTimestamp is included in the DataSetMessages.

If this flag is set, the fields are represented as DataValue.

ServerTimestamp

2

The DataValue structure field ServerTimestamp is included in the DataSetMessages.

If this flag is set, the fields are represented as DataValue.

SourcePicoSeconds

3

The DataValue structure field SourcePicoSeconds is included in the DataSetMessages.

If this flag is set, the fields are represented as DataValue. This flag is ignored if the SourceTimestamp flag is not set.

ServerPicoSeconds

4

The DataValue structure field ServerPicoSeconds is included in the DataSetMessages.

If this flag is set, the fields are represented as DataValue. This flag is ignored if the ServerTimestamp flag is not set.

RawData

5

If this flag is set, the values of the DataSet are encoded as Structure and all other field related flags shall be ignored.

The RawData representation 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. Fields shall not have an abstract DataType or shall have a fixed ValueRank. Fields shall have dimensions defined if the DataType is String or ByteString or if it is an array. This includes Structure fields with such fields. The flag shall be ignored and the fields shall be represented as Variant if the fields do not fulfil these requirements.

 

The DataSetFieldContentMask representation in the AddressSpace is defined in Table 15.

Table 15 – DataSetFieldContentMask Definition

Attributes

Value

BrowseName

DataSetFieldContentMask

IsAbstract

False

References

NodeClass

BrowseName

DataType

Subtype of UInt32 defined in OPC 10000-5.

HasProperty

Variable

OptionSetValues

LocalizedText [ ]

 

The DataSetFieldContentMask defines different options that influence the information flow from Publisher to Subscriber in the case of a Bad Value Status or other error situations. Figure 21 depicts the parameters and the information flow from DataSet field to DataSetMessage creation on Publisher side and the decoded DataSet field on the Subscriber side. The DataSetFieldContentMask controls the representation of the DataSet fields in a DataSetMessage.

Figure24_

Figure 21 – PubSub Information Flow dependency to field representation

The representation of the DataSet fields in a DataSetMessage on the Publisher side and the decoding back to the DataSet fields on the Subscriber side is defined in Table 16. The representation on the Publisher side depends on the field representation defined in the DataSetFieldContentMask.

Table 16 – DataSetMessage field representation options

DataSet Publisher

Field

DataSetMessage

DataSet Subscriber

Value

Status(4)

Value

Status(4)

Value

Status(4)

Value 1

Good_*

Variant

Value 1

N/A (1)

Value 1

N/A (1)

Value 1

Uncertain_*

Value 1

Value 1

Null

Bad_*

Bad_* (1)

Null

Bad_*

Value 1

Good_*

DataValue

Value 1

Good_*

Value 1

Good_*

Value 1

Uncertain_*

Value 1

Uncertain_*

Value 1

Uncertain_*

Null

Bad_*

Null

Bad_*

Null

Bad_*

Value 1

Good_*

RawData

Value 1

N/A

Value 1

N/A

Value 1

Uncertain_*

Value 1(2)

Value 1

Null

Bad_*

DefaultValue(3)

DefaultValue

Note 1:    A bad status is transferred instead of a value. An uncertain status is not transferred for a field. If                the status field is included in the DataSetMessage header, the status is set to uncertain if one of                the fields has an uncertain status.

Note 2:    If the worst status for one or more fields is uncertain, the DataSetMessage status shall be set to                Uncertain.

Note 3:    If the worst status for one or more fields is bad, the DataSetMessage status shall be set to Bad.

Note 4:    If no specific StatusCode is used, the grouping into severity Good, Uncertain or Bad is used.
               In this case, the resulting Status matches the input Status.

 

6.2.3.3         KeyFrameCount

The KeyFrameCount with DataType UInt32 is the multiplier of the PublishingInterval that defines the maximum number of times the PublishingInterval expires before a key frame message with values for all published Variables is sent. The delta frame DataSetMessages contains just the changed values. If no changes exist, the delta frame DataSetMessage shall not be sent. If the KeyFrameCount is set to 1, every message contains a key frame.

For PublishedDataSets like PublishedDataItems that provide cyclic updates of the DataSet, the value shall be greater or equal to 1. For non-cyclic PublishedDataSets, like PublishedEvents, that provide event based DataSets, the value shall be 0.

6.2.3.4         DataSetWriterProperties

The DataSetWriterProperties parameter is an array of DataType KeyValuePair that specifies additional properties for the configured DataSetWriter. The KeyValuePair DataType is defined in OPC 10000-5 and consists of a QualifiedName and a value of BaseDataType.

The mapping of the name and value to concrete functionality may be defined by transport protocol mappings, future versions of this specification or vendor specific extensions.

6.2.3.5         DataSetWriter Structure

6.2.3.5.1          DataSetWriterDataType

This Structure DataType is used to represent the DataSetWriter parameters. The DataSetWriterDataType is formally defined in Table 17.

Table 17 – DataSetWriterDataType Structure

Name

Type

Description

DataSetWriterDataType

Structure

 

     name

String

The name of the DataSetWriter.

     enabled

Boolean

The enabled state of the DataSetWriter.

     dataSetWriterId

UInt16

Defined in 6.2.3.1.

     dataSetFieldContentMask

DataSetFieldContentMask

Defined in 6.2.3.2.

     keyFrameCount

UInt32

Defined in 6.2.3.3.

     dataSetName

String

The name of the corresponding PublishedDataSet.

     dataSetWriterProperties

KeyValuePair[]

Defined in 6.2.3.4.

     transportSettings

DataSetWriterTransportDataType

Transport mapping specific DataSetWriter parameters. The abstract base type is defined in 6.2.3.5.2. The concrete subtypes are defined in the sections for transport mapping specific parameters.

     messageSettings

DataSetWriterMessageDataType

DataSetMessage mapping specific DataSetWriter parameters. The abstract base type is defined in 6.2.3.5.3. The concrete subtypes are defined in the sections for message mapping specific parameters.

 

6.2.3.5.2          DataSetWriterTransportDataType

This Structure DataType is an abstract base type for transport mapping specific DataSetWriter parameters. The abstract DataType does not define fields.

The DataSetWriterTransportDataType Structure representation in the AddressSpace is defined in Table 18.

Table 18 – DataSetWriterTransportDataType Definition

Attributes

Value

BrowseName

DataSetWriterTransportDataType

IsAbstract

True

References

NodeClass

BrowseName

IsAbstract

Description

Subtype of Structure defined in OPC 10000-5.

HasSubtype

DataType

BrokerDataSetWriterTransportDataType

FALSE

Defined in 6.4.2.3.7.

 

6.2.3.5.3          DataSetWriterMessageDataType

This Structure DataType is an abstract base type for message mapping specific DataSetWriter parameters. The abstract DataType does not define fields.

The DataSetWriterMessageDataType Structure representation in the AddressSpace is defined in Table 19.

Table 19 – DataSetWriterMessageDataType Structure

Attributes

Value

BrowseName

DataSetWriterMessageDataType

IsAbstract

True

References

NodeClass

BrowseName

IsAbstract

Description

Subtype of Structure defined in OPC 10000-5.

HasSubtype

DataType

UadpDataSetWriterMessageDataType

FALSE

Defined in 6.3.1.2.6.

HasSubtype

DataType

JsonDataSetWriterMessageDataType

FALSE

Defined in 6.3.2.2.2.

 

6.2.4        Shared PubSubGroup Parameters

6.2.4.1         General

The parameters are shared between WriterGroup and ReaderGroup.

The parameters are related to PubSub NetworkMessage security. See 5.4.3 for an introduction of PubSub security and 8 for the definition of the PubSub Security Key Service.

6.2.4.2         SecurityMode

The SecurityMode indicates the level of security applied to the NetworkMessages published by a WriterGroup or received by a ReaderGroup. The MessageSecurityMode DataType is defined in OPC 10000-4.

6.2.4.3         SecurityGroupId

The SecurityGroupId with DataType String is the identifier for a SecurityGroup in the Security Key Server. It is unique within a SKS.

The parameter is null if the SecurityMode is NONE_1.

If the SecurityMode is not NONE_1 the SecurityGroupId identifies the SecurityGroup. The SecurityGroup defines the SecurityPolicy and the security keys used for the NetworkMessage security. The PubSubGroup defines the SecurityMode for the NetworkMessages sent by the group.

6.2.4.4         SecurityKeyServices

SecurityKeyServices is an array of the DataType EndpointDescription and defines one or more Security Key Servers (SKS) that manage the security keys for the SecurityGroup assigned to the PubSubGroup. The EndpointDescription DataType is defined in OPC 10000-4.

The parameter is null if the SecurityMode is NONE_1.

Each element in the array is an Endpoint for an SKS that can supply the security keys for the SecurityGroupId. Multiple Endpoints exist because an SKS may support multiple transport profiles and/or may have multiple redundant instances. The UserTokenPolicies in each Endpoint specify what user credentials are required. OPC 10000-4 describes UserTokenPolicies in more detail.

6.2.4.5         MaxNetworkMessageSize

The MaxNetworkMessageSize with DataType UInt32 indicates the maximum size in bytes for NetworkMessages created by the WriterGroup. It refers to the size of the complete NetworkMessage including padding and signature without any additional headers added by the transport protocol mapping. If the size of a NetworkMessage exceeds the MaxNetworkMessageSize, the behaviour depends on the message mapping.

The transport protocol mappings defined in 7.3 may define restrictions for the maximum value of this parameter.

Note 1: The value for the MaxNetworkMessageSize should be configured in a way that ensures that NetworkMessages together with additional headers added by the transport protocol are still smaller or equal than the transport protocol MTU.

6.2.4.6         GroupProperties

The GroupProperties parameter is an array of DataType KeyValuePair that specifies additional properties for the configured group. The KeyValuePair DataType is defined in OPC 10000-5 and consists of a QualifiedName and a value of BaseDataType.

The mapping of the name and value to concrete functionality may be defined by transport protocol mappings, future versions of this specification or vendor specific extensions.

6.2.4.7         PubSubGroup Structure

This Structure DataType is an abstract base type for PubSubGroups. The PubSubGroupDataType is formally defined in Table 20.

Table 20 – PubSubGroupDataType Structure

Name

Type

Description

PubSubGroupDataType

Structure

 

     name

String

The name of the PubSubGroup.

     enabled

Boolean

The enabled state of the PubSubGroup.

     securityMode

MessageSecurityMode

Defined in 6.2.4.2.

     securityGroupId

String

Defined in 6.2.4.3.

     securityKeyServices

EndpointDescription[]

Defined in 6.2.4.4.

     maxNetworkMessageSize

UInt32

Defined in 6.2.4.5.

     groupProperties

KeyValuePair[]

Defined in 6.2.4.6.

 

The PubSubGroupDataType Structure representation in the AddressSpace is defined in Table 21.

Table 21 – PubSubGroupDataType Definition

Attributes

Value

BrowseName

PubSubGroupDataType

IsAbstract

True

References

NodeClass

BrowseName

IsAbstract

Description

Subtype of Structure defined in OPC 10000-5.

HasSubtype

DataType

WriterGroupDataType

FALSE

Defined in 6.2.5.6.1.

HasSubtype

DataType

ReaderGroupDataType

FALSE

Defined in 6.2.7.2.1.

 

6.2.5        WriterGroup Parameters

6.2.5.1         WriterGroupId

The WriterGroupId with DataType UInt16 is an identifier for the WriterGroup and shall be unique across all WriterGroups for a PublisherId. All values, except for 0, are valid. The value 0 is defined as null value.

6.2.5.2         PublishingInterval

The PublishingInterval with the DataType Duration defines the interval in milliseconds for publishing NetworkMessages and the embedded DataSetMessages created by the related DataSetWriters.

In the case of Event based DataSets, this may result in zero to many DataSetMessages produced for one PublishedDataSet in a PublishingInterval. All Events that occur between two PublishingIntervals shall be buffered until the next NetworkMessage is sent. If the number of Events exceeds the buffer capability of the DataSetWriter, an Event of type EventQueueOverflowEventType is inserted into the buffer.

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

6.2.5.3         KeepAliveTime

The KeepAliveTime with DataType Duration defines the time in milliseconds until the Publisher sends a keep alive DataSetMessage in the case where no DataSetMessage was sent in this period by a DataSetWriter. The minimum value shall equal the PublishingInterval.

6.2.5.4         Priority

The Priority with DataType Byte defines the relative priority of the WriterGroup to all other WriterGroups across all PubSubConnections of the Publisher.

If more than one WriterGroup needs to be processed, the priority number defines the order of processing. The highest priority is processed first.

The lowest priority is zero and the highest is 255.

6.2.5.5         LocaleIds

The LocaleIds with DataType LocaleId defines a list of locale ids in priority order for localized strings for all DataSetWriters in the WriterGroup. The first LocaleId in the list has the highest priority.

If the Publisher sends a localized String, the Publisher shall send the translation with the highest priority that it can. If it does not have a translation for any of the locales identified in this list, then it shall send the String value that it has and include the LocaleId with the String. If no locale id is configured, the Publisher shall use any that it has. See OPC 10000-3 for more detail on LocaleId.

6.2.5.6         WriterGroup Structures

6.2.5.6.1          WriterGroupDataType

This Structure DataType is used to represent the configuration parameters for WriterGroups. It is a subtype of PubSubGroupDataType defined in 0.

The WriterGroupDataType is formally defined in Table 22.

Table 22 – WriterGroupDataType Structure

Name

Type

Description

WriterGroupDataType

Structure

 

     writerGroupId

UInt16

Defined in 6.2.5.1.

     publishingInterval

Duration

Defined in 6.2.5.2.

     keepAliveTime

Duration

Defined in 6.2.5.3.

     priority

Byte

Defined in 6.2.5.4.

     localeIds

LocaleId[]

Defined in 6.2.5.5.

     headerLayoutUri

String

 

     transportSettings

WriterGroupTransportDataType

Transport mapping specific WriterGroup parameters. The abstract base type is defined in 6.2.5.6.2. The concrete subtypes are defined in the sections for transport mapping specific parameters.

     messageSettings

WriterGroupMessageDataType

NetworkMessage mapping specific WriterGroup parameters. The abstract base type is defined in 6.2.5.6.3. The concrete subtypes are defined in the sections for message mapping specific parameters.

     dataSetWriters

DataSetWriterDataType[]

The DataSetWriters contained in the WriterGroup. The DataSetWriter parameters are defined in 6.2.3.

 

The WriterGroupDataType Structure representation in the AddressSpace is defined in Table 23.

Table 23 – WriterGroupDataType Definition

Attributes

Value

BrowseName

WriterGroupDataType

IsAbstract

False

References

NodeClass

BrowseName

IsAbstract

Subtype of PubSubGroupDataType defined in 0.

 

6.2.5.6.2          WriterGroupTransportDataType

This Structure DataType is an abstract base type for transport mapping specific WriterGroup parameters. The abstract DataType does not define fields.

The WriterGroupTransportDataType Structure representation in the AddressSpace is defined in Table 24.

Table 24 – WriterGroupTransportDataType Definition

Attributes

Value

BrowseName

WriterGroupTransportDataType

IsAbstract

True

References

NodeClass

BrowseName

IsAbstract

Description

Subtype of Structure defined in OPC 10000-5.

HasSubtype

DataType

DatagramWriterGroupTransportDataType

FALSE

Defined in 6.4.1.2.3.

HasSubtype

DataType

BrokerWriterGroupTransportDataType

FALSE

Defined in 6.4.2.2.6.

 

6.2.5.6.3          WriterGroupMessageDataType

This Structure DataType is an abstract base type for message mapping specific WriterGroup parameters. The abstract DataType does not define fields.

The WriterGroupMessageDataType Structure representation in the AddressSpace is defined in Table 25.

Table 25 – WriterGroupMessageDataType Structure

Attributes

Value

BrowseName

WriterGroupMessageDataType

IsAbstract

True

References

NodeClass

BrowseName

IsAbstract

Description

Subtype of Structure defined in OPC 10000-5.

HasSubtype

DataType

UadpWriterGroupMessageDataType

FALSE

Defined in 6.3.1.1.7.

HasSubtype

DataType

JsonWriterGroupMessageDataType

FALSE

Defined in 6.3.2.1.2.

 

6.2.6        PubSubConnection Parameters

6.2.6.1         PublisherId

The PublisherId is a unique identifier for a Publisher within a Message Oriented Middleware. It can be included in sent NetworkMessage for identification or filtering. The value of the PublisherId is typically shared between PubSubConnections but the assignment of the PublisherId is vendor specific.

The PublisherId parameter is only relevant for the Publisher functionality inside a PubSubConnection. The filter setting on the Subscriber side is contained in the DataSetReader parameters.

Valid DataTypes are UInteger and String.

6.2.6.2         TransportProfileUri

The TransportProfileUri parameter with DataType String indicates the transport protocol mapping and the message mapping used.

The possible TransportProfileUri values are defined as URI of the transport protocols defined as PubSub transport Facet in OPC 10000-7.

6.2.6.3         Address

The Address parameter contains the network address information for the communication middleware. The different Structure DataTypes used to represent the Address are defined in 6.2.6.5.3.

6.2.6.4         ConnectionProperties

The ConnectionProperties parameter is an array of DataType KeyValuePair specifies additional properties for the configured connection. The KeyValuePair type is defined in OPC 10000-5 and consists of a QualifiedName and a value of BaseDataType.

The mapping of the namespace, name, and value to concrete functionality may be defined by transport protocol mappings, future versions of this specification or vendor specific extensions.

6.2.6.5         PubSubConnection Structure

6.2.6.5.1          PubSubConnectionDataType

This Structure DataType is used to represent the configuration parameters for PubSubConnections. The PubSubConnectionDataType is formally defined in Table 26.

Table 26 – PubSubConnectionDataType Structure

Name

Type

Description

PubSubConnectionDataType

Structure

 

     name

String

The name of the PubSubConnection.

     enabled

Boolean

The enabled state of the PubSubConnection.

     publisherId

BaseDataType

Defined in 6.2.6.1.

     transportProfileUri

String

Defined in 6.2.6.2.

     address

NetworkAddressDataType

Defined in 6.2.6.3.

The NetworkAddressDataType is defined in 6.2.6.5.3.

     connectionProperties

KeyValuePair[]

Defined in 6.2.6.4.

     transportSettings

ConnectionTransportDataType

Transport mapping specific PubSubConnection parameters. The abstract base type is defined in 6.2.6.5.2. The concrete subtypes are defined in the sections for transport mapping specific parameters.

     writerGroups

WriterGroupDataType[]

The WriterGroups contained in the PubSubConnection. The WriterGroup is defined in 6.2.5.

     readerGroups

ReaderGroupDataType[]

The ReaderGroups contained in the PubSubConnection. The ReaderGroup is defined in 6.2.7.

 

6.2.6.5.2          ConnectionTransportDataType

This Structure DataType is an abstract base type for transport mapping specific PubSubConnection parameters. The abstract DataType does not define fields.

The ConnectionTransportDataType Structure representation in the AddressSpace is defined in Table 27.

Table 27 – ConnectionTransportDataType Definition

Attributes

Value

BrowseName

ConnectionTransportDataType

IsAbstract

True

References

NodeClass

BrowseName

IsAbstract

Subtype of Structure defined in OPC 10000-5.

 

6.2.6.5.3          NetworkAddressDataType

Subtypes of this abstract Structure DataType are used to represent network address information. The NetworkAddressDataType is formally defined in Table 28.

Table 28 – NetworkAddressDataType Structure

Name

Type

Description

NetworkAddressDataType

Structure

 

     networkInterface

String

The name of the network interface used for the communication relation.

 

The NetworkAddressDataType Structure representation in the AddressSpace is defined in Table 29.

Table 29 – NetworkAddressDataType Definition

Attributes

Value

BrowseName

NetworkAddressDataType

IsAbstract

True

References

NodeClass

BrowseName

IsAbstract

Description

Subtype of Structure defined in OPC 10000-5.

HasSubtype

DataType

NetworkAddressUrlDataType

False

Defined in 6.2.6.5.4.

 

6.2.6.5.4          NetworkAddressUrlDataType

This Structure DataType is used to represent network address information in the form of an URL String. The NetworkAddressUrlDataType is formally defined in Table 30.

Table 30 – NetworkAddressUrlDataType Structure

Name

Type

Description

NetworkAddressUrlDataType

Structure

 

     url

String

The address string for the communication relation in the form on an URL String.

 

The NetworkAddressUrlDataType Structure representation in the AddressSpace is defined in Table 31.

Table 31 – NetworkAddressUrlDataType Definition

Attributes

Value

BrowseName

NetworkAddressUrlDataType

IsAbstract

False

References

NodeClass

BrowseName

IsAbstract

Subtype of NetworkAddressDataType defined in 6.2.6.5.3.

 

6.2.7        ReaderGroup Parameters

6.2.7.1         General

The ReaderGroup does not add parameters to the shared PubSubGroup parameters.

The ReaderGroup is used to group a list of DataSetReaders. It is not symmetric to a WriterGroup and it is not related to a particular NetworkMessage. The NetworkMessage related filter settings are on the DataSetReaders.

6.2.7.2         ReaderGroup Structures

6.2.7.2.1          ReaderGroupDataType

This Structure DataType is used to represent the configuration parameters for ReaderGroups. The ReaderGroupDataType is formally defined in Table 32.

Table 32 – ReaderGroupDataType Structure

Name

Type

Description

ReaderGroupDataType

Structure

 

     transportSettings

ReaderGroupTransportDataType

Transport mapping specific ReaderGroup parameters. The abstract base type is defined in 6.2.7.2.2. The concrete subtypes are defined in the sections for transport mapping specific parameters.

     messageSettings

ReaderGroupMessageDataType

NetworkMessage mapping specific ReaderGroup parameters. The abstract base type is defined in 6.2.7.2.3. The concrete subtypes are defined in the sections for message mapping specific parameters.

     dataSetReaders

DataSetReaderDataType[]

The DataSetReaders contained in the ReaderGroup. The DataSetReader is defined in 6.2.8.

 

The ReaderGroupDataType Structure representation in the AddressSpace is defined in Table 33.

Table 33 – ReaderGroupDataType Definition

Attributes

Value

BrowseName

ReaderGroupDataType

IsAbstract

False

References

NodeClass

BrowseName

IsAbstract

Subtype of PubSubGroupDataType defined in 0.

 

6.2.7.2.2          ReaderGroupTransportDataType

This Structure DataType is an abstract base type for transport mapping specific ReaderGroup parameters. The abstract DataType does not define fields.

The ReaderGroupTransportDataType Structure representation in the AddressSpace is defined in Table 34.

Table 34 – ReaderGroupTransportDataType Definition

Attributes

Value

BrowseName

ReaderGroupTransportDataType

IsAbstract

True

References

NodeClass

BrowseName

IsAbstract

Subtype of Structure defined in OPC 10000-5.

 

6.2.7.2.3          ReaderGroupMessageDataType

This Structure DataType is an abstract base type for message mapping specific ReaderGroup parameters. The abstract DataType does not define fields.

The ReaderGroupMessageDataType Structure representation in the AddressSpace is defined in Table 35.

Table 35 – ReaderGroupMessageDataType Structure

Attributes

Value

BrowseName

ReaderGroupMessageDataType

IsAbstract

True

References

NodeClass

BrowseName

IsAbstract

Subtype of Structure defined in OPC 10000-5.

 

6.2.8        DataSetReader Parameters

6.2.8.1         PublisherId

The parameter PublisherId defines the Publisher to receive NetworkMessages from.

If the value is null, the parameter shall be ignored and all received NetworkMessages pass the PublisherId filter.

Valid DataTypes are UInteger and String.

6.2.8.2         WriterGroupId

The parameter WriterGroupId with DataType UInt16 defines the identifier of the corresponding WriterGroup.

The default value 0 is defined as null value, and means this parameter shall be ignored.

6.2.8.3         DataSetWriterId

The parameter DataSetWriterId with DataType UInt16 defines the DataSet selected in the Publisher for the DataSetReader.

If the value is 0 (null), the parameter shall be ignored and all received DataSetMessages pass the DataSetWriterId filter.

6.2.8.4         DataSetMetaData

The parameter DataSetMetaData provides the information necessary to decode DataSetMessages from the Publisher. If the DataSetMetaData changes in the Publisher and the MajorVersion was changed, the DataSetReader needs an update of the DataSetMetaData for further operation. If the update cannot be retrieved in the duration of the MessageReceiveTimeout, the State of the DataSetReader shall change to Error_3. The related PublishedDataSet is defined in 6.2.2. The DataSetMetaDataType is defined in 6.2.2.1.2. The options for retrieving the update of the DataSetMetaData are described in 5.2.3.

6.2.8.5         DataSetFieldContentMask

The parameter DataSetFieldContentMask with DataType DataSetFieldContentMask indicates the fields of a DataValue included in the DataSetMessages.

The DataSetFieldContentMask DataType is defined in 6.2.3.2.

6.2.8.6         MessageReceiveTimeout

The parameter MessageReceiveTimeout is the maximum acceptable time between two DataSetMessages. If there is no DataSetMessage received within this period, the DataSetReader State shall be changed to Error_3 until the next DataSetMessage is received. The DataSetMessages can be data or keep alive messages.

The MessageReceiveTimeout is related to the Publisher side parameters PublishingInterval, KeepAliveTime and KeyFrameCount.

6.2.8.7         SecurityMode

The parameter is defined in 6.2.4.2.

This parameter overwrites the corresponding setting on the ReaderGroup if the value is not INVALID_0.

6.2.8.8         SecurityGroupId

The parameter is defined in 6.2.4.3.

The parameter shall be null if the SecurityMode is INVALID_0.

6.2.8.9         SecurityKeyServices

The parameter is defined in 6.2.4.4.

The parameter shall be null if the SecurityMode is INVALID_0.

6.2.8.10      DataSetReaderProperties

The DataSetReaderProperties parameter is an array of DataType KeyValuePair that specifies additional properties for the configured DataSetReader. The KeyValuePair DataType is defined in OPC 10000-5 and consists of a QualifiedName and a value of BaseDataType.

The mapping of the name and value to concrete functionality may be defined by transport protocol mappings, future versions of this specification or vendor specific extensions.

6.2.8.11      DataSetReader Structure

6.2.8.11.1       DataSetReaderDataType

This Structure DataType is used to represent the DataSetReader parameters. The DataSetReaderDataType is formally defined in Table 36.

Table 36 – DataSetReaderDataType Structure

Name

Type

Description

DataSetReaderDataType

Structure

 

     name

String

The name of the DataSetReader.

     enabled

Boolean

The enabled state of the DataSetReader.

     publisherId

BaseDataType

Defined in 6.2.8.1.

     writerGroupId

UInt16

Defined in 6.2.8.2.

     dataSetWriterId

UInt16

Defined in 6.2.8.3.

     dataSetMetaData

DataSetMetaDataType

Defined in 6.2.8.4.

     dataSetField‌ContentMask

DataSetFieldContentMask

Defined in 6.2.8.5.

     messageReceiveTimeout

Duration

Defined in 6.2.8.6.

     keyFrameCount

UInt32

 

     headerLayoutUri

String

 

     securityMode

MessageSecurityMode

Defined in 6.2.8.7.

     securityGroupId

String

Defined in 6.2.8.8.

     securityKeyServices

EndpointDescription[]

Defined in 6.2.8.9.

     dataSetReaderProperties

KeyValuePair[]

Defined in 6.2.8.10.

     transportSettings

DataSetReaderTransportDataType

Transport specific DataSetReader parameters. The abstract base type is defined in 6.2.8.11.2. The concrete subtypes are defined in the sections for transport mapping specific parameters

     messageSettings

DataSetReaderMessageDataType

DataSetMessage mapping specific DataSetReader parameters. The abstract base type is defined in 6.2.8.11.3. The concrete subtypes are defined in the sections for message mapping specific parameters.

     subscribedDataSet

SubscribedDataSetDataType

The SubscribedDataSet specific parameters. The abstract base type and the concrete subtypes are defined 6.2.9.

 

6.2.8.11.2       DataSetReaderTransportDataType

This Structure DataType is an abstract base type for transport specific DataSetReader parameters. The DataSetReaderTransportDataType is formally defined in Table 37.

Table 37 – DataSetReaderTransportDataType Structure

Name

Type

Description

DataSetReaderTransportDataType

Structure

 

 

The DataSetReaderTransportDataType Structure representation in the AddressSpace is defined in Table 38.

Table 38 – DataSetReaderTransportDataType Definition

Attributes

Value

BrowseName

DataSetReaderTransportDataType

IsAbstract

True

References

NodeClass

BrowseName

IsAbstract

Description

Subtype of Structure defined in OPC 10000-5.

HasSubtype

DataType

BrokerDataSetReaderTransportDataType

FALSE

Defined in 6.4.2.4.6.

 

6.2.8.11.3       DataSetReaderMessageDataType

This Structure DataType is an abstract base type for message mapping specific DataSetReader parameters. The DataSetReaderMessageDataType is formally defined in Table 39.

Table 39 – DataSetReaderMessageDataType Structure

Name

Type

Description

DataSetReaderMessageDataType

Structure

 

 

The DataSetReaderMessageDataType Structure representation in the AddressSpace is defined in Table 40.

Table 40 – DataSetReaderMessageDataType Definition

Attributes

Value

BrowseName

DataSetReaderMessageDataType

IsAbstract

True

References

NodeClass

BrowseName

IsAbstract

Description

Subtype of Structure defined in OPC 10000-5.

HasSubtype

DataType

UadpDataSetReaderMessageDataType

FALSE

Defined in 6.3.1.3.10.

HasSubtype

DataType

JsonDataSetReaderMessageDataType

FALSE

Defined in 6.3.2.3.3.

 

6.2.9        SubscribedDataSet Parameters

6.2.9.1         SubscribedDataSetDataType

This Structure DataType is an abstract base type for SubscribedDataSet parameters. The SubscribedDataSetDataType is formally defined in Table 41.

Table 41 – SubscribedDataSetDataType Structure

Name

Type

Description

SubscribedDataSetDataType

Structure

 

 

The SubscribedDataSetDataType Structure representation in the AddressSpace is defined in Table 42.

Table 42 – SubscribedDataSetDataType Definition

Attributes

Value

BrowseName

SubscribedDataSetDataType

IsAbstract

True

References

NodeClass

BrowseName

IsAbstract

Description

Subtype of Structure defined in OPC 10000-5.

HasSubtype

DataType

TargetVariablesDataType

FALSE

Defined in 6.2.9.2.2.

HasSubtype

DataType

SubscribedDataSetMirrorDataType

FALSE

Defined in 6.2.9.3.3.

 

6.2.9.2         TargetVariables

6.2.9.2.1          General

The SubscribedDataSet option TargetVariables defines a list of Variable mappings between received DataSet fields and target Variables in the Subscriber AddressSpace. The FieldTargetDataType is defined in 6.2.9.2.3. Target Variables shall only be used once within the same TargetVariables list.

6.2.9.2.2          TargetVariablesDataType

This Structure DataType is used to represent TargetVariables specific parameters. It is a subtype of the SubscribedDataSetDataType defined in 6.2.9.1.

The TargetVariablesDataType is formally defined in Table 43.

Table 43 – TargetVariablesDataType Structure

Name

Type

Description

TargetVariablesDataType

Structure

 

     targetVariables

FieldTargetDataType[]

Defined in 6.2.9.2.1.

 

6.2.9.2.3          FieldTargetDataType

This DataType is used to provide the metadata for the relation between a field in a DataSetMessage and a target Variable in a DataSetReader. The FieldTargetDataType is formally defined in Table 44.

Table 44 – FieldTargetDataType Structure

Name

Type

Description

FieldTargetDataType

Structure

 

     dataSetFieldId

Guid

The unique ID of the field in the DataSet. The fields and their unique IDs are defined in the DataSetMetaData Structure.

     receiverIndexRange

NumericRange

Index range used to extract parts of an array out of the received data.

It is used to identify a single element of an array, or a single range of indexes for arrays for the received DataSet field. If a range of elements is specified, the values are returned as a composite. The first element is identified by index 0 (zero). The NumericRange type is defined in OPC 10000-4.

This parameter is null if the specified Attribute is not an array. However, if the specified Attribute is an array, and this parameter is null, then the complete array is used.

The resulting data array size of this NumericRange shall match the resulting data array size of the writeIndexRange NumericRange setting.

     targetNodeId

NodeId

The NodeId of the Variable where to write the received DataSetMessage field value to.

     attributeId

IntegerId

Id of the Attribute to write e.g. the Value Attribute. This shall be a valid AttributeId.

The Attributes are defined in OPC 10000-3. The IntegerId DataType is defined in OPC 10000-4. The IntegerIds for the Attributes are defined in OPC 10000-6.

     writeIndexRange

NumericRange

The index range used for writing received data to the target node.

It is used to identify a single element of an array, or a single range of indexes for arrays for the write operation to the target Node. If a range of elements is specified, the values are written as a composite. The first element is identified by index 0 (zero). The NumericRange type is defined in OPC 10000-4.

This parameter is null if the specified Attribute is not an array. However, if the specified Attribute is an array, and this parameter is null, then the complete array is used.

     overrideValueHandling

OverrideValueHandling

The value is used to define the override value handling behaviour if the State of the DataSetReader is not Operational_2 or if the corresponding field in the DataSet contains a Bad StatusCode.

The handling of the OverrideValue in different scenarios is defined in 6.2.10.

The OverrideValueHandling enumeration DataType is defined in 6.2.9.2.4.

     overrideValue

Variant

This value is used if the OverrideValueHandling is set to OverrideValue_2 and the State of the DataSetReader is not Operational_2 or if the corresponding field in the DataSet contains a Bad StatusCode.

The handling of the OverrideValue in different scenarios is defined in 6.2.10.

This Value shall match the DataType of the target Node.

 

6.2.9.2.4          OverrideValueHandling

The OverrideValueHandling is an enumeration that specifies the possible options for the handling of Override values. The possible enumeration values are described in Table 45.

Table 45 – OverrideValueHandling Values

Value

Description

Disabled_0

The override value handling is disabled.

LastUsableValue_1

In the case of an error, the last usable value is used. If no last useable value is available, the default value for the data type is used.

OverrideValue_2

In the case of an error, the configured override value is used.

 

6.2.9.3         SubscribedDataSetMirror

6.2.9.3.1          ParentNodeName

This parameter with DataType String defines the BrowseName and DisplayName of the parent Node for the Variables representing the fields of the subscribed DataSet.

6.2.9.3.2          RolePermissions

This parameter with DataType RolePermissionType defines the value of the RolePermissions Attribute to be set on the parent Node. This value is also used as RolePermissions for all Variables of the DataSet mirror.

6.2.9.3.3          SubscribedDataSetMirrorDataType

This Structure DataType is used to represent SubscribedDataSetMirror specific parameters. It is a subtype of the SubscribedDataSetDataType defined in 6.2.9.1.

The SubscribedDataSetMirrorDataType is formally defined in Table 46.

Table 46 – SubscribedDataSetMirrorDataType Structure

Name

Type

Description

SubscribedDataSetMirrorDataType

Structure

 

     parentNodeName

String

Defined in 6.2.9.3.1.

     rolePermissions

RolePermissionType[]

Defined in 6.2.9.3.2.

 

6.2.10      Information flow and status handling

The configuration model defines different parameters that influence the information flow from Publisher to Subscriber in the case of a Bad Value Status or other error situations. Figure 22 depicts the parameters and the information flow inside a Publisher and inside a Subscriber.

The parameters and behaviour relevant for the encoding of a DataSetMessage on the Publisher side and the decoding of the DataSetMessage on the Subscriber side are defined in 6.2.3.1 together with the DataSetFieldContentMask.

Figure25_

Figure 22 – PubSub Information Flow

The mapping of source value and status to the DataSet in the Publisher depends on the substitute value. The dependencies are defined in Table 47.

Table 47 – Source to message input mapping

Source

Substitute

Value

DataSet Publisher side

Value

Status(1)

Value

Status(1)

Value 1

Good_*

Value 2

 

Value 1

Good_*

Value 1

Uncertain_*

Value 1

Uncertain_*

Null

Bad_*

Value 2

Uncertain_SubstituteValue

Value 1

Good_*

Null

Value 1

Good_*

Value 1

Uncertain_*

Value 1

Uncertain_*

Null

Bad_*

Null

Bad_*

Note 1:    If no specific StatusCode is used, the grouping into severity Good, Uncertain or Bad is used.
               In this case, the resulting Status matches the input Status.

 

The mapping of the decoded DataSet on the Subscriber side to the value and status of the target Variable depends on the override value. The dependencies are defined in Table 48.

Table 48 – Message output to target mapping

Decoded DataSet Subscriber

Override Value Handling Enum

Override

Value

Reader

State

Target

Value

Status(1)

Value

Status(1)

Value 1

Good_*

OverrideValue_2

 

Value 2

Operational_2

Value 1

Good_*

Value 1

Uncertain_*

Value 1

Uncertain_*

Null

Bad_*

Value 2

Good_LocalOverride

Value 1

Good_*

LastUsableValue_1

Null

Value 1

Good_*

Value 1

Uncertain_*

Value 1

Uncertain_*

Null

Bad_*

LastValue(2)

Uncertain_LastUsableValue

Value 1

Good_*

Disabled_0

Null

Value 1

Good_*

Value 1

Uncertain_*

Value 1

Uncertain_*

Null

Bad_*

Null

Bad_*

No message received.

The target values are updated once after a reader state change.

OverrideValue_2

Value 2

Diabled_0

Paused_1

Value 2

Good_LocalOverride

LastUsableValue_1

Null

LastValue(2)

Uncertain_LastUsableValue

Disabled_0

Null

Null

Bad_OutOfService

OverrideValue_2

Value 2

Error_3

Value 2

Good_LocalOverride

LastUsableValue_1

Null

LastValue(2)

Uncertain_LastUsableValue

Disabled_0

Null

Null

Bad_NoCommunication

Note 1:    If no specific StatusCode is used, the grouping into severity Good, Uncertain or Bad is used.
               In this case, the resulting Status matches the input Status.

Note 2:    The last value is either the last received value or the default value for the data type if there was never a value                    received before.

 

6.2.11      PubSubConfigurationDataType

This Structure DataType is used to represent the PubSub configuration of an OPC UA Application. The PubSubConfigurationDataType is formally defined in Table 49.

Table 49 – PubSubConfigurationDataType Structure

Name

Type

Description

PubSubConfigurationDataType

Structure

 

     publishedDataSets

PublishedDataSetDataType[]

The PublishedDataSets contained in the configuration. The PublishedDataSet is defined in 6.2.2.

     connections

PubSubConnectionDataType[]

The PubSubConnections contained in the configuration. The PubSubConnection is defined in 6.2.6.

The connection includes WriterGroups and ReaderGroups.

     enabled

Boolean

The enabled state of the PubSub configuration.

 

If the PubSub configuration is stored in a file, the UABinaryFileDataType and the related definitions in A.2 shall be used to encode the file content. The values of the UABinaryFileDataType structure are described in Table 50.

Table 50 – PubSubConfiguration File Content

Field

Type

Value

namespaces

String[]

null

The DataTypes used for configuration are defined in the OPC UA namespace.

structureDataTypes

StructureDescription[]

null

DataTypes used for configuration are defined by OPC UA.

enumDataTypes

EnumDescription[]

null

DataTypes used for configuration are defined by OPC UA.

simpleDataTypes

SimpleTypeDescription[]

null

DataTypes used for configuration are defined by OPC UA.

schemaLocation

String

null

fileHeader

KeyValuePair[]

null

body

BaseDataType

PubSubConfigurationDataType Structure

The PubSub configuration represented by the PubSubConfigurationDataType.

 

6.3       Message Mapping Configuration Parameters

6.3.1        UADP Message Mapping

6.3.1.1         UADP NetworkMessage Writer

6.3.1.1.1          Relationship of Timing Parameters

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 PublishsingInterval 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 23 shows an example how to select the possible start of a PublishingInterval.

Figure26_

Figure 23 – Start of the periodic publisher execution

The different timing offsets inside a PublishingInterval cycle on Publisher and Subscriber side are shown in Figure 24. 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.3.

Figure27_

Figure 24 – Timing offsets in a PublishingInterval

6.3.1.1.2          GroupVersion

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

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

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

Table 51 – DataSetOrderingType Values

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_0 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_1 the Publisher has to 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 25.

Figure28_

Figure 25 – DataSetOrdering and MaxNetworkMessageSize

6.3.1.1.4          NetworkMessageContentMask

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

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

DataSetClassId

9

The DataSetClassId is included in the NetworkMessages.

PromotedFields

10

The PromotedFields are included in the NetworkMessages.

 

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

Table 53 – UadpNetworkMessageContentMask Definition

Attributes

Value

BrowseName

UadpNetworkMessageContentMask

IsAbstract

False

References

NodeClass

BrowseName

DataType

Subtype of UInt32 defined in OPC 10000-5.

HasProperty

Variable

OptionSetValues

LocalizedText [ ]

 

6.3.1.1.5          SamplingOffset

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

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.

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

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

Figure29_

Figure 26 – 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 are 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

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

The UadpWriterGroupMessageDataType is formally defined in Table 54.

Table 54 – UadpWriterGroupMessageDataType Structure

Name

Type

Description

UadpWriterGroupMessageDataType

Structure

 

     groupVersion

UInt32

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.

 

6.3.1.2         UADP DataSetMessage Writer

6.3.1.2.1          General

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 1: 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.2.2          DataSetMessageContentMask

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

Table 55 – 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 HeaderTimestamp 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 16.

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

Table 56 – UadpDataSetMessageContentMask Definition

Attributes

Value

BrowseName

UadpDataSetMessageContentMask

IsAbstract

False

References

NodeClass

BrowseName

DataType

Subtype of UInt32 defined in OPC 10000-5.

HasProperty

Variable

OptionSetValues

LocalizedText [ ]

 

6.3.1.2.3          ConfiguredSize

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 1 to entry: 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.2.4          NetworkMessageNumber

The parameter NetworkMessageNumber with the DataType UInt16 is a read-only parameter set by the Publisher in the case of a fixed NetworkMessage layout. The default value is 0 and indicates that the position of the DataSetMessage in a NetworkMessage is not fixed.

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

The parameter DataSetOffset with the DataType UInt16 is a read-only parameter set by the Publisher that specifies 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.

6.3.1.2.6          UadpDataSetWriterMessageDataType Structure

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

The UadpDataSetWriterMessageDataType is formally defined in Table 57.

Table 57 – UadpDataSetWriterMessageDataType Structure

Name

Type

Description

UadpDataSetWriterMessageDataType

Structure

 

     dataSetMessageContentMask

UadpDataSetMessageContentMask

Defined in 6.3.1.2.2.

     configuredSize

UInt16

Defined in 6.3.1.2.3.

     networkMessageNumber

UInt16

Defined in 6.3.1.2.4.

     dataSetOffset

UInt16

Defined in 6.3.1.2.5.

 

6.3.1.3         UADP DataSetMessage Reader

6.3.1.3.1          GroupVersion

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

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.

6.3.1.3.3          DataSetOffset

The parameter DataSetOffset with DataType UInt16 defines the offset for the DataSetMessage inside the corresponding NetworkMessage. The default value 0 is defined as null value, and means this parameter shall be ignored.

6.3.1.3.4          DataSetClassId

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.3.5          Network‌Message‌ContentMask

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.3.6          DataSetMessage‌ContentMask

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

The UadpDataSetMessageContentMask DataType is defined in 6.3.1.2.2.

6.3.1.3.7          PublishingInterval

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

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.

6.3.1.3.9          ProcessingOffset

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

The different timing offsets inside a PublishingInterval cycle on Publisher and Subscriber side are shown in Figure 24.

6.3.1.3.10       UadpDataSetReaderMessageDataType

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

The UadpDataSetReaderMessageDataType is formally defined in Table 58.

Table 58 – UadpDataSetReaderMessageDataType Structure

Name

Type

Description

UadpDataSetReaderMessageDataType

Structure

 

     groupVersion

VersionTime

Defined in 6.3.1.3.1.

     networkMessageNumber

UInt16

Defined in 6.3.1.3.2.

     dataSetOffset

UInt16

Defined in 6.3.1.3.3.

     dataSetClassId

Guid

Defined in 6.3.1.3.4.

     network‌Message‌ContentMask

UadpNetworkMessageContentMask

Defined in 6.3.1.3.5.

     dataSetMessage‌ContentMask

UadpDataSetMessageContentMask

Defined in 6.3.1.3.6.

     publishingInterval

Duration

Defined in 6.3.1.3.7.

     receiveOffset

Duration

Defined in 6.3.1.3.8.

     processingOffset

Duration

Defined in 6.3.1.3.9.

 

6.3.2        JSON Message Mapping

6.3.2.1         JSON NetworkMessage Writer

6.3.2.1.1          NetworkMessageContentMask

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

The DataType JsonNetworkMessageContentMask is formally defined in Table 59.

Table 59 – JsonNetworkMessageContentMask Values

Value

Bit No.

Description

NetworkMessageHeader

0

The JSON NetworkMessage header is included in the NetworkMessages.

If this bit is false, bits 2 to 4 shall be 0.

DataSetMessageHeader

1

The JSON DataSetMessage header is included in each DataSetMessage.

If this bit is false then the DataSetMessageContentMask for the DataSetWriters are ignored (see 6.3.2.2.1).

SingleDataSetMessage

2

Each JSON NetworkMessage contains only one DataSetMessage.

PublisherId

3

The PublisherId is included in the NetworkMessages.

DataSetClassId

4

The DataSetClassId is included in the NetworkMessages.

ReplyTo

5

The ReplyTo is included in the NetworkMessages.

 

The JsonNetworkMessageContentMask representation in the AddressSpace is defined in Table 60.

Table 60 – JsonNetworkMessageContentMask Definition

Attributes

Value

BrowseName

JsonNetworkMessageContentMask

IsAbstract

False

References

NodeClass

BrowseName

DataType

Subtype of UInt32 defined in OPC 10000-5.

HasProperty

Variable

OptionSetValues

LocalizedText [ ]

 

6.3.2.1.2          JsonWriterGroupMessageDataType Structure

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

The JsonWriterGroupMessageDataType is formally defined in Table 61.

Table 61 – JsonWriterGroupMessageDataType Structure

Name

Type

Description

JsonWriterGroupMessageDataType

Structure

 

     networkMessageContentMask

JsonNetworkMessageContentMask

Defined in 6.3.2.1.1.

 

6.3.2.2         JSON DataSetMessage Writer

6.3.2.2.1          DataSetMessageContentMask

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

The JsonDataSetMessageContentMask DataType is formally defined in Table 62.

Table 62 – JsonDataSetMessageContentMask Values

Value

Bit No.

Description

DataSetWriterId

0

If this flag is set, a DataSetWriterId shall be included in the DataSetMessage header.

MetaDataVersion

1

If this flag is set, the ConfigurationVersion is included in the DataSetMessage header.

SequenceNumber

2

If this flag is set, the DataSetMessageSequenceNumber is included in the DataSetMessage header.

Timestamp

3

If this flag is set, a timestamp shall be included in the DataSetMessage header.

Status

4

If this flag is set, an overall status is included in the DataSetMessage header.

 

The JsonDataSetMessageContentMask representation in the AddressSpace is defined in Table 63.

Table 63 – JsonDataSetMessageContentMask Definition

Attributes

Value

BrowseName

JsonDataSetMessageContentMask

IsAbstract

False

References

NodeClass

BrowseName

DataType

Subtype of UInt32 defined in OPC 10000-5.

HasProperty

Variable

OptionSetValues

LocalizedText [ ]

 

6.3.2.2.2          JsonDataSetWriterMessageDataType Structure

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

The JsonDataSetWriterMessageDataType is formally defined in Table 64.

Table 64 – JsonDataSetWriterMessageDataType Structure

Name

Type

Description

JsonDataSetWriterMessageDataType

Structure

 

     dataSetMessageContentMask

JsonDataSetMessageContentMask

Defined in 6.3.2.2.1.

 

6.3.2.3         JSON DataSetMessage Reader

6.3.2.3.1          Network‌Message‌ContentMask

The NetworkMessageContentMask with DataType JsonNetworkMessageContentMask indicates the optional header fields included in the received NetworkMessages. The JsonNetworkMessageContentMask DataType is defined in 6.3.2.1.1.

6.3.2.3.2          DataSetMessage‌ContentMask

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

The JsonDataSetMessageContentMask DataType is defined in 6.3.2.2.1.

6.3.2.3.3          JsonDataSetReaderMessageDataType Structure

This Structure DataType is used to represent JSON DataSetMessage mapping specific DataSetReader parameters. It is a subtype of the DataSetReaderMessageDataType defined in 6.2.8.11.3.

The JsonDataSetReaderMessageDataType is formally defined in Table 65.

Table 65 – JsonDataSetReaderMessageDataType Structure

Name

Type

Description

JsonDataSetReaderMessageDataType

Structure

 

     networkMessageContentMask

JsonNetworkMessageContentMask

Defined in 6.3.2.3.1.

     dataSetMessageContentMask

JsonDataSetMessageContentMask

Defined in 6.3.2.3.2.

 

6.4       Transport Protocol Mapping Configuration Parameters

6.4.1        Datagram Transport Protocol

6.4.1.1         Datagram PubSubConnection

6.4.1.1.1          DiscoveryAddress

The DiscoveryAddress parameter contains the network address information used for the discovery request and response messages. The different Structure DataTypes used to represent the Address are defined in 6.2.6.5.3.

6.4.1.1.2          DatagramConnectionTransportDataType Structure

This Structure DataType is used to represent the configuration parameters for the Datagram transport protocol specific settings of PubSubConnections. It is a subtype of the ConnectionTransportDataType defined in 6.2.6.4.

The DatagramConnectionTransportDataType is formally defined in Table 66.

Table 66 – DatagramConnectionTransportDataType Structure

Name

Type

Description

DatagramConnectionTransportDataType

Structure

 

     discoveryAddress

NetworkAddressDataType

Defined in 6.4.1.1.1.

The NetworkAddressDataType is defined in 6.2.6.5.3.

 

6.4.1.2         Datagram WriterGroup

6.4.1.2.1          MessageRepeatCount

The MessageRepeatCount with DataType Byte defines how many times every NetworkMessage is repeated. The default value is 0 and disables the repeating.

6.4.1.2.2          MessageRepeatDelay

The MessageRepeatDelay with DataType Duration defines the time between NetworkMessage repeats in milliseconds. The parameter shall be ignored if the parameter MessageRepeatCount is set to 0.

6.4.1.2.3          DatagramWriterGroupTransportDataType Structure

This Structure DataType is used to represent the datagram specific transport mapping parameters for WriterGroups. It is a subtype of the WriterGroupTransportDataType defined in 6.2.5.6.2.

The DatagramWriterGroupTransportDataType is formally defined in Table 67.

Table 67 – DatagramWriterGroupTransportDataType Structure

Name

Type

Description

DatagramWriterGroupTransportDataType

Structure

 

     messageRepeatCount

Byte

Defined in 6.4.1.2.1.

     messageRepeatDelay

Duration

Defined in 6.4.1.2.2.

 

6.4.1.3         Datagram DataSetWriter Parameters

There are no datagram specific transport mapping parameters defined for the DataSetWriter.

6.4.1.4         Datagram DataSetReader

There are no datagram specific transport mapping parameters defined for the DataSetReader.

6.4.2        Broker Transport Protocol

6.4.2.1         Broker PubSubConnection

6.4.2.1.1          ResourceUri

The ResourceUri parameter of DataType String enables the transport implementation to look up a configured key from the corresponding KeyCredentialConfigurationType instance defined in OPC 10000-12 to use for authenticating access to the broker at the connection level or for queues configured below the connection.

If null, no authentication or anonymous authentication shall be assumed as default unless authentication settings are provided on a subordinated WriterGroup or a DataSetWriter to authenticate access to individual queues.

6.4.2.1.2          AuthenticationProfileUri

The parameter AuthenticationProfileUri of DataType String allows the selection of the authentication protocol used by the transport implementation. This maps to the ProfileUri Property in the KeyCredentialConfigurationType instance selected through the ResourceUri and AuthenticationProfileUri Strings.

This parameter is optional. If more than one ProfileUri describing the protocol to use for authentication is configured and this value is null, the transport will choose one. If the transport cannot fine a suitable authentication mechanism in the ProfileUri array, the transport sets the State of the PubSubConnection is set to Error_3.

6.4.2.1.3          BrokerConnectionTransportDataType Structure

This Structure DataType is used to represent the Broker specific transport mapping parameters for the PubSubConnection. It is a subtype of the ConnectionTransportDataType defined in 6.2.6.4.

The BrokerConnectionTransportDataType is formally defined in Table 68.

Table 68 – BrokerConnectionTransportDataType Structure

Name

Type

Description

BrokerConnectionTransportDataType

Structure

 

     resourceUri

String

Defined in 6.4.2.1.1.

     authenticationProfileUri

String

Defined in 6.4.2.1.2.

 

6.4.2.2         Broker WriterGroup

6.4.2.2.1          QueueName

The QueueName parameter with DataType String specifies the queue in the Broker that receives NetworkMessages sent by the Publisher. This could be the name of a queue or topic defined in the Broker.

6.4.2.2.2          ResourceUri

The ResourceUri property of DataType String allows the transport implementation to look up the configured key from the corresponding KeyCredentialConfigurationType instance defined in OPC 10000-12 to use for authenticating access to the specified queue.

If this String is not null, it overrides the ResourceUri of the PubSubConnection authentication settings.

6.4.2.2.3          AuthenticationProfileUri

The parameter AuthenticationProfileUri of DataType String allows the selection of the authentication protocol used by the transport implementation for authenticating access to the specified queue.

If this String is not null, it overrides the AuthenticationProfileUri of the PubSubConnection transport settings defined in 6.4.2.1.2.

6.4.2.2.4          RequestedDeliveryGuarantee

The RequestedDeliveryGuarantee parameter with DataType BrokerTransportQualityOfService specifies the delivery guarantees that shall apply to all NetworkMessages published by the WriterGroup unless otherwise specified on the DataSetWriter transport settings. The DataType BrokerTransportQualityOfService is defined in 6.4.2.2.5.

The value NotSpecified_0 is not allowed on the WriterGroup. If the selected delivery guarantee cannot be applied, the WriterGroup shall set the state to Error_3.

6.4.2.2.5          BrokerTransportQualityOfService Enumeration

The BrokerTransportQualityOfService Enumeration DataType is formally defined in Table 71.

The mapping of quality of service to the broker transport specific implementation is defined in 7.3.4.5 for AMQP and 7.3.5.5 for MQTT.

Table 69 – BrokerTransportQualityOfService Values

Value

Description

NotSpecified_0

The value is not specified and the value of the parent object shall be used.

BestEffort_1

The transport shall make the best effort to deliver a message. Worst case this means data loss or data duplication are possible.

AtLeastOnce_2

The transport guarantees that the message shall be delivered at least once, but duplication is possible. Readers must de-duplicate based on message id or sequence number.

AtMostOnce_3

The transport guarantees that the message shall be sent once, but if it is lost it is not sent again.

ExactlyOnce_4

The transport handshake guarantees that the message shall be delivered to the broker exactly once and not more or less.

 

6.4.2.2.6          BrokerWriterGroupTransportDataType Structure

This Structure DataType is used to represent the Broker specific transport mapping parameters for WriterGroups. It is a subtype of the WriterGroupTransportDataType defined in 6.2.5.6.2.

The BrokerWriterGroupTransportDataType is formally defined in Table 70.

Table 70 – BrokerWriterGroupTransportDataType Structure

Name

Type

Description

BrokerWriterGroupTransportDataType

Structure

 

     queueName

String

Defined in 6.4.2.2.1.

     resourceUri

String

Defined in 6.4.2.2.2.

     authenticationProfileUri

String

Defined in 6.4.2.2.3.

     requestedDeliveryGuarantee

BrokerTransportQualityOfService

Defined in 6.4.2.2.4.

 

6.4.2.3         Broker DataSetWriter

6.4.2.3.1          QueueName

The QueueName parameter with DataType String specifies the queue in the Broker that receives NetworkMessages sent by the Publisher for the DataSetWriter. This could be the name of a queue or topic defined in the Broker. This parameter is only valid if the NetworkMessages from the WriterGroup contain only one DataSetMessage.

If this String is not null, it overrides the QueueName of the WriterGroup transport settings.

6.4.2.3.2          ResourceUri

The ResourceUri property of DataType String allows the transport implementation to look up the configured key from the corresponding KeyCredentialConfigurationType instance defined in OPC 10000-12 to use for authenticating access to the specified queue.

If this String is not null, it overrides the ResourceUri of the WriterGroup authentication settings.

6.4.2.3.3          AuthenticationProfileUri

The parameter AuthenticationProfileUri of DataType String allows the selection of the authentication protocol used by the transport implementation for authenticating access to the specified queue.

If this String is not null, it overrides the AuthenticationProfileUri of the WriterGroup transport settings.

6.4.2.3.4          RequestedDeliveryGuarantee

The RequestedDeliveryGuarantee parameter with DataType BrokerTransportQualityOfService specifies the delivery guarantees that shall apply to all messages published by the DataSetWriter. The DataType BrokerTransportQualityOfService is defined in 6.4.2.2.5.

If the value is not NotSpecified_0, it overrides the RequestedDeliveryGuarantee of the WriteGroup transport settings.

If the selected delivery guarantee cannot be applied, the DataSetWriter shall set the state to Error_3.

6.4.2.3.5          MetaDataQueueName

For message mappings like UADP, the Subscriber needs access to the DataSetMetaData to process received DataSetMessages. The Publisher can provide the DataSetMetaData through a dedicated queue.

The parameter MetaDataQueueName with the DataType String specifies the Broker queue that receives messages with DataSetMetaData sent by the Publisher for this DataSetWriter. This could be the name of a queue or topic defined in the Broker.

6.4.2.3.6          MetaDataUpdateTime

Specifies the interval in milliseconds with Data Type Duration at which the Publisher shall send the DataSetMetaData to the MetaDataQueueName. A value of 0 or any negative value shall be interpreted as infinite interval.

The broker transport shall publish all messages with an expiration time that is equal or greater than this value.

If the update time is infinite, a broker transport shall attempt to negotiate message retention if possible. In this case the DataSetMetaData is only sent if the ConfigurationVersion of the corresponding DataSetMetaData is changed and DataSetWriters shall try to negotiate AtLeastOnce_2 or ExactlyOnce_4 delivery guarantees with the broker for any DataSetMetaData sent to ensure meta data is available to readers.

The DataSetWriterProperties settings apply also to DataSetMetaData sent to the queue named through the MetaDataQueueName parameter.

6.4.2.3.7          BrokerDataSetWriterTransportDataType Structure

This Structure DataType is used to represent the Broker specific transport mapping parameters for DataSetWriters. It is a subtype of the DataSetWriterTransportDataType defined in 6.2.3.5.2.

The BrokerDataSetWriterTransportDataType is formally defined in Table 71.

Table 71 – BrokerDataSetWriterTransportDataType Structure

Name

Type

Description

BrokerDataSetWriterTransportDataType

Structure

 

     queueName

String

Defined in 6.4.2.3.1.

     resourceUri

String

Defined in 6.4.2.3.2.

     authenticationProfileUri

String

Defined in 6.4.2.3.3.

     requestedDeliveryGuarantee

BrokerTransportQualityOfService

Defined in 6.4.2.3.4.

     metaDataQueueName

String

Defined in 6.4.2.3.5.

     metaDataUpdateTime

Duration

Defined in 6.4.2.3.6.

 

6.4.2.4         Broker DataSetReader

6.4.2.4.1          QueueName

The QueueName parameter with DataType String specifies the queue in the Broker where the DataSetReader can receive NetworkMessages with the DataSet of interest sent by the Publisher. This could be the name of a queue or topic defined in the Broker. This parameter is only valid if the NetworkMessages from the WriterGroup contain only one DataSetMessage.

6.4.2.4.2          ResourceUri

The ResourceUri property of DataType String allows the transport implementation to look up the configured key from the corresponding KeyCredentialConfigurationType instance defined in OPC 10000-12 to use for authenticating access to the specified queue.

If this String is not null, it overrides the ResourceUri of the PubSubConnection authentication settings.

6.4.2.4.3          AuthenticationProfileUri

The parameter AuthenticationProfileUri of DataType String allows the selection of the authentication protocol used by the transport implementation for authenticating access to the specified queue.

If this String is not null, it overrides the AuthenticationProfileUri of the PubSubConnection transport settings defined in 6.4.2.1.2.

6.4.2.4.4          RequestedDeliveryGuarantee

The RequestedDeliveryGuarantee parameter with DataType BrokerTransportQualityOfService specifies the delivery guarantees the DataSetReader negotiates with the broker for all messages received. The DataType BrokerTransportQualityOfService is defined in 6.4.2.2.5.

The value NotSpecified_0 is not allowed on the DataSetReader. If the selected delivery guarantee cannot be applied, the DataSetReader shall set the state to Error_3.

6.4.2.4.5          MetaDataQueueName

The parameter MetaDataQueueName with the DataType String specifies the Broker queue that provides messages with DataSetMetaData sent by the Publisher for the DataSet of interest. This could be the name of a queue or topic defined in the Broker.

6.4.2.4.6          BrokerDataSetReaderTransportDataType Structure

This Structure DataType is used to represent the Broker specific transport mapping parameters for DataSetWriters. It is a subtype of the DataSetReaderTransportDataType defined in 6.2.8.11.2.

The BrokerDataSetReaderTransportDataType is formally defined in Table 72.

Table 72 – BrokerDataSetReaderTransportDataType Structure

Name

Type

Description

BrokerDataSetReaderTransportDataType

Structure

 

     queueName

String

Defined in 6.4.2.4.1.

     resourceUri

String

Defined in 6.4.2.4.2.

     authenticationProfileUri

String

Defined in 6.4.2.4.3.

     requestedDeliveryGuarantee

BrokerTransportQualityOfService

Defined in 6.4.2.4.4.

     metaDataQueueName

String

Defined in 6.4.2.4.5.

 


 

7       PubSub Mappings

7.1       General

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.

7.2       Message Mappings

7.2.1        General

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.

7.2.2        UADP Message Mapping

7.2.2.1         General

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.

7.2.2.2         NetworkMessage

7.2.2.2.1          General

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.

Figure30_

Figure 27 – UADP NetworkMessage

7.2.2.2.2          NetworkMessage Layout

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

     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

     1xx Reserved

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