> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-4-2/guides/system-connectivity/industry-standards-interoperability/umati-integration.md). # umati Integration 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](https://github.com/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](/2-4-2/guides/system-connectivity/industry-standards-interoperability/using-connectware-as-an-opc-ua-client.md). * Access to the [Admin UI](/2-4-2/access/admin-ui.md) with sufficient [user permissions](/2-4-2/access/user-management.md). * Basic knowledge of MQTT and the Connectware [services](/2-4-2/data-flows/services.md) concept (for example, [service commissioning files](/2-4-2/data-flows/service-commissioning-files.md), [connections](/2-4-2/data-flows/service-commissioning-files/resources/cybus-connection.md), and [endpoints](/2-4-2/data-flows/service-commissioning-files/resources/cybus-endpoint.md)). ## Connectware and umati Integration [umati](https://umati.org) 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)](https://reference.opcfoundation.org/MachineTool/v102/docs/), 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](/2-4-2/connectors/shop-floor-connectors/opc-ua/opc-ua-client.md) 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](/2-4-2/guides/system-connectivity/industry-standards-interoperability/using-connectware-as-an-opc-ua-client.md). 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 (`////`), 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](/2-4-2/connectors/shop-floor-connectors/opc-ua/opc-ua-client.md#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. {% hint style="warning" %} 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. {% endhint %} ### 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. {% code lineNumbers="true" %} ```yaml 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 ``` {% endcode %} ### 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](/2-4-2/connectors/shop-floor-connectors/opc-ua/opc-ua-client/opcuaconnection.md) and [Using Connectware as an OPC UA Client](/2-4-2/guides/system-connectivity/industry-standards-interoperability/using-connectware-as-an-opc-ua-client.md). {% code lineNumbers="true" %} ```yaml resources: umatiConnection: type: Cybus::Connection properties: protocol: Opcua connection: host: !ref machineHost port: !ref machinePort username: !ref opcuaUser password: !ref opcuaPass ``` {% endcode %} ### 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. {% code lineNumbers="true" %} ```yaml 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' ``` {% endcode %} Each message contains the value and the OPC UA source timestamp. For `OperationMode`, the value is the numeric enumeration value: {% code lineNumbers="true" %} ```json { "timestamp": "2026-07-16T09:30:00.000Z", "value": 1 } ``` {% endcode %} `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. {% code lineNumbers="true" %} ```yaml 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' ``` {% endcode %} 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. {% code lineNumbers="true" %} ```yaml 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' ``` {% endcode %} 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](https://github.com/umati/Sample-Server) for details. 1. Install the service and set the parameters with the values of your machine. See [Installing Services](/2-4-2/data-flows/services/managing/installing.md). 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](/2-4-2/monitoring/data-explorer.md) 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 {% file src="/files/MEdBXalXmgVxGGi32z21" %} {% code title="umati-example.yml" lineNumbers="true" expandable="true" %} ```yaml --- # ---------------------------------------------------------------------------- # Service Commissioning File # ---------------------------------------------------------------------------- # Copyright: Cybus GmbH # Contact: support@cybus.io # ---------------------------------------------------------------------------- # 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 > > ...). 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' ``` {% endcode %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cybus.io/2-4-2/guides/system-connectivity/industry-standards-interoperability/umati-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.