Heidenhain DNC

The Connectware implementation of the Heidenhain DNC protocol enables interaction with CNC machines over Heidenhain DNC. It supports:

• Reading machine data and status information.

• Editing tool and pocket tables.

• Accessing data and files on the machine’s filesystem.

Each machine connection consists of:

• Connection settings: How Connectware connects to the machine.

• Data mappings: How Heidenhain data is mapped to MQTT topics.

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.

Installing the Cybus Heidenhain Agent

1. Download the Cybus Heidenhain Installer.

Cybus Heidenhain Installer (v4.0.3)

1. Run the installer.

2. After installation, enable/start the agent via the Windows Services console.

3. Optional: Configure the service to restart on failure.

4. Agent logs are available in Windows Event Viewer.

Service Commissioning File Specifics

This section explains the Cybus::Connection and Cybus::Endpoint configuration objects.

For a complete reference, see the example:

20KB

heidenhain-dnc-reference.yml

Open

For an overview of the available connection and endpoint properties, see:

• Connection Properties

• Endpoint Properties

Data Mappings

Data mappings are defined in the Heidenhain Methods section.

Each mapping for a Heidenhain method specifies:

• Communication pattern

• Heidenhain method (e.g., setToolTableRow)

Every Heidenhain method provides one of the following access patterns:

• subscription

• read (request/response) or write (as an alias)

• notification

Subscription

Use the subscribe pattern to poll a Heidenhain method at a fixed interval.

Example mapping

getStateSubscribe:
    type: Cybus::Endpoint
    properties:
        protocol: Heidenhain
        connection: !ref heidenhainConnection
        topic: myCustomOutputTopic
        subscribe:
            type: poll
            method: getState
            pollInterval: 5000

Payload format

The MQTT message of the output data will be sent to the topic as specified in the endpoint configuration (in the example: myCustomOutputTopic). See also topic property.

Message format

{ 'result': <data>, 'timestamp': <timestamp> }

Read

The endpoint’s read property implements a request/response pattern. This enables you to request a machine action and receive a response.

It follows JSON-RPC 2.0 specification with the following exceptions:

• The method is defined by the Cybus::Endpoint (derived from the MQTT topic) and is not provided in the request.

• The jsonrpc member is ignored and currently not sent.

Send requests to the MQTT topic <endpointName>/req (e.g., setToolTableRow/req), and receive responses on <endpointName>/res.

Alternatively, configure the endpoint as write. The behavior is identical to read except that the request topic uses /set (responses still arrive on /res). In other words, write is just an alias for read.

The payload of the initial request message must be a JSON object as string, which must contain the params member as a JSON array (unless the method has no parameters anyway). The params member must be a JSON array with the method arguments listed as JSON values. The array of method arguments is passed on to the machine and is used depending on the Heidenhain machine method. The response message of reador write will contain the return value from the machine method as payload member result, or, if the method call failed, a payload member error which contains the error message.

Example mapping

setToolTableRow:
 type: Cybus::Endpoint
  properties:
    protocol: Heidenhain
    connection: !ref heidenhainConnection
    read:
      method: setToolTableRow

MQTT payload

The MQTT request payload must be a valid JSON object and can contain the following properties:

• id (optional): User-defined correlation ID which can be used to identify the response. If this property was given, its value will be returned in the return message.

• params: Array of parameters required for the used method. If the method requires no parameters, this property is optional.

Following the example mapping above (method: setToolTableRow), the request payload sent on topic setToolTableRow/req must be as follows:

{ 'params': ['1', { 'NAME': 'REQUEST-EXAMPLE' }], 'id': '1' }

This modifies the tool table row 1 and sets the field NAME of that row to REQUEST-EXAMPLE. The following response will be replied on topic setToolTableRow/res:

On success: { 'result': null, timestamp: 123123123, 'id': '1' }
On error: { 'error': '<error message>', timestamp: 123123123, 'id': '1' }

Since setToolTableRow returns void, the successful result is null.

Notification

Some Heidenhain methods provide a notification pattern, publishing messages when specific events occur.

Example mapping

onToolTableChangedSubscribe:
    type: Cybus::Endpoint
    properties:
        protocol: Heidenhain
        connection: !ref heidenhainConnection
        subscribe:
            type: notify
            method: onToolTableChanged

