OPC UA Custom Data Types
OPC UA Custom Data Types
Instead of being limited to the predefined generic data types provided by the OPC UA, system integrators can create their own structures and unions that exactly reflect the specific data and relationships within their environment.
Benefits of Using Custom Data Types
In OPC UA, custom data types are defined through the use of custom structures and unions. A structure in OPC UA is analogous to a structure in many programming languages: it is a user-defined data type containing multiple fields (or members), each of which has its own data type. Structures let related pieces of data be grouped together into a single cohesive unit.
For example, consider the following custom data structure that can be used to control a robot arm:
| Field Name | Data Type | Description |
|---|---|---|
| CommandID | String | A unique identifier for tracking this command (e.g., “CMD_00123”). |
| TargetPosition | SubStructure (e.g. Position3D) | The 3D coordinates or pose the robot should move to. A sub-structure that could include X, Y, Z, and orientation. |
| Speed | Float | The desired movement speed (e.g. in mm/s or degrees/s). |
| Acceleration | Float | The desired acceleration limit (e.g. in mm/s²). |
| OperationMode | UInt16 | Specifies the type of operation, for example: 0 = MoveToPosition; 1 = Home; 2 = JointControl; 3 = ErrorRecovery (etc.) |
| ToolID | String | If the robot has multiple end-effectors, this indicates which tool is in use. |
| OverrideFlags | UInt32 (Bit Mask) | Bitmask or flags for special overrides (e.g. collision avoidance override, safety override). |
Although the same control data set could be represented as individual OPC UA variables, grouping them into a single custom structure has some advantages. Firstly, the values can then be read or written at once as a single OPC UA variable node value. For this example, this ensures that the robot either receives the atomic, consistent set of instructions at once or not at all, which helps avoid partial updates or mismatched parameters. Secondly, the clients can subscribe to the entire data structure and therefore receive updates when any of the members change, which usually is more resource-efficient than subscribing to each variable individually.
In OPC UA, the structure members can also be optional, meaning that the member can be omitted from the structure when it is not needed. This is useful when the structure is used in multiple contexts and some members are not always needed. For example, the ToolID member in the robot arm command structure might be optional if the robot only has one end-effector.
Unions are similar to structures, but only one member value is stored at a time. This is useful when there is a set of related data that can only be one of several types. For example, a robot arm might have a union that can be either a Cartesian position or a joint position, but not both at the same time. The union has a SwitchField property, whose value is a 1-based index of the active member in the member list, that is used to select which union member is active at any time.
Using OPC UA Custom Data Types in CDP
To utilize custom data types in CDP, a suitable custom data type variable must be added to the configuration:
| Variable in OPC-UA-Server | Variable in OPC-UA-Client | Description |
|---|---|---|
| ServerVariableNodeStruct | ClientVariableNodeStruct | A variable of custom data structure. Structures consist of a set of related data fields (i.e. members) that can be of different data types. |
| ServerVariableNodeUnion | ClientVariableNodeUnion | A variable of custom data union. Unions are similar to structures, but they only store one value at a time. This is useful when there is a set of related data that can only be one of several types. A SwitchField property in the union, whose value is a 1-based index of the active member in the member list, is used to select which union member is active at any time. |
| ServerVariableNodeStruct1DArray | ClientVariableNodeStruct1DArray | A variable that is an one-dimensional array of custom data structures of the same type. |
| ServerVariableNodeUnion1DArray | ClientVariableNodeUnion1DArray | A variable that is an one-dimensional array of custom data unions of the same type. |
Under the OPC UA variable node, the following elements can be added to define the members of the custom data type:
| Element Type in OPC-UA-Server | Element Type in OPC-UA-Client | Description |
|---|---|---|
| CustomMember<type> | Member<type> | A member having simple data type like bool, char, unsigned char, short, unsigned short, int, unsigned int, int64_t, uint64_t, float, double, or string. This member value can then be used in other parts of the CDP system value in any way needed. |
| CustomMember1DArray<type> | Member1DArray<type> | A one-dimensional array of simple data type like bool, char, unsigned char, short, unsigned short, int, unsigned int, int64_t, uint64_t, float, double, or string. The required number of Channel<type> elements can be added to the array that act as the elements of the array and their value can then be used in other parts of the CDP system value in any way needed. |
| CustomSubStruct | SubStruct | A member that is a custom data structure itself. The sub-structure has its own set of members. |
| CustomSubStruct1DArray | SubStruct1DArray | A one-dimensional array of custom data structures. Each element of the array is a custom data structure having the same type. |
| CustomSubUnion | SubUnion | A member that is a custom data union itself. The sub-union has its own set of members and a SwitchField property, whose value is a 1-based index of the active member in the member list, that is used to select which union member is active at any time. |
| CustomSubUnion1DArray | SubUnion1DArray | A one-dimensional array of custom data unions. Each element of the array is a custom data union having the same union type. |
All members in the OPC UA custom data type are referenced via their unique names. The following properties can be used to define the member name in the OPC UA data type:
| Property | Description |
|---|---|
| Name<string> | The member name in the CDP configuration. When the UAName property is not specified, then this name is also used as the member name in the OPC UA data type. |
| UAName<string> | The member name in the OPC UA data type. The property can be left empty, in which case the value of Name property is also used as the member name in the OPC UA data type. This property is mostly needed when referring to the OPC UA structure members whose name is not valid as a CDP name (for example, contains dot symbols in it, etc.). |
| IsOptional<bool> | If set, the member is optional in the OPC UA structure. The IsExisting property then controls whether the member value is present at any time. |
| IsExisting<bool> | If set, the member is present in the OPC UA structure. When IsOptional is set, this property controls whether the member value is present in the current node value. |
Configuring the Custom Data Types
In OPC UA, a server defines the custom data type and exposes it to the clients. Every custom data type has its own unique Type ID (i.e. DataType NodeId in OPC UA) and its Encoding ID (i.e. DataTypeEncoding NodeId) which nodes then use to identify their data type in the OPC UA address space.
To define a custom data type in OPC UA in the server, the following properties can be used:
| Property | Description |
|---|---|
| Type<string> | The custom type name of the member (i.e. type BrowseName in OPC UA context). Will be auto-filled with node full location in CDP configuration, when left empty. When the same custom type name is referenced by multiple variables, a single custom type is created and shared among all variables. |
| UAType<string> | Complete specification of the OPC UA custom structure type that defines the TypeId and EncodingId. The specification can be left empty, in which case the TypeId and EncodingId are auto-generated in the server. |
When multiple nodes are referring to the same custom data type in the OPC-UA-Server, the custom data type is shared among all the nodes. This means that when the member list is changed in one node, the change is reflected in all the nodes. It also means that the member list should be the same or at least compatible with all the nodes that refer to the same, meaning that their member types must match otherwise, the server will log an error on startup and the incompatibly configured variable node will not be created.
Some example configurations of Type and UAType properties:
| Type | UAType | Description |
|---|---|---|
| MyFirstType | TypeId="ns=1;i=1234", EncodingId="ns=1;i=5678" | The type BrowseName is set to MyFirstType. The type will have an OPC UA Type ID having an integer identifier 1234 from namespace index 1, and Encoding ID having an integer identifier 5678 from namespace index 1. |
| MySecondType | TypeId="ns=1;i=2345" | The type BrowseName is set to MySecondType and it will have OPC UA Type ID having an integer identifier 2345 from namespace index 1 and a unique Encoding ID will be auto-generated by CDP. |
| MyThirdType | The type BrowseName is set to MyThirdType and the unique TypeId and unique Encoding ID will be auto-generated. | |
| The type BrowseName is set to the referencing node location and the unique TypeId and unique Encoding ID will be auto-generated by CDP. |
As can be seen, the simplest method to utilize custom data types is to leave the Type and UAType properties empty. In this case, CDP will automatically generate the TypeId and EncodingId for the custom data type. This method is very easy but is suitable only when the data is used by a single variable. When the custom data type needs to be used by multiple variables, it is necessary to define at least the Type property to give the custom data type a unique name and then refer to it by that name in the variables or sub-structure elements.
In the OPC-UA-Client, there is no need to set up the custom data type properties. The OPC-UA-Client will automatically fetch the custom data type of the node from the server and fill the Type and UAType properties with the correct values.
When different variables refer to the same type, they need not have all members of this type added to the node - when some members are missing in some instances, they will be filled with zero values for that variable. The same rule applies to the OPC-UA-Client - only the members whose value is actually needed by the client must be added to the node.
Note: For OPC-UA-Client, the easiest way to configure the custom data node variables is to use the CDP Studio discovery functionality. The discovery process finds all the variables and their member names and types from the running OPC UA server. Then the discovered pre-configured variables can be added to the OPC-UA-Client configuration using resource add functionality, from the Resource tree.
Direction of Custom Data Type Variables
Similar to the other variable types, the direction of the custom data type variables can be controlled by the following properties (both in the OPC-UA-Server and OPC-UA-Client):
| Property | Description |
|---|---|
| Input<bool> | Set to true for custom data typed variables whose value must be controlled by CDP (routed) or false for variables whose value changes must be observed only. Note: Input property in CDP is always considered from the CDP point of view (i.e. not from the OPC UA point of view). |
| Bidirectional<bool> | If set, the variable value is synced to the OPC UA network and also back from the OPC UA network despite the Input property value. Set Bidirectional to true when control of the variable value is needed and also when it is necessary to reflect the value changes received from OPC UA (e.g., value changes made by the server or other clients), for example when routing the value to the GUI widget. |
Note: As custom data type values have to be sent or received as a whole atomic entity, the direction of the custom data type variable members is always the same as the direction of the variable. Because of that, at variable creation on startup, all member directions are set to be the same as the variable direction.
Get started with CDP Studio today
Let us help you take your great ideas and turn them into the products your customer will love.