OPC UA Companion Specification Implementation: Hands-On Tutorial (2026)
Most OPC UA tutorials stop once a MyTemperature variable shows up in UaExpert, and call that interoperability. It isn’t. Interoperability means a client written once can read a pump from any vendor, because every vendor exposes the same typed nodes in the same place. An OPC UA companion specification is the agreement that makes that possible.
Making it work in a real server is harder than the specs suggest. NodeSet versions have to match your stack. Namespace indices change between servers. And one default flag in a popular Python library will quietly create more than 3,000 nodes for every pump you add.
This rewrite replaces our May 2026 version. Every example has been run against open62541 v1.5.10, asyncua 2.1.0 and the UA-Nodeset UA-1.05.07-2026-07-30 release. Where the old version guessed at API names, this one shows code that ran and the numbers it produced.
What this covers: how companion specs stack (DI, IA, Machinery, Pumps), a working Python server and a working C server, a generic client, a check for missing mandatory nodes, measured startup and memory costs, and the failure modes that cost teams weeks.
Context and Background: The OPC UA Companion Specification Landscape
OPC UA defines how to model information, not what any particular machine means. The base specification (OPC 10000-3 for the address space model, OPC 10000-5 for the standard information model) gives you ObjectTypes, VariableTypes, References and ModellingRules. It says nothing about which nodes a pump, a robot or a packaging line should expose. Each OPC UA companion specification fills that gap for one domain.
Each one is published by the OPC Foundation, usually with a partner body such as VDMA, PackML’s OMAC sponsors or the MTConnect Institute. Each one defines a namespace, a set of types and an executable model file. If you need a refresher on the core protocol first, our complete technical guide to the OPC UA protocol covers sessions, the address space and the security model.
The catalogue is large. The OPC UA Online Reference lists roughly 150 documents as of November 2026. About 110 of them are companion specifications rather than core parts.
The specs you will meet most often in discrete and process manufacturing are below. Every number was checked against the online reference or the OPC Foundation’s document pages.
| Spec | Number | Namespace focus |
|---|---|---|
| Devices (DI) | OPC 10000-100 | Device, component and nameplate base types reused almost everywhere |
| Industrial Automation (IA) | OPC 10000-200 | Basic building blocks such as stack lights; required by Machinery 1.04 |
| Machinery Basic Building Blocks | OPC 40001-1 | Machines entry point, machine identification, item and operation-mode state machines |
| Pumps and Vacuum Pumps | OPC 40223 | PumpType, pump identification, operational measurements, supervision |
| Robotics | OPC 40010-1 | Motion devices, axes, controllers, safety states |
| Machine Tools | OPC 40501-1 | CNC machine-tool monitoring (the basis for umati) |
| Machine Vision | OPC 40100-1 | Vision systems, recipes, results |
| PackML | OPC 30050 | ISA-TR88 packaging state machine and PackTags |
| MTConnect | OPC 30070-1 | MTConnect device model mapped into OPC UA |
| UAFX (Field eXchange) | OPC 10000-80 to 10000-84 | Controller-to-controller and controller-to-device exchange |
| UA Cloud Library | OPC 30400-1, 30400-2 | Hosting and querying NodeSets over REST and GraphQL |
Two governance points matter if you plan to write your own OPC UA companion specification. OPC 11021, the UA Companion Specification Guideline (currently 1.02.1), sets out the editorial template and the required profile and conformance-unit sections. The second is that working groups now publish their machine-readable models in two places: the OPCFoundation/UA-Nodeset GitHub repository and the UA Cloud Library, which the OPC Foundation launched with CESMII. An OPC UA companion specification is not finished until its NodeSet2 file is published in one of those places.
What changed since early 2026? DI moved to version 1.05.0 (published 2025-11-15). Machinery moved to 1.04.1 in January 2026, and a Machinery-1.04.2-2026-11-01 tag appeared in UA-Nodeset this month.
UAFX reached 1.00.04 in July 2026. The Pumps model is still at 1.0.0 from April 2021. That gap between a fast-moving base layer and a stable domain layer causes most of the build failures described later.
Reference Architecture: How an OPC UA Companion Specification Lives Inside a Server
Direct answer: an OPC UA companion specification is a versioned NodeSet2 XML model with its own NamespaceUri. You load it into a server’s address space after its dependencies, in dependency order. You then create instances of its ObjectTypes in your own vendor namespace. Clients find those instances through well-known entry points such as Machinery’s Machines folder and look up namespace indices by URI when they connect.

