Heidenhain DNC
Last updated
Last updated
© Copyright 2024, Cybus GmbH
The Connectware Heidenhain DNC protocol implementation makes it possible to interact with CNC machines via the Heidenhain DNC communication protocol. It offers the possibility to read data and status information, to manipulate the tool and pocket table, and to access data as well as files on the filesystem. A machine connection is defined by:
Connection settings (how to connect to the machine), and
Data mappings (how to map data from Heidenhain to MQTT)
In order to access the Heidenhain DNC COM component, the Connectware makes use of the Windows based Cybus Heidenhain Agent running as a Windows Service.
The Cybus Heidenhain Agent is a Windows Service implementing the Heidenhain RemoTools SDK which provides a Microsoft COM component for communication with Heidenhain DNC interfaces. Use the convenient MSI Installer package for installation. After installation the agent needs to be enabled with the Windows Service application. Optional, but recommended is to set the restart behavior of the service to restart on failure. Agent log messages can be found in the Windows Events.
The following sections describe the configuration objects Cybus::Connection and Cybus::Endpoint. See also the example:
The data mappings are described in the Heidenhain Methods section below. Each data mapping of a Heidenhain method is described by
Communication pattern
Heidenhain method (e.g. setToolTableRow), see section below
Each Heidenhain method provides one of the following three possible access patterns:
subscription
read implementing a request/response pattern (or write as an alias)
notification pattern
The subscribe pattern offers the possibility to subscribe to a Heidenhain method. This polls the specified method in a given interval.
Example mapping:
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.
The message has the following format:
The read property of an endpoint implement a request/response pattern. This offers the possibility to request a machine action and receive a response. The pattern follows the JSON-RPC 2.0 Specification, with two exceptions: The method member is set by the Cybus::Endpoint definition for the respective MQTT topic and not explicitly given in the request object. And the jsonrpc member is ignored and currently not sent.
The request message must be sent on the MQTT topic that is composed of the endpoint name with an additional /req
suffix (shorthand for request), e.g. for an endpoint setToolTableRow the topic must be setToolTableRow/req. The result will be returned as a message on the MQTT topic with an additional /res
suffix (shorthand for result).
Alternatively, the endpoints could also be configured as write endpoints, which results in exactly the same behaviour, with the single exception that the request message must be sent on a MQTT topic with the /set
suffix. The results will be returned on the topic with /res
suffix, identical to read endpoints, and with identical format. In that sense, 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 will be passed on to the machine and will be used depending on the Heidenhain machine method. The response message of read or 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:
MQTT payload
The MQTT request 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 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, too.
Following the example mapping above (method: setToolTableRow
), the request payload, sent on topic setToolTableRow/req
, needs to be as following:
This modifies the tool table row 1
and sets the field ǸAME
of that row to REQUEST-EXAMPLE
. The following response will be replied on topic setToolTableRow/res
:
On success, the result value is a null value since setToolTableRow
is defined as void.
Certain Heidenhain methods offers the notification pattern. Notification messages will be published when a certain event is triggered.
Example mapping:
Available Heidenhain methods. The long list below shows the function prototypes in pseudo-code to clarify the input and output data types. The function name is identical to the method name (see examples below).
isConnected
Returns true if the CNC control is connected to the agent.
getVersion
Get the version of the Heidenhain SDK which the agent is using for communicating to the machine.
getState
Get the connection state of the connected CNC.
getNcUpTime
Get the CNC up-time.
getMachineUpTime
Get the machine up-time.
getSpindleRunningTime
Get the cumulative spindle run-time the spindle has been running since installation. Parameter is the identifier of the spindle.
getMachineRunningTime
Get the machine working time since installation.
getMachineState
Returns a json object with the specified information about the machine state
getAvailableInterfaces
Returns an object with key/value pair for every of the known interfaces of the CNC controller. The value is 1 (true) if the respective interface is available, and 0 (false) if it is not.
hasAutomaticInterface
Returns true if the Automatic interface is available at this CNC controller
hasDataAccessInterface
Returns true if the DataAccess interface is available at this CNC controller
hasErrorInterface
Returns true if the Error interface is available at this CNC controller
hasFileSystemInterface
Returns true if the FileSystem interface is available at this CNC controller
hasItncTableInterface
Returns true if the ItncTable interface is available at this CNC controller
hasProcessDataInterface
Returns true if the ProcessData interface is available at this CNC controller
hasAutomaticEvents
Returns true if the AutomaticEvents interface is available at this CNC controller
hasDataAccessEvents
Returns true if the DataAccessEvents interface is available at this CNC controller
hasErrorEvents
Returns true if the ErrorEvents interface is available at this CNC controller
hasMachineEvents
Returns true if the MachineEvents interface is available at this CNC controller
getToolTableRow
Read row identified by tool ID (row number) from tool table.
setToolTableRow
Set tool table row. Parameters are the tool ID and an Object of key (column name) - value pairs.
addLinkedToolTableRow
Set the next empty tool table row and link the tool to the next empty pocket table ID.
removeTool
DEPRECATED - use removeToolTableRow instead. Alias for removeToolTableRow. Remove the given toolId from the tool table
removeToolTableRow
Remove the tool with the given toolId from the tool table
clearToolTableRow
Clear the row in the tool table with the given toolId so that it is empty
getToolTableCell
Read cell from tool table. Parameters are the tool ID and the column name.
setToolTableCell
Set tool table cell. Parameters are the tool ID, the column name and the value.
getLinkedToolId
Get the linked tool ID of the pocket table entry by specifying the pocket table ID (row number).
linkToolToPocketTable
Link tool to pocket table by specifying the pocket table ID (row number) and the tool ID to be linked.
unlinkToolFromPocketTable
Unlink tool from pocket table by specifying the pocket table ID of tool to be unlinked.
setLinkedToolTableRow
Set the next empty tool table row and link the tool to the specified pocket table ID.
getPocketTable
Read entire pocket table. Return is an array of objects, each representing one pocket table row
getToolTableRowByPocketId
Returns the tool table row of the tool which is currently selected in the pocket table at the given pocketId
removeToolTableRowByPocketId
Removes the tool table row of the tool which is currently selected in the pocket table at the given pocketId
setTool
In the tool table, set the tool entry at the given toolId to the content of the newToolRow object. Additionally, if pocketId is given, link the new tool at the given pocketId
addLinkedToolTableRow
Set the next empty tool table row and link the tool to the next empty pocket table ID.
setAccessMode
Set the access mode to gain access to protected data sub trees. Not available for iTNCs.
getValue
Read value.
setValue
Set value.
getPlcData
Read PLC Data.
transmitFile
Transmits the given buffer (of base64 encoded bytes) to the CNC where it should be stored as a file at the given destinationPath.
receiveFile
Receives the given file from the CNC. Returns it as base64 (!!) encoded string, not in direct binary or text form.
deleteFile
Delete the file at the given path
copyFile
Copy the file specified by sourceFilePath to the destination destFilePath
readDirectory
Returns the list of entries of the directory at the given directoryPath. The json structure contains the actual path (input argument plus potential prefix), and the list of entries.
makeDirectory
Make (create) a new directory at the given path
deleteDirectory
Delete (remove) the directory at the given path. Directory must be empty.
deleteDirectoryRecursively
Delete (remove) all files and directories recursively at the given path. Watch out and use this with care.
selectProgram
(Un)select an NC part program for execution.
stopProgram
Stop executing the active NC part program.
cancelProgram
Cancels the execution of a stopped NC program.
setExecutionMode
Set the execution mode.
startProgram
Start or restart the specified program.
getProgramStatus
Get the current program execution status.
getDncMode
Get the current DNC mode.
clearControl
Execute a Clear Control.
setOverrideFeed
Set the feed override.
setOverrideSpeed
Set the speed override.
setOverrideRapid
Set the rapid override.
getOverrideInfoFeed
Get the current feed override.
getOverrideInfoSpeed
Get the current speed override.
getOverrideInfoRapid
Get the current rapid override.
getAgentVersion
Returns the version of the Cybus Heidenhain Agent.
setTableMonitorInterval
For itnc530 and tnc426, sets the manual monitoring (polling) interval of the tool table.
getTableMonitorInterval
For itnc530 and tnc426, returns the manual monitoring (polling) interval of the tool table.
setSdkMutexTimeout
Set the special timeout value that ensures thread-safe access to the Heidenhain SDK methods (only needed for some itnc530 variants)
getSdkMutexTimeout
Returns the special timeout value that ensures thread-safe access to the Heidenhain SDK methods (only needed for some itnc530 variants)
All event methods are available as subscribe operation with type: notify.
onToolTableChanged
Notification on any tool table cell change.
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.
onStateChanged
Connection state changed event. Notifies the client application of the connection state changes of the CNC. (_IJHMachineEvents2::onStateChanged)
onDncModeChanged
DNC mode change event.
onPocketTableChanged
Notification on any pocket table cell change.
onProgramChanged
Notification on execution switch to another program, subprogram or macro.
onNcProgramChanged
Notification on a changed NC program. From _IJHAutomaticEvents3::OnProgramChanged and also _IJHAutomaticEvents3::OnProgramStatusChanged. This event is fired when the CNC program execution status is changed. At itnc530 watch out: 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.
onProgramStatusChanged
Notification on program execution status change.
The long file containing all implemented methods is available for download here:
Short example file, Download:
MQTT Examples following the example device commissioning file above.
Legend:
Get SDK Version
Set tool table row
Get tool table cell