The OPC UA address space: nodes, NodeIds, attributes and references

Catalin NegruPublished 7 min read

Part of the OPC UA guide

The OPC UA address space is the set of nodes a server exposes and the references that connect them. Every piece of data is a node, every node is identified by a NodeId such as ns=2;s=Temperature, and every node carries a fixed list of numbered attributes, of which the Value attribute, number 13, is the one a client reads most. A client finds nodes by following references from a small set of standard starting points.

This page is part of the OPC UA guide. The definitions come from Part 3 (Address Space Model), Part 5 (Information Model) and Part 6 (Mappings) of the OPC UA specification.

Nodes and node classes

Part 3 defines eight node classes. Each has a numeric value, which is what the NodeClass attribute returns when a client reads it.

Node classValueWhat it represents
Object1A thing or a folder: a motor, a PLC program, the Objects folder
Variable2A value: a temperature, a setpoint, a property of an object
Method4A function the client can call with arguments
ObjectType8The definition an Object is an instance of
VariableType16The definition a Variable is an instance of
ReferenceType32A kind of relationship between nodes
DataType64A data type, built-in or defined by the server
View128A named subset of the address space

A data collector deals almost entirely with Variable nodes. Objects are how those variables are organized, and the four type classes describe structure that a browser shows but a read does not need.

NodeId formats

A NodeId has two parts: a namespace index and an identifier. The identifier is one of four types, and the text form used in configuration files and client tools marks the type with a letter.

Identifier typeText formExampleTypical use
Numericns=N;i=...ns=3;i=1001Standard nodes, and servers that number their tags
Stringns=N;s=...ns=2;s=TemperaturePLC tag names and paths
GUIDns=N;g=...ns=2;g=09087e75-8e5e-499b-954f-f2a9603db28aGenerated identifiers
Opaque (ByteString)ns=N;b=...ns=2;b=M/RbKBsRVkePCePcx24oRA==Server-internal keys, Base64 in text

When the namespace index is 0, the ns=0; prefix is normally omitted, so i=85 means node 85 in namespace 0.

A string identifier is compared exactly. ns=2;s=Temperature and ns=2;s=temperature are different nodes, and a trailing space or a different path separator produces BadNodeIdUnknown. Copy the NodeId from a browser instead of typing it.

Namespaces and the namespace index

A namespace is a URI that says who defined a node. The server holds a table of them, the NamespaceArray, and the ns= number in a NodeId is an index into that table.

Index 0 is always the OPC UA namespace, http://opcfoundation.org/UA/, which holds the standard nodes. Index 1 is the server’s own local namespace. Indexes from 2 upward are assigned by the server to its tag providers, PLC programs and companion specifications.

Those higher indexes are the trap. The URI is the stable identity; the index is only its position in this server’s table at this moment. Adding a driver or a companion specification to a server can shift the others, and a client configured with ns=2;s=Temperature then asks for a node that has become ns=3;s=Temperature. The NamespaceArray itself is a variable at i=2255, so reading it shows the current mapping. After any change to a server’s configuration, check that the indexes in the client still point at the same namespace URIs.

Attributes

Each node class has a fixed set of attributes, identified by number. A Read request names a NodeId and an attribute ID; there is no way to read “the node” as a whole.

IDAttributeNode classesContent
1NodeIdAllThe node’s identifier
2NodeClassAllOne of the eight values above
3BrowseNameAllNamespace-qualified name used in browse paths
4DisplayNameAllLocalized name for display
5DescriptionAllLocalized description, optional
13ValueVariable, VariableTypeThe data itself
14DataTypeVariable, VariableTypeNodeId of the value’s data type
15ValueRankVariable, VariableType-1 for a scalar, 1 for a one-dimensional array
17AccessLevelVariableBit mask: readable, writable, history
18UserAccessLevelVariableThe same mask for the current user
19MinimumSamplingIntervalVariableFastest rate the server can sample, in milliseconds
20HistorizingVariableWhether the server is storing history

The full list runs to attribute 22 in the base specification, with more added for roles and permissions in later versions. Only attribute 13 returns a DataValue with a meaningful status and source timestamp. In AccessLevel, bit 0 is CurrentRead and bit 1 is CurrentWrite, so a value of 1 is read-only and 3 is readable and writable. UserAccessLevel can be narrower than AccessLevel when the logged-in user has fewer rights.

References and browsing

