Connecting a Machine via Heidenhain DNC Interface

How to connect a machine via Heidenhain DNC Interface to Connectware.

This guide explains how to connect a Heidenhain controller to Connectware, using the TNC 640 emulator as a practical example.

The following topics are covered:

Setting up the Cybus Heidenhain Agent
Selecting the methods
Creating the service commissioning file
Installing the service
Verifying data in the Data Explorer

The service commissioning files used in this guide are available in the Example Files Repository on GitHub.

About Heidenhain DNC

Heidenhain is a leading manufacturer of measurement and control technology for CNC machines. Their controllers offer the Heidenhain DNC interface (also known as Option 18), which enables vertical integration by providing access to machine data and functions.

The DNC protocol uses Remote Procedure Calls (RPC), allowing operations to be executed by invoking methods on the target device.

For a complete list of available methods, see Heidenhain Methods.

Cybus Heidenhain Agent

To access the Heidenhain DNC COM component, Connectware uses the Windows-based Cybus Heidenhain Agent, which runs as a Windows service.

The Cybus Heidenhain Agent implements the Heidenhain RemoTools SDK, exposing a Microsoft COM component for communication with Heidenhain DNC interfaces.

To download and install the Cybus Heidenhain Agent, see Installing the Cybus Heidenhain Agent.

Prerequisites

To follow this guide, you will need the following:

A running instance of Cybus Connectware.
Cybus Heidenhain Agent is installed.
Access to the Admin UI with sufficient user permissions.
Basic knowledge of MQTT and the Connectware services concept (e.g. service commissioning files, connections, and endpoints).
It helps to be familiar with Connecting an MQTT Client to Publish and Subscribe Data.

System Requirements

The host machine running the Cybus Heidenhain Agent must meet the following requirements:

Windows 10 or Windows Server 2019
Installed Heidenhain SDK
Network access to the target controllers or emulators

Port and protocol Requirements

iTNC 530 / TNC 426

ICMP (Ping) from Windows Host to Controller
TCP 19000 from Windows Host to Controller

TNC 640

ICMP (Ping) from Windows Host to Controller
TCP 19003 from Windows Host to Controller
TCP 19010–19015 from Controller to Agent Host

Connectware access

TCP 8883 from Windows Host to Connectware

Installation

Launch the Cybus Heidenhain Agent installer and follow the prompts.
Enter the Connectware host IP address when prompted.

After installation, the Cybus Heidenhain Agent service will run automatically.

Configured to start on Windows boot and restart after a crash
Status can be checked in Windows Services
Logs are available in the Windows Event Viewer

Post-Installation Configuration

Go to the Connectware Admin User Interface (Admin UI) and log in.

One-Time Setup: Agent Role

The agent needs MQTT topic access for publishing and subscribing.

Create a new role and assign the following permission:
- Name: heidenhain-agent
- Data permission: edge.cybus/# (read and write)

Per-Agent Setup: Onboarding

Use the Client Registry to onboard the agent.

Follow the self-registration process, wait for the agent to appear, approve it, and assign the heidenhain-agent role.

Installing and Starting the Heidenhain Emulator

For this guide, we will use the TNC 640 emulator running on Windows instead of a physical controller.

Download the latest TNC 640 Programming Station from heidenhain.com.
Install it on the same Windows machine as the agent (or another machine in the same network).
Launch the emulator from the desktop shortcut TNC 640.
On startup, if you see "Power interrupted", press CE on the keypad to enter manual mode.

The emulator should now be available on the network.

Selecting the Methods

In the service commissioning file for our Heidenhain DNC application, we must specify a set of controller methods we want to make available with Connectware. In this example, we use the following subset of the available Heidenhain Methods:

getState
getPlcData
getToolTableRow
transmitFile
onToolTableChanged

Creating the Service Commissioning File

A service commissioning file defines the resources needed for data collection and exchange. It is written in YAML and read by Connectware.

