OPC UA Specification
OPC 10000-8
OPC Unified Architecture Part 8: Data Access     Release 1.05.04 2024-10-15

 

 

 

CONTENTS

 

1      Scope. 1

2      Normative references. 1

3      Terms, definitions and abbreviated terms. 1

3.1       Terms and definitions. 1

3.2       Abbreviated terms. 2

4      Concepts. 2

5      Model 4

5.1       General 4

5.2       SemanticsChanged. 4

5.3       Variable Types. 4

5.3.1        DataItemType. 4

5.3.2        AnalogItem VariableTypes. 5

5.3.3        DiscreteItemType. 8

5.3.4        ArrayItemType. 10

5.4       Address Space model 15

5.5       Attributes of DataItems. 16

5.6       DataTypes. 17

5.6.1        Overview. 17

5.6.2        Range. 17

5.6.3        EUInformation. 17

5.6.4        ComplexNumberType. 19

5.6.5        DoubleComplexNumberType. 20

5.6.6        AxisInformation. 20

5.6.7        AxisScaleEnumeration. 21

5.6.8        XVType. 21

6      Quantities and Units model 23

6.1       General 23

6.2       Quantities entry point 23

6.3       Syntax References. 23

6.3.1        General 23

6.3.2        Using Dictionary References. 24

6.3.3        Syntax Reference Identifier 25

6.4       ObjectTypes. 26

6.4.1        QuantityType ObjectType definition. 26

6.4.2        UnitType and subtypes. 28

6.4.3        SyntaxReferenceEntryType ObjectType definition. 31

6.5       References. 32

6.5.1        HasEngineeringUnitDetails. 32

6.5.2        HasQuantity. 32

6.6       DataTypes. 33

6.6.1        AnnotationDataType DataType definition. 33

6.6.2        LinearConversionDataType DataType definition. 33

6.6.3        ConversionLimitEnum.. 34

6.6.4        QuantityDimension. 35

7      Data Access specific usage of Services. 37

7.1       General 37

7.2       PercentDeadband. 37

7.3       Data Access status codes. 37

7.3.1        Overview. 37

7.3.2        Operation level result codes. 37

7.3.3        LimitBits. 39

Annex A (normative)  OPC COM DA to UA mapping. 40

A.1      Introduction. 40

A.2      Security Considerations. 40

A.3      COM UA wrapper for OPC DA Server 41

A.3.1        Information Model mapping. 41

A.3.2        Data and error mapping. 44

A.3.3        Read data. 47

A.3.4        Write Data. 48

A.3.5        Subscriptions. 49

A.4      COM UA proxy for DA Client 49

A.4.1        Guidelines. 49

A.4.2        Information Model and Address Space mapping. 49

A.4.3        Data and error mapping. 53

A.4.4        Read data. 56

A.4.5        Write data. 57

A.4.6        Subscriptions. 57

Annex B (normative)  UCUM Symbols. 59

B.1      Introduction - License. 59

B.2      Representation. 59

B.3      Tables of terminal symbols. 60

B.3.1        General 60

B.3.2        Prefixes. 60

B.3.3        Base units. 61

B.3.4        Derived unit atoms. 61

B.3.5        Customary unit atoms. 64

B.3.6        Other legacy units. 68

Annex C (informative)  Outline of Syntax References. 72

C.1      UCUM syntax reference. 72

C.2      QUDT syntax reference. 72

C.3      UNECE syntax reference. 73

C.4      IEC CDD syntax reference. 74

C.5      LATEX_SIUNITX syntax reference. 75

Bibliography. 76

 

FIGURES

 

Figure 1 – OPC DataItems are linked to automation data............................ 3

Figure 2 – DataItem VariableType hierarchy............................................. 4

Figure 3 – Graphical view of a YArrayItem.............................................. 12

Figure 4 – Representation of DataItems in the AddressSpace.................... 16

Figure 5 – Enhanced EUInformation example.......................................... 18

Figure 6 – Quantity model overview...................................................... 23

Figure 7 – References to external works................................................ 25

Figure 8 – QuantityType..................................................................... 26

Figure 9 – Units model....................................................................... 28

Figure 10 – MathML example linear conversion....................................... 31

Figure 11 – MathML example inverse linear conversion............................ 31

Figure A.12 – Sample OPC UA Information Model for OPC DA................... 41

Figure A.13 – OPC COM DA to OPC UA data and error mapping................ 45

Figure A.14 – Status Code mapping...................................................... 46

Figure A.15 – Sample OPC DA mapping of OPC UA Information Model and Address Space................................................................................. 50

Figure A.16 – OPC UA to OPC DA data & error mapping........................... 54

Figure A.17 – OPC UA Status Code to OPC DA quality mapping................ 55

 

TABLES

 

Table 1 – DataItemType definition.......................................................... 5

Table 2 – BaseAnalogType definition...................................................... 6

Table 3 – AnalogItemType definition....................................................... 7

Table 4 – AnalogUnitType definition........................................................ 7

Table 5 – AnalogUnitRangeType definition............................................... 8

Table 6 – DiscreteItemType definition..................................................... 8

Table 7 – TwoStateDiscreteType definition............................................... 8

Table 8 – MultiStateDiscreteType definition.............................................. 9

Table 9 – MultiStateValueDiscreteType definition.................................... 10

Table 10 – ArrayItemType definition...................................................... 11

Table 11 – YArrayItemType definition.................................................... 11

Table 12 – YArrayItem item description.................................................. 12

Table 13 – XYArrayItemType definition.................................................. 13

Table 14 – ImageItemType definition..................................................... 14

Table 15 – CubeItemType definition...................................................... 14

Table 16 – NDimensionArrayItemType definition...................................... 15

Table 17 – Range DataType structure................................................... 17

Table 18 – Range definition................................................................. 17

Table 19 – EUInformation DataType structure......................................... 18

Table 20 – EUInformation definition...................................................... 18

Table 21 – Examples from the UNECE Recommendation.......................... 19

Table 22 – ComplexNumberType DataType structure............................... 19

Table 23 – ComplexNumberType definition............................................. 20

Table 24 – DoubleComplexNumberType DataType structure...................... 20

Table 25 – DoubleComplexNumberType definition................................... 20

Table 26 – AxisInformation DataType structure....................................... 20

Table 27 – AxisInformation definition..................................................... 21

Table 28 – AxisScaleEnumeration values............................................... 21

Table 29 – AxisScaleEnumeration definition........................................... 21

Table 30 – XVType DataType structure.................................................. 21

Table 31 – XVType definition............................................................... 22

Table 32 – Quantities definition............................................................ 23

Table 33 – List of Syntax References.................................................... 24

Table 34 – Definition of NodeId for instances of the SyntaxReferenceEntryType      24

Table 35 – List of Syntax Reference Identifiers........................................ 25

Table 36 – QuantityType definition........................................................ 27

Table 37 – QuantityType Additional Subcomponents................................ 27

Table 38 – UnitType definition.............................................................. 28

Table 39 – Non-exhaustive list of well-known systems of units................... 29

Table 40 – ServerUnitType definition..................................................... 29

Table 41 – ServerUnitType Additional Subcomponents............................. 30

Table 42 – AlternativeUnitType definition............................................... 30

Table 43 – SyntaxReferenceEntryType Definition.................................... 32

Table 44 – HasEngineeringUnitDetails definition...................................... 32

Table 45 – HasQuantity definition......................................................... 33

Table 46 – AnnotationDataType Structure.............................................. 33

Table 47 – AnnotationDataType examples.............................................. 33

Table 48 – AnnotationDataType definition.............................................. 33

Table 49 – LinearConversionDataType Structure..................................... 34

Table 50 – LinearConversionDataType Definition..................................... 34

Table 51 – ConversionLimitEnum Items................................................. 34

Table 52 – ConversionLimitEnum Definition............................................ 35

Table 53 – QuantityDimension DataType structure................................... 35

Table 54 – QuantityDimension definition................................................ 35

Table 55 – QuantityDimension examples................................................ 36

Table 56 – Operation level result codes for BAD data quality..................... 38

Table 57 – Operation level result codes for UNCERTAIN data quality.......... 38

Table 58 – Operation level result codes for GOOD data quality.................. 38

Table A.59 – OPC COM DA to OPC UA Properties mapping...................... 43

Table A.60 – DataTypes and mapping................................................... 46

Table A.61 – Quality mapping.............................................................. 47

Table A.62 – OPC DA Read error mapping............................................. 48

Table A.63 – OPC DA Write error code mapping...................................... 48

Table A.64 – DataTypes and Mapping................................................... 55

Table A.65 – Quality mapping.............................................................. 56

Table A.66 – OPC UA Read error mapping............................................. 57

Table A.67 – OPC UA Write error code mapping...................................... 57

 

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 © 2006-2024, 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
http://www.opcfoundation.org.

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: http://www.opcfoundation.org/errata.

 

Revision 1.05.04 Highlights

The following table includes the Mantis issues resolved with this revision.

 

Mantis ID	Scope	Summary	Resolution
9348	Errata	Property “Description” not needed	Removed the optional Property “Description” in the ObjectTypes UnitType and QuantityType and changed the text so that it refers to the “Description” Attribute.
9881	Errata	In MultiStateValueDiscreteType the ValueAsText Property is useless for Values other than scalar.	Specified that ValueAsText is Null if the Value is not scalar.

 

OPC UNIFIED ARCHITECTURE –

 

Part 8: Data Access

 

1      Scope

This part of OPC 10000 is part of the overall OPC Unified Architecture (OPC UA) standard series and defines the information model associated with Data Access (DA). It particularly includes additional VariableTypes and complementary descriptions of the NodeClasses and Attributes needed for Data Access, additional Properties, and other information and behaviour.

The complete address space model, including all NodeClasses and Attributes is specified in OPC 10000-3. The services to detect and access data are specified in OPC 10000-4.

Annex A specifies how the information received from OPC COM Data Access (DA) Servers is mapped to the Data Access model.

2      Normative references

The following referenced documents are indispensable for the application of this document. 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-3, OPC Unified Architecture - Part 3: Address Space Model

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

OPC 10000-4, OPC Unified Architecture - 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-19, OPC Unified Architecture - Part 19: Dictionary References

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

UN/CEFACT: UNECE Recommendation N° 20, Codes for Units of Measure Used in International Trade

https://unece.org/trade/cefact/UNLOCODE-Download

3      Terms, definitions and abbreviated terms

3.1       Terms and definitions

For the purposes of this document, the terms and definitions given in OPC 10000-1, OPC 10000-3, and OPC 10000-4 and the following apply.

3.1.1         

DataItem

link to arbitrary, live automation data, that is, data that represents currently valid information

Note 1 to entry: Examples of such data are

·      device data (such as temperature sensors),

·      calculated data,

·      status information (open/closed, moving),

·      dynamically-changing system data (such as stock quotes),

·      diagnostic data.

3.1.2         

AnalogItem

DataItem that represents continuously-variable physical quantities (e.g., length, temperature), in contrast to the digital representation of data in discrete items

Note 1 to entry: Typical examples are the values provided by temperature sensors or pressure sensors. OPC UA defines specific VariableTypes to identify an AnalogItem. Properties describe the possible ranges of AnalogItems.

3.1.3         

DiscreteItem

DataItem that represents data that can take on only a certain number of possible values (e.g., OPENING, OPEN, CLOSING, CLOSED)

Note 1 to entry: Specific VariableTypes are used to identify DiscreteItems with two states or with multiple states. Properties specify the string values for these states.

3.1.4         

ArrayItem

DataItem that represents continuously-variable physical quantities and where each individual data point consists of multiple values represented by an array (e.g., the spectral response of a digital filter)

Note 1 to entry: Typical examples are the data provided by analyser devices. Specific VariableTypes are used to identify ArrayItem variants.

3.1.5         

EngineeringUnits

units of measurement for AnalogItems that represent continuously-variable physical quantities (e.g., length, mass, time, temperature)