Figure 1: How the companion specification layers stack inside one server address space, and where vendor instances live.
Figure 1 shows the dependency graph you load for a pump server built on the Pumps OPC UA companion specification. Namespace 0 holds the core types. DI depends only on the core. IA depends on DI.
Machinery 1.04 depends on DI and IA. Pumps depends on DI and Machinery. Your vendor namespace sits beside all of them and owns only instance NodeIds. It never redefines a type.
A generic client, such as an MES connector or a historian collector, never hard-codes your NodeIds. It looks up namespace URIs, browses from the Machines folder, and recognises a pump by its TypeDefinition.
The dependency chain is declared, versioned, and stricter than it looks
Every NodeSet2 file starts with a <Models> block that declares its ModelUri, its version and its RequiredModel entries. These are the declarations from the November 2026 files we used:
| NodeSet | Model version | Publication date | Declared requirements |
|---|---|---|---|
| DI | 1.05.0 | 2025-11-15 | Core 1.05.04 |
| IA | 1.01.4 | 2025-05-23 | Core 1.05.01, DI 1.03.1 |
| Machinery | 1.04.1 | 2026-01-01 | Core 1.05.02, DI 1.04.0, IA 1.01.2 |
| Pumps | 1.0.0 | 2021-04-19 | Core 1.04.7, DI 1.02.2, Machinery 1.0.0 |
Each requirement is a minimum version, so Pumps 1.0.0 loads on top of Machinery 1.04.1. The surprise is IA. Older tutorials, including the previous version of this one, load DI, then Machinery, then Pumps. That order fails on current Machinery releases, because they declare IA as a required model and reference its types.
The core namespace is also a dependency. DI 1.05.0 references Core 1.05.04 nodes that a reduced namespace 0 does not contain. That is why open62541 needs a full namespace 0 to build it, as the walk-through shows.
NodeSet2 is the contract; ModellingRules are the conformance surface
The NodeSet2 format is defined in OPC 10000-6 Annex F (the UANodeSet.xsd schema). It is the executable form of an OPC UA companion specification. The PDF explains the semantics, but servers load the XML, clients can parse it, and test tools compare against it. Inside it, each InstanceDeclaration under a type carries a HasModellingRule reference.
Four rules matter. Mandatory (i=78) means every instance must have the child. Optional (i=80) means it may. OptionalPlaceholder (i=11508) and MandatoryPlaceholder (i=11510) mark zero-to-many and one-to-many children whose BrowseNames you choose.
The Pumps model shows how lean the mandatory surface can be. PumpType (ns=1;i=1052 in the Pumps file) has one Mandatory child, Identification of PumpIdentificationType. That child has three Mandatory properties, all inherited from DI: Manufacturer, SerialNumber and ProductInstanceUri.
Everything else is Optional: Configuration, Documentation, Events, Maintenance, Operational and Ports, plus about 50 measurement variables such as Speed, DifferentialPressure and PumpTotalHead. Placeholder BrowseNames such as <Drive> and <InletConnection> under Ports are templates, not literal names. Your instance replaces them with real names.
That split is deliberate. The mandatory set is the minimum a client can rely on. The optional set is a menu, and the spec’s Profiles and ConformanceUnits (section 9 of OPC 40223 defines Server Facets) say which optional groups a server must implement to claim a given facet. Conformance to an OPC UA companion specification means implementing the mandatory nodes, then the optional groups your claimed facets require, and nothing that pretends to be data you don’t have.
Namespace indices are runtime facts, not constants
A NodeId in a NodeSet file uses the file’s local namespace table. Inside the Pumps file, index 1 is Pumps, 2 is Machinery and 3 is DI. When a server loads several files, it remaps those indices to its own NamespaceArray.
In our Python server, DI ended up at index 2, IA at 3, Machinery at 4, Pumps at 5 and the vendor namespace at 6. The C server produced the same order only because we loaded the models in the same order. Another vendor’s server, or the same server with one more spec loaded, will differ.
The rule follows directly. Numeric identifiers inside a namespace (1052 for PumpType, 1001 for Machines) are stable, because the spec’s NodeIds CSV fixes them. Namespace indices are not stable. Code that writes ns=4;i=1052 is relying on luck.
Code that reads NamespaceArray, finds http://opcfoundation.org/UA/Pumps/, and builds the NodeId from that index will work on every conformant server. The previous version of this tutorial hard-coded indices. That was its most serious bug.
When an OPC UA companion specification is the wrong starting point
Not every asset class has an OPC UA companion specification, and forcing one onto the wrong asset does more harm than having none. If your equipment is a pump, a robot or a CNC machine, use the published model and extend it in your vendor namespace. If nothing fits, derive your own ObjectType from DI’s ComponentType and give it Machinery’s MachineIdentificationType nameplate. That way generic clients can still read the nameplate, even when they cannot interpret the rest.
Overlap is the other case. Machine tools can be modelled with OPC 40501-1 or exposed through the MTConnect mapping in OPC 30070-1, and some vendors ship both. Pick the OPC UA companion specification your customers’ clients already consume, and treat the second as a gateway concern. Our comparison of umati, MTConnect and OPC UA for machine tools covers that decision in detail.
Three ways to get a NodeSet into a server
Once you have the XML for an OPC UA companion specification, there are three ways to load it, and the choice affects everything after it. Code generation, used by open62541’s nodeset compiler and the OPC Foundation’s .NET stack, turns the model into C or C# at build time, so startup cost is close to zero. Runtime import, used by asyncua’s import_xml and open62541’s optional nodesetLoader, parses the XML on every start, which costs startup time and memory.
Vendor SDKs, such as Unified Automation’s, Prosys’s or Siemens’ toolchain, sit between the two and usually wrap one of these approaches in a graphical modeller. The walk-through measures the first two on the same machine.
Walk-through: Implementing the Pumps OPC UA Companion Specification Two Ways
We implement the same OPC UA companion specification server twice: once in Python with asyncua for fast iteration, and once in C with open62541 for an embedded or PLC-class target. Both expose a PumpType instance called P-101 under Machines. Both fill the mandatory nameplate and publish a live Speed measurement. One generic client and one conformance checker test both servers without changes.