We will create the heidenhain-example-commissioning-file.yml with the following sections:

Description
Metadata
Parameters
Resources

To learn more about the structure of service commissioning files, see Service Commissioning Files.

1. Description and Metadata

These sections contain general information about the service commissioning file. You can give a short description and add a stack of metadata. Regarding the metadata, only the name is required while the rest is optional. We will just use the following set of information for this guide:

description: >
  Heidenhain DNC Example Commissioning File
  Cybus Connectware - How to connect a machine via Heidenhain DNC interface
  https://docs.cybus.io/documentation/machine-connectivity/connecting-a-machine-via-heidenhain-dnc-interface

metadata:
  name: Heidenhain DNC Example
  version: 1.0.0
  icon: https://www.cybus.io/wp-content/uploads/2019/03/Cybus-logo-Claim-lang.svg
  provider: Cybus GmbH
  homepage: https://www.cybus.io

2. Parameters

Parameters allow you to prepare service commissioning files for multiple use cases by referring to them from within the file. Every time a service commissioning file is applied or a service is reconfigured in Connectware, you are asked to enter custom values for the parameters or to confirm the default values.

parameters:
  agentId:
    type: string
    description: Agent Identification (Cybus Heidenhain Agent)
    default: <yourAgentId>
  machineIP:
    type: string
    description: IP Address of the machine
    default: <yourMachineAddress>
  cncType:
    type: string
    default: tnc640
    description: >-
      Type of the machine control (DNC Type). Allowed values: tnc640, itnc530,
      itnc426.
    allowedValues:
      - tnc640
      - itnc530
      - tnc426

The parameters we define here could vary from setup to setup, so it is advised to make them configurable. The agentId is the name of the agent's user in Connectware, which was defined during client registration. The machineIP in our example is the address of the Windows machine running the TNC 640 emulator or would be the address of the machine tool you want to connect to. As parameter cncType, we define the type of controller we use and additionally specify the currently supported controller types as allowedValues for this parameter.

3. Resources

In the resources section, we declare every resource needed for our application. For details about the different resource types and available protocols, see Resources.

Connection

The first resource we need is a connection to the Heidenhain controller. The connection is defined by its type and its type-specific properties. In the case of Cybus::Connection we declare which protocol and connection parameters we want to use. For the definition of our connection we reference the earlier declared parameters agentId, machineIP and cncType by using !ref.

resources:
  heidenhainConnection:
    type: 'Cybus::Connection'
    properties:
      protocol: Heidenhain
      connection:
        agent: !ref agentId
        ipAddress: !ref machineIP
        cncType: !ref cncType
        plcPassword: <password>
        usrPassword: <password>
        tablePassword: <password>
        sysPassword: <password>

Access to your TNC 640 controller is restricted by four pre-configured passwords. If you need help to find out the necessary passwords, contact our Support Team. For iTNC 530 and TNC 426, no password is required.

Endpoints

The next resources needed are the endpoints which will provide or accept data. All endpoints have some properties in common, namely the protocol defined as Heidenhain, the connection which is referenced to the previously defined connection resource using !ref, and the optional topic defining on which MQTT topic the result will be published. In the default case, the full endpoint topic will expand to services/<serviceId>/<topic>. For more information, see Cybus::Endpoint.

The endpoints will make use of the methods we selected earlier. Those methods are all a bit different, so let’s take a look at each of the endpoint definitions.

getStatePolling:
  type: 'Cybus::Endpoint'
  properties:
    protocol: Heidenhain
    connection: !ref heidenhainConnection
    topic: getState
    subscribe:
      method: getState
      type: poll
      pollInterval: 5000
      params: []

The first endpoint uses the method getState, which requests the current machine state. The result is published on the topic getState. This endpoint is defined with the property subscribe, which in the context of a Heidenhain connection means that it will request the state at the frequency defined by pollInterval. This is also known as polling and brings us to the definition of the type, which therefore is poll.