Note 1 to entry: This standard defines Properties to inform about the unit used for the DataItem value and about the highest and lowest value likely to be obtained in normal operation.

3.2       Abbreviated terms

DA               Data Access

EU               Engineering Unit

NaN             “Not a Number” defined in IEEE 754

UA               Unified Architecture

4      Concepts

Data Access deals with the representation and use of automation data in Servers.

Automation data can be located inside the Server or on I/O cards directly connected to the Server. It can also be located in sub-servers or on other devices such as controllers and input/output modules, connected by serial links via field buses or other communication links. OPC UA Data Access Servers provide one or more OPC UA Data Access Clients with transparent access to their automation data.

The links to automation data instances are called DataItems. Which categories of automation data are provided is completely vendor-specific. Figure 1 illustrates how the AddressSpace of a Server can contain a broad range of different DataItems.

Figure 1 – OPC DataItems are linked to automation data

Clients can read or write DataItems, or monitor them for value changes. The Services needed for these operations are specified in OPC 10000-4. Changes are defined as a change in status (quality) or a change in value that exceeds a client-defined range called a Deadband. To detect the value change, the difference between the current value and the last reported value is compared to the Deadband.

5      Model

5.1       General

The DataAccess model extends the variable model by defining VariableTypes. The DataItemType is the base type. ArrayItemType, BaseAnalogType and DiscreteItemType are specializations. See Figure 2. Each of these VariableTypes can be further extended to form domain or server specific DataItems.

Figure 2 – DataItem VariableType hierarchy

5.2       SemanticsChanged

The StatusCode also contains an informational bit called SemanticsChanged.

Servers that implement Data Access shall set this Bit in notifications if certain Property values defined in this standard change. The corresponding Properties are specified individually for each VariableType.

Clients that use any of these Properties should re-read them before they process the data value.

5.3       Variable Types

5.3.1        DataItemType

This VariableType defines the general characteristics of a DataItem. All other DataItem Types derive from it. The DataItemType derives from the BaseDataVariableType and therefore shares the variable model as described in OPC 10000-3 and OPC 10000-5. It is formally defined in Table 1.

Table 1 – DataItemType definition

 

Definition is a vendor-specific, human readable string that specifies how the value of this DataItem is calculated. Definition is non-localized and will often contain an equation that can be parsed by certain clients.

Example:                       Definition::= “(TempA – 25) + TempB”

ValuePrecision specifies the maximum precision that the Server can maintain for the item based on restrictions in the target environment.

ValuePrecision can be used for the following DataTypes:

·        For Float, Double, and Decimal values it specifies the number of digits after the decimal place when it is a positive number. When it is a negative number, it specifies the number of insignificant digits to the left of the decimal place.

For example a ValuePrecision of -2 specifies that the precision of the Value is to the nearest 100. The ValuePrecision should always be a whole number and it shall always be interpreted as a whole number by rounding it to the nearest whole number.

·        For DateTime values it shall always be a positive number which indicates the minimum time difference in nanoseconds. For example, a ValuePrecision of 20 000 000 defines a precision of 20 ms. The ValuePrecision should always be a whole number and it shall always be interpreted as a whole number by rounding it to the nearest whole number.

·        ValuePrecision can also be used for other subtypes of Double (like Duration) and other Number subtypes that can be represented by a Double.

The ValuePrecision Property is an approximation that is intended to provide guidance to a Client. A Server is expected to silently round any value with more precision that it supports. This implies that a Client can encounter cases where the value read back from a Server differs from the value that it wrote to the Server. This difference shall be no more than the difference suggested by this Property.

The algorithm for rounding should follow the so-called “Banker’s rounding” (aka Round half to even), in which numbers which are equidistant from the two nearest integers are rounded to the nearest even integer. Thus, 0.5 rounds down to 0; 1.5 rounds up to 2.

Other decimal fractions round as you would expect: 0.4 to 0, 0.6 to 1, 1.4 to 1, 1.6 to 2, etc. Only x.5 numbers get the "special" treatment.

 

5.3.2        AnalogItem VariableTypes

5.3.2.1         General

The VariableTypes in this subclause define the characteristics of AnalogItems. The types have identical semantics and Properties but with diverging ModellingRules for individual Properties.

The Properties are only described once - in 5.3.2.2. The descriptions apply to the Properties for the other VariableTypes as well.

5.3.2.2         BaseAnalogType

This VariableType is the base type for analog items. All Properties are optional. Subtypes of this base type will mandate some of the Properties. The BaseAnalogType derives from the DataItemType. It is formally defined in Table 2.

Table 2 – BaseAnalogType definition

 

The following paragraphs describe the Properties of this VariableType. If the analog item’s Value contains an array, the Properties shall apply to all elements in the array.

InstrumentRange defines the value range that can be returned by the instrument.

Example:                       InstrumentRange::= {-9999.9, 9999.9}

Although defined as optional, it is strongly recommended for Servers to support this Property. Without an InstrumentRange being provided, Clients will commonly assume the full range according to the DataType.

The InstrumentRange Property can also be used to restrict a Built-in DataType such as Byte or Int16) to a smaller range of values.

Examples:

UInt4:                InstrumentRange::= {0, 15}

Int6:                  InstrumentRange::= {-32, 31}

The Range DataType is specified in 5.6.2.

EURange defines the value range likely to be obtained in normal operation. It is intended for such use as automatically scaling a bar graph display.

Sensor or instrument failure or deactivation can result in a returned item value which is actually outside of this range. Client software must be prepared to deal with this possibility. Similarly a Client can attempt to write a value that is outside of this range back to the server. The exact behaviour (accept, reject, clamp, etc.) in this case is Server-dependent. However, in general Servers shall be prepared to handle this.

Example:                       EURange::= {-200.0,1400.0}

See also 7.2 for a special monitoring filter (PercentDeadband) which is based on the engineering unit range.

NOTE If EURange is not provided on an instance, the PercentDeadband filter cannot be used for that instance (see clause 7.2).

EngineeringUnits specifies the units for the DataItem’s value (e.g., DEGC, hertz, seconds). The EUInformation type is specified in 5.6.3. The NonHierarchical References HasQuantity (see 6.5.2) and HasEngineeringUnitDetail (see 6.5.1) can be used to expose further information for the unit.

It is important to note that understanding the units of a measurement value is essential for a uniform system. In an open system in particular where Servers from different cultures can be used, it is essential to know what the units of measurement are. Based on such knowledge, values can be converted if necessary before being used. Therefore, although defined as optional, support of the EngineeringUnits Property is strongly advised.

OPC UA recommends using the “Codes for Units of Measurement” (see UN/CEFACT: UNECE Recommendation N° 20). The mapping to the EngineeringUnits Property is specified in 5.6.3.

Examples for unit mixup: In 1999, the Mars Climate Orbiter crashed into the surface of Mars. The main reason was a discrepancy over the units used. The navigation software expected data in newton second; the company who built the orbiter provided data in pound-force seconds. Another, less expensive, disappointment occurs when people used to British pints order a pint in the USA, only to be served what they consider a short measure.

The StatusCode SemanticsChanged bit shall be set if any of the EURange (could change the behaviour of a Subscription if a PercentDeadband filter is used) or EngineeringUnits (could create problems if the Client uses the value to perform calculations) Properties are changed (see clause 5.2 for additional information).

5.3.2.3         AnalogItemType

This VariableType requires the EURange Property. The AnalogItemType derives from the BaseAnalogType. It is formally defined in Table 3.

Table 3 – AnalogItemType definition

 

5.3.2.4         AnalogUnitType

This VariableType requires the EngineeringUnits Property. The AnalogUnitType derives from the BaseAnalogType. It is formally defined in Table 4.

Table 4 – AnalogUnitType definition

 

5.3.2.5         AnalogUnitRangeType

The AnalogUnitRangeType derives from the AnalogItemType and additionally requires the EngineeringUnits Property. It is formally defined in Table 5.

Table 5 – AnalogUnitRangeType definition

 

5.3.3        DiscreteItemType

5.3.3.1         General

This VariableType is an abstract type. That is, no instances of this type can exist. However, it can be used in a filter when browsing or querying. The DiscreteItemType derives from the DataItemType and therefore shares all of its characteristics. It is formally defined in Table 6.

Table 6 – DiscreteItemType definition

 

5.3.3.2         TwoStateDiscreteType

This VariableType defines the general characteristics of a DiscreteItem that can have two states. The TwoStateDiscreteType derives from the DiscreteItemType. It is formally defined in Table 7.

Table 7 – TwoStateDiscreteType definition

 

TrueState contains a string to be associated with this DataItem when it is TRUE. This is typically used for a contact when it is in the closed (non-zero) state.

            for example: "RUN", "CLOSE", "ENABLE", "SAFE", etc.

FalseState contains a string to be associated with this DataItem when it is FALSE. This is typically used for a contact when it is in the open (zero) state.

            for example: "STOP", "OPEN", "DISABLE", "UNSAFE", etc.

If the item contains an array, then the Properties will apply to all elements in the array.

The StatusCode SemanticsChanged bit shall be set if any of the FalseState or TrueState Properties are changed (see 5.2 for additional information).

5.3.3.3         MultiStateDiscreteType

This VariableType defines the general characteristics of a DiscreteItem that can have more than two states. The MultiStateDiscreteType derives from the DiscreteItemType. It is formally defined in Table 8.

Table 8 – MultiStateDiscreteType definition

 

EnumStrings is a string lookup table corresponding to sequential numeric values (0, 1, 2, etc.)

Example:

            "OPEN"

            "CLOSE"

            "IN TRANSIT" etc.

Here the string "OPEN" corresponds to 0, "CLOSE" to 1 and "IN TRANSIT" to 2.

Clients should be prepared to handle item values outside of the range of the list; and robust servers should be prepared to handle writes of illegal values, by providing errorcode “Bad_OutOfRange”.

If the item contains an array then this lookup table shall apply to all elements in the array.

NOTE The EnumStrings property is also used for Enumeration DataTypes (for the specification of this DataType, see OPC 10000-3).

The StatusCode SemanticsChanged bit shall be set if the EnumStrings Property is changed (see 5.2 for additional information).

5.3.3.4         MultiStateValueDiscreteType

This VariableType defines the general characteristics of a DiscreteItem that can have more than two states and where the state values (the enumeration) do not consist of consecutive numeric values (can have gaps) or where the enumeration is not zero-based. The MultiStateValueDiscreteType derives from the DiscreteItemType. It is formally defined in Table 9.

Table 9 – MultiStateValueDiscreteType definition

 

EnumValues is an array of EnumValueType. Each entry of the array represents one enumeration value with its integer notation, a human-readable representation, and help information. This represents enumerations with integers that are not zero-based or have gaps (e.g. 1, 2, 4, 8, 16). See OPC 10000-3 for the definition of this type. MultiStateValueDiscrete Variables expose the current integer notation in their Value Attribute. Clients will often read the EnumValues Property in advance and cache it to lookup a name or help whenever they receive the numeric representation.

Only DataTypes that can be represented with EnumValues are allowed for Variables of MultiStateValueDiscreteType. These are Integers up to 64 Bits (signed and unsigned).

The numeric representation of the current enumeration value is provided via the Value Attribute of the MultiStateValueDiscrete Variable. If the Value is scalar, the ValueAsText Property provides the localized text representation of the enumeration value. It can be used by Clients only interested in displaying the text to subscribe to the Property instead of the Value Attribute. If the Value is not scalar then ValueAsText should be Null. In that case, Clients can use the EnumValues Property to lookup the display information.

The StatusCode SemanticsChanged bit shall be set if the EnumValues Property value is changed (see clause 5.2 for additional information).

5.3.4        ArrayItemType

5.3.4.1         General

This abstract VariableType defines the general characteristics of an ArrayItem. Values are exposed in an array but the content of the array represents a single entity like an image. Other DataItems can contain arrays that represent for example several values of several temperature sensors of a boiler.