Figure 2: The companion specification toolchain, from model authoring to the three ways a NodeSet reaches a running server.
Figure 2 is the pipeline end to end. Working groups author a model in a graphical tool or as ModelDesign XML. UA-ModelCompiler turns it into NodeSet2 plus a NodeIds CSV and datatype schemas.
The release goes to UA-Nodeset and the UA Cloud Library. From there each stack consumes the XML its own way. This tutorial starts at the publication step and follows the open62541 and asyncua branches.
Step 0: toolchain versions verified for this tutorial
| Component | Version used | Source |
|---|---|---|
| UA-Nodeset release | UA-1.05.07-2026-07-30 tag |
github.com/OPCFoundation/UA-Nodeset |
| open62541 | v1.5.10 (pins UA-Nodeset commit 257db9a) |
github.com/open62541/open62541 |
| asyncua | 2.1.0 (PyPI, 2026-10-06; requires Python 3.10 or later) | pypi.org/project/asyncua |
| Python | 3.13 | — |
| UA-ModelCompiler | .NET global tool OPCFoundation.Opc.Ua.ModelCompiler.Tool |
github.com/OPCFoundation/UA-ModelCompiler |
asyncua moved from the 1.x line to 2.0 in June 2026 and to 2.1.0 in October 2026. The calls used here (import_xml, add_object, instantiate, get_namespace_index) all exist in 2.1.0, and we checked their signatures directly. If you are still on 1.x, the same code should work, but test it first.
Step 1: fetch exactly the NodeSets you need, pinned by tag
UA-Nodeset is a large repository with nearly 80 model folders, one per OPC UA companion specification family plus the core schema. A sparse, shallow clone at a release tag takes seconds and pins your versions so they can be reproduced:
python3 -m venv .venv && source .venv/bin/activate
pip install "asyncua==2.1.0"
git clone --depth 1 --filter=blob:none --sparse \
-b UA-1.05.07-2026-07-30 https://github.com/OPCFoundation/UA-Nodeset ua-nodeset
cd ua-nodeset && git sparse-checkout set Schema DI IA Machinery Pumps && cd ..
mkdir -p nodesets
cp ua-nodeset/DI/Opc.Ua.Di.NodeSet2.xml \
ua-nodeset/IA/Opc.Ua.IA.NodeSet2.xml \
ua-nodeset/Machinery/Opc.Ua.Machinery.NodeSet2.xml \
ua-nodeset/Pumps/Opc.Ua.Pumps.NodeSet2.xml nodesets/
# Sanity check: print each model's URI, version and its declared dependencies
grep -h -A4 "<Models>" nodesets/*.xml | grep -E "Model |RequiredModel"
The Pumps file is much larger than the rest: 6.6 MB and 9,624 nodes, compared with 296 KB for DI, 109 KB for IA and 126 KB for Machinery. Most of that size is the long list of optional measurement, documentation and supervision declarations. Keep that ratio in mind, because it explains the startup numbers later.
Step 2: a Python server that loads the chain and instantiates PumpType
The server loads the four OPC UA companion specification files in dependency order. It then resolves every namespace index by URI and instantiates PumpType with only its mandatory children. After that it adds the one optional branch it can actually populate, Operational/Measurements/Speed.
"""pump_server.py - Pumps companion-spec server: DI -> IA -> Machinery -> Pumps."""
import asyncio
import logging
import math
from pathlib import Path
from asyncua import Server, ua
from asyncua.common.instantiate_util import instantiate
NODESETS = Path(__file__).parent / "nodesets"
LOAD_ORDER = [
"Opc.Ua.Di.NodeSet2.xml", # OPC 10000-100 Devices
"Opc.Ua.IA.NodeSet2.xml", # OPC 10000-200 Industrial Automation
"Opc.Ua.Machinery.NodeSet2.xml", # OPC 40001-1 Machinery
"Opc.Ua.Pumps.NodeSet2.xml", # OPC 40223 Pumps and Vacuum Pumps
]
URI_DI = "http://opcfoundation.org/UA/DI/"
URI_MACH = "http://opcfoundation.org/UA/Machinery/"
URI_PUMPS = "http://opcfoundation.org/UA/Pumps/"
URI_VENDOR = "urn:example:acme-pumps:server"
async def child(node, *path):
"""Browse a relative path of (namespace_index, name) tuples."""
return await node.get_child([f"{ns}:{name}" for ns, name in path])
async def main():
server = Server()
await server.init()
server.set_endpoint("opc.tcp://0.0.0.0:4840/acme/pumps/")
server.set_server_name("ACME Pump Server")
# Dev only: production servers must use Basic256Sha256 or the ECC policies.
server.set_security_policy([ua.SecurityPolicyType.NoSecurity])
for name in LOAD_ORDER:
await server.import_xml(str(NODESETS / name), strict_mode=False)
ns_di = await server.get_namespace_index(URI_DI)
ns_mach = await server.get_namespace_index(URI_MACH)
ns_pumps = await server.get_namespace_index(URI_PUMPS)
ns_v = await server.register_namespace(URI_VENDOR)
machines = server.get_node(ua.NodeId(1001, ns_mach)) # Machinery: Machines folder
pump_type = server.get_node(ua.NodeId(1052, ns_pumps)) # Pumps: PumpType
# Mandatory children only; add optional ones deliberately below.
pump = await machines.add_object(
ua.NodeId("P-101", ns_v), ua.QualifiedName("P-101", ns_v),
objecttype=pump_type.nodeid, instantiate_optional=False,
)
# Machines is a FolderType, so asyncua links the pump with Organizes, as Machinery requires.
ident = await child(pump, (ns_di, "Identification"))
await (await child(ident, (ns_di, "Manufacturer"))).write_value(
ua.LocalizedText("ACME Pumps GmbH", "en"))
await (await child(ident, (ns_di, "SerialNumber"))).write_value("ACME-2026-000417")
await (await child(ident, (ns_di, "ProductInstanceUri"))).write_value(
"urn:acme-pumps.example:P-101:ACME-2026-000417")
# Optional children the spec defines, added on purpose: Operational/Measurements/Speed.
operational = await pump.add_object(
ua.NodeId("P-101.Operational", ns_v), ua.QualifiedName("Operational", ns_pumps),
objecttype=ua.NodeId(1053, ns_pumps), instantiate_optional=False) # OperationalGroupType
measurements = await operational.add_object(
ua.NodeId("P-101.Measurements", ns_v), ua.QualifiedName("Measurements", ns_pumps),
objecttype=ua.NodeId(1054, ns_pumps), instantiate_optional=False) # MeasurementsType
[speed] = (await instantiate(
measurements, server.get_node(ua.ObjectIds.BaseAnalogType),
nodeid=ua.NodeId("P-101.Speed", ns_v), bname=ua.QualifiedName("Speed", ns_pumps),
dname=ua.LocalizedText("Speed"), instantiate_optional=False))[:1]
await speed.write_attribute(ua.AttributeIds.DataType,
ua.DataValue(ua.Variant(ua.NodeId(ua.ObjectIds.Double))))
print(f"P-101 up: ns DI={ns_di} Machinery={ns_mach} Pumps={ns_pumps} vendor={ns_v}",
flush=True)
async with server:
t = 0.0
while True:
await speed.write_value(1450.0 + 15.0 * math.sin(t), ua.VariantType.Double) # rpm
t += 0.1
await asyncio.sleep(1)
if __name__ == "__main__":
logging.basicConfig(level=logging.WARNING)
asyncio.run(main())
Five choices in this file are worth explaining, because each one fixes a real failure.
strict_mode=False is needed for DI 1.05.0. That file contains nine DesignToolOnly="true" objects (ns=1;i=73 to 75 and 90 to 95, such as Configuration and Diagnostics). They have no parent in the runtime model.
In strict mode asyncua 2.1.0 stops on the first one with BadParentNodeIdInvalid. In lenient mode it logs nine warnings and skips them. Those nodes exist only for design tools, so skipping them is correct.
instantiate_optional=False is the most important argument in the file. asyncua’s default is True, which copies every Optional declaration. More on the cost in the gotchas section.
The Machines link uses Organizes because the Machinery spec says Machines organizes every top-level machine. asyncua picks Organizes automatically when the parent’s TypeDefinition is FolderType, and Machines is a folder. Under any other parent, the same call would create HasComponent.
Speed uses the spec’s BrowseName (Pumps namespace, name Speed) and the declaration’s type, BaseAnalogType (i=15318), with a Double DataType. That is the difference between the speed of a conformant pump and a vendor variable that happens to be called Speed. A client following the spec’s browse path finds it. A vendor-namespace variable would be invisible to that client.
The vendor namespace owns the instance NodeIds (ns=6;s=P-101), while BrowseNames inside the type structure stay in the spec namespaces. This is the usual separation of concerns. Types and their declared children belong to the spec. Instances and any vendor extensions belong to you.
Step 3: a generic client that knows the spec, not the vendor
Nothing in this client is specific to the vendor. It has no knowledge of ACME, of ns=6 or of string NodeIds. It knows three namespace URIs and two numeric identifiers from the specs, and that is enough to find every pump on any conformant server.
"""pump_client.py - generic Machinery client: discover machines, read nameplates."""
import asyncio
from asyncua import Client, ua
URI_DI = "http://opcfoundation.org/UA/DI/"
URI_MACH = "http://opcfoundation.org/UA/Machinery/"
URI_PUMPS = "http://opcfoundation.org/UA/Pumps/"
async def main(url="opc.tcp://localhost:4840/acme/pumps/"):
async with Client(url) as client:
# Resolve indices by URI at runtime -- never hard-code ns=2, ns=4 ...
ns_di = await client.get_namespace_index(URI_DI)
ns_mach = await client.get_namespace_index(URI_MACH)
ns_pumps = await client.get_namespace_index(URI_PUMPS)
pump_type = ua.NodeId(1052, ns_pumps)
machines = client.get_node(ua.NodeId(1001, ns_mach))
for machine in await machines.get_children(refs=ua.ObjectIds.Organizes):
tdef = await machine.read_type_definition()
ident = await machine.get_child(f"{ns_di}:Identification")
mfr = await (await ident.get_child(f"{ns_di}:Manufacturer")).read_value()
sn = await (await ident.get_child(f"{ns_di}:SerialNumber")).read_value()
name = (await machine.read_browse_name()).Name
print(f"{name}: type={tdef.to_string()} pump={tdef == pump_type} "
f"manufacturer={mfr.Text} serial={sn}")
if tdef == pump_type:
try: # Optional in the spec: absence is legal, so handle it
speed = await machine.get_child(
[f"{ns_pumps}:Operational", f"{ns_pumps}:Measurements", f"{ns_pumps}:Speed"])
print(f" speed = {await speed.read_value():.1f} rpm")
except ua.UaStatusCodeError:
print(" speed not exposed (optional)")
if __name__ == "__main__":
asyncio.run(main())
Against both the Python and the C server it printed:
P-101: type=ns=5;i=1052 pump=True manufacturer=ACME Pumps GmbH serial=ACME-2026-000417
speed = 1457.2 rpm
Two details make this client production-grade rather than demo-grade. First, it treats a missing optional node as a normal case, not an exception path, because absence is legal under the spec. Second, it compares the TypeDefinition with an exact match.
A stricter client would also accept subtypes of PumpType by walking HasSubtype references, since vendors may derive their own pump types. Machinery’s MachineIdentificationType and the DI nameplate interfaces exist so that a client can read Manufacturer and SerialNumber from any machine, pump or not, through the same browse path.

Figure 3: Startup and discovery sequence. The server loads and instantiates, then the client resolves URIs, browses Machines, checks the type and reads the nameplate.
Figure 3 shows the protocol view. The important step is the second client request, reading NamespaceArray. Every NodeId the client builds afterwards depends on it. The get_child calls turn into TranslateBrowsePathsToNodeIds service calls, so the client never needs the server’s internal identifiers.
Step 4: check mandatory nodes before anyone else does
The OPC Foundation’s Compliance Test Tool (CTT) is the authority for certification. You still want a fast check in CI that fails a build when someone removes a mandatory node. This checker walks the instance’s type and all its supertypes, collects every Mandatory InstanceDeclaration by browse path, and confirms that each one resolves on the instance.
"""check_mandatory.py - verify an instance carries every Mandatory declaration of its type."""
import asyncio
import sys
from asyncua import Client, ua
MANDATORY = ua.NodeId(ua.ObjectIds.ModellingRule_Mandatory)
STOP = {ua.NodeId(ua.ObjectIds.BaseObjectType), ua.NodeId(ua.ObjectIds.BaseVariableType)}
async def supertypes(client, type_id):
"""The type and all its supertypes, most-derived first."""
chain = []
while type_id is not None and type_id not in STOP:
chain.append(type_id)
sup = await client.get_node(type_id).get_references(
refs=ua.ObjectIds.HasSubtype, direction=ua.BrowseDirection.Inverse)
type_id = sup[0].NodeId if sup else None
return chain
async def mandatory_paths(client, decl, prefix=()):
"""Yield browse paths of Mandatory declarations below a type or declaration node."""
for ref in await decl.get_references(refs=ua.ObjectIds.Aggregates, # not HasSubtype
direction=ua.BrowseDirection.Forward):
child = client.get_node(ref.NodeId)
rules = await child.get_referenced_nodes(refs=ua.ObjectIds.HasModellingRule)
if any(r.nodeid == MANDATORY for r in rules):
path = prefix + (ref.BrowseName.to_string(),)
yield path
async for p in mandatory_paths(client, child, path):
yield p
async def check(url, instance_id):
async with Client(url) as client:
inst = client.get_node(instance_id)
missing, checked = [], 0
for t in await supertypes(client, await inst.read_type_definition()):
async for path in mandatory_paths(client, client.get_node(t)):
checked += 1
try:
await inst.get_child(list(path))
except ua.UaStatusCodeError:
missing.append("/".join(path))
print(f"checked {checked} mandatory declarations, missing {len(missing)}")
for m in missing:
print(" MISSING", m)
return not missing
if __name__ == "__main__":
url = sys.argv[1] if len(sys.argv) > 1 else "opc.tcp://localhost:4840/acme/pumps/"
node = sys.argv[2] if len(sys.argv) > 2 else "ns=6;s=P-101"
sys.exit(0 if asyncio.run(check(url, node)) else 1)
Against P-101 it reports checked 4 mandatory declarations, missing 0. Those four are Identification, Manufacturer, ProductInstanceUri and SerialNumber. Two bugs we hit while writing it are worth knowing, because the same mistakes show up in hand-written browsers.
Browsing with HierarchicalReferences follows HasSubtype too, since it is hierarchical, and recurses forever. Restrict the walk to Aggregates. asyncua’s get_references also defaults to both directions, so an inverse HasComponent leads back to the parent. Pass BrowseDirection.Forward.
This check is necessary but not sufficient. It does not test the DataTypes, the EngineeringUnits or the optional groups that a claimed facet requires. Treat it as a fast regression guard. Run the CTT with the spec’s conformance units before you claim conformance.
Step 5: the same server in C with open62541 v1.5.10
For a PLC, gateway firmware or any target where 250 MB of Python is not an option, open62541 compiles each OPC UA companion specification NodeSet to C. In v1.5 there are two ways to do this. You can call tools/nodeset_compiler/nodeset_compiler.py and the CMake macro ua_generate_nodeset_and_datatypes yourself.
Or you can use the built-in UA_INFORMATION_MODEL_AUTOLOAD option, which already knows the dependency graph for dozens of companion specs, including Machinery (DI and IA) and Pumps (DI and Machinery). AUTOLOAD is the simpler path:
git clone --depth 1 -b v1.5.10 https://github.com/open62541/open62541
cd open62541
git submodule update --init --depth 1 deps/ua-nodeset # the NodeSet commit this release was tested with
mkdir build && cd build
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release \
-DUA_NAMESPACE_ZERO=FULL \
-DUA_INFORMATION_MODEL_AUTOLOAD="DI;IA;Machinery;Pumps" ..
ninja open62541 # 4 min 46 s on a 2-vCPU sandbox; libopen62541.a = 57 MB
With AUTOLOAD, the generated UA_Server_injectNodesets() runs inside UA_Server_new(). Your main() never calls a per-namespace function, which is where the old tutorial’s guessed function names went wrong. If you run the nodeset compiler by hand instead, note that --xml takes one file and the generated function is named after the positional output basename. It is not a second argument after --xml.
/* pump_server.c -- Pumps companion spec on open62541 v1.5.x
* Build open62541 with:
* -DUA_NAMESPACE_ZERO=FULL -DUA_INFORMATION_MODEL_AUTOLOAD="DI;IA;Machinery;Pumps"
* The nodeset injector loads DI -> IA -> Machinery -> Pumps inside UA_Server_new(). */
#include <open62541/server.h>
#include <open62541/server_config_default.h>
#include <open62541/plugin/log_stdout.h>
#include <open62541/nodeids_pumps.h>
#include <math.h>
#define URI_DI "http://opcfoundation.org/UA/DI/"
#define URI_MACH "http://opcfoundation.org/UA/Machinery/"
#define URI_PUMPS "http://opcfoundation.org/UA/Pumps/"
#define MACHINERY_MACHINES 1001 /* Machinery NodeIds.csv: Machines,1001,Object */
static UA_UInt16 nsIndex(UA_Server *s, const char *uri) {
size_t idx = 0;
if(UA_Server_getNamespaceByName(s, UA_STRING((char *)(uintptr_t)uri), &idx) != UA_STATUSCODE_GOOD)
return 0;
return (UA_UInt16)idx;
}
/* Resolve a relative browse path (all segments in one namespace) to a NodeId. */
static UA_StatusCode resolve(UA_Server *s, UA_NodeId origin, UA_UInt16 ns,
const char *a, const char *b, UA_NodeId *out) {
UA_QualifiedName path[2] = {UA_QUALIFIEDNAME(ns, (char *)(uintptr_t)a),
UA_QUALIFIEDNAME(ns, (char *)(uintptr_t)b)};
UA_BrowsePathResult r = UA_Server_browseSimplifiedBrowsePath(s, origin, b ? 2 : 1, path);
UA_StatusCode rc = r.statusCode;
if(rc == UA_STATUSCODE_GOOD && r.targetsSize > 0)
rc = UA_NodeId_copy(&r.targets[0].targetId.nodeId, out);
UA_BrowsePathResult_clear(&r);
return rc;
}
static void updateSpeed(UA_Server *server, void *data) {
static double t = 0.0;
UA_Double rpm = 1450.0 + 15.0 * sin(t);
t += 0.1;
UA_Variant v;
UA_Variant_setScalar(&v, &rpm, &UA_TYPES[UA_TYPES_DOUBLE]);
UA_Server_writeValue(server, *(UA_NodeId *)data, v);
}
int main(void) {
UA_Server *server = UA_Server_new(); /* companion nodesets injected here */
if(!server)
return EXIT_FAILURE;
UA_UInt16 nsDi = nsIndex(server, URI_DI);
UA_UInt16 nsMach = nsIndex(server, URI_MACH);
UA_UInt16 nsPumps = nsIndex(server, URI_PUMPS);
UA_UInt16 nsVendor = UA_Server_addNamespace(server, "urn:example:acme-pumps:server");
if(!nsDi || !nsMach || !nsPumps) {
UA_LOG_ERROR(UA_Log_Stdout, UA_LOGCATEGORY_SERVER, "companion namespaces missing");
UA_Server_delete(server);
return EXIT_FAILURE;
}
/* 1. Instantiate PumpType under Machines. Only Mandatory children are created. */
UA_ObjectAttributes oattr = UA_ObjectAttributes_default;
oattr.displayName = UA_LOCALIZEDTEXT("en", "P-101");
UA_NodeId pump;
UA_StatusCode rc = UA_Server_addObjectNode(server,
UA_NODEID_STRING(nsVendor, "P-101"),
UA_NODEID_NUMERIC(nsMach, MACHINERY_MACHINES),
UA_NODEID_NUMERIC(0, UA_NS0ID_ORGANIZES),
UA_QUALIFIEDNAME(nsVendor, "P-101"),
UA_NODEID_NUMERIC(nsPumps, UA_PUMPSID_PUMPTYPE),
oattr, NULL, &pump);
if(rc != UA_STATUSCODE_GOOD)
goto fail;
/* 2. Fill the mandatory nameplate (DI properties inside Pumps:Identification). */
UA_NodeId ident, n;
if(resolve(server, pump, nsDi, "Identification", NULL, &ident) != UA_STATUSCODE_GOOD)
goto fail;
UA_LocalizedText mfr = UA_LOCALIZEDTEXT("en", "ACME Pumps GmbH");
UA_String serial = UA_STRING("ACME-2026-000417");
UA_String piu = UA_STRING("urn:acme-pumps.example:P-101:ACME-2026-000417");
UA_Variant v;
if(resolve(server, ident, nsDi, "Manufacturer", NULL, &n) == UA_STATUSCODE_GOOD) {
UA_Variant_setScalar(&v, &mfr, &UA_TYPES[UA_TYPES_LOCALIZEDTEXT]);
UA_Server_writeValue(server, n, v);
UA_NodeId_clear(&n);
}
if(resolve(server, ident, nsDi, "SerialNumber", NULL, &n) == UA_STATUSCODE_GOOD) {
UA_Variant_setScalar(&v, &serial, &UA_TYPES[UA_TYPES_STRING]);
UA_Server_writeValue(server, n, v);
UA_NodeId_clear(&n);
}
if(resolve(server, ident, nsDi, "ProductInstanceUri", NULL, &n) == UA_STATUSCODE_GOOD) {
UA_Variant_setScalar(&v, &piu, &UA_TYPES[UA_TYPES_STRING]);
UA_Server_writeValue(server, n, v);
UA_NodeId_clear(&n);
}
/* 3. Optional children, added deliberately: Operational/Measurements/Speed. */
UA_NodeId oper, meas, speed;
oattr.displayName = UA_LOCALIZEDTEXT("en", "Operational");
rc = UA_Server_addObjectNode(server, UA_NODEID_STRING(nsVendor, "P-101.Operational"), pump,
UA_NODEID_NUMERIC(0, UA_NS0ID_HASCOMPONENT), UA_QUALIFIEDNAME(nsPumps, "Operational"),
UA_NODEID_NUMERIC(nsPumps, UA_PUMPSID_OPERATIONALGROUPTYPE), oattr, NULL, &oper);
oattr.displayName = UA_LOCALIZEDTEXT("en", "Measurements");
rc |= UA_Server_addObjectNode(server, UA_NODEID_STRING(nsVendor, "P-101.Measurements"), oper,
UA_NODEID_NUMERIC(0, UA_NS0ID_HASCOMPONENT), UA_QUALIFIEDNAME(nsPumps, "Measurements"),
UA_NODEID_NUMERIC(nsPumps, UA_PUMPSID_MEASUREMENTSTYPE), oattr, NULL, &meas);
UA_VariableAttributes vattr = UA_VariableAttributes_default;
UA_Double zero = 0.0;
UA_Variant_setScalar(&vattr.value, &zero, &UA_TYPES[UA_TYPES_DOUBLE]);
vattr.dataType = UA_TYPES[UA_TYPES_DOUBLE].typeId;
vattr.displayName = UA_LOCALIZEDTEXT("en", "Speed");
rc |= UA_Server_addVariableNode(server, UA_NODEID_STRING(nsVendor, "P-101.Speed"), meas,
UA_NODEID_NUMERIC(0, UA_NS0ID_HASCOMPONENT), UA_QUALIFIEDNAME(nsPumps, "Speed"),
UA_NODEID_NUMERIC(0, UA_NS0ID_BASEANALOGTYPE), vattr, NULL, &speed);
if(rc != UA_STATUSCODE_GOOD)
goto fail;
UA_Server_addRepeatedCallback(server, updateSpeed, &speed, 1000.0, NULL);
UA_LOG_INFO(UA_Log_Stdout, UA_LOGCATEGORY_SERVER,
"P-101 up: ns DI=%u Machinery=%u Pumps=%u vendor=%u",
nsDi, nsMach, nsPumps, nsVendor);
rc = UA_Server_runUntilInterrupt(server);
UA_Server_delete(server);
return rc == UA_STATUSCODE_GOOD ? EXIT_SUCCESS : EXIT_FAILURE;
fail:
UA_LOG_ERROR(UA_Log_Stdout, UA_LOGCATEGORY_SERVER, "setup failed: %s",
UA_StatusCode_name(rc));
UA_Server_delete(server);
return EXIT_FAILURE;
}
Build and link it against the static library and the generated headers:
O=/path/to/open62541
gcc -std=c99 -O2 -Wall pump_server.c \
-I$O/include -I$O/plugins/include -I$O/arch -I$O/build/src_generated \
-L$O/build/bin -lopen62541 -lm -lpthread -o pump_server
./pump_server # Ctrl-C to stop; UA_Server_runUntilInterrupt installs the signal handler
The Release build of open62541 enables link-time optimisation, so this final link took about 4.5 minutes on our 2-vCPU sandbox. The resulting unstripped binary was 36 MB. Build the library with -DCMAKE_BUILD_TYPE=Debug while you iterate, and keep the Release build with LTO for release images.
Unlike asyncua, open62541 creates only Mandatory children when you call UA_Server_addObjectNode with a TypeDefinition. Optional children appear only if you register a createOptionalChild callback in the server’s node lifecycle, or add them explicitly as the code above does. The same Python client and conformance checker gave identical output against this binary. That is the point of an OPC UA companion specification: the client did not change.
Measured cost of loading an OPC UA companion specification: runtime import versus generated code
We ran both servers on the same 2-vCPU x86-64 Linux sandbox, once each, and read resident memory with ps after startup finished. Treat the figures as orders of magnitude, not benchmarks.
| Metric | asyncua 2.1.0, import_xml |
open62541 v1.5.10, AUTOLOAD |
|---|---|---|
| Time to load DI, IA, Machinery | 0.16 s, 0.06 s, 0.07 s | included below |
| Time to load Pumps NodeSet | 21.8 s | — |
| Total companion-model load at startup | about 22 s | about 0.15 s (log timestamps) |
| Resident memory after startup | about 254 MB | about 49 MB |
| Build-time cost | none | 4 min 46 s library build; 26.6 MB generated namespace_pumps_generated.c |
| Nodes in address space after load | 16,538 (6,174 core + 10,364 companion) | similar; not counted |
Methodology caveats: these are single runs on a shared cloud sandbox with debug logging off. The asyncua figure is dominated by Python-level parsing and node creation for the 9,624-node Pumps file. A faster CPU will shrink it but will not change its shape.
The open62541 figure is the gap between the injector’s “Attaching the AUTOLOAD Nodesets” log line and our “P-101 up” line, so it includes instantiation. Neither number includes TLS certificate creation. The conclusion holds regardless: runtime import of a large OPC UA companion specification costs tens of seconds and hundreds of megabytes, while generated code moves that cost to build time.
Authoring your own model: UA-ModelCompiler, UA Modeler, SiOME and the Cloud Library
Sooner or later you will need types that no published OPC UA companion specification has, either as vendor extensions or as the start of a new companion spec. The OPC Foundation’s UA-ModelCompiler is now distributed as a cross-platform .NET global tool (dotnet tool install --global OPCFoundation.Opc.Ua.ModelCompiler.Tool, with builds for .NET 8 and .NET 10). It accepts a ModelDesign XML file or a NodeSet2 file.
It produces a NodeSet2, a NodeIds CSV, XSD and BSD datatype schemas, .NET classes, JSON Schema and OpenAPI for DataTypes, and constants for C#, Python and TypeScript. The README’s own example compiles Machinery against DI. The same pattern for a vendor model that extends Pumps looks like this:
Opc.Ua.ModelCompiler compile \
-d2 ./AcmePumps.ModelDesign.xml,Acme,AcmePumps \
-d2 ./nodesets/Opc.Ua.Pumps.NodeSet2.xml,Opc.Ua.Pumps,Pumps \
-d2 ./nodesets/Opc.Ua.Machinery.NodeSet2.xml,Opc.Ua.Machinery,Machinery \
-d2 ./nodesets/Opc.Ua.Di.NodeSet2.xml,Opc.Ua.DI,DI \
-cg ./AcmePumps.NodeIds.csv -version v105 -exclude Draft -o2 ./out
The CSV file is what keeps numeric NodeIds stable across releases. Commit it and never regenerate it from scratch, or every client that cached an identifier breaks. Graphical editors produce the same NodeSet2 output.
Unified Automation’s UA Modeler and Siemens’ SiOME (the free Siemens OPC UA Modeling Editor) are the two most common. Many working groups draft in a GUI and then normalise the result through ModelCompiler.
Publishing is the last step. The UA Cloud Library, specified in OPC 30400-1 and OPC 30400-2, hosts NodeSets with metadata and exposes REST and GraphQL interfaces, so tools can fetch a model by its namespace URI instead of a file path. Cloud-aware tools and AI agents increasingly use it to resolve unknown namespaces. Our piece on exposing companion specs to AI agents through MCP tools shows that pattern.
Trade-offs, Gotchas, and What Goes Wrong in Companion Spec Projects