Nodes are connected by references, and each reference has a type. Hierarchical reference types form the tree a browser shows:

  • Organizes connects a folder to its contents.
  • HasComponent connects an object to the variables, methods and sub-objects that are part of it.
  • HasProperty connects a node to a property that describes it, such as engineering units.

Non-hierarchical references carry other relationships. The most common is HasTypeDefinition, which points from an object or variable to its type.

Every server has the same top of the tree, defined in Part 5:

Root i=84 Objects i=85 Server i=2253 NamespaceArray i=2255 ServerStatus i=2256 CurrentTime i=2258 (the server's own objects and folders) Types i=86 Views i=87

Browsing means calling the Browse service on a starting node and receiving its references, then repeating on each target. Process data sits under the Objects folder, i=85. i=2258, the server’s current time, exists on every server and returns a new value on every read, which makes it a good first read when testing a connection.

A node also has a BrowseName, and a sequence of BrowseNames from a known starting node is a browse path. The TranslateBrowsePathsToNodeIds service turns a path into a NodeId. This matters for typed objects: the type definition fixes the BrowseNames of the components, so a client written against a companion specification can find the same variable on any server without knowing that server’s NodeIds.

Variables and data types

A Variable’s DataType attribute holds the NodeId of its type. The built-in types have fixed numeric identifiers in namespace 0, and the same numbers are used as the type tag inside the binary encoding of a Variant.

Data typeNodeIdSize and range
Booleani=1True or false
SByte, Bytei=2, i=38-bit signed, unsigned
Int16, UInt16i=4, i=516-bit signed, unsigned
Int32, UInt32i=6, i=732-bit signed, unsigned
Int64, UInt64i=8, i=964-bit signed, unsigned
Floati=10IEEE 754 single precision
Doublei=11IEEE 754 double precision
Stringi=12UTF-8 text
DateTimei=13100-nanosecond intervals since January 1, 1601 UTC

Because the type travels with the value, there is no word-order or scaling guesswork of the kind that surrounds a 32-bit float in two Modbus registers. The server states that a value is a Float and sends four bytes in a defined order.

Two things still go wrong. A node whose ValueRank is 1 holds an array, and a client expecting a single number has to be told which element to take. A node whose DataType is a structure (a PLC user-defined type, for instance) is sent as an ExtensionObject, which a generic client cannot interpret as a number at all. In both cases, browse one level deeper: most servers also expose the individual elements or structure members as their own scalar Variable nodes.

Analog values often come as an AnalogItemType variable, defined in Part 8, with EURange and EngineeringUnits properties attached by HasProperty references. The value is already in engineering units; the properties say which units and what span.

Common mistakes with NodeIds

SymptomLikely cause
BadNodeIdUnknownWrong namespace index, wrong case, or a string identifier typed instead of copied
Worked yesterday, BadNodeIdUnknown todayThe server’s namespace table changed and the index shifted
BadAttributeIdInvalidReading attribute 13 on an Object or folder node, which has no Value
BadNotReadable or BadUserAccessDeniedThe node’s access level or the user’s rights do not allow the read
Value arrives as text or as bytesThe node is a String, an array or a structure, not a scalar number
BadNotWritable on a writeAccessLevel has no CurrentWrite bit, or the PLC marks the tag read-only for OPC UA

The security page covers the access-denied cases, and the client and server page covers the Read and Write services themselves.

Entering nodes in the ControlCom Edge Server

In the ControlCom Edge Server’s OPC UA client, an item is one node read from the server. The item’s Node ID field takes the text forms above, for example ns=2;s=Temperature or ns=3;i=1001. The Attribute ID field defaults to 13, the Value attribute, and accepts others such as 1 (NodeId), 2 (NodeClass) and 3 (BrowseName). The Topic Property Path selects the platform variable that receives the value, and the item’s data type (number, boolean or string) follows that variable. A number item can be given a Scale, an Offset and a number of Decimals; if the server reports 857 and the real value is 8.57, the scale is 0.01. Selecting a Write Variable lets the platform write to the node; the default is No Write Allowed.

Item lists can be exported to CSV and imported again, which is the practical way to enter a few hundred NodeIds. The OPC UA client documentation  describes each field, and the page for controls engineers covers the wider commissioning workflow.

Each NodeId you enter on the Edge Server becomes a variable in ControlCom Connect with its own history, alarms and place on a dashboard.