ArrayItemType or its subtype shall only be used when the Title and AxisScaleType Properties can be filled with reasonable values. If this is not the case DataItemType and subtypes like AnalogItemType, which also support arrays, shall be used. The ArrayItemType is formally defined in Table 10.

Table 10 – ArrayItemType definition

 

InstrumentRange defines the range of the Value of the ArrayItem.

EURange defines the value range of the ArrayItem likely to be obtained in normal operation. It is intended for such use as automatically scaling a bar graph display.

EngineeringUnits holds the information about the engineering units of the Value of the ArrayItem.

For additional information about InstrumentRange, EURange, and EngineeringUnits see the description of BaseAnalogType in 5.3.2.2.

Title holds the user readable title of the Value of the ArrayItem.

AxisScaleType defines the scale to be used for the axis where the Value of the ArrayItem shall be displayed.

The StatusCode SemanticsChanged bit shall be set if any of the InstrumentRange, EURange, EngineeringUnits or Title Properties are changed (see 5.2 for additional information).

5.3.4.2         YArrayItemType

YArrayItemType represents a single-dimensional array of numerical values used to represent spectra or distributions where the x axis intervals are constant. YArrayItemType is formally defined in Table 11.

Table 11 – YArrayItemType definition

 

The Value of the YArrayItem contains the numerical values for the Y-Axis. Engineering Units and Range for the Value are defined by corresponding Properties inherited from the ArrayItemType.

The DataType of this VariableType is restricted to SByte, Int16, Int32, Int64, Float, Double, ComplexNumberType and DoubleComplexNumberType.

The XAxisDefinition Property holds the information about the Engineering Units and Range for the X-Axis.

The StatusCode SemanticsChanged bit shall be set if any of the following five Properties are changed: InstrumentRange, EURange, EngineeringUnits, Title or XAxisDefinition (see 5.2 for additional information).

Figure 3 shows an example of how Attributes and Properties can be used in a graphical interface.

Figure 3 – Graphical view of a YArrayItem

Table 12 describes the values of each element presented in Figure 3.

Table 12 – YArrayItem item description

 

Interpretation notes:

·      Not all elements of this table are used in the graphic.

·      The X axis is displayed in reverse order, however, the XAxisDefinition.Range.low shall be lower than XAxisDefinition.Range.high. It is only a graphical representation that reverses the display order.

·      There is a constant X axis

5.3.4.3         XYArrayItemType

XYArrayItemType represents a vector of XVType values like a list of peaks, where XVType.x is the position of the peak and XVType.value is its intensity. XYArrayItemType is formally defined in Table 13.

Table 13 – XYArrayItemType definition

 

The Value of the XYArrayItem contains an array of structures (XVType) where each structure specifies the position for the X-Axis (XVType.x) and the value itself (XVType.value), used for the Y-Axis. Engineering units and range for the Value are defined by corresponding Properties inherited from the ArrayItemType.

XAxisDefinition Property holds the information about the Engineering Units and Range for the X-Axis.

The axisSteps of XAxisDefinition shall be set to NULL because it is not used.

The StatusCode SemanticsChanged bit shall be set if any of the InstrumentRange, EURange, EngineeringUnits, Title or XAxisDefinition Properties are changed (see 5.2 for additional information).

5.3.4.4         ImageItemType

ImageItemType defines the general characteristics of an ImageItem which represents a matrix of values like an image, where the pixel position is given by X which is the column and Y the row. The value is the pixel intensity.

ImageItemType is formally defined in Table 14.

Table 14 – ImageItemType definition

 

Engineering units and range for the Value are defined by corresponding Properties inherited from the ArrayItemType.

The DataType of this VariableType is restricted to SByte, Int16, Int32, Int64, Float, Double, ComplexNumberType and DoubleComplexNumberType.

The ArrayDimensions Attribute for Variables of this type or subtypes shall use the first entry in the array ([0]) to define the number of columns and the second entry ([1]) to define the number of rows, assuming the size of the matrix is not dynamic.

XAxisDefinition Property holds the information about the engineering units and range for the X-Axis.

YAxisDefinition Property holds the information about the engineering units and range for the Y-Axis.

The StatusCode.SemanticsChanged bit shall be set if any of the InstrumentRange, EURange, EngineeringUnits, Title, XAxisDefinition or YAxisDefinition Properties are changed.

5.3.4.5         CubeItemType

CubeItemType represents a cube of values like a spatial particle distribution, where the particle position is given by X which is the column, Y the row and Z the depth. In the example of a spatial partical distribution, the value is the particle size. CubeItemType is formally defined in Table 15.

Table 15 – CubeItemType definition

 

Engineering units and range for the Value are defined by corresponding Properties inherited from the ArrayItemType.

The DataType of this VariableType is restricted to SByte, Int16, Int32, Int64, Float, Double, ComplexNumberType and DoubleComplexNumberType.

The ArrayDimensions Attribute for Variables of this type or subtypes should use the first entry in the array ([0]) to define the number of columns, the second entry ([1]) to define the number of rows, and the third entry ([2]) define the number of steps in the Z axis, assuming the size of the matrix is not dynamic.

XAxisDefinition Property holds the information about the engineering units and range for the X-Axis.

YAxisDefinition Property holds the information about the engineering units and range for the Y-Axis.

ZAxisDefinition Property holds the information about the engineering units and range for the Z-Axis.

The StatusCode SemanticsChanged bit shall be set if any of the InstrumentRange, EURange, EngineeringUnits, Title, XAxisDefinition, YAxisDefinition or ZAxisDefinition Properties are changed (see 5.2 for additional information).

5.3.4.6         NDimensionArrayItemType

This VariableType defines a generic multi-dimensional ArrayItem.

This approach minimizes the number of types however it can be proved more difficult to utilize for control system interactions.

NDimensionArrayItemType is formally defined in Table 16.

Table 16 – NDimensionArrayItemType definition

 

The DataType of this VariableType is restricted to SByte, Int16, Int32, Int64, Float, Double, ComplexNumberType and DoubleComplexNumberType.

AxisDefinition Property holds the information about the EngineeringUnits and Range for all axis.

The StatusCode SemanticsChanged bit shall be set if any of the InstrumentRange, EURange, EngineeringUnits, Title or AxisDefinition Properties are changed (see 5.2 for additional information).

5.4       Address Space model

DataItems are always defined as data components of other Nodes in the AddressSpace. They are never defined by themselves. A simple example of a container for DataItems would be a “Folder Object” but it can be an Object of any other type.

Figure 4 illustrates the basic AddressSpace model of a DataItem, in this case an AnalogItem.

Figure 4 – Representation of DataItems in the AddressSpace

Each DataItem is represented by a DataVariable with a specific set of Attributes. The TypeDefinition reference indicates the type of the DataItem (in this case the AnalogItemType). Additional characteristics of DataItems are defined using Properties. The VariableTypes in 5.2 specify which properties can exist. These Properties have been found to be useful for a wide range of Data Access clients. Servers that want to disclose similar information should use the OPC-defined Property rather than one that is vendor-specific.

The above figure shows only a subset of Attributes and Properties. Other Attributes that are defined for Variables in OPC 10000-3 (e.g., Description) can also be available.

5.5       Attributes of DataItems

This subclause lists the Attributes of Variables that have particular importance for Data Access. They are specified in detail in OPC 10000-3. The following Attributes are particularly important for Data Access:

·      Value

·      DataType

·      AccessLevel

·      MinimumSamplingInterval

Value is the most recent value of the Variable that the Server has. Its data type is defined by the DataType Attribute. The AccessLevel Attribute defines the Server’s basic ability to access current data and MinimumSamplingInterval defines how current the data is.

When a client requests the Value Attribute for reading or monitoring, the Server will always return a StatusCode (the quality and the Server’s ability to access/provide the value) and, optionally, a ServerTimestamp and/or a SourceTimestamp – based on the Client’s request. See OPC 10000-4 for details on StatusCode and the meaning of the two timestamps. Specific status codes for Data Access are defined in 7.3.

5.6       DataTypes

5.6.1        Overview

Following is a description of the DataTypes defined in this specification.

DataTypes like String, Boolean, Double or LocalizedText are defined in OPC 10000-3. Their representation is specified in OPC 10000-5.

5.6.2        Range

This structure defines the Range for a value. Its elements are defined in Table 17.

Table 17 – Range DataType structure

Name	Type	Description
Range	structure
low	Double	Lowest value in the range.
high	Double	Highest value in the range.

 

NOTE For some DataTypes, e.g. Int64, UInt64, or Decimal, there can be a loss in precision in the representation of the range with a Double.

If a limit is not known a NaN shall be used.

Its representation in the AddressSpace is defined in Table 18

Table 18 – Range definition

 

5.6.3        EUInformation

5.6.3.1       General

EUInformation contains information about the EngineeringUnits.

The intention of the OPC UA standard is not to define a set of units but a way to expose units based on existing systems. Since there is not a single worldwide set of units used in all industries, the EUInformation structure includes a separate field (the namespaceUri) to identify the system on which the exposed unit is based.

The default OPC UA mapping is based on UN/CEFACT as defined in 5.6.3.4, because it can be programmatically interpreted by generic OPC UA Clients. However, the EUInformation structure has been defined such that other standards bodies can incorporate their engineering unit definitions into OPC UA. If Servers use such an approach, then they shall identify this standards body by using a proper URI in EUInformation.namespaceUri.

5.6.3.2       Extented Unit information and Quantity

Servers can enhance EUInformation by providing the Quantity and Unit model (see 6) and referencing from EUInformation instances to the appropriate instances for quantity and unit. See Figure 5 for an example.

Figure 5 – Enhanced EUInformation example

5.6.3.3       Definition of EUInformation

The EUInformation elements are defined in Table 19.

Table 19 – EUInformation DataType structure

Name	Type	Description
EUInformation	structure
namespaceUri	String	Identifies the organization (company, standards organization) that defines the EUInformation.
unitId	Int32	Identifier for programmatic lookup. −1 is used if a unitId is not available.
displayName	LocalizedText	The displayName of the engineering unit is typically the abbreviation of the engineering unit, for example "h" for hour or "m/s" for meter per second.
description	LocalizedText	Contains the full name of the engineering unit such as "hour" or "meter per second".

 

Its representation in the AddressSpace is defined in Table 20.

Table 20 – EUInformation definition

 

5.6.3.4       Mapping of UN/CEFACT to EUInformation

This clause specifies how to apply the “Codes for Units of Measurement” published by the “United Nations Centre for Trade Facilitation and Electronic Business” (see UNECE). This recommendation establishes a single list of code elements to represent units of the International System of Units (SI Units) like units of measure for length, mass (weight), volume and other quantities and in addition covers administration, commerce, transport, science, technology, industry etc. It provides a fixed code that can be used for automated evaluation.

Table 21 contains a small excerpt of the relevant columns in the UNECE recommendation:

Table 21 – Examples from the UNECE Recommendation

 

The UNECE recommendation in several cases defines multiple instances of the same unit (same name and symbol) for different quantities. Therefore, the relevant information for EUInformation.unitId, EUInformation.displayName, and EUInformation.description has been extracted by eliminating duplicates. This extract is available here:

http://www.opcfoundation.org/UA/EngineeringUnits/UNECE/UNECE_to_OPCUA.csv

This mapping has been generated as follows:

·      The namespaceUri shall be http://www.opcfoundation.org/UA/units/un/cefact

·      The Common Code (represented as an alphanumeric variable length of up to 3 characters) has been converted into a 32 Bit Integer and is used for the unitId. The following pseudo code specifies the conversion algorithm:

  Int32 unitId = 0; 
  Int32 c;
  for (i=0; i<=3;i++)
  {

   c = CommonCode[i];  
   if (c == 0) break;         // end of Common Code
   unitId = unitId << 8;
   unitId = unitId | c; 
}