Figure 4: Implementation decision flow, with the version-pinning gate where most builds fail.
Figure 4 shows the decision flow, and each gate below matches a failure we hit while preparing this OPC UA companion specification tutorial.
NodeSet and stack versions drift apart. Our first open62541 build failed with Reference ns=1;i=15001<--[ns=0;i=47]--ns=0;i=11715 has an unknown target. DI 1.05.0 links its namespace metadata object to Server/Namespaces (i=11715), which the default reduced namespace 0 leaves out. The fix was -DUA_NAMESPACE_ZERO=FULL.
Each open62541 release also pins a specific UA-Nodeset commit (257db9a for v1.5.10). Pointing UA_NODESET_DIR at a newer tag is an untested combination. Pin the stack and the models together, and upgrade them together.
Optional instantiation explodes. In asyncua 2.1.0, add_object(..., objecttype=PumpType) defaults to instantiate_optional=True. We measured one pump instance at 5 nodes with mandatory children only, and 3,262 nodes with every optional child copied. A skid with 20 pumps goes from 100 nodes to about 65,000.
Each one is browseable, reports a null or default value, and suggests to clients that you measure things you don’t. Instantiate mandatory children and add only the optional ones you can fill.
Hard-coded namespace indices. This was covered above, but it is the most common bug in field integrations. It survives testing because the test server always loads models in the same order. It fails when a customer’s gateway loads one more spec.
Missing intermediate dependencies. Leaving IA out of the chain stops the import. In asyncua 2.1.0, importing Machinery straight after DI raises ValueError: Server doesn't satisfy required XML-Models. Import them first!, and the message does not say which model is missing. Read the RequiredModel block, not a blog post’s load order.
Wrong reference types. Linking a machine to Machines with HasComponent instead of Organizes still looks fine in a browser, but clients that browse only Organizes find nothing. In the other direction, putting spec-defined children in your vendor namespace (6:Speed instead of 5:Speed) breaks every spec-aware browse path.
Placeholders taken literally. BrowseNames such as <Drive> are templates. An instance that contains a node literally named <Drive> is a bug.
Not every spec builds on DI. PackML 1.01 (OPC 30050) declares only the core namespace as a requirement. MTConnect (OPC 30070-1) maps its own device model. Bridging them to a Machinery-based nameplate is integration work, not something the specs do for you.
Our PackML state machine architecture guide covers that mapping. Spec versions also move at very different speeds: Pumps is still 1.0.0 from 2021, while Machinery has seven tagged releases since 2020.
Security is not part of the spec. An OPC UA companion specification defines semantics, not transport security. The NoSecurity endpoint in our demo is for a laptop only. Production pump servers need certificates, a security policy such as Basic256Sha256 or the ECC policies, and user authentication. Our OPC UA security, certificates and GDS guide walks through the setup.
Practical Recommendations for Your Next OPC UA Companion Specification Server
Choose your stack for an OPC UA companion specification server by target hardware. Generated code (open62541, the .NET stack’s generated classes) suits anything with constrained memory or a startup-time budget. Runtime import (asyncua) suits gateways, simulators and prototypes, where a 20-second start and a few hundred megabytes are acceptable. If you prototype in Python and ship in C, the generic client and the mandatory-node checker from this tutorial prove the two are equivalent, because they test against the specification rather than the implementation.
Treat every OPC UA companion specification NodeSet as a dependency with a lockfile. Record the UA-Nodeset tag or commit, each model’s ModelUri and version, and your own NodeIds CSV in version control. When a base layer such as DI or Machinery moves, upgrade it on a branch.
Rebuild, rerun the checker and CTT, then merge. Never mix NodeSet files from different releases without reading their RequiredModel blocks.
Design the instance before you write code against any OPC UA companion specification. List the mandatory nodes, then the optional groups your target facet requires. Then list the optional variables you can actually source from the device.
Anything not on those three lists stays out of the address space. If you also feed an MQTT broker or a unified namespace architecture, map topics from the OPC UA companion specification’s browse paths, so OT and IT share one vocabulary.
Checklist:
- Pin UA-Nodeset to a release tag, or to your stack’s pinned submodule commit.
- Load dependencies in
RequiredModelorder; include IA for Machinery 1.04. - Build open62541 with
UA_NAMESPACE_ZERO=FULLwhen loading current DI. - Resolve every namespace index by URI, on both server and client.
- Instantiate mandatory children only; add optional groups deliberately.
- Use spec BrowseNames for spec children and the vendor namespace for instance NodeIds.
- Run a mandatory-node check in CI and the CTT before claiming conformance.
- Enable a real security policy before the server leaves the lab.
Frequently Asked Questions
What is an OPC UA companion specification?
An OPC UA companion specification is an industry-specific information model built on the OPC UA core. It defines a namespace URI, ObjectTypes, VariableTypes, methods and modelling rules for one domain, such as pumps, robots, machine tools or packaging lines. It is published as a document plus a machine-readable NodeSet2 XML file.
Servers load that file and create instances of its types. Clients can then read any conformant device through the same browse paths and type definitions, without writing per-vendor mapping code.
Which NodeSets do I need to load for OPC 40223 Pumps?
For the current releases you need the core namespace (built into every stack), then DI (OPC 10000-100), then IA (OPC 10000-200), then Machinery (OPC 40001-1), then Pumps (OPC 40223), in that order. Pumps 1.0.0 declares DI and Machinery as requirements. Machinery 1.04.x also requires IA, which older tutorials leave out.
Always read the RequiredModel entries in each file’s Models block, because dependency chains change as base layers are revised. A missing IA namespace shows up as unrelated parent-node errors inside Machinery.
Should I use open62541’s nodeset compiler or asyncua import_xml?
For an OPC UA companion specification server, use the open62541 nodeset compiler, or its AUTOLOAD option, for embedded devices, PLC-class hardware and anything that needs a fast start. The model is compiled into C, and in our test the companion layers loaded in about 0.15 seconds, with about 49 MB resident memory. Use asyncua import_xml for gateways, simulators and prototypes. It needs no build step, but loading the Pumps NodeSet took about 22 seconds and the process used about 254 MB.
Why does my OPC UA client break when it connects to a different vendor’s server?
Usually because it hard-codes namespace indices such as ns=4 instead of resolving each OPC UA companion specification by its URI. Indices are assigned by each server based on the order it loads models, so they differ between vendors and even between firmware versions. Numeric identifiers within a namespace, such as PumpType at 1052, are stable.
Read the server’s NamespaceArray when you connect, find the index for each companion specification’s URI, and build NodeIds from that index. Use browse paths for children rather than cached NodeIds.
Where do I download official companion specification NodeSet files?
There are two official sources. The OPCFoundation/UA-Nodeset repository on GitHub publishes every released model, tagged per specification and per bundle, for example UA-1.05.07-2026-07-30. The UA Cloud Library, defined in OPC 30400, hosts the same models with metadata and lets tools query them over REST or GraphQL by namespace URI.
The OPC UA Online Reference at reference.opcfoundation.org has the readable specification text and a documentation link for each node. Pin the tag you download in version control.
How do I prove my server conforms to a companion specification?
Start with automated checks in CI. Verify that every Mandatory InstanceDeclaration resolves on your instances, as the checker in this tutorial does. Then confirm the DataTypes and engineering units.
For a formal claim, run the OPC Foundation Compliance Test Tool against the profiles and conformance units listed in the specification’s conformance section. Certification through an OPC Foundation test lab is the final step when customers require an OPC UA companion specification claim to be independently verified.
Further Reading
- OPC UA protocol: the complete technical guide for address space, services and security fundamentals.
- Production-ready OPC UA server in Python with asyncua for hardening the Python path shown here.
- OPC UA Robotics companion specification (OPC 40010) in depth to apply the same pattern to robots.
- umati vs MTConnect vs OPC UA for machine tools for choosing a machine-tool model.
- AAS vs DTDL vs OPC UA information models to place companion specs within digital-twin modelling.
- OPC UA FX field exchange reference architecture for where UAFX (OPC 10000-80 to 84) fits.
- OPC 40223 Pumps and Vacuum Pumps on the OPC UA Online Reference for the normative text.
- OPCFoundation/UA-Nodeset on GitHub for every released NodeSet2 file.
By Riju — about

Pingback: AAS Submodels in Practice (2026 Guide)