Heidenhain Methods

These are the available Heidenhain methods. The examples are shown in pseudo-code to clarify input and output types. Each function name matches its corresponding method name (see examples).

Machine Information

isConnected

Indicates whether the CNC controller is currently connected to the agent. Returns true if the CNC controller is connected to the agent.

bool isConnected = isConnected()

getVersion

Returns the version of the Heidenhain SDK that the agent uses to communicate with the machine.

string version = getVersion()

getState

Retrieves the connection state of the CNC.

string state =  getState()

getNcUpTime

Returns the CNC up-time in minutes.

int ncUpTimeMin = getNcUpTime()

getMachineUpTime

Returns the machine up-time in minutes.

int machineUpTimeMin = getMachineUpTime()

getSpindleRunningTime

Get the cumulative spindle run-time the spindle has been running since installation. Parameter is the identifier of the spindle.

int spindleRunningTimeMin = getSpindleRunningTime (int axisId)

getMachineRunningTime

Returns the total machine working time (in minutes) since installation.

int machineRunningTimeMin = getMachineRunningTime()

getMachineState

Returns a JSON object with selected machine state information.

{state, machineRunningTime, machineUpTime, ncUpTime} = getMachineState()

getAvailableInterfaces

Returns an object with key/value pairs for each known CNC interface. Values are 1 (available) or 0 (unavailable).

object getAvailableInterfaces()

hasAutomaticInterface

Returns true if the Automatic interface is available for this CNC controller.

bool hasAutomaticInterface()

hasDataAccessInterface

Returns true if the DataAccess interface is available for this CNC controller.

bool hasDataAccessInterface()

hasErrorInterface

Returns true if the Error interface is available for this CNC controller.

bool hasErrorInterface()

hasFileSystemInterface

Returns true if the FileSystem interface is available for this CNC controller.

bool hasFileSystemInterface()

hasItncTableInterface

Returns true if the ItncTable interface is available for this CNC controller.

bool hasItncTableInterface()

hasProcessDataInterface

Returns true if the ProcessData interface is available for this CNC controller.

bool hasProcessDataInterface()

hasAutomaticEvents

Returns true if the AutomaticEvents interface is available for this CNC controller.

bool hasAutomaticEvents()

hasDataAccessEvents

Returns true if the DataAccessEvents interface is available for this CNC controller.

bool hasDataAccessEvents()

hasErrorEvents

Returns true if the ErrorEvents interface is available for this CNC controller.

bool hasErrorEvents()

hasMachineEvents

Returns true if the MachineEvents interface is available for this CNC controller.

bool hasMachineEvents()

Tool and Pocket Table

getToolTableRow

Returns the tool table row for the specified tool ID (row number).

object row = getToolTableRow (string toolId)

setToolTableRow

Writes a tool table row. Provide the tool ID and an object of key (column name) value pairs.

void setToolTableRow (string toolId, object row)

addLinkedToolTableRow

Creates the next empty tool table row and links the tool to the next empty pocket table ID.

string pocketId = addLinkedToolTableRow(object row)

removeTool

DEPRECATED: Alias of removeToolTableRow. Removes the given toolId from the tool table. Use removeToolTableRow instead.

void removeTool(string toolId)

removeToolTableRow

Removes the tool with the specified toolId from the tool table.

void removeToolTableRow(string toolId)

clearToolTableRow

Empties the row in the tool table identified by toolId.

void clearToolTableRow(string toolId)

getToolTableCell

Reads a single cell from the tool table. Parameters: tool ID and column name.

string cell = getToolTableCell (string toolId, string fieldName)

setToolTableCell

Writes a single cell in the tool table. Parameters: tool ID, column name, and value.

void setToolTableCell (string toolId, string fieldName, string fieldValue)

getLinkedToolId

Returns the tool ID linked to the specified pocket table ID (row number).

string toolId = getLinkedToolId (string pocketId)

linkToolToPocketTable

Link tool to pocket table by specifying the pocket table ID (row number) and the tool ID to be linked.

void linkToolToPocketTable (string pocketId, string toolId)

unlinkToolFromPocketTable