·      The Symbol field shall be used as invariant locale for displayName. Servers can configure multiple additional locales for each displayName. However, if none of the LocaleIds specified by the Client for the Session matches these additional locales, the Server shall return the invariant locale.

·      The Name field shall be used as invariant locale for description. Servers can configure multiple additional locales for each description. However, if none of the LocaleIds specified by the Client for the Session matches these additional locales, the Server shall return the invariant locale.

 

5.6.4        ComplexNumberType

This structure defines float IEEE 32 bits complex value. Its elements are defined in Table 22.

Table 22 – ComplexNumberType DataType structure

Its representation in the AddressSpace is defined in Table 23

Table 23 – ComplexNumberType definition

 

5.6.5        DoubleComplexNumberType

This structure defines double IEEE 64 bits complex value. Its elements are defined in Table 24.

Table 24 – DoubleComplexNumberType DataType structure

 

Its representation in the AddressSpace is defined in Table 25.

Table 25 – DoubleComplexNumberType definition

 

5.6.6        AxisInformation

This structure defines the information for auxiliary axis for ArrayItemType Variables.

There are three typical uses of this structure:

a)   The step between points is constant and can be predicted using the range information and the number of points. In this case, axisSteps can be set to NULL.

b)   The step between points is not constant, but remains the same for a long period of time (from acquisition to acquisition for example). In this case, axisSteps contains the value of each step on the axis.

c)    The step between points is not constant and changes at every update. In this case, a type like XYArrayType shall be used and axisSteps is set to NULL.

Its elements are defined in Table 26.

Table 26 – AxisInformation DataType structure

 

Its representation in the AddressSpace is defined in Table 27.

Table 27 – AxisInformation definition

 

When the steps in the axis are constant, axisSteps can be set to “Null” and in this case, the Range limits are used to compute the steps. The number of steps in the axis comes from the parent ArrayItem.ArrayDimensions.

5.6.7        AxisScaleEnumeration

This enumeration identifies on which type of axis the data shall be displayed. Its values are defined in Table 28.

Table 28 – AxisScaleEnumeration values

 

Its representation in the AddressSpace is defined in Table 29.

Table 29 – AxisScaleEnumeration definition

 

5.6.8        XVType

This structure defines a physical value relative to a X axis and it is used as the DataType of the Value of XYArrayItemType. For details see 5.3.4.3.

Many devices can produce values that can perfectly be represented with a float IEEE 32 bits but, they can position them on the X axis with an accuracy that requires double IEEE 64 bits. For example, the peak value in an absorbance spectrum where the amplitude of the peak can be represented by a float IEEE 32 bits, but its frequency position required 10 digits which implies the use of a double IEEE 64 bits.

Its elements are defined in Table 30.

Table 30 – XVType DataType structure

 

Its representation in the AddressSpace is defined in Table 31.

Table 31 – XVType definition

 

6      Quantities and Units model

6.1       General

This model supplements the information of EngineeringUnit Properties, providing comprehensive ObjectTypes for quantities and units and their linkage. See 5.6.3 how EngineeringUnit Properties reference instances of these ObjectTypes. It is also possible to specify AlternativeUnits and the conversion factors.

Furthermore, the model provides a powerful way to relate quantities and units to established works of other organizations (see Syntax References in 6.3).

Figure 6 Illustrates the model.

Figure 6 – Quantity model overview

6.2       Quantities entry point

Quantities is a standardized entry point to access all Quantities and their Units managed in the Server. It is formally defined in Table 32. All Objects of the QuantityType defined in clause 6.4.1, that are managed in the Server, shall be referenced directly from this Object with Organizes or a subtype of Organizes.

Table 32 – Quantities definition

 

6.3       Syntax References

6.3.1        General

Syntax References represent established works of other organizations. Such works – among others – can define semantic information, topologies, a language for a code set, or dictionaries and facilitate the programmatic evaluation or the lookup of a quantity or unit e.g. in a dictionary or ontology. They can be publicly defined by standard bodies such as IEC or proprietary (e.g. vendor-specific dictionaries).

The Quantities and Unit Model provides a powerful way to relate quantities and units to such Syntax References using the Dictionary References model defined in OPC 10000-19.

Table 33 lists Syntax References that are applied in certain markets. This list can be extended in future versions. Vendors or organizations can also specify additional Syntax References.

An overview for each Syntax Reference in this table is provided in Annex C.

Table 33 – List of Syntax References

Common Name	Syntax Reference URI	Full Name
UCUM	https://ucum.org	Unified Code for Units of Measure
QUDT	https://qudt.org	Quantities, Units, Dimensions and Types Ontology
IEC CDD	https://cdd.iec.ch/	Common Data Dictionary
UNECE	https://unece.org/trade/uncefact/cl-recommendations	Codes for Units of Measure Used in International Trade
LATEX_SIUNITX	https://www.namsu.de/Extra/pakete/Siunitx.html	LaTeX SI Unit Extension

 

6.3.2        Using Dictionary References

HasDictionaryEntry is used to define the relationship to a Syntax Reference by referencing from quantity or unit Nodes to an instance of a SyntaxReferenceEntryType. Each quantity or unit instance can have zero, one or more such references.

Instances of SyntaxReferenceEntryType have a well-defined NodeId as defined in Table 34.

Table 34 – Definition of NodeId for instances of the SyntaxReferenceEntryType

 

When calling the Browse Service for a Quantity or Unit Node, the response includes the HasDictionaryEntry Reference together with the well-defined NodeId for the SyntaxReferenceEntryType instance. The actual instance therefore is not required in the AddressSpace.

Figure 7 provides an example of References to external works.

Figure 7 – References to external works

6.3.3        Syntax Reference Identifier

Table 35 defines the identifiers for each Syntax Reference.

Table 35 – List of Syntax Reference Identifiers

Common Name	Identifier
UCUM	QuantityType instances: The UCUM Syntax ReferenceID for quantities shall include the prefix “quantityKind:” followed by the name of the quantity.
	UnitType instances: The UCUM SyntaxReferenceId for units shall include an expression based on the UCUM syntax making use of the symbols named in the “C/S” entry of the UCUM spec (https://ucum.org/ucum.html). Codes (expressions) for common units are defined in Annex B.
QUDT	QuantityType instances: The QUDT Syntax ReferenceID for quantities shall include the prefix “quantityKind:” followed by the name of the quantity as in https://www.qudt.org/doc/DOC_VOCAB-QUANTITY-KINDS.html. Example quantities are in C.2
	UnitType instances: The QUDT Syntax ReferenceID for units shall include the prefix “unit:” followed by the name of the unit as in https://www.qudt.org/doc/DOC_VOCAB-UNITS.html. Example units are in C.2.
IEC CDD	QuantityType instances: The IEC CDD SyntaxReferenceId shall include the IRDI of the respective quantity. Example quantities are in C.4.
	UnitType instances: The IEC CDD SyntaxReferenceId shall include the IRDI of the respective unit. Example units are in C.4.
UNECE	QuantityType instances: There are no UNECE Syntax References for quantities.
	UnitType instances: The UNECE SyntaxReferenceId shall include the common code from “Codes for Units of Measurement” published by the “United Nations Centre for Trade Facilitation and Electronic Business” (see UNECE).   Example units are in C.3.
LATEX_SIUNITX	QuantityType instances: There are no LATEX_SIUNITX Syntax References for quantities.
	UnitType instances: The LATEX_SIUNITX SyntaxReferenceId shall include the leading slash, the keyword of the macro as well as the entire argument.   Example units are in C.5.

 

6.4       ObjectTypes

6.4.1        QuantityType ObjectType definition

The QuantityType defines a model for physical quantities. These are listed in the Quantites Folder. Each quantity has a ServerUnits Folder in which the units, referenced by EngineeringUnit Properties with HasEngineeringUnitDetails, are listed. Each ServerUnit can have a list of alternative units to which the Variable value can be converted.

Figure 8 – QuantityType

It is illustrated in Figure 8 and formally defined in Table 36.

Table 36 – QuantityType definition

 

The DisplayName Attribute of each instance shall provide the name of the quantity, e.g. “acceleration”, “battery capacity” or “pressure in relation to volume flow rate”.

The Description Attribute should be used to expose a more verbose explanation of the QuantityType instance.

The Symbol Property is used for the symbol of the quantity (e.g. ‘l’ for length, ‘t’ for time, or ‘T’ for temperature).

Annotation allows naming annotations for a physical quantity. These Annotations are explanations of the physical quantity such as "relative" for a relative velocity. The AnnotationDataType is described in chapter 6.6.1.

For example, a V_{AC RMS} measurement is the quadratic mean measurement of an AC voltage. We are using two annotation elements to represent it. Its Instance would contain the following values:

Annotation	Discipline	uri
AC	Electrical Engineering	https://www.britannica.com/science/alternating-current
RMS	Electrical Engineering	https://en.wikipedia.org/wiki/Root_mean_square)

 

ConversionService allows to name an external conversion service for the unit in which the client can have a conversion to a target unit performed.

Dimension describes the dimension of a physical quantity in power representation. Its DataType is described in chapter 6.6.4.

ServerUnits allows listing ServerUnits for a physical quantity. The ServerUnits are of ServerUnitType which is described in 6.4.2.

Syntax References: Instances of the QuantityType can identify the physical quantity in a specific external reference work using HasDictionaryEntry References – see 6.3.2.

The components of the QuantityType have additional subcomponents which are defined in Table 37.

Table 37 – QuantityType Additional Subcomponents

BrowsePath	References	NodeClass	BrowseName	DataType	TypeDefinition	Others
ServerUnits	HasComponent	Object	<ServerUnit>		ServerUnitType	MP

 

6.4.2        UnitType and subtypes

6.4.2.1         General

The Units model describes the relations between UnitType, ServerUnitType and AlternativeUnitType.

The UnitType is the base class and defines details that are relevant of all derived types.

Figure 9 – Units model

 

6.4.2.2         UnitType ObjectType Definition

It is formally defined in Table 38.

Table 38 – UnitType definition

 

The DisplayName Attribute of each instance shall provide the name of the unit, e.g. “second”, “degree Celsius” or “square metre”. This matches the “description” field of the EUInformation structure (see 5.6.3.3).

The Description Attribute should be used to expose a more verbose explanation of the UnitType instance.

The Symbol Property is used for the symbol of the unit (e.g. "h" for hour or "m/s" for meter per second). If no symbol is defined for the unit, the DisplayName Attribute shall be used as symbol. Symbol matches the “displayName” field of the EUInformation structure (see 5.6.3.3).

The UnitSystem Property describes the system of units (e.g. ISQ) in which the unit is specified. If any of the well-known systems defined in Table 39 is used, the acronym in the column “UnitSystem” shall be used for the value of this Property.

Table 39 – Non-exhaustive list of well-known systems of units

 

Syntax References: Instances of the UnitType can identify the unit in a specific external reference work using HasDictionaryEntry References – see 6.3.2.

6.4.2.3         ServerUnitType ObjectType Definition

Instances of ServerUnitType define the units utilizes in the Server. They are assigned to the proper Quantities. EngineeringUnit Properties can refer to it. It is formally defined in Table 40.

Table 40 – ServerUnitType definition

 

The optional Object AlternativeUnits contains Objects of the AlternativeUnitsType. These explicitly specify the units into which the conversion can be made.

The mandatory Property ConversionLimit indicates whether the ServerUnit can be converted. A distinction is made between NO_CONVERSION, LIMITED and UNLIMITED.

UNLIMITED means the client can perform conversions based on the rules defined by the given UnitSystem.

LIMITED conversion means that a conversion can not be performed by simply applying the rules defined by the given UnitSystem. Either only the conversions mentioned in the AlternativeUnits are to be used or the client requires application specific know-how for a conversion on his own.

NO_CONVERSION means that no conversion is allowed (e.g. for statistical values).

The CoherentUnit of a value is a derived unit that, for a given system of quantities and for a chosen set of base units, is a product of powers of base units, with the proportionality factor being one. Therefore it shall share the same UnitSystem as the ServerUnit.

The components of the ServerUnitType have additional subcomponents which are defined in Table 41.

Table 41 – ServerUnitType Additional Subcomponents

BrowsePath	References	NodeClass	BrowseName	DataType	TypeDefinition	Other
AlternativeUnits	HasComponent	Object	<AlternativeUnit>		AlternativeUnitType	MP

 

6.4.2.4         AlternativeUnitType ObjectType Definition

The AlternativeUnitType describes alternative units to a ServerUnit. It is required to specify a conversion method for a value from the ServerUnit to this AlternativeUnit. It is formally defined in Table 42.

The use of conversions enables that a server and a client can work with different units and even in different systems of units. E.g. a server works with imperial units and a client uses metric units.

As a single server can distribute values to a number of clients with different needs the actual conversion has to be performed at client side.

Table 42 – AlternativeUnitType definition

 

The Server shall provide either a LinearConversion or a MathMLConversion together with a corresponding MathMLInverseConversion. It can provide Linear and MathML conversions in parallel.

The optional Property LinearConversion represents a simple conversion according to the following formula. The values (a, b, c, d) are given in a Structure as defined in the LinearConversionDataType in chapter 6.6.2. The value x is published by the Server in the named server unit and y is the value converted into the named alternative unit.

 

Figure 10 – MathML example linear conversion

This also defines the inverse conversion to be used if a Client wants to write a value to the Server. The values (a, b, c, d) are given in a Structure as defined in the LinearConversionDataType in chapter 6.6.2. The value y¹ is the value that the Client wants to write to the Server in the named alternative unit and x¹ is the value the Client actually has to write to the Server instead

 

Figure 11 – MathML example inverse linear conversion

The optional Property MathMLConversion allows the specification of all kinds of conversion methods. The MathML syntax is used for this. Within the MathML expression X always stands for the value at the server side and Y for the value at the client side. An example (formula of the LinearConversion) looks as follows.

6.4.3        SyntaxReferenceEntryType ObjectType definition

The SyntaxReferenceEntryType defined in Table 43 is used to represent Syntax References that use Syntax Reference specific IDs as unique identifiers.

Because of their well-defined NodeIds (see 6.3.2), instances of this type are not required in the AddressSpace.

Table 43 – SyntaxReferenceEntryType Definition

 

CommonName shall be the corresponding field in Table 33.

The namespace for the NodeId and the BrowseName Attributes of instances of the SyntaxReferenceEntryType shall be the URI of the Syntax Reference as defined in Table 33.

6.5       References

6.5.1        HasEngineeringUnitDetails

The HasEngineeringUnitDetails is a concrete ReferenceType and can be used directly. It is a subtype of NonHierarchicalReferences.

The semantics of this ReferenceType is to link a Variable with EUInformation DataType to its more detailed AddressSpace representation Instance of the ServerUnitType ObjectType.

The SourceNode of References of this type shall be a Variable with EUInformation DataType.

The TargetNode of this ReferenceType shall be an Instance of the ServerUnitType ObjectType.

The Reference has to change if the value (the concrete EngineeringUnit) is changing. Clients can subscribe to the value and then need to rebrowse.

The HasEngineeringUnitDetails is formally defined in Table 44.

Table 44 – HasEngineeringUnitDetails definition

 

6.5.2        HasQuantity

The HasQuantity is a concrete ReferenceType and can be used directly. It is a subtype of NonHierarchicalReferences.

The semantics of this ReferenceType is to link a Variable with EUInformation DataType to an Instance of the QuantityType ObjectType.

The SourceNode of References of this type shall be a Variable with EUInformation DataType (typically the EngineeringUnits Property).

The TargetNode of this ReferenceType shall be an Instance of the QuantityType ObjectType.

The HasQuantity is formally defined in Table 45.

Table 45 – HasQuantity definition

 

6.6       DataTypes

6.6.1        AnnotationDataType DataType definition

This structure contains additions as explanation and specification of the physical quantity such as "relative" for a relative velocity. The structure is defined in Table 46.

Table 46 – AnnotationDataType Structure

 

Examples are given in Table 47.

Table 47 – AnnotationDataType examples

 

Its representation in the AddressSpace is defined in Table 48.

Table 48 – AnnotationDataType definition

 

6.6.2        LinearConversionDataType DataType definition

This structure contains a simple conversion according to the following formula. The factors (a = inititialAddend, b = multiplicand, c = divisor, d = finalAddend) are given in a Structure. X is the source value (in source unit) and f(x) the target value (in target unit). The structure is defined in Table 49.

 

The values of the structure can also be used for a simple inverse conversion. It can be used if a Client wants to write a value to the Server. The value y¹ is the value that the Client wants to write to the Server in the named alternative unit and x¹ is the value the Client actually has to write to the Server instead.

Table 49 – LinearConversionDataType Structure

 

Its representation in the AddressSpace is defined in Table 48.

Table 50 – LinearConversionDataType Definition

 

6.6.3        ConversionLimitEnum

ConversionLimitEnum indicates whether the ServerUnit can be converted. A distinction is made between NO_CONVERSION, LIMITED and UNLIMITED. NO_CONVERSION means that no conversion is allowed (e.g. for statistical values). LIMITED conversion means that either only the conversions mentioned in the AlternativeUnits are to be used or the client requires specific know-how for the conversion. UNLIMITED means the conversion is simple and possible if the client knows the UnitSystem. The enumeration is defined in Table 51.

Table 51 – ConversionLimitEnum Items

 

Its representation in the AddressSpace is defined in Table 52.

Table 52 – ConversionLimitEnum Definition

 

6.6.4        QuantityDimension

The QuantityDimension Structure DataType describes the dimensionality of a kind of quantity in the context of a system of units. In the SI system of units, the dimensions of a kind of quantity are expressed as a product of the basic physical dimensions length (L), mass (M), time (T), current (I), absolute temperature (θ), amount of substance (N) and luminous intensity (J) as

.

The rational powers of the dimensional exponents (α, β, γ, δ, ε, η, v), are positive, negative, or zero.

An additional dimensionless exponent is used for countable things that have no physical quantity assigned.

The QuantityDimension elements are defined in Table 53.

Table 53 – QuantityDimension DataType structure

Name	Type	Description
QuantityDimension	Structure
MassExponent	SByte	Exponent of the dimension mass for the physical quantity.
LengthExponent	SByte	Exponent of the dimension length for the physical quantity.
TimeExponent	SByte	Exponent of the dimension time for the physical quantity.
ElectricCurrentExponent	SByte	Exponent of the dimension electric current for the physical quantity.
AmountOfSubstanceExponent	SByte	Exponent of the dimension amount of substance for the physical quantity.
LuminousIntensityExponent	SByte	Exponent of the dimension luminous intensity for the physical quantity.
AbsoluteTemperatureExponent	SByte	Exponent of the dimension absolute temperature for the physical quantity.
DimensionlessExponent	SByte	Exponent for dimensionless quantities.

 

Its representation in the AddressSpace is defined in Table 54.

Table 54 – QuantityDimension definition

 

For example, the dimension of the physical quantity kind

 ,

the dimension of the physical quantity kind force is

 ,

and the dimension of the physical quantity kind “things (e.g., screws) per time” is

 .

 

Table 55 – QuantityDimension examples

Name	Values for speed	Values for force	Values for “things per time”
QuantityDimension
MassExponent	0	1	0
LengthExponent	1	1	0
TimeExponent	-1	-2	-1
ElectricCurrentExponent	0	0	0
AmoutOfSubstanceExponent	0	0	0
LuminousIntensityExponent	0	0	0
AbsoluteTemperatureExponent	0	0	0
DimensionlessExponent	0	0	1

 

The extended SI System of units includes derived units that are built as a product of base units. That makes it difficult to compare units as SI allows an unlimited number of “SI unit strings” to describe the same quantity.

All 3 are valid SI representations of the quantity “speed” and therefore share the same quantity dimensions. A specific representation of a unit is often used to express details how the unit was measured. The dimension structure makes it much easier to identify and compare the kind of quantity of EU values.

7      Data Access specific usage of Services

7.1       General

OPC 10000-4 specifies the complete set of services. The services needed for the purpose of DataAccess are:

·     The View service set and Query service set to detect DataItems, and their Properties.

·     The Attribute service set to read or write Attributes and in particular the value Attribute.

·     The MonitoredItem and Subscription service set to set up monitoring of DataItems and to receive data change notifications.

7.2       PercentDeadband

The DataChangeFilter in OPC 10000-4 defines the conditions under which a data change notification shall be reported. This filter contains a deadbandValue which can be of type AbsoluteDeadband or PercentDeadband. OPC 10000-4 already specifies the behaviour of the AbsoluteDeadband. This sub-clause specifies the behaviour of the PercentDeadband type.

DeadbandType = PercentDeadband

For this type of deadband the deadbandValue is defined as the percentage of the EURange. That is, it applies only to AnalogItems with an EURange Property that defines the typical value range for the item. This range shall be multiplied with the deadbandValue and then compared to the actual value change to determine the need for a data change notification. The following pseudo code shows how the deadband is calculated:

DataChange if (absolute value of (last cached value - current value) >
              (deadbandValue/100.0) * ((high–low) of EURange)))

The range of the deadbandValue is from 0,0 to 100,0 per cent. Specifying a deadbandValue outside of this range will be rejected and reported with the StatusCode Bad_DeadbandFilterInvalid (see Table 56).

If the Value of the MonitoredItem is an array, then the deadband calculation logic shall be applied to each element of the array. If an element that requires a DataChange is found, then no further deadband checking is necessary and the entire array shall be returned.

7.3       Data Access status codes

7.3.1        Overview

This subclause defines additional codes and rules that apply to the StatusCode when used for Data Access values.

The general structure of the StatusCode is specified in OPC 10000-4 and includes a set of common operational result codes that also apply to Data Access.

7.3.2        Operation level result codes

Certain conditions under which a Variable value was generated are only valid for automation data and in particular for device data; they are similar, but are slightly more generic than the description of data quality in the various fieldbus specifications.

Table 56 contains codes with BAD severity which indicates a failure.

Table 57 contains codes with UNCERTAIN severity which indicates that the value has been generated under sub-normal conditions.

Table 58 contains GOOD (success) codes.

Note again, that these are the codes that are specific for Data Access and supplement the codes that apply to all types of data which are defined in OPC 10000-4.

Table 56 – Operation level result codes for BAD data quality

 

Table 57 – Operation level result codes for UNCERTAIN data quality

 

Table 58 – Operation level result codes for GOOD data quality

 

7.3.3        LimitBits

The bottom 16 bits of the StatusCode are bit flags that contain additional information, but do not affect the meaning of the StatusCode. Of particular interest for DataItems is the LimitBits field. In some cases, such as sensor failure it can provide useful diagnostic information.

Servers that do not support Limit have to set this field to 0.

 

Annex A
(normative)

OPC COM DA to UA mapping

A.1       Introduction

This Annex provides details on mapping OPC COM Data Access (DA) information to OPC UA to help vendors migrate to OPC UA based systems while still being able to access information from existing OPC COM DA systems.

The OPC Foundation provides COM UA Wrapper and Proxy samples that act as a bridge between the OPC DA and the OPC UA systems.

The COM UA Wrapper is an OPC UA Server that wraps an OPC DA Server and with that enables an OPC UA Client to access information from the DA Server. The COM UA Proxy enables an OPC DA Client to access information from an OPC UA Server.

The mappings describe generic DA interoperability components. It is recommended that vendors use this mapping if they develop their own components, however, some applications can benefit from vendor specific mappings.

A.2       Security Considerations

COM DA relies on the Microsoft COM security infrastructure and does not specify any security parameters such as user identity. The developer of UA Wrapper and Proxy therefore has to consider the mapping of security aspects.

The COM UA Wrapper for instance can accept any Username/password and then try to impersonate this user by calling proper Windows services before connecting to the COM DA Server.

A.3       COM UA wrapper for OPC DA Server

A.3.1         Information Model mapping

A.3.1.1         General

OPC DA defines 3 elements in the address space: Branch, Item and Property. The COM UA Wrapper maps these types to the OPC UA types as described in Subclauses A.4.3.2 to A.4.3.4.

Figure A.12 – Sample OPC UA Information Model for OPC DA

 

A.3.1.2         Branch

DA Branches are represented in the COM UA Wrapper as Objects of FolderType.

The top-level branch (the root) should be represented by an Object where the BrowseName is the Server ProgId.

The OPC DA Address space hierarchy is discovered using the ChangeBrowsePosition from the Root and BrowseOPCItemIds to get the Branches, Items and Properties.

The name returned from the BrowseOPCItemIds enumString is used as the BrowseName and the DisplayName for each Branch. See also clause A.3.1.5.

The ItemId obtained using the GetItemID is used as a part of the NodeId for each Branch. See also clause A.3.1.5.

An OPC UA Folder representing a DA Branch uses the Organizes References to reference child DA Branches and uses HasComponent References for DA Leafs (Items). It is acceptable for customized wrappers to use a sub-type of these ReferenceTypes.

A.3.1.3         Item

DA items (leafs) are represented in the COM UA Wrapper as Variables. The VariableType depends on the existance of special DA properties as follows:

·     AnalogItemType: An item in the DA server that has High EU and Low EU properties or its EU Type property is Analog is represented as Variable of AnalogItemType in the COM UA Wrapper. The AnalogItemType has the following Properties:

o  EURange: The values of the High EU and Low EU properties of the DA Item are assigned to the EURange Property

o  EngineeringUnits: The value of the Engineering Unit property of the DA Item are assigned to the EngineeringUnits Property.

o  InstrumentRange: The values of the High IR and Low IR properties of the DA Item are assigned to the InstrumentRange Property

·     TwoStateDiscreteType: An item in DA server that has Open Label and Close Label properties is represented as Variable of TwoStateDiscreteType in the COM UA Wrapper. The TwoStateDiscreteType has the following Properties

o  TrueState: The value of the Close Label property of the DA item is assigned to the TrueState Property.

o  FalseState: The value of the Open Label property of the DA item is assigned to the FalseState Property.

·     MultiStateDiscreteType: An item in the DA server that has its EU Type property as enumerated is represented as Variable of MultiStateDiscreteType in the COM UA Wrapper. The MultiStateDiscreteType has the following Property:

o   EnumStrings: The enumerated values of the EUInfo Property of the DA item are assigned to the EnumStrings Property.

·      DataItemType: An item in the DA Server that is not any of the above types is represented as Variable of DataItemType in the COM UA Wrapper.

Below are mappings that are common for all item types

·      The name of the item in the DA Server is used as the BrowseName and the DisplayName for the Node in the COM UA Wrapper. See also clause A.3.1.5.

·      The ItemId in the DA server is used as a part of the NodeId for the Node. See also clause A.3.1.5.

·      TimeZone property in the DA server is represented by a TimeZone Property.

·      The Description property value in the DA server is assigned to the Description Attribute.

·      The DataType property value in the DA server is assigned to the DataType Attribute.

·      If the item in the DA server is an array, the ValueRank Attribute is set as OneOrMoreDimensions. If not, it is set to Scalar.

·      The AccessLevel Attribute is set with the AccessRights value in the DA server:

o   OPC_READABLE -> Readable

o   OPC_WRITABLE -> Writable

Note that the same values are also set for the UserAccessLevel in the COM UA Wrapper.

·      The ScanRate property value in the DA server is assigned to the MinimumSamplingInterval Attribute.

Any Properties added to a Node in the COM UA Wrapper are referenced using the HasProperty ReferenceType.

A.3.1.4         Property

A property in the DA server is represented in the COM UA Wrapper as a Variable with TypeDefinition as PropertyType.

The properties for an item are retrieved using the QueryAvailableProperties call in the DA server.

Below are mappings of the property details to the OPC UA Property:

·      The description of a property in the DA server is used as the BrowseName and the DisplayName of the Node in the COM UA Wrapper.

·      The PropertyID and ItemID (if they exist for the property) in the DA server are used as a part of the NodeID for the node in the COM UA Wrapper.

·      The DataType value in the DA server is used as value for the DataType Attribute of the Property in the COM UA Wrapper.

·      If the property value in the DA server is an array, the ValueRank Attribute of the Property is set to OneOrMoreDimensions. Otherwise, it is set to Scalar.

·      If the property has an ItemID in the DA server, then the AccessLevel attribute for the Node is set to ReadableOrWriteable. If not, it is set to Readable.

 

Table A.59 shows the mapping between the common OPC COM DA properties to the OPC UA Node attributes/properties.

Table A.59 – OPC COM DA to OPC UA Properties mapping

 

A.3.1.5         BrowseName and DisplayName Mapping

As described above, both the OPC UA Browsename and Displayname for Nodes representing COM DA Branches and Leafs are derived from the name of the corresponding item in the COM DA Server.

This name can only be acquired by using the COM DA Browse Services. In OPC UA, however, the BrowseName and DisplayName are Attributes that Clients can ask for at any time. There are several options to support this in a Wrapper but all of them have pros and cons. Here are some popular implementation options:

a.    Allow browsing the complete COM DA Address Space and then build and persist an offline copy of it. Resolve the BrowseName by scanning this offline copy.

o   Pro: The ItemID can be used as is for the OPC UA NodeId.

o   Con: The initial browse can take a while and can have to be repeated for COM DA Servers with a dynamic Address Space.

b.    Create OPC UA NodeId values that include both the COM DA ItemID and the Item name. When the OPC UA Client passes such a NodeId to read the BrowseName or DisplayName Attribute, the wrapper can easily extract the name from the NodeId value.

o   Pro: Efficient and reliable.

o   Con: The NodeId will not represent the ItemId. It becomes difficult for human users to match the two IDs.

c.    A number of COM DA Servers use ItemIDs that consist of a path where the path elements are separated with a delimiter and the last element is the item name. Wrappers can provide ways to configure the delimiter so that they can easily extract the item name.

o   Pro: Efficient and reliable. The ItemID can be used as is for the OPC UA NodeId.

o   Con: Not a generic solution. Only works for specific COM-DA Servers.

For wrappers that are custom to a specific Server, knowledge of the COM DA server address space can result in other optimizations or short cuts (i.e. the server will always have a certain schema / naming sequence etc.).

 

A.3.2         Data and error mapping

A.3.2.1         General

In a DA server, Automation Data is represented by Value, Quality and Time Stamp for a Tag.

The COM UA Wrapper maps the VQT data to the Data Value and Diagnostic Info structures.

The Error codes returned by the DA server are based on the HRESULT type. The COM UA Wrapper maps this error code to an OPC UA Status Code. Figure A.13 illustrates this mapping.

Figure A.13 – OPC COM DA to OPC UA data and error mapping

A.3.2.2         Value

The data values in the DA server are represented as Variant data type. The COM UA Wrapper converts them to the corresponding OPC UA DataType. The mapping is shown in Table A.60:

Table A.60 – DataTypes and mapping

.

A.3.2.3         Quality

The Quality of a Data Value in the DA server is represented as a 16 bit value where the lower 8 bits is of the form QQSSSSLL (Q: Main Quality, S: Sub Status, L: Limit) and higher 8 bits is vendor specific.

The COM UA Wrapper maps the DA server to the OPC UA Status code as shown in Figure A.14:

Figure A.14 – Status Code mapping

The primary quality is mapped to the Severity field of the Status code. The Sub Status is mapped to the SubCode and the Limit is mapped to the Limit Bits of the Status Code.

Please note that the Vendor quality is currently discarded.

Table A.61 shows a mapping of the OPC COM DA primary quality mapping to OPC UA status code

Table A.61 – Quality mapping

OPC DA Primary Quality (Quality & Sub status QQSSSS)	OPC UA Status Code
GOOD	Good
LOCAL_OVERRIDE	Good_LocalOverride
UNCERTAIN	Uncertain
SUB_NORMAL	Uncertain_SubNormal
SENSOR_CAL	Uncertain_SensorNotAccurate
EGU_EXCEEDED	Uncertain_EngineeringUnitsExceeded
LAST_USABLE	Uncertain_LastUsableValue
BAD	Bad
CONFIG_ERROR	Bad_ConfigurationError
NOT_CONNECTED	Bad_NotConnected
COMM_FAILURE	Bad_NoCommunication
DEVICE_FAILURE	Bad_DeviceFailure
SENSOR_FAILURE	Bad_SensorFailure
LAST_KNOWN	Bad_OutOfService
OUT_OF_SERVICE	Bad_OutOfService
WAITING_FOR_INITIAL_DATA	Bad_WaitingForInitialData

 

A.3.2.4         Timestamp

The Timestamp provided for a value in the DA server is assigned to the SourceTimeStamp of the DataValue in the COM UA Wrapper.

The ServerTimeStamp in the DataValue is set to the current time by the COM UA Wrapper at the start of the Read Operation.

A.3.3         Read data

The COM UA Wrapper supports performing Read operations to DA servers of versions 2.05a and 3.

For version 2.05a, the COM UA wrapper creates a Group using the IOPCServer::AddGroup method and adds the items whose data is to be read to the Group using IOPCItemMgmt::AddItems method. The Data is retrieved for the items using the IOPCSyncIO::Read method. The VQT for each item is mapped to the DataValue structure as shown in Figure A.13. Please note that only Read from Device is supported for this version. The “maxAge” parameter is ignored.

For version 3, the COM UA Wrapper uses the IOPCItemIO::Read to retrieve the data. The VQT for each item is mapped to the DataValue structure as shown in Figure A.13. The Read supports both the Read from Device and Cache and uses the “maxAge” parameter.

If there are errors for the items in the Read from the DA server, then these are mapped to the StatusCode of the DataValue in the COM UA Wrapper.

The mapping of the OPC COM DA Read Errors code to OPC UA Status code (in the COM UA Wrapper) is shown in Table A.62:

Table A.62 – OPC DA Read error mapping

OPC DA Error ID	OPC UA Status Code
OPC_E_BADRIGHTS	Bad_NotReadable
E_OUTOFMEMORY	Bad_OutOfMemory
OPC_E_INVALIDHANDLE	Bad_NodeIdUnknown
OPC_E_UNKNOWNITEMID	Bad_NodeIdUnknown
E_INVALIDITEMID	Bad_NodeIdInvalid
E_INVALID_PID	Bad_AttributeIdInvalid
E_ACCESSDENIED	Bad_OutOfService
Others	Bad_UnexpectedError

 

A.3.4         Write Data

The COM UA Wrapper supports performing Write operations to DA servers of versions 2.05a and 3.

For version 2.05a, the COM UA wrapper creates a Group using the IOPCServer::AddGroup method and adds the items whose data is to be written using IOPCItemMgmt::AddItems method. The value is written for the items using the IOPCSyncIO::Write method. Note that if the StatusCode or TimeStamps (Source or Server) is specified to be written for the item then the COM UA Wrapper returns a BadWriteNotSupported Status code for the item.

For version 3, the COM UA Wrapper uses the IOPCItemIO::WriteVQT data including StatusCode and TimeStamp. If a SourceTimeStamp is provided, this timestamp is used for the Write else the ServerTimeStamp is used.

If there are errors for the items in the Write from the DA server, then these are mapped to the StatusCode for the corresponding item.

The mapping of the OPC COM DA Write Errors code to OPC UA Status code (in the COM UA Wrapper) is shown in Table A.63:

Table A.63 – OPC DA Write error code mapping

OPC DA Error ID	OPC UA Status Code
E_BADRIGHTS	Bad_NotWritable
DISP_E_TYPEMISMATCH	Bad_TypeMismatch
E_BADTYPE	Bad_TypeMismatch
E_RANGE	Bad_OutOfRange
DISP_E_OVERFLOW	Bad_OutOfRange
E_OUTOFMEMORY	Bad_OutOfMemory
E_INVALIDHANDLE	Bad_NodeIdUnknown
E_UNKNOWNITEMID	Bad_NodeIdUnknown
E_INVALIDITEMID	Bad_NodeIdInvalid
E_INVALID_PID	Bad_NodeIdInvalid
E_NOTSUPPORTED	Bad_WriteNotSupported
S_CLAMP	Good_Clamped
Others	Bad_UnexpectedError

 

A.3.5         Subscriptions

A subscription is created in the DA server when a MonitoredItem is created in the COM UA Wrapper.

The SamplingInterval and the Deadband value are used for the subscription to setup a periodic data change call back on the COM UA Wrapper. Note that only the PercentDeadbandType is supported by the COM UA Wrapper.

The VQT for each item is mapped to the DataValue structure as shown in Figure A.13 and published to the client by the COM UA Wrapper periodically.

The mapping of the OPC COM DA Read Errors code to OPC UA Status code (in the COM UA Wrapper) is the same as the Read mapping in Figure A.13.

A.4       COM UA proxy for DA Client

A.4.1         Guidelines

The Data Access COM UA Proxy is a COM Server combined with a UA Client. It maps the Data Access address space of UA Data Access Server into the appropriate COM Data Access objects.

Clauses A.4.1 through A.4.6 identify the design guidelines and constraints used to develop the Data Access COM UA Proxy provided by the OPC Foundation. In order to maintain a high degree of consistency and interoperability, it is strongly recommended that vendors, who choose to implement their own version of the Data Access COM UA Proxy, follow these same guidelines and constraints.

The Data Access COM Client simply needs to address how to connect to the UA Data Access Server. Connectivity approaches include the one where Data Access COM Clients connect to a UA Data Access Server with a CLSID just as if the target Server were a Data Access COM Server. However, the CLSID can be considered virtual since it is defined to connect to intermediary components that ultimately connect to the UA Data Access Server. Using this approach, the Data Access COM Client calls co-create instance with a virtual CLSID as described above. This connects to the Data Access COM UA Proxy components. The Data Access COM UA Proxy then establishes a secure channel and session with the UA Data Access Server. As a result, the Data Access COM Client gets a COM Data Access Server interface pointer.

A.4.2         Information Model and Address Space mapping

A.4.2.1         General

OPC UA defines 8 Node Class types in the address space Object, Variable, Method, ObjectType, VariableType, ReferenceType, DataType, View. The COM UA Proxy maps only the nodes of Node Class types Object, Variable to the OPC DA types as shown in the figure below. Only the nodes under the Objects node are considered for the COM UA Proxy address space and others such as Types, Views are not mapped.

Figure A.15 shows an example mapping of OPC DA to OPC UA information.

Figure A.15 – Sample OPC DA mapping of OPC UA Information Model and Address Space

A.4.2.2         Object Nodes

A node of Object Node class in the OPC UA server is represented in the Data Access COM UA Proxy as a Branch.

The root of the Data Access COM UA Proxy is the Objects folder of the OPC UA Server.

The OPC UA Address space hierarchy is discovered using the Browse Service for the Objects Node using the following filters:

·      BrowseDirection as Forward

·      ReferenceTypeId as Organizes and HasChild.

·      IncludeSubtypes as True

·      NodeClassMask as Object and Variable

The DisplayName of the OPC UA node is used as the Name for each Branch in the Data Access COM UA Proxy

Each Branch in the Data Access COM UA Proxy is assigned 3 properties:

·      UA Browse Name (Property ID: 613): The value of the BrowseName attribute of the node in the OPC UA Server is assigned to this property.

·      UA Description (Property ID: 614): The value of the Description attribute of the node in the OPC UA Server is assigned to this property, if a Description attribute is provided.

·      Item Description (Property ID: 101): The value of the DisplayName attribute of the node in the OPC UA Server is assigned to this property.

NOTE COM DA Clients typically display the ItemID and the Item Description. Since the ItemID generated by the UA Proxy can be particularly difficult to read and understand, proxies can use the DisplayName as value for the Item Description Property as it will be easier to understand by a human user.

 

A.4.2.3         Variable Nodes

A node of Variable Node class in the OPC UA server is represented in the Data Access COM UA Proxy as an Item.

The DisplayName of the OPC UA node is used as the Name for each Item in the Data Access COM UA Proxy.

The NodeId of the OPC UA node is used as the ItemId for each Item in the Data Access COM UA Proxy. But the ‘=’ character is replaced with ‘-’ in the string. E.g. NodeId: ns=4,i=10, ItemID = “ns-4;i-10” or NodeId: ns=4,s=FL102, ItemID = “ns-4,s-FL102”

Each Item in the Data Access COM UA Proxy is assigned the following properties based on the node attributes or its references:

Standard Properties:

·      Item Canonical Data Type (Property ID: 1): The combined value of the DataType attribute and the ValueRank attribute of the node in the OPC UA Server is assigned to this property (see A.4.3.2).

·      Item Value (Property ID: 2): The value of the Value attribute of the node in the OPC UA Server is assigned to this property. Details on Value mapping are in A.4.3.2

·      Item Quality (Property ID: 3): The StatusCode of the Value obtained for the node in the OPC UA Server is assigned to this property. Details on Quality mapping are in A.4.3.3

·      Item Timestamp (Property ID: 4): The SourceTimestamp or ServerTimestamp of the Value obtained for the node in the OPC UA Server is assigned to this property. Details on Timestamp mapping are in A.4.3.4

·      Item Access Rights (Property ID: 5): The value of the AccessLevel attribute of the node in the OPC UA Server is assigned to this property based on the following mapping:

o   CurrentRead -> OPC_READABLE

o   CurrentWrite -> OPC_WRITABLE

The other AccessLevel provided by OPC are ignored

·      Server Scan Rate (Property ID: 6): The value of the MinimumSamplingInterval attribute of the node in the OPC UA Server is assigned to this property.

·      Item EU Type (Property ID: 7): The EU Type value is assigned based on the references of the node in the OPC UA Server:

·     Analog(1) : if the node in the OPC UA Server references a EURange property node, then it is assigned the Analog EU Type.

·     Enumerated(2): if the node in the OPC UA Server references a EnumStrings property node, then it is assigned the Enumerated EU Type.

·     Empty(0): For a node in the OPC UA Server that does not meet above criteria, the type is set as 0 (Empty)

·      EU Info (Property ID: 8): if the node in the OPC UA Server references an EnumStrings property node, then the enumerated values of the property node is assigned to this property.

·      EU Units (Property ID: 100): if the node in the OPC UA Server references a EngineeringUnits property node, then the value of the EngineeringUnits property node is assigned the EU Units property.

·      Item Description (Property ID: 101): The value of the DisplayName attribute of the node in the OPC UA Server is assigned to this property.

·      High EU (Property ID: 102): if the node in the OPC UA Server references a EURange property node, then the ‘High’ value of the property node is assigned to this property.

·      Low EU (Property ID: 103): if the node in the OPC UA Server references a EURange property node, then the ‘Low’ value of the property node is assigned to this property.

·      High Instrument Range (Property ID: 104): if the node in the OPC UA Server references an InstrumentRange property node, then the ‘High’ value of the property node is assigned to this property.

·      Low Instrument Range (Property ID: 105): if the node in the OPC UA Server references an InstrumentRange property node, then the ‘Low’ value of the property node is assigned to this property.

·      Contact Close Label (Property ID: 106): if the node in the OPC UA Server references a FalseState property node, then the value of the property node is assigned to this property.

·      Contact Open Label (Property ID: 107): if the node in the OPC UA Server references a TrueState property node, then the value of the property node is assigned to this property.

·      Item Time Zone (Property ID: 108): if the node in the OPC UA Server references a TimeZone property node, then the ‘Offset’ value of the property node is assigned to this property.

New Properties:

·      UA BuiltIn Type (Property ID: 610): The identifier value of the DataType node associated with the DataType attribute of the node in the OPC UA Server is assigned to this property.

·      UA Data Type Id (Property ID: 611): The complete NodeId value (namespace and identifier) of the DataType node associated with the DataType attribute of the node in the OPC UA Server is assigned to this property.

·      UA Value Rank (Property ID: 612): The value of the ValueRank attribute of the node in the OPC UA Server is assigned to this property.

·      UA Browse Name (Property ID: 613): The value of the BrowseName attribute of the node in the OPC UA Server is assigned to this property.

·      UA Description (Property ID: 614): The value of the Description attribute of the node in the OPC UA Server is assigned to this property.

 

A.4.2.4         Namespace Indices

For generating ItemIDs, the Proxy uses Namespace Indices. To assure that Clients can persist these ItemIDs, the Namespace Indices must never change. To accomplish this the Proxy has to persist its Namespace Table and only append entries but never change existing ones.

The Proxy also has to provide a translation from the current Namespace Table in the Server to the persisted Namespace Table.

If you move or copy the Proxy to another machine, the Namespace Table has to be copied to this machine as well.

 

A.4.3         Data and error mapping

A.4.3.1         General

In an OPC UA Server, Automation Data is represented as a Data Value and and status, in addition additional error data can be provided via Diagnostic Info for a tag

The COM UA Proxy maps the Data Value structure into VQT data and error code.

For successful operations(StatusCode of Good and Uncertain), the COM UA Proxy maps the Status Code of the DataValue to the OPC DA Quality But in case of error(StatusCode of Bad), the Status Code is mapped to the OPC DA Error code.

The StatusCode in the Diagnostic Info returned by the OPC UA Server are mapped to OPC DA Error codes. Figure A.16 illustrates this mapping.

 

Figure A.16 – OPC UA to OPC DA data & error mapping

A.4.3.2         Value

The COM UA Proxy converts the OPC UA Data Value to the corresponding OPC DA Variant type. The mapping is shown in Table A.64. For DataTypes that are subtypes of an existing base DataType the conversion for the Base DataType is used.

Table A.64 – DataTypes and Mapping

 

A.4.3.3         Quality

The Quality of a Data Value in the OPC UA Server is represented as a StatusCode.

The COM UA Proxy maps the Severity, Subcode and the limit bits of the OPC UA Status code to the lower 8 bits of the OPC DA Quality structure (of the form QQSSSSLL). Figure A.17 illustrates this mapping.

Figure A.17 – OPC UA Status Code to OPC DA quality mapping

The Severity field of the Status code is mapped to the primary quality. The SubCode is mapped to the Sub Status and the Limit Bits are mapped to the Limit field.

Table A.65 shows a mapping of the OPC UA status code to OPC DA primary quality

Table A.65 – Quality mapping

OPC UA Status Code	OPC DA Primary Quality (Quality & Sub status QQSSSS)
Good	GOOD
Good_LocalOverride	LOCAL_OVERRIDE
Uncertain	UNCERTAIN
Uncertain_SubNormal	SUB_NORMAL
Uncertain_SensorNotAccurate	SENSOR_CAL
Uncertain_EngineeringUnitsExceeded	EGU_EXCEEDED
Uncertain_LastUsableValue	LAST_USABLE
Bad	BAD
Bad_ConfigurationError	CONFIG_ERROR
Bad_NotConnected	NOT_CONNECTED
Bad_NoCommunication	COMM_FAILURE
Bad_OutOfService	OUT_OF_SERVICE
Bad_DeviceFailure	DEVICE_FAILURE
Bad_SensorFailure	SENSOR_FAILURE
Bad_WaitingForInitialData	WAITING_FOR_INITIAL_DATA

 

A.4.3.4         Timestamp

If available, the SourceTimestamp of the DataValue in the OPC UA Server is assigned to the Timestamp for the value in the COM UA Proxy. If SourceTimestamp is not available, then the ServerTimestamp is used.

A.4.4         Read data

The COM UA Proxy converts all the ItemIds in the Read into valid NodeIds by replacing the ‘-’ with ‘=’ and calls the OPC UA Read Service for the Value Attribute.

If the Read Service call is successful then DataValue for each node is mapped to the VQT for each item as shown in Figure A.16.

If the Read Service call fails or If there are errors for some of the Nodes, then the StatusCodes of these Nodes are mapped to the error code by the COM UA Proxy.

The mapping of the OPC UA Status code to OPC DA Read Error code (in the COM UA Proxy) is shown in Table A.66:

Table A.66 – OPC UA Read error mapping

OPC UA Status Code	OPC DA Error ID
Bad_OutOfMemory	E_OUTOFMEMORY
Bad_NodeIdInvalid	E_INVALIDITEMID
Bad_NodeIdUnknown	E_UNKNOWNITEMID
Bad_NotReadable	E_BADRIGHTS
Bad_UserAccessDenied	E_ACCESSDENIED
Bad_AttributeIdInvalid	E_INVALIDITEMID
Bad_UnexpectedError	E_FAIL
Bad_InternalError	E_FAIL
Bad_SessionClosed	E_FAIL
Bad_TypeMismatch	E_BADTYPE

 

A.4.5         Write data

The COM UA Proxy converts all the ItemIds in the Write into valid NodeIds by replacing the ‘-’ with ‘=’. It converts the Value, Quality and Timestamp (VQT) to a DataValue structure as per the mapping in Figure A.16. and calls the OPC UA Write Service for the Value Attribute.

If the Write Service call fails or if there are errors for some of the Nodes, then the StatusCodes of these Nodes are mapped to the error code by the COM UA Proxy.

The mapping of the OPC UA Status code to OPC DA Write Error code (in the COM UA Proxy) is shown in Table A.67:

Table A.67 – OPC UA Write error code mapping

OPC UA Status Code	OPC DA Error ID
Bad_TypeMismatch	E_BADTYPE
Bad_OutOfMemory	E_OUTOFMEMORY
Bad_NodeIdInvalid	E_INVALIDITEMID
Bad_NodeIdUnknown	E_UNKNOWNITEMID
Bad_NotWritable	E_BADRIGHTS
Bad_UserAccessDenied	E_ACCESSDENIED
Bad_AttributeIdInvalid	E_UNKNOWNITEMID
Bad_WriteNotSupported	E_NOTSUPPORTED
Bad_OutOfRange	E_RANGE

 

A.4.6         Subscriptions

The COM UA Proxy creates a Subscription in the OPC UA Server when a Group is created. The Name, Active flag, UpdateRate parameters of the Group are used while creating the subscription.

The COM UA Proxy Creates Monitored Items in the OPC UA Server when items are added to the Group.

Following parameters and filters are used for creating the monitored items:

·      The ItemIds are converted to valid NodeIds by replacing the ‘-’ with ‘=’.

·      Data Change Filter is used for Items with EU type as Analog:

·     Trigger = STATUS_VALUE

·     If DeadBand value is specified for the Group, the;

o   DeadbandType = Percent

o   DeadbandValue = deadband specified for the group.

The COM UA Proxy calls the Publish Service of the OPC UA Server periodically and sends any data changes to the client.

 

 

                                                                            Annex B
(normative)

UCUM Symbols

B.1       Introduction - License

This Annex provides an excerpt from the UCUM Specification available at https://ucum.org.

The Unified Code for Units of Measure (UCUM), also known as the “UCUM Specification”, is copyright ©1999-2021, Regenstrief Institute, Inc. All rights reserved.

The UCUM license is available in https://ucum.org/license. This license includes a disclaimer of warranties.

 

B.2       Representation

UCUM can represent any number of valid units derived from 7 basic units. To that end, the standard combines various components:

·      Basic units

o   metre (m, length)

o   second (s, time)

o   gram (g, mass)

o   radian (rad, angle)

o   Kelvin (K, temperature)

o   Coulomb (C, electric charge)

o   candela (cd, luminous intensity)

·      derived units with conversion factors and formulas for the reduction to base units

·      prefixes, i.e. a list of 30 standard prefixes to generate multiples (e.g. k for kilo, multiplier 10³) or fractions (e.g. d for deci, multiplier 10-1) of measurement units

·      symbols and operators as well as syntax rules for their combination as follows:

 

<sign>	::=	“+” | “-”
<digit>	::=	“0” | “1” | “2” | “3” | “4” | “5” | “6” | “7” | “8” | “9”
<digits>	::=	<digit><digits> | <digit>
<factor>	::=	<digits>
<exponent>	::=	<sign><digits> | <digits>
<simple-unit>	::=	<ATOM-SYMBOL> | <PREFIX-SYMBOL><ATOM-SYMBOL[metric]>
<annotatable>	::=	<simple-unit><exponent> | <simple-unit>
<component>	::=	<annotatable><annotation> | <annotatable> | <annotation> | <factor> | “(”<term>“)”
<term>	::=	<term>“.”<component> | <term>“/”<component> | <component>
<main-term>	::=	“/”<term> | <term>
<annotation>	::=	“{”<ANNOTATION-STRING>“}”

 

 

B.3       Tables of terminal symbols

B.3.1         General

The following tables define prefixes and unit symbols. The columns define:

–     The UCUM representation (Symbol (c/s))

–     The full name (Display Name)

–     The Print Symbol – recommended for display and printing

–     Value (for prefixes) is the scalar value by which the unit atom is multiplied if combined with the prefix.

–     Kind of Quantity (for units) is the quantity name.

Full name and print symbol are defined by other bodies and are out of scope of The Unified Code for Units of Measure.

B.3.2         Prefixes

 

 

 

 

B.3.3         Base units

The base units are used to define all the unit atoms of The Unified Code for Units of Measure according to its grammar and semantics.

The selection of the base and the order of the units in the base are not normative. Any other base is acceptable as long as there is an isomorphism between the group of units generated by the other base system and this one. All base units are metric.

 

B.3.4         Derived unit atoms

 

 

 

 

 

 

 

 

 

 

B.3.5         Customary unit atoms

.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

B.3.6         Other legacy units

 

 

 

 

 

 

.

 

 

 

 

 

 

 

 

                                                                            Annex C
(informative)

Outline of Syntax References

C.1       UCUM syntax reference

 

Type	Language / syntactical evaluation of unit expressions
Coverage	Unlimited / is able to express any imaginable unit of measure
Hosted by	Regenstrief Institute
Homepage	https://ucum.org

 

UCUM (Unified Code for Units of Measure) can represent any unit used in science, engineering a business for electronic communication. It provides a single coding system for units that is complete, free of all ambiguities, and that assigns to each defined unit a concise semantics.

UCUM makes use of atomic expressions representing well known base units and a syntax used to combine these atoms to more complex units if needed.

The SI/ISQ as well as other unit systems system allows an unlimited number of possible unit expressions for a single unit. UCUM is able to clearly identify a unit no matter what unit expression is used for it.

UCUM is a recognized standard in a wide field of applications and is recommended or incorporated by other standards for example the medical field (HL7, DICOM, ISO 11240), or geosciences (WMS, GML)

UCUM defines

·      atomic symbols for the 7 base units of the SI / ISQ System

·      symbols for prefixes used with atomic units

·      a large list of symbols used for named, atomic, non-SI units

·      a syntax description defining the rules used to combine the defined atomic symbols to express complex units

 

C.2       QUDT syntax reference

 

Type	Ontology
Coverage	Limited / around 1750 Units originating from 10 systems of units for 880 quantity kinds
Hosted by	public charity non-profit organization
Homepage	https://qudt.org https://github.com/qudt/qudt-public-repo

 

The QUDT ontology includes

·      physical constants, quantity kinds, units, unit systems, prefixes and dimension vectors

·      a semantic description of the named entries including the relation to other entries

·      translations to other standards of unit description

QUDT is modelled in OWL (Web Ontology Language). Other descriptions and interfaces are available like RDF/XML, TURTLE, JSON or SPARQL.

QUDT not only focuses on defining models and a publicly available vocabulary to express quantities and units but also wants to offer a translation between existing standards doing the same. Therefore, the ontology also names UCUM, UNECE, IEC 61360 and LaTeX codes for the entries.

QUDT originated from a NASA project trying to define a semantic specification for units of measure, quantity kind and dimensions used in science and engineering. Today it is governed by a board of directors from different research institutes and the industry.

Quantity examples:

Unit examples:

 

C.3       UNECE syntax reference

 

Type	Dictionary
Coverage	A single list of code elements for units of measure for use worldwide in administration, commerce, transport, science and technology.
Hosted by	The United Nations, through its Centre for Trade Facilitation and Electronic Business (UN/CEFACT).
Homepage	https://www.unece.org/cefact/

 

The United Nations Economic Commission for Europe through its UN Centre for Trade Facilitation and Electronic Business (https://www.unece.org/cefact/), develops, maintains and publishes for free of charge a number of code lists.

Recommendation 20 provides three character alphabetic and alphanumeric codes for representing units of measurement for length, area, volume/capacity, mass (weight), time, and other quantities used in international trade. The codes are intended for use in manual and/or automated systems for the exchange of information in administration, commerce, transport, science and technology.

The code list (see https://unece.org/trade/cefact/UNLOCODE-Download) is presented in three separate annexes:

·      Annex I – Code elements listed by quantity category;

·      Annex II – Code elements listed by unit of measure name; and

·      Annex III – Code elements listed by common code.

See 5.6.3.4 how this information is mapped to Properties of DataType EUInformation.

Unit examples:

 

C.4       IEC CDD syntax reference

 

Type	Dictionary
Coverage	A registry for metadata used for classification and description of products in all industrial/technical domains.
Hosted by	International Electrotechnical Commission (IEC)
Homepage	https://cdd.iec.ch/

 

The IEC Common Data Dictionary (CDD) is a registry for metadata used for classification and description of products in all industrial/technical domains.

The data model is described in IEC 61360. The dictionary includes quantities and units that are described in IEC 62720 - Identification of units of measurement for computer-based processing.

It covers any standard or non-standard units of measure currently in use, in two or more distinct ethno-linguistic groups or nations, at least in one domain of industry, for which an explicit method of conversion to a known standard unit of measure or its equivalent is well documented or evident from external references.

Quantity examples:

IRDI	Symbol	Name
0112/2///62720#UAD002#001	---	acceleration
0112/2///62720#UAD107#001	---	mass flow rate

Unit examples:

IRDI	Symbol	Name
0112/2///62720#UAB044#001	in/s2	inch per second squared
0112/2///62720#UAA497#001	g/s	gram per second

 

C.5       LATEX_SIUNITX syntax reference

 

Type	Typesetting Rules
Coverage	Limited / Focuses on the SI units and provides rules to create complex units
Hosted by	Joseph Wright
Homepage	siunitx is free at https://ctan.org/pkg/siunitx https://www.texdev.net/

 

The siunitx package is a set of tools for the software system LaTeX. It is used to typeset pysical quantities from the SI. The package has an extended set of configuration options which make it possible to follow varying typographic conventions with the same input syntax.

Unit examples:

 

 

Bibliography

UCUM: Unified Code for Units of Measure
            https://ucum.org

QUDT: Quantities, Units, Dimensions and Data Types Ontologies
            https://qudt.org
            https://github.com/qudt/qudt-public-repo

UNECE: Recommendation N° 20, Codes for Units of Measure Used in International Trade
            https://unece.org/trade/cefact/UNLOCODE-Download

IEC CDD: IEC Common Data Dictionary
            https://cdd.iec.ch/

LATEX_SIUNITX: A comprehensive (si) units package
            https://ctan.org/pkg/siunitx
            https://www.texdev.net/

 

______________