getState:
  type: 'Cybus::Endpoint'
  properties:
    protocol: Heidenhain
    connection: !ref heidenhainConnection
    topic: getState
    read:
      method: getState

Alternatively, you can use the method getState by requesting the state only once when it is called. The definition of this endpoint differs from the previous in the property read instead of subscribe. To utilize this endpoint and call the method, you need to publish an MQTT message to the topic services/<serviceId>/<topic>/req. The result of the method will be published on the topic services/<serviceId>/<topic>/res. <topic> should be replaced with the topic we defined for this endpoint, namely getState. The serviceId will be defined during the installation of the service and can be found in the services list in the Connectware Admin UI.

getToolTableRow:
  type: 'Cybus::Endpoint'
  properties:
    protocol: Heidenhain
    connection: !ref heidenhainConnection
    topic: getToolTableRow
    read:
      method: getToolTableRow

The previously used method getState did not expect any arguments, so we could just call it by issuing an empty message on the req topic. The method getToolTableRow is used to request a specific row of the tool table. To specify which row should be requested, we need to supply the toolId. We will look at an example of this method call in the last section of this guide.

getPlcData:
  type: 'Cybus::Endpoint'
  properties:
    protocol: Heidenhain
    connection: !ref heidenhainConnection
    topic: getPlcData
    read:
      method: getPlcData

Using the method getPlcData allows us to request data stored on any memory address of the controller. The arguments that must be provided are the memoryType and the memoryAddress.

transmitFile:
  type: 'Cybus::Endpoint'
  properties:
    protocol: Heidenhain
    connection: !ref heidenhainConnection
    topic: transmitFile
    read:
      method: transmitFile

The method transmitFile allows us to transmit a file in the form of a base64-encoded buffer to a destination path on the Heidenhain controller. It expects two arguments: the string fileBuffer and another string destinationPath.

onToolTableChanged:
  type: 'Cybus::Endpoint'
  properties:
    protocol: Heidenhain
    connection: !ref heidenhainConnection
    topic: notify/onToolTableChanged
    subscribe:
      type: notify
      method: onToolTableChanged

The last endpoint we define calls the method onToolTableChanged. This is an event method which will send a notification in case of a changed tool table. For this, we use the property subscribe along with the type notify. This means that we are not polling the method in this context but subscribe to it and wait for a notification on the specified topic. You can trigger a notification by modifying the tool table in the TNC emulator.

Installing the Service Commissioning File

Install the service commissioning file. See Installing Services.
Enable the service. See Enabling Services.

Result: The service is enabled. This results in the installation of a service that manages all the resources we have just defined. This includes the Heidenhain connection, the endpoints that collect data from the device, and the mapping that controls where this data can be accessed.

After enabling this service, you can verify that everything works correctly.

How Components Work Together

The Heidenhain agent running on the Windows machine tries to connect to Connectware at the IP address that was defined during its installation, as soon as it is started. We recognized these connection attempts when we opened the Connectware client registry and accepted the request of the Heidenhain agent with the name heidenhain-<windows-pc-hostname>. As a result, a user with this name was created in Connectware. We manually assigned this user the role heidenhain-agent and through that granted the permission to access the MQTT topic for data exchange.

After the installation of the service in Connectware, it tries to establish the Heidenhain connection we declared in the resources section of the service commissioning file. There we have defined the name of the Heidenhain agent and the IP address of the Heidenhain controller to connect to, or in our case of the emulator, which runs on the same machine as the agent. (When working with a real machine controller, that would obviously not be the case.) As soon as the connection to the Heidenhain controller is established, the service enables the endpoints which rely on the method calls issued by the agent to the Heidenhain controller via RPC. To address multiple Heidenhain controllers, you could utilize the same agent but need to specify separate connection resources for each of them.

Verifying the Connection