Unlink tool from pocket table by specifying the pocket table ID of tool to be unlinked.

void unlinkToolFromPocketTable (string pocketId)

setLinkedToolTableRow

Set the next empty tool table row and link the tool to the specified pocket table ID.

void setLinkedToolTableRow(string pocketId, object row)

getPocketTable

Reads the entire pocket table. Returns an array of objects, one per row.

array pocketTable = getPocketTable()

getToolTableRowByPocketId

Returns the tool table row for the tool currently selected at the given pocketId.

TableRow getToolTableRowByPocketId(string pocketId)

removeToolTableRowByPocketId

Removes the tool table row for the tool currently selected at the given pocketId.

void removeToolTableRowByPocketId(string pocketId)

setTool

Sets the tool table entry at toolId to newToolRow. If pocketId is provided, this also links the tool to that pocket.

string setTool(string pocketId, string toolId, TableRow newToolRow)

addLinkedToolTableRow

Set the next empty tool table row and link the tool to the next empty pocket table ID.

string pocketId = addLinkedToolTableRow(object row)

Data Access

setAccessMode

Set the access mode to gain access to protected data sub trees. Not available for iTNCs.

void setAccessMode (string dataPath, string password)

getValue

Reads a value.

string value = getValue (string dataPath)

setValue

Writes a value.

void setValue (string dataPath, string value)

getPlcData

Reads PLC data.

string value = getPlcData (string memoryType, string memoryAddress)

File System

transmitFile

Sends a base64-encoded buffer to the CNC and stores it as a file at destinationPath.

void transmitFile (string fileBuffer, string destinationPath)

receiveFile

Retrieves a file from the CNC as a base64-encoded string (not raw binary or text).

string receiveFile(string cncFile)

deleteFile

Deletes the file at the given path.

void deleteFile(string filePath)

copyFile

Copies the file at sourceFilePath to destFilePath.

void copyFile(string sourceFilePath, string destFilePath)

readDirectory

Lists entries in the directory at directoryPath. The returned JSON includes the resolved path (input argument plus potential prefix) and the entry list.

object readDirectory(string directoryPath)

makeDirectory

Creates a directory at the specified path.

void makeDirectory(string directoryPath)

deleteDirectory

Removes the directory at the specified path. The directory must be empty.

void deleteDirectory(string directoryPath)

deleteDirectoryRecursively

Recursively deletes all files and subdirectories at the path. Use with caution.

object deleteDirectoryRecursively(string directoryPath)

NC Program Handling

selectProgram

Selects or deselects an NC part program for execution.

void selectProgram (int channel, string programName, string startBlockNumber)

stopProgram

Stops the active NC program.

void stopProgram (int channel, bool onBlockEnd)

cancelProgram

Cancels the execution of a stopped NC program.

void cancelProgram (int channel)

setExecutionMode

Sets the execution mode.

void setExecutionMode (string executionMode)

startProgram

Starts or restarts the specified program.

void startProgram (string programName)

getProgramStatus

Returns the current program execution status.

string programStatus = getProgramStatus()

getDncMode

Returns the current DNC mode.

string dncMode = getDncMode()

clearControl

Executes a Clear Control.

void clearControl()

setOverrideFeed

Sets the feed override (percentage).

void setOverrideFeed (int percentage)

setOverrideSpeed

Sets the speed override (percentage).

void setOverrideSpeed (int percentage)

setOverrideRapid

Sets the rapid override (percentage).

void setOverrideRapid (int percentage)

getOverrideInfoFeed

Gets the current feed override.

int feed = getOverrideInfoFeed()

getOverrideInfoSpeed

Gets the current speed override.

int speed = getOverrideInfoSpeed()

getOverrideInfoRapid

Gets the current rapid override.

int rapid = getOverrideInfoRapid()

Custom Functions of the Cybus Heidenhain Agent

getAgentVersion

Returns the Cybus Heidenhain Agent version.

string getAgentVersion()

setTableMonitorInterval

For itnc530 and tnc426, sets the manual monitoring (polling) interval of the tool table.

void setTableMonitorInterval(int32_t seconds)

getTableMonitorInterval

For itnc530 and tnc426, returns the manual tool-table polling interval.

int32_t getTableMonitorInterval()

setSdkMutexTimeout

Sets the special timeout ensuring thread-safe access to Heidenhain SDK methods (needed only for some itnc530 variants).

void setSdkMutexTimeout(int32_t seconds)

getSdkMutexTimeout

Returns the special timeout for thread-safe SDK access (needed only for some itnc530 variants).

int32_t getSdkMutexTimeout()

Events

All event methods are available as subscribe operation with type: notify.

onToolTableChanged

Notification on any tool table cell change.

{ toolId, oldRow, newRow } = onToolTableChanged()

onToolChanged

Tool in spindle changed event. This event is fired by the CNC when a new tool is placed in the spindle or when the actual tool is removed from the spindle.

{ int toolId, object toolOut, object toolIn, double timestamp } = onToolChanged()

onStateChanged

Connection state changed event. Notifies the client application of the connection state changes of the CNC. (_IJHMachineEvents2::onStateChanged).

{ string newState } = onStateChanged()

onDncModeChanged

Notifies when DNC mode changes.

{ string newDncMode } = onDncModeChanged()

onPocketTableChanged

Notification on any pocket table cell change.

{ toolId, oldRow, newRow } = onPocketTableChanged()

onProgramChanged

Notification on execution switch to another program, subprogram, or macro.

string program = onProgramChanged()

onNcProgramChanged

Notification on a changed NC program. From _IJHAutomaticEvents3::OnProgramChanged and _IJHAutomaticEvents3::OnProgramStatusChanged. This event is fired when the CNC program execution status is changed. For itnc530 note that the iTNC 530 emits this event when a newly selected program is started and not when the program is selected.

Typically, this event will be emitted after the OnProgramStatusChanged programEvent DNC_PRG_EVT_STARTED.

{string state, string programPath, string programName} = onNcProgramChanged

onProgramStatusChanged

Notification on program execution status change.

string programEvent = onProgramStatusChanged()

Service Commissioning File (Example)

3KB

heidenhain-example.yml

Open

heidenhain-example.yml

---
# ----------------------------------------------------------------------------#
# Commissioning File
# ----------------------------------------------------------------------------#
# Protocol: Heidenhain
# Copyright: Cybus GmbH (2020)
# Contact: [email protected]
# ----------------------------------------------------------------------------#
description: >
    Heidenhain sample commissioning file

metadata:
    name: Heidenhain example
    icon: https://www.cybus.io/wp-content/uploads/2017/10/for-whom1.svg
    provider: cybus
    homepage: https://www.cybus.io
    version: 1.0.0

parameters:
    ipAddress:
        type: string
        description: The IP address of the CNC machine
        default: 10.0.0.2

    cncType:
        type: string
        description: The CNC type; can be tnc640, itnc530, tnc426
        default: tnc640

    agentName:
        type: string
        description: The name of the Cybus Heidenhain agent on the windows machine
        default: heidenhain-WIN1234

resources:
    heidenhainConnection:
        type: Cybus::Connection
        properties:
            protocol: Heidenhain
            connection:
                domain: edge.cybus
                agent: !ref agentName
                ipAddress: !ref ipAddress
                cncType: !ref cncType
                plcPassword: <password>
                usrPassword: <password>
                tablePassword: <password>
                sysPassword: <password>
                connectionStrategy:
                    initialDelay: 5000
                    maxDelay: 30000
                    incrementFactor: 2

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

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

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

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

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

MQTT Examples

MQTT examples following the example device service commissioning file above.

Request --> (MQTT topic) MQTT payload
Response <-- (MQTT topic) MQTT payload

Get SDK Version

--> (getVersion/req) { "params": [], "id": 1 }
<-- (getVersion/res) { "result": "1.6.3", "id": 1 }

Set tool table row

--> (setToolTableRow/req) { "params": ["10", { "NAME": "MY-AWESOME-TOOL", "L": "1", "R":"4" }], "id": 2 }
<-- (setToolTableRow/res) { "result": null, "id": 2 }

Get tool table cell

--> (getToolTableCell/req) { "params": ["10", "NAME"], "id": 3 }
<-- (getToolTableCell/res) { "result": "MY-AWESOME-TOOL", "id": 3 }