.. _user/protocols/heidenhain: ************** Heidenhain DNC ************** 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) Cybus Heidenhain Agent ====================== 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. .. code:: ----------- --------- --------------- | Machine | <-----> | Agent | <-------> | Connectware | ----------- RPC --------- MQTTS --------------- .. code 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. Commissioning file specifics ============================ The following sections describe the configuration objects **Cybus::Connection** and **Cybus::Endpoint**. See also the example :download:`Heidenhain reference commissioning file <../../heidenhain/heidenhain-dnc-reference.yml>` .. _user/protocols/heidenhain_connection: .. include:: ../protocolSchemas/HeidenhainConnection.rst .. _user/protocols/heidenhain_endpoint: .. include:: ../protocolSchemas/HeidenhainEndpoint.rst Data mappings ============== 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 Subscription ------------- The `subscribe` pattern offers the possibility to subscribe to a Heidenhain method. This polls the specified method in a given interval. Example mapping: .. code-block:: yaml :linenos: 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 :ref:`topic property `. The message has the following format: .. code:: javascript { "result": , "timestamp": } Read ----- 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: .. code-block:: yaml :linenos: 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 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: .. code:: javascript { "params": [ "1", { "NAME": "REQUEST-EXAMPLE" } ], "id": "1" } 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``: .. code:: javascript On success: { "result": null, timestamp: 123123123, "id": "1" } On error : { "error": "", timestamp: 123123123, "id": "1" } On success, the `result` value is a null value since ``setToolTableRow`` is defined as void. Notification ------------- Certain Heidenhain methods offers the `notification` pattern. Notification messages will be published when a certain event is triggered. Example mapping: .. code-block:: yaml :linenos: onToolTableChangedSubscribe: type: Cybus::Endpoint properties: protocol: Heidenhain connection: !ref heidenhainConnection subscribe: type: notify method: onToolTableChanged .. Next part: The auto-generated list of methods/events .. _user/protocols/heidenhain/methods: .. include:: ../../heidenhain/heidenhain-docs.rst Commissioning File Example ========================== The long file containing all implemented methods is available for download here: :download:`Heidenhain reference commissioning file <../../heidenhain/heidenhain-dnc-reference.yml>` Short example file, Download: :download:`heidenhain-example.yml` .. literalinclude:: heidenhain-example.yml :language: yaml :linenos: MQTT Examples ------------- MQTT Examples following the example device commissioning file above. Legend: .. code:: Request --> (MQTT topic) MQTT payload Response <-- (MQTT topic) MQTT payload Get SDK Version ^^^^^^^^^^^^^^^ .. code:: --> (getVersion/req) { "params": [], "id": 1 } <-- (getVersion/res) { "result": "1.6.3", "id": 1 } Set tool table row ^^^^^^^^^^^^^^^^^^ .. code:: --> (setToolTableRow/req) { "params": ["10", { "NAME": "MY-AWESOME-TOOL", "L": "1", "R":"4" }], "id": 2 } <-- (setToolTableRow/res) { "result": null, "id": 2 } Get tool table cell ^^^^^^^^^^^^^^^^^^^ .. code:: --> (getToolTableCell/req) { "params": ["10", "NAME"], "id": 3 } <-- (getToolTableCell/res) { "result": "MY-AWESOME-TOOL", "id": 3 }