umati Integration

How to read operation mode, program information, and stacklight signals from machine tools that implement umati (OPC 40501-1) using the Connectware OPC UA client connector.

This guide describes how to read data from machine tools that implement umati (universal machine technology interface) with Connectware. You configure a service commissioning file that connects to the machine's OPC UA server, subscribes to the operation mode, the active program, and the stacklight, and publishes the values to an ISA-95-style MQTT topic hierarchy. A complete example file is available at the end of this guide.

Objectives

• Understanding umati and the OPC UA for Machine Tools information model.

• Resolving the namespace index and NodeIds of the machine tool nodes on your machine.

• Connecting Connectware to the machine's OPC UA server.

• Subscribing to the operation mode, the active program, and the stacklight.

• Publishing the values to an ISA-95-style MQTT topic hierarchy.

• Testing the integration against the public umati sample server.

Prerequisites

To follow this guide, you will need the following:

• A running instance of Cybus Connectware.

• A machine tool whose OPC UA server implements OPC UA for Machine Tools (OPC 40501-1), reachable from Connectware over the network. If you do not have a machine available, you can follow the guide against the public umati sample server instead.

• An OPC UA client for browsing the machine's address space, for example UaExpert or one of the tools listed in Using Connectware as an OPC UA Client.

• Access to the Admin UI with sufficient user permissions.

• Basic knowledge of MQTT and the Connectware services concept (for example, service commissioning files, connections, and endpoints).

Connectware and umati Integration

umati is a community of machine builders, component suppliers, and software vendors, initiated by the VDW (German Machine Tool Builders' Association) and the VDMA (German Engineering Federation). umati is not a protocol of its own. It promotes the adoption of OPC UA companion specifications across the machinery industry, so that machines from different vendors expose their data in the same standardized structure. For machine tools, the relevant companion specification is OPC UA for Machine Tools (OPC 40501-1), which builds on the basic building blocks of OPC UA for Machinery (OPC 40001-1). A machine that carries the umati label for machine tools implements OPC 40501-1.

Connectware connects to the machine's OPC UA server with the OPC UA client connector and subscribes to the machine tool nodes in the same way as any other OPC UA nodes. For generic OPC UA setup topics such as browsing the address space, security policies, and certificate exchange, see Using Connectware as an OPC UA Client. This guide focuses on the umati specifics: where the data lives and how to address it.

The MQTT topics in this guide follow an ISA-95-style equipment hierarchy (<enterprise>/<site>/<area>/<line>/<cell>), with one topic per data point below the machine level. This keeps the machine data addressable in a Unified Namespace alongside other equipment.

The OPC UA for Machine Tools Information Model

A machine tool that implements OPC 40501-1 exposes one instance of MachineToolType per machine. All instances are referenced from the Machines folder that OPC UA for Machinery defines directly below the Objects folder, so a client finds every machine tool of a server in one place. The components of the machine tool instance group the machine data:

Component	Content
Identification	Manufacturer, model, serial number, and software identification.
Monitoring	Operating state of the machine tool and its subsystems, including the operation mode and the stacklight.
Production	The active program (ActiveProgram) and, optionally, the production plan (ProductionPlan) with its jobs and production statistics.
Equipment	The tools mounted on the machine. Optional.
Notification	Machine messages (alarms and warnings) and prognoses of upcoming events, such as required tool changes or the end of a production job.

For an MES-style integration that reads data from the machine, the most relevant nodes are the following:

• Monitoring.MachineTool.OperationMode: The current operation mode as an enumeration value: 0 (Manual), 1 (Automatic), 2 (Setup), 3 (AutoWithManualIntervention), 4 (Service), 5 (Other).

• Monitoring.MachineTool.PowerOnDuration: The total duration the machine has been powered on, counted in full hours. Optional.

• Monitoring.Stacklight: The composition and status of the machine's stacklight. Each lamp is an element with SignalOn (whether the lamp is lit) and SignalColor (the lamp color as an enumeration value, for example 1 for red and 2 for green).

• Production.ActiveProgram: The NC program that is currently running, with Name, NumberInList (the position of the program in the production plan), and State. The state machine's CurrentState variable holds the current program state: Initializing, Running, Ended, Interrupted, or Aborted.

In addition to these variables, the Notification component delivers machine messages and prognoses as OPC UA events, which you can receive with Connectware as described in Events for OPC UA. This guide uses variable subscriptions, which cover the typical monitoring data needs.

Resolving the Namespace Index and NodeIds

The BrowseNames in the OPC UA for Machine Tools information model are standardized, but the NodeIds of the instance nodes are not. Each OPC UA server assigns its namespaces a numeric index at runtime, and machine vendors place the instance nodes in their own namespace with vendor-specific identifiers. A NodeId that works on one machine does not work on another. Before you write the service commissioning file, resolve the actual NodeIds on your machine:

1. Connect to the machine's OPC UA server with an OPC UA client, for example UaExpert.

2. Read the NamespaceArray variable (ns=0;i=2255). Its value lists all namespace URIs of the server. The position of a URI in this array is its namespace index. If the machine implements OPC UA for Machine Tools, the array contains the namespace URI http://opcfoundation.org/UA/MachineTool/. The instance nodes of the machine usually live in a separate vendor-specific namespace.

3. Browse to Objects > Machines and open the machine tool instance of your machine.

4. Navigate along the standardized BrowseNames, for example Monitoring > MachineTool > OperationMode, select the node, and copy the NodeId shown in the attributes pane. This is the value for the nodeId property of the corresponding Connectware endpoint. The namespace index of the instance nodes is the value for the namespaceIndex parameter.

The NodeIds in this guide, such as ns=5;s=ExampleMachineTool.Monitoring.MachineTool.OperationMode, are machine-specific examples. Both the namespace index and the identifier differ between machine vendors, and many machines use numeric instead of string identifiers. Always use the NodeIds that your OPC UA client shows for your machine.

umati Parameters

We add the connection details, the namespace index, and the topic root as parameters to the service commissioning file, so you can set them when you install the service.

Do not worry about copying the service commissioning file snippets together into one, the complete example file is available at the end of this guide.

• machineHost and machinePort: The address of the machine's OPC UA server. The default OPC UA port is 4840, the machine documentation tells you the actual value.

• opcuaUser and opcuaPass: The credentials for the OPC UA server. Leave them empty for anonymous access.

• namespaceIndex: The namespace index of the machine tool instance nodes on your machine, resolved from the NamespaceArray.

• topicRoot: The ISA-95-style topic prefix for this machine.

parameters:
  machineHost:
    description: Hostname or IP address of the machine's OPC UA server
    type: string
    default: 192.168.1.100

  machinePort:
    description: Port of the machine's OPC UA server
    type: integer
    default: 4840

  opcuaUser:
    description: Username for the machine's OPC UA server (empty for anonymous access)
    type: string
    default: ''

  opcuaPass:
    description: Password for the machine's OPC UA server
    type: string
    default: ''

  namespaceIndex:
    description: >-
      Namespace index of the machine tool instance nodes on your machine.
      Resolve it from the NamespaceArray (ns=0;i=2255) of your machine's
      OPC UA server.
    type: integer
    default: 5

  topicRoot:
    description: Root of the ISA-95-style MQTT topic hierarchy for this machine
    type: string
    default: enterprise/hamburg/machining/line-1/machine-tool-01

umati Connection

To connect to the machine's OPC UA server, we set up a Cybus::Connection resource that uses the OPC UA connector. For the complete set of connection options, including messageSecurityMode, securityPolicy, and client certificates, see the OPC UA connection properties and Using Connectware as an OPC UA Client.

resources:
  umatiConnection:
    type: Cybus::Connection
    properties:
      protocol: Opcua
      connection:
        host: !ref machineHost
        port: !ref machinePort
        username: !ref opcuaUser
        password: !ref opcuaPass

Reading the Operation Mode

The monitoring endpoints subscribe to Monitoring.MachineTool.OperationMode and Monitoring.MachineTool.PowerOnDuration. Because these are subscriptions, the OPC UA server only sends data when a value changes, for example when an operator switches the machine from Setup to Automatic. The topic property publishes each value to its place in the ISA-95 hierarchy.

operationMode:
  type: Cybus::Endpoint
  properties:
    protocol: Opcua
    connection: !ref umatiConnection
    topic: !sub '${topicRoot}/monitoring/operation-mode'
    subscribe:
      nodeId: !sub 'ns=${namespaceIndex};s=ExampleMachineTool.Monitoring.MachineTool.OperationMode'

powerOnDuration:
  type: Cybus::Endpoint
  properties:
    protocol: Opcua
    connection: !ref umatiConnection
    topic: !sub '${topicRoot}/monitoring/power-on-duration'
    subscribe:
      nodeId: !sub 'ns=${namespaceIndex};s=ExampleMachineTool.Monitoring.MachineTool.PowerOnDuration'

Each message contains the value and the OPC UA source timestamp. For OperationMode, the value is the numeric enumeration value:

{ "timestamp": "2026-07-16T09:30:00.000Z", "value": 1 }

PowerOnDuration is optional in OPC 40501-1 and deprecated in favor of the OperationCounters object since release 1.02. If your machine exposes Monitoring.MachineTool.OperationCounters.PowerOnDuration instead, use that node. Its data type is Duration, a floating point number of milliseconds, rather than full hours.

Reading the Active Program

The program endpoints subscribe to the active program under Production.ActiveProgram. The name and the list position identify what the machine is executing, the state tells you how the program is progressing. State.CurrentState is a localized text with values such as Running or Interrupted. If you prefer the numeric state (0 to 4), subscribe to the Number property below CurrentState instead.

programName:
  type: Cybus::Endpoint
  properties:
    protocol: Opcua
    connection: !ref umatiConnection
    topic: !sub '${topicRoot}/production/active-program/name'
    subscribe:
      nodeId: !sub 'ns=${namespaceIndex};s=ExampleMachineTool.Production.ActiveProgram.Name'

programNumberInList:
  type: Cybus::Endpoint
  properties:
    protocol: Opcua
    connection: !ref umatiConnection
    topic: !sub '${topicRoot}/production/active-program/number-in-list'
    subscribe:
      nodeId: !sub 'ns=${namespaceIndex};s=ExampleMachineTool.Production.ActiveProgram.NumberInList'

programState:
  type: Cybus::Endpoint
  properties:
    protocol: Opcua
    connection: !ref umatiConnection
    topic: !sub '${topicRoot}/production/active-program/state'
    subscribe:
      nodeId: !sub 'ns=${namespaceIndex};s=ExampleMachineTool.Production.ActiveProgram.State.CurrentState'

For job-level information, such as planned quantities and produced parts, check whether your machine exposes the optional Production.ProductionPlan component and add endpoints for its job nodes in the same way.

Reading the Stacklight

The stacklight endpoints subscribe to the signal state of one stacklight lamp under Monitoring.Stacklight. The stacklight is modeled as an ordered list of lamp elements, each with SignalOn and SignalColor variables. The number of lamps and their browse names, for example Light0, are server-specific, so browse the stacklight of your machine and add one pair of endpoints per lamp you want to monitor.

stacklightSignalOn:
  type: Cybus::Endpoint
  properties:
    protocol: Opcua
    connection: !ref umatiConnection
    topic: !sub '${topicRoot}/monitoring/stacklight/light-0/signal-on'
    subscribe:
      nodeId: !sub 'ns=${namespaceIndex};s=ExampleMachineTool.Monitoring.Stacklight.Light0.SignalOn'

stacklightSignalColor:
  type: Cybus::Endpoint
  properties:
    protocol: Opcua
    connection: !ref umatiConnection
    topic: !sub '${topicRoot}/monitoring/stacklight/light-0/signal-color'
    subscribe:
      nodeId: !sub 'ns=${namespaceIndex};s=ExampleMachineTool.Monitoring.Stacklight.Light0.SignalColor'

The Stacklight component is optional in OPC 40501-1. If your machine does not expose it, remove these endpoints from the service commissioning file.

Verifying the Integration

If you do not have a machine tool at hand, you can verify the service against the public umati sample server. It runs at opc.tcp://opcua.umati.app:4840 with anonymous authentication and accepts unencrypted connections, and it simulates several machine tools with pseudo-randomly changing values below its Machines folder. Set machineHost to opcua.umati.app, browse the simulated machines with your OPC UA client, and set namespaceIndex and the NodeIds to the values of one of them. See the umati Sample-Server repository for details.

1. Install the service and set the parameters with the values of your machine. See Installing Services.

2. Check that the connection is in the Connected state on the service details page in the Admin UI. If the connection stays in the connecting state, verify the host, the port, and the security settings of the machine's OPC UA server.

3. Open the Data Explorer and subscribe to the topic root, for example enterprise/hamburg/machining/line-1/machine-tool-01/#. The monitoring topics receive their current values right after the subscription is established.

4. Change the operation mode on the machine control panel and check that a new value arrives on the monitoring/operation-mode topic.

5. Start an NC program and check that the production/active-program topics update and that the stacklight topics change with the machine state. If a topic stays empty, verify the NodeId of the corresponding endpoint against your OPC UA client, a wrong namespace index is the most common cause.

Service Commissioning File Example

umati-example.yml

5KB

Open

umati-example.yml

---
# ----------------------------------------------------------------------------
# Service Commissioning File
# ----------------------------------------------------------------------------
# Copyright: Cybus GmbH
# Contact: [e-mail]
# ----------------------------------------------------------------------------
# umati Integration (Example)
# ----------------------------------------------------------------------------

description: >
  Service commissioning file for reading operation mode, active program
  information, and stacklight signals from a machine tool that implements
  umati (OPC UA for Machine Tools, OPC 40501-1) (Example)

metadata:
  name: umati Integration
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0

parameters:
  machineHost:
    description: Hostname or IP address of the machine's OPC UA server
    type: string
    default: 192.168.1.100

  machinePort:
    description: Port of the machine's OPC UA server
    type: integer
    default: 4840

  opcuaUser:
    description: Username for the machine's OPC UA server (empty for anonymous access)
    type: string
    default: ''

  opcuaPass:
    description: Password for the machine's OPC UA server
    type: string
    default: ''

  namespaceIndex:
    description: >-
      Namespace index of the machine tool instance nodes on your machine.
      Resolve it from the NamespaceArray (ns=0;i=2255) of your machine's
      OPC UA server.
    type: integer
    default: 5

  topicRoot:
    description: Root of the ISA-95-style MQTT topic hierarchy for this machine
    type: string
    default: enterprise/hamburg/machining/line-1/machine-tool-01

resources:
  # Connection to the machine's OPC UA server. For security policies and
  # certificate exchange, see the OPC UA client documentation.
  umatiConnection:
    type: Cybus::Connection
    properties:
      protocol: Opcua
      connection:
        host: !ref machineHost
        port: !ref machinePort
        username: !ref opcuaUser
        password: !ref opcuaPass

  # --------------------------------------------------------------------------
  # Monitoring (Monitoring.MachineTool and Monitoring.Stacklight)
  # --------------------------------------------------------------------------
  # All NodeId string identifiers below are machine-specific examples.
  # Replace them with the NodeIds that your OPC UA client shows for your
  # machine (Objects > Machines > <machine tool instance> > ...).

  operationMode:
    type: Cybus::Endpoint
    properties:
      protocol: Opcua
      connection: !ref umatiConnection
      topic: !sub '${topicRoot}/monitoring/operation-mode'
      subscribe:
        nodeId: !sub 'ns=${namespaceIndex};s=ExampleMachineTool.Monitoring.MachineTool.OperationMode'

  powerOnDuration:
    type: Cybus::Endpoint
    properties:
      protocol: Opcua
      connection: !ref umatiConnection
      topic: !sub '${topicRoot}/monitoring/power-on-duration'
      subscribe:
        nodeId: !sub 'ns=${namespaceIndex};s=ExampleMachineTool.Monitoring.MachineTool.PowerOnDuration'

  # The stacklight element names (for example, Light0) are server-specific.
  # Browse Monitoring > Stacklight on your machine for the actual elements.

  stacklightSignalOn:
    type: Cybus::Endpoint
    properties:
      protocol: Opcua
      connection: !ref umatiConnection
      topic: !sub '${topicRoot}/monitoring/stacklight/light-0/signal-on'
      subscribe:
        nodeId: !sub 'ns=${namespaceIndex};s=ExampleMachineTool.Monitoring.Stacklight.Light0.SignalOn'

  stacklightSignalColor:
    type: Cybus::Endpoint
    properties:
      protocol: Opcua
      connection: !ref umatiConnection
      topic: !sub '${topicRoot}/monitoring/stacklight/light-0/signal-color'
      subscribe:
        nodeId: !sub 'ns=${namespaceIndex};s=ExampleMachineTool.Monitoring.Stacklight.Light0.SignalColor'

  # --------------------------------------------------------------------------
  # Active program (Production.ActiveProgram)
  # --------------------------------------------------------------------------

  programName:
    type: Cybus::Endpoint
    properties:
      protocol: Opcua
      connection: !ref umatiConnection
      topic: !sub '${topicRoot}/production/active-program/name'
      subscribe:
        nodeId: !sub 'ns=${namespaceIndex};s=ExampleMachineTool.Production.ActiveProgram.Name'

  programNumberInList:
    type: Cybus::Endpoint
    properties:
      protocol: Opcua
      connection: !ref umatiConnection
      topic: !sub '${topicRoot}/production/active-program/number-in-list'
      subscribe:
        nodeId: !sub 'ns=${namespaceIndex};s=ExampleMachineTool.Production.ActiveProgram.NumberInList'

  programState:
    type: Cybus::Endpoint
    properties:
      protocol: Opcua
      connection: !ref umatiConnection
      topic: !sub '${topicRoot}/production/active-program/state'
      subscribe:
        nodeId: !sub 'ns=${namespaceIndex};s=ExampleMachineTool.Production.ActiveProgram.State.CurrentState'