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.
----------- --------- ---------------
| Machine | <-----> | Agent | <-------> | Connectware |
----------- RPC --------- MQTTS ---------------
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
Download the Cybus Heidenhain Installer.
Run the installer.
After installation, enable/start the agent via the Windows Services console.
Optional: Configure the service to restart on failure.
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:
For an overview of the available connection and endpoint properties, see:
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) orwrite
(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 theCybus::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 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
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)
---
# ----------------------------------------------------------------------------#
# 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 }
Last updated
Was this helpful?