Now that we have a connection established between the Heidenhain controller and Connectware, we can go to the Data Explorer, where we see a tree structure of our newly created data points. Since we subscribed to the method getState, we should already see data being polled and published on this topic. Find the topic getState under services/heidenhainexample.

On MQTT topics, the data is provided in JSON format. To utilize a method that expects arguments, you would issue a request by publishing a message on the corresponding req topic with the arguments as payload. For example, to use the endpoint getToolTableRow, you could publish the following message to request the tool information of tool table ID 42:

{ "id": "1", "params": ["42"] }

The payload must be a valid JSON object and can contain two properties:

id: (optional) User-defined correlation ID which can be used to identify the response. If this property is given, its value will be returned in the response message.
params: Array of parameters required for the used method. If the method requires no parameters, this property is optional.

For a list of all arguments required for each call along with the methods, see Heidenhain Methods.

The answer you would receive to this method call could look as follows:

{
  "timestamp": 1598534586513,
  "result": {
    "CUR_TIME": "0",
    "DL": "+0",
    "DR": "+0",
    "DR2": "+0",
    "L": "+90",
    "NAME": "MILL_D24_FINISH",
    "PLC": "%00000000",
    "PTYP": "0",
    "R": "+12",
    "R2": "+0",
    "T": "32",
    "TIME1": "0",
    "TIME2": "0"
  },
  "id": "1"
}

To learn how you can easily test and interact with MQTT topics like in this example, see Connecting an MQTT Client to Publish & Subscribe Data.

In the Workbench, you can open the menu in the upper right corner, select Import, and select the nodered-flow.json from the Example Repository on the Cybus GitHub repo to add the test flow shown below. Add your MQTT credentials to the purple subscribe and publish nodes, then trigger requests.

[
  {
    "id": "cba40915.308b38",
    "type": "tab",
    "label": "Heidenhain DNC Demo",
    "disabled": false,
    "info": ""
  },
  {
    "id": "bc623e05.ae0f7",
    "type": "inject",
    "z": "cba40915.308b38",
    "name": "Trigger "getState" request (see here for payload)",
    "props": [
      {
        "p": "payload"
      },
      {
        "p": "topic",
        "vt": "str"
      }
    ],
    "repeat": "",
    "crontab": "",
    "once": false,
    "onceDelay": 0.1,
    "topic": "",
    "payload": "{"id":"1","params":[]}",
    "payloadType": "json",
    "x": 240,
    "y": 200,
    "wires": [
      [
        "aff3fdcf.d275d",
        "9fd44184.a11d1"
      ]
    ]
  },
  {
    "id": "f450d307.396ee",
    "type": "comment",
    "z": "cba40915.308b38",
    "name": "Demo for Connectware Documentation "How to connect a machine via Heidenhain DNC interface"",
    "info": "",
    "x": 360,
    "y": 60,
    "wires": []
  },
  {
    "id": "aff3fdcf.d275d",
    "type": "mqtt out",
    "z": "cba40915.308b38",
    "name": "",
    "topic": "services/heidenhaindncexample/getState/req",
    "qos": "0",
    "retain": "false",
    "broker": "b7832f1d.e9d4e",
    "x": 630,
    "y": 200,
    "wires": []
  },
  {
    "id": "ddec5b0c.c0c418",
    "type": "mqtt in",
    "z": "cba40915.308b38",
    "name": "",
    "topic": "services/heidenhaindncexample/getState/res",
    "qos": "0",
    "datatype": "auto",
    "broker": "b7832f1d.e9d4e",
    "x": 2

Summary

We successfully connected a Heidenhain controller to Connectware via the DNC interface, using the Cybus Heidenhain Agent and RemoTools SDK. We created a service commissioning file, connected to a TNC 640 emulator, and retrieved machine data.

This integration enables secure, unified access to Heidenhain DNC data alongside other industrial interfaces through Connectware’s API.

PreviousConnecting & Integrating a SICK RFID Sensor via SOPAS NextSystem Connectivity

Last updated 1 day ago

Was this helpful?