{"id":9419,"date":"2024-07-11T20:07:35","date_gmt":"2024-07-11T18:07:35","guid":{"rendered":"https:\/\/www.basyskom.de\/?p=9419"},"modified":"2024-10-08T11:16:48","modified_gmt":"2024-10-08T09:16:48","slug":"opc-ua-programming-against-type-descriptions","status":"publish","type":"post","link":"https:\/\/www.basyskom.de\/en\/opc-ua-programming-against-type-descriptions\/","title":{"rendered":"OPC UA: Programming against Type Descriptions"},"content":{"rendered":"\t\t
\n\t\t\t\t
\n\t\t\t\t
\n\t\t\t\t
\n\t\t\t\t\t

Addressing OPC UA Nodes<\/h2>\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t
\n\t\t\t\t
\n\t\t\t\t\t\t\t\t\t

Information in OPC UA servers is stored in so-called “nodes”. Every node is identified by a NodeId<\/a>\u00a0which is used to address the node in OPC UA service calls (e.g. read\/write\/method call). So a client that wants to access the nodes of a server needs to find out about the NodeIds involved. While it might be tempting to launch a graphical browser like UaExpert<\/em> to find the nodes you need and to copy their NodeIds into your application code, this is most often a bad idea.<\/p>

This article explains why this is the case and shows the preferable approach, leading to more robust, portable client code.<\/p>\t\t\t\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t

\n\t\t\t\t
\n\t\t\t\t\t

Introduction to the OPC UA Address Space<\/h2>\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t
\n\t\t\t\t
\n\t\t\t\t\t\t\t\t\t

The address space of an OPC UA server is a full mesh network of nodes connected by references.<\/p>

Nodes are grouped into different NodeClasses<\/i> (e.g. Object<\/i>, ObjectType<\/i>, Variable<\/i>, …) and have\u00a0a set of data elements named attributes<\/em> that can be read and written. Some attributes like NodeId<\/i>, BrowseName<\/i> and DisplayName<\/i> are present for all<\/span>\u00a0<\/span>NodeClasses<\/i> while others like Value<\/i> or EventNotifier<\/i> are NodeClass<\/i> specific.<\/p>

A server’s address space is divided into different namespaces<\/i> that are identified by a URI and are listed in the Namespaces<\/i> array node of the Server<\/i> object. The array index of a namespace is used as part of the NodeId<\/i><\/a> type in the NodeId<\/i> attribute of every node to assign it to a namespace<\/i>. The identifier part of the NodeId<\/i> can be an integer<\/i>, a string<\/i>, a GUID<\/i>\u00a0or an opaque ByteString<\/i> and must be unique in the context of its namespace.<\/p>

References connect nodes to other nodes and have a semantic meaning expressed by their name. For example, an Object<\/i> node of the type FolderType<\/i> has Organizes<\/i> references to the nodes it contains. An Object<\/i> node modelling a complex real world object usually references its children using\u00a0HasComponent<\/i>. References may also connect nodes in different namespaces.<\/p>\t\t\t\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t

\n\t\t\t\t
\n\t\t\t\t\t

Why not to use hardcoded NodeIds<\/h2>\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t
\n\t\t\t\t
\n\t\t\t\t\t\t\t\t\t

While there are some well-known NodeIds defined by the OPC UA standard or a companion specification like the Objects<\/i> folder, the Server<\/i> object or the Machines<\/i> folder from the Machinery CS, most of the server specific nodes containing data are not guaranteed to always have the same NodeId. Some servers will use string NodeIds representing a path (e.g.\u00a0<\/span>MyMachine.Motor.RPM<\/i>) or implement some mechanism to generate numeric NodeIds to keep them somewhat static, but most servers will use random integer NodeIds that might be completely different after a restart. A server might also expose different objects depending on currently connected hardware or the availability of other external data sources.<\/span><\/p>

Also if your application needs to work with any server implementing a certain companion specification, there is no guarantee that you\u2019ll always find the companion specification\u2019s namespace on the same index in the namespaces array.<\/p>

To summarize: embedding hardcoded NodeIds in your client code will make your application less robust, less portable and harder to maintain.<\/p>\t\t\t\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t

\n\t\t\t\t
\n\t\t\t\t\t

What to do?<\/h2>\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t
\n\t\t\t\t
\n\t\t\t\t\t\t\t\t\t

OPC UA nodes of all classes have two naming related attributes. While the DisplayName<\/em> contains a LocalizedText<\/em><\/a> name for display purposes, which usually describes the node’s function in one word or a short CamelCase<\/i> string, the\u00a0<\/span>BrowseName<\/i><\/a> attribute holds a <\/span>QualifiedName<\/a>,<\/em>\u00a0which consists of a namespace index and a name string. It should be unique on its level in the server’s node hierarchy. Its intended usage is building<\/span>\u00a0<\/span>RelativePaths<\/a>,\u00a0which consist of BrowseNames<\/em> and information about the reference connecting the node to the previous node.<\/span><\/p>

As each model in the server has its own namespace, the BrowseName’<\/i>s namespace index indicates which model a node is from. If a model defines a new object type, variable type or event type with child nodes, all of them have a BrowseName<\/i> from its namespace. If a model extends an existing type from a different model by inheritance, only the newly added child nodes will have its namespace index in the BrowseName<\/i> while the inherited children keep their namespace index.<\/p>

The RelativePath<\/i> concept lends itself to programming against type definitions instead of specific nodes identified by their<\/span>\u00a0<\/span>NodeId<\/i>\u00a0<\/span>because there is always an unambiguous path from the type’s top level node to each child node deeper in the hierarchy.<\/span><\/p>\t\t\t\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t

\n\t\t\t\t
\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\"basysKom,\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t
\n\t\t\t\t
\n\t\t\t\t\t\t\t\t\t

To put this knowledge into practice, OPC UA provides the\u00a0<\/span>TranslateBrowsePathsToNodeIds<\/a>\u00a0service, which takes a start NodeId and a\u00a0<\/span>RelativePath<\/i>. The last RelativePathElement’s<\/em>\u00a0BrowseName<\/em> may be left empty, which will return all child nodes matching the given reference information. The NodeId(s) obtained from this service can then be used in any OPC UA service.<\/span><\/p>

Most companion specifications define a point of entry like the Machines<\/em> folder that references the server specific objects that implement a certain object type from that specification. In order to find interesting objects, the Browse<\/a> service can be called to return all NodeIds and BrowseNames of Object<\/em>\u00a0nodes referenced by the point of entry along with the NodeId of their TypeDefinition<\/em> node. This information is then used as a starting point for TranslateBrowsePathsToNodeIds<\/em> calls to find the object’s child nodes according to its type.<\/span><\/p>

The Browse<\/em> and TranslateBrowsePathsToNodeIds<\/i>\u00a0services used in conjunction with the server’s namespace array to resolve the URIs of the involved models to a namespace index are a mighty tool to find a certain node on any server implementing a given specification.<\/p>\t\t\t\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t

\n\t\t\t\t
\n\t\t\t\t\t

Example with Qt OPC UA<\/h2>\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t
\n\t\t\t\t
\n\t\t\t\t\t\t\t\t\t

The following example demonstrates how to find some selected Identification<\/i> properties of all woodworking machines on the public umati sample server<\/a> at opc.tcp:\/\/opcua.umati.app<\/i> using Qt OPC UA.<\/i> This server contains simulated instances of machines for most companion specifications where the\u00a0umati initiative<\/a>\u00a0is involved and has proven a handy tool to test OPC UA enabled client applications implementing these specifications.<\/p>

The server provides two simulated woodworking machines:<\/p>