.NET Based OPC UA Client/Server SDK
3.1.1.506
|
The following page describes the concepts for OPC UA data types.
OPC UA variables, methods and events are used to exchange application specific data as variable value, method arguments or event fields. Such application specific data can use different DataTypes. The ValueRank is defined in addition to indicate if the DataType is used as scalar value (-1), as array (1) or as multidimensional array (>1).
DataTypes are exposed as nodes in the server address space. These nodes build a type hierarchy with the BaseDataType as root of the DataType hierarchy.
OPC UA defines 24 so called built-in DataTypes. These built-in DataTypes are either simple DataTypes like Boolean, floating point types, integer types, string or they are structures like NodeId that are used in OPC UA services.
Built-in DataType | Description |
---|---|
Boolean | A value that is either TRUE or FALSE |
SByte | One byte signed integer between −128 and 127 inclusive. |
Byte | One byte unsigned integer in the range of 0 to 255 inclusive. |
Int16 | Two byte (16-bit) signed integer between −32 768 and 32 767 inclusive. |
UInt16 | Two byte (16-bit) unsigned integer in the range of 0 to 65 535 inclusive. |
Int32 | Four byte (32-bit) signed integer between −2 147 483 648 and 2 147 483 647 inclusive. |
UInt32 | Four byte (32-bit) unsigned integer in the range of 0 to 4 294 967 295 inclusive. |
Int64 | Eight byte (64-bit) signed integer between −9 223 372 036 854 775 808 and 9 223 372 036 854 775 807 inclusive. |
UInt64 | Eight byte (64-bit) unsigned integer in the range of 0 to 18 446 744 073 709 551 615 inclusive. |
Float | Four byte floating point value that adheres to the ISO/IEC/IEEE 60559:2011 single precision data type definition. |
Double | Eight byte floating point value that adheres to the ISO/IEC/IEEE 60559:2011 double precision data type definition. |
String | Unicode character string that should exclude control characters that are not white-spaces. |
DateTime | Date and time represented as 64-bit signed integer which represents the number of 100 nanosecond intervals since January 1, 1601 (UTC). |
Guid | 128-bit Globally Unique Identifier. |
ByteString | Sequence of Byte values with length information. |
XmlElement | DataType used to transport XML elements. |
ExtensionObject | Used to transport structure DataTypes. The ExtensionObject contains the encoding NodeId of the structure DataType and the structure as blob encoded in the requested format. |
NodeId | Globally unique identifier for a Node in the OPC UA server address space. See OPC UA NodeIds for more details. The DataType is mainly used in OPC UA services. |
ExpandedNodeId | Extended NodeId used to refer to Nodes in other OPC UA Servers. The DataType is mainly used in OPC UA services. |
StatusCode | Four byte numerical value that is used to report the overall result of an operation performed by an OPC UA server. StatusCodes are defined by the OPC UA specification. Application specific StatusCodes are not allowed. The DataType is mainly used in OPC UA services. |
QualifiedName | Qualified name that consists of a name and a namespace. The name part of the QualifiedName is restricted to 512 characters. The DataType is mainly used in OPC UA services. |
LocalizedText | Localized text that consists of the text in a locale-specific translation and the identifier for the locale. The DataType is mainly used in OPC UA services. |
DataValue | Structure used to transport values of variables together with a StatusCode and timestamps. The DataType is only used in OPC UA services. |
DiagnosticInfo | Structure used to provide additional optional diagnostic information for an operation performed by an OPC UA server. The DataType is only used in OPC UA services. |
These built-in DataTypes are transported on the wire in a Variant union. This includes arrays or multidimensional arrays of the built-in DataTypes.
Any other OPC UA or application defined DataType can be transported using one of these built-in DataTypes. This is described in the next section.
Any subtype of simple types like Duration (subtype of Double) is represented as the corresponding built-in type on the wire.
There are three DataTypes (Enumerations, OptionSets and Structures), where application specific sub-types define the semantic of the DataType and its values. The data is transported as one of the built-in DataTypes but the client need to read additional information from the server type system to get the semantic.
Enumeration DataTypes are transported as 32 bit signed integer built-in DataType. The name of the different enumeration values are exposed as EnumStrings property of the Enumeration DataType.
OptionSet DataTypes (bit masks) are transported as one of the unsigned integer built-in DataTypes. The name of the bits in the bit mask is exposed as OptionSetValues property of the OptionSet DataType.
Structure DataTypes are transported with the special built-in DataType ExtensionObject. An ExtensionObject contains the encoding NodeId of the structure DataType and the structure as blob encoded in the requested format e.g. OPC UA Binary.
The encoding NodeId is provided by an object of type DataTypeEncodingType. This object is referenced by the structure DataType with a non-hierarchical HasEncoding reference. The browse name of this object for OPC UA Binary encoding is 'Default Binary'. A server may support other encodings like JSON encoding. In this case, the server references more than one encoding object from the structure DataType node.
The fields of the structure DataType are described by the value of the DataTypeDefinition attribute of the structure DataType node (e.g. MyStruct).
The DataTypeDefinition attribute was introduced in OPC UA 1.04 and provides a simplified option to get access to the meta-data of a structure DataType. It is also provided for Enumeration and OptionSet DataTypes.
The DataTypeDefinition Attribute contains either a structureDefinition or an EnumDefinition. The following table contains the description of the SsructureDefinition DataType.
Fields of the structureDefinition DataType
Structure field name | Structure field DataType | Description |
---|---|---|
DefaultEncodingId | NodeId | The NodeId of the default DataTypeEncoding for the DataType. The default depends on the message encoding, Default Binary for UA Binary encoding, Default JSON for JSON encoding and Default XML for XML encoding. |
BaseDataType | NodeId | The NodeId of the direct super-type of the DataType. This might be the abstract structure or the Union DataType. |
StructureType | Enum StructureType | An enumeration that specifies the type of structure defined by the DataType. Options are structure (A structure without optional fields), structureWithOptionalFields (A structure with optional fields) and Union (A Union DataType). Only one of the fields defined for the data type is encoded into a value if the data type is a Union. |
Fields | StructureField [] | The list of fields that make up the data type. This definition assumes the structure has a sequential layout. For structures derived from another structure DataType this list starts with the fields of the BaseDataType followed by the fields of this StructureDefinition. |
Fields of the StructureField DataType
Structure field name | Structure field DataType | Description |
---|---|---|
Name | String | A name for the field that is unique within the StructureDefinition. |
Description | LocalizedText | A localized description of the field. |
DataType | NodeId | The NodeId of the DataType for the field. |
ValueRank | Int32 | The value rank for the field. It shall be Scalar (-1) or a fixed rank Array (>=1). |
ArrayDimensions | UInt32[] | This field specifies the maximum supported length of each dimension. If the maximum is unknown the value shall be 0. The number of elements shall be equal to the value of the valueRank field. This field shall be null if valueRank ≤ 0. The maximum number of elements of an array transferred on the wire is 2147483647 (max Int32). |
MaxStringLength | UInt32 | If the DataType field is a String or ByteString then this field specifies the maximum supported length. If the maximum is unknown the value shall be 0. If the DataType field is not a String or ByteString the value shall be 0. If the valueRank is greater than 0 this field applies to each element of the array. |
To encode or decode data in or from an ExtensionObject, the application needs to have the list of fields in the structure DataType. If a structure field has a built-in DataType, the corresponding encoding or decoding can be used. If a structure field is again a structure, the fields of this structure must be decoded with the rules for the contained built-in DataType.
The older and deprecated way to expose the description of structure DataTypes in an OPC UA server address space is a DataTypeDictionary.
The DataTypeDictionary is a XML file that is provided by a variable of type DataTypeDictionaryType. The value of the variable contains the XML document. In the example above, this is the variable with the name 'MyDictionary'.
The following example shows a dictionary XML file with two structure DataTypes.
The list of DataTypeDictionaries for OPC UA Binary encoding can be found below Types > DataTypes > OPC Binary.
The relation of a structure DataType to a DataTypeDictionary is created by a chain of OPC UA References from the
The value of the DataTypeDescriptionType variable matches the name of the structure DataType description in the XML document that is the value of the Dictionary variable. This is normally also the name of the DataType Node and the name of the DataTypeDescriptionType variable.
An OPC UA client that is able to handle structure DataTypes must build a type cache to do the time consuming discovery of the DataType description only once during a working Session with an OPC UA server. After the creation of a new Session, the type cache must be updated.
For each structure DataType, the cache consists of two NodeIds and the DataType description
One strategy is to read all descriptions after Session creation with the following steps
If the DataTypeDefinition is present
If the DataTypeDefinition is not present
The next chapter describes the OPC UA Namespaces.