Sinumerik
Connectware device driver for Siemens Sinumerik 840Dsl and 828D CNC systems. The driver acts as client for the Sinumerik “Access MyMachine / OPC UA” machine interface.
To be able to access the Sinumerik OPC UA interface the machine requires Sinumerik Operate, a Sinumerik OPC UA license and a compatible OPC UA server version. For information on the machine prerequisites, compatibility & setup please see the SINUMERIK Access MyMachine / OPC UA Configuration Manual
Some Sinumerik vocabulary
Tool number (
toolNo
): Sinumerik internal tool number which uniquely identifies each toolTool identifier (
toolIdent
): Tool name. In the tool management each tool is explicitly defined both by its identifier and its duplo number. This means that a tool area can only contain equal tool identifiers with different duplo numbers.Duplo number (
duploNo
): Number of replacement (“sister”) toolCutting edges (
numCuttEdges
): Number of cutting edges of a tool. This is not the number of blades but the number of different cut radius along the tool. Most tools have one cutting edge (eg regular drill). Also called D-Number.
Commissioning File Specifics
The following describes the available device specifics for a Sinumerik device. The Cybus Sinumerik OPC UA Reference file can be found in section Reference Device File
Connection Settings
The device connection is configured with a resource of type Cybus::Connection. Please note that the Sinumerik driver uses the Connectware OPC UA driver implementation and therefore the same settings apply here.
protocol
Required. Must be Sinumerik
.
connectionhost
Required.
For a detailed overview on all available OPC UA connection
settings see the Connectware OPC UA Client driver documentation.
Endpoint settings
Each connection can have several endpoints. They define the operations that are supported.
You define an endpoint by adding a resource of type Cybus::Endpoint
They have two key properties:
An operation
and a Sinumerik driver method
A Sinumerik endpoint support the following modes of operation:
Read
Write
Polling subscription (subscribe operation with type poll)
Notify subscription (subscribe operation with type notify)
Polling subscription
The subscribe
pattern offers the possibility to subscribe to a Sinumerik driver method and poll the specified method in a given interval.
Example mapping:
propertiesprotocol
Required. Must be Sinumerik
connection
Required. Must be a reference to a Sinumerik
connection
topic
Optional. Your MQTT topic to write the data to.
operation
Required. Must to be subscribe
type
Required. Must be poll
.
method
Required. Describes the Sinumerik driver method.
params
Optional. Array of method parameter.
pollInterval
Optional. Polling interval in milliseconds. Default 1000ms.
Read
The read
operation offers the possibility to request a machine action and receive a response. The operation follows the JSON-RPC 2.0 Specification. To make it work you only need to specify a read
operation on the desired method and send a message on a request-topic (req
):
Example message:
Example mapping:
endpoint propertiesprotocol
Required. Must be Sinumerik
connection
Required. Must be a Sinumerik
connection.
operation
Required. Must to be read
.
method
Required. Describes the Sinumerik method.
This configuration will subscribe to getMachineInfo/req
and publish responses to getMachineInfo/res
.
MQTT payload
The MQTT request payload requires two keys:
id
: User-defined correlation ID which can be used to identify the responseparams
: Array of parameters required for the used driver method
Following the example mapping above (method: getMachineInfo
), the request payload, send on topic getMachineInfo/req
, needs to be as following:
This invokes the Sinumerik driver method getMachineInfo
and returns the following response on topic getMachineInfo/res
:
See the Examples section for further information.
Write
Endpoints configured with the write
operation works exactly as endpoints configured with the read
operation, allowing you to execute Sinumerik methods by sending a message to a set-topic (set
).
Currently, these endpoints don’t support the return of any result.
Please refer to the Read section for more information.
Notify subscription
Certain Sinumerik driver methods offer events realized through the subscribe
operation with type notify
. Notifications are fired when a certain event is triggered.
This feature is highly unstable and can crash the OPC UA server.
Example mapping:
endpoint propertiesprotocol
Required. Must be Sinumerik
connection
Required. Must be a Sinumerik
connection.
operation
Required. Must to be subscribe
.
type
Required. Must be notify
.
method
Required.
Sinumerik Methods
This section describes the available Sinumerik driver methods. Each method is a specific RPC call which requires certain parameters and provides a defined return. The method paramter must be provides in the request payload in the params
section. See the Examples section for further information.
Important
Each driver method requires certain access rights on the Sinumerik. The driver automatically sets the required OPC UA access rights for the currently connected OPC UA user. Please make sure the user is allowed to change its access rights. See also method getMyAccessRights
.
Sinumerik NC variables are described here as:
<variable-name>
(<type>, <sinumerik-machine-data-reference>): <description>
Note
NC variable details are found in the Siemens Sinumerik NC variables documentation, see e.g. SINUMERIK 840D sl NC variables.
Machine Information
Some machine information
Get Machine Information
Provides static Sinumerik machine information.
Method:
getMachineInfo
Operation:
subscribe
orreq/res
Parameter: none
Return
nckType
(string, -): NC typenckVersion
(string, $AN_NCK_VERSION): NC versionanLanguageOnHmi
(string, $AN_LANGUAGE_ON_HMI): Current language set on HMImaskToolManagement
(string, $MC_TOOL_MANAGEMENT_MASK): Channel-specific settings for NCK tool management functionbasicLengthUnit
(string, -): Global basic unitnumCuttEdgeParams
(string, -): Number of parameters of a cutting edge in the T/TO modulenumCuttEdgeParams_ts
(string, ): Number of monitoring parameters of a cutting edge in the T/TS modulenumToolParams_tu
(string, MD 18094: MM_CC_TDA_PARAM ): Number of OEM data of a tool in the T/TU modulenumCuttEdgeParams_tu
(string, MD 18096: MM_CC_TOA_PARAM): Number of OEM data of a cutting edge in the T/TUE module.
Get Machine State
Provides current Sinumerik machine state.
Method:
getMachineState
Operation:
subscribe
orreq/res
Parameter: none
Return
anPoweronState
(string, $AN_POWERON_STATE): machine power on statepoweronTime
(string, $AN_POWERON_TIME): machine runtime in minuteslicenseStatus
(string, -): Licensing statusnckMode
(string, -): Mode in which the NCK workssysTimeSinceStartup
(string, -): System run time in seconds since NCK ramp-upprogStatus
(string, DB21-30, DBX35.0 - DBX35.4): Program statusprogName
(string, -): Active program nameworkPName
(string, -): Active workpiece nameaccessLevel
(string, -): Level of the access rights currently set
Get Spindle Speed
Get spindle speed.
Method:
getSpindleSpeed
Operation:
subscribe
orreq/res
Parameter: none
Return
actualSpeed
(string, $AA_S[x]): Spindle speed actual valuecommandSpeed
(string, -): Spindle speed desired value
Get Spindle Feed
Get spindle feed.
Method:
getSpindleFeed
Operation:
subscribe
orreq/res
Parameter: none
Return
actualFeed
(string, -): Current constant cutting ratecommandFeed
(string, -): Constant cutting rate of the master spindle
On NC program change
The method provides an event when the execution of a NC-file changes.
Method:
onNcProgramChanged
Operation:
notify
Parameter: none
Return
progStatus
(string, DB21-30, DBX35.0 - DBX35.4): NC program stateprogName
(string, -): Name of active NC-fileworkPName
(string, -): Work piece name
Tool Interaction
Get Tool
Read tool by tool number. Method returns the essential tool configuration. See also Examples.
Method:
getTool
Method signature:
object tool = getTool (string toolNo)
Operation:
subscribe
orreq/res
Parameter:
toolNo
(string): Tool number of tool to read
Return:
toolNo
(string, ): Internal tool number of the tooladaptNo
(string, -): Number of adapter defined by system parameter $TC_ADPxduploNo
(string, $TC_TP1): Duplo number (number of replacement tool)numCuttEdges
(string, $P_TOOLND): Number of cutting edges of a tooltoolIdent
(string, $TC_TP2): Tool identifiertoolInfo
(string, $TC_TP11): Definition of the sub-group to which the tool belongstoolInMag
(string, $A_TOOLMN): Current magazine in which the tool is locatedtoolInPlace
(string, $A_TOOLMLN): Current location in which the tool is locatedtoolMon
(string, $TC_TP9): Type of tool monitoringtoolplace_spec
(string, $TC_TP7): Magazine location type of tooltoolSearch
(string, $TC_TP10): Selection of the order of the replacement toolstoolMyMag
(string, $A_MYMN): Owner magazine of the tool magazine from which the tool was loadedtoolMyPlace
(string, $A_MYMLN): Owner magazine of the tool - Magazine location from which the tool was loadedtoolsize_left
(string, $TC_TP3): Tool size to the left in half locationstoolsize_right
(string, $TC_TP4): Tool size to the right in half locationstoolsize_upper
(string, $TC_TP5): Tool size upwards in half locationstoolsize_down
(string, $TC_TP6): Tool size downwards in half locationstoolOverSize
(string, $TC_TP3 … $TC_TP6): Tool size as fixed setting (two half locations left & right, one half location top & bottom) (true
,false
,special
)toolState
(string, $TC_TP8): Tool statetoolStateLocked
(string, $TC_TP8.2): Tool state - tool is locked (true
,false
)toolMaxVelo
(string, $TC_TP_MAX_VELO): Maximum speed of the tool if the value is >0. There is no monitoring if no speed limit is defined (=0).toolMaxAcc
(string, $TC_TP_MAX_ACC): Maximum angular acceleration of the tool if the value is >0. There is no monitoring if no acceleration limit is defined (=0).lifetime
(string, $TC_MOP2): Remaining service life in minutesmaxLifetime
(string, $TC_MOP5): Desired service lifetoolType
(string, $TC_DP1): Tool typelength1
(string, $TC_DP3): Tool length 1length2
(string, $TC_DP4): Tool length 2radius
(string, $TC_DP6): Tool radiuswearLength1
(string, $TC_DP12): Tool wear length 1wearLength2
(string, $TC_DP13): Tool wear length 2wearRadius
(string, $TC_DP15): Tool wear radiuscoolant1
(string, $TC_DP25.10): Coolant 1 (on
,off
)coolant2
(string, $TC_DP25.11): Coolant 2 (on
,off
)spindleDirection
(string, $TC_DP2.8 & $TC_DP2.9): Spindle direction (left
,right
,off
)teethCount
(string, $TC_DPNT): Number of teeth of a cutting edge
Get Tool Complete
Read tool by tool number. Method returns the complete tool configuration. See also Examples.
Method:
getToolComplete
Method signature:
object tool = getToolComplete (string toolNo)
Operation:
subscribe
orreq/res
Parameter:
toolNo
(string): Tool number of tool to read
Return: Method returns all essential tool information (see
getTool
), plustoolCompensationEdgeData
(object, $TC_DPx): Tool edge offset data. Note:objectIndex = parameterIndex - 1
toolSupervisionData
(object, TC_MOPx): Monitoring data per tool edge. Size given bynumCuttEdgeParams_ts
. Note:objectIndex = parameterIndex - 1
toolUserData
(object, $TC_TPCx): User-defined tool parameter. Size given bynumToolParams_tu
. Keys addressed astoolUser_1
…toolUser_n
.toolUserEdgeData
(object, $TC_DPCx): User-defined cutting edge parameter. Size given bynumCuttEdgeParams_tu
. Note:objectIndex = parameterIndex - 1
Get Tools
Read all available tools on the Sinumerik. Method returns essential tool information for each tool.
Method:
getTools
Method signature:
object tools = getTools ()
Operation:
subscribe
orreq/res
Parameter: none
Return
object of
getTool
objects. Key is the tool number.
Get Tools Complete
Read all available tools on the Sinumerik. Method returns complete tool information for each tool.
Method:
getToolsComplete
Method signature:
object tools = getToolsComplete ()
Operation:
subscribe
orreq/res
Parameter: none
Return
object of
getToolComplete
objects. Key is the tool number.
Create Tool
Create new tool on the Sinumerik and set tool configuration.
Method:
createTool
Method signature:
createTool (toolNo, fields, toolArea)
Operation:
subscribe
orreq/res
Parameter:
toolNo
(string): Tool number to be createdfields
(object): Optional, default ={}
. Tool configuration to set (see Set Tool Configuration)toolArea
(string): Optional, default =1
. Tool area in which the tool should be created.
Return
Status code
0: success
1: Tool area does not exist
2: Tool number out of range
3: Tool number exists already
4: Maximum number of tools reached)
Set Tool Configuration
Set or modify the configuration of a tool.
Method:
setToolFields
Method signature:
setToolFields (toolNo, fields)
Operation:
subscribe
orreq/res
Parameter:
toolNo
(string): Tool number to be createdfields
(object): Tool configuration to set
Return: status code
Tool configuration
The tool configuration (fields
) can be any of the essential tool configuration (see return of getTool
method). Simply add the setting key to the fields
object. Additionally any ToolUserData ($TC_TPCx), ToolCompensationEdgeData, ToolSupervisionData and ToolUserEdgeData parameter can be written by adding the key toolUser_x
, toolCompensationEdgeData_x
, toolSupervisionData_x
and toolUserEdgeData_x
, where x
should be replaced by the corresponding parameter number, to the fields
object.
Example:
See also Examples.
Set Tool
Convenient method to create a tool, set tool configurations and load the tool into a magazine. If no tool number is given the method searches for the first available tool number and uses this for tool creation. See also Examples.
Method:
setTool
Method signature:
string toolNo = setTool (toolNo, toolInMag, toolInPlace, fields)
Operation:
subscribe
orreq/res
Parameter:
toolNo
(string): Tool number to be created. Auto-assigned iftoolNo = ""
.toolInMag
(string): Magazine number the tool should be loaded to. Not loaded iftoolInMag = ""
.toolInPlace
(string): Magazine place the tool should be loaded to. Not loaded iftoolInPlace = ""
.fields
(object): Tool configuration to set. (see Set Tool Configuration)
Return
toolNo
(string): Tool number of the created tool
Delete Tool
Delete an existing tool.
Method:
deleteTool
Method signature:
deleteTool (toolNo, toolArea)
Operation:
subscribe
orreq/res
Parameter:
toolNo
(string): Tool number to be deletedtoolArea
(string): Optional, default = 1. Tool area in which the tool should be deleted.
Return
Status code
0: success
1: Tool area does not exist
2: Tool number out of range
3: Tool number exists already
6: Tool active
Delete Tool and Unload
Delete an existing tool. If the tool is loaded into a magazine, the tool is unloaded prior to deletion.
Method:
deleteToolAndUnload
Method signature:
deleteToolAndUnload (toolNo, toolArea = '1')
Operation:
subscribe
orreq/res
Parameter:
toolNo
(string): Tool number to be deletedtoolArea
(string): Optional, default = 1. Tool area in which the tool should be deleted.
Return: status code (see
deleteTool
)
Get Tools in Magazine
Returns which tools are loaded into the magazine locations (places) for a given magazine.
Method:
getToolsInMagazine
Method signature:
object places = getToolsInMagazine (magazineNo)
Operation:
subscribe
orreq/res
Parameter:
magazineNo
(string): Magazine number
Return
places
(object): Object with magazine places and corresponding tool numbers (0 = no tool loaded)
Get Tools in Magazines
Returns which tools are loaded into the magazine locations (places) for all magazines on the Sinumerik.
Method:
getToolsInMagazines
Method signature:
object magazines = getToolsInMagazines ()
Operation:
subscribe
orreq/res
Parameter: none
Return
magazines
(object): Object with magazine number and magazine places (object, seegetToolsInMagazine
)
Load Tool
Load tool into magazine.
Note
The tool configuration and the magazine configuration need to match in order to successfully load a tool into a magazine, e.g. the tool place type (toolplace_spec
) needs to match the magazine place type.
Method:
loadTool
Method signature:
loadTool (toolInMag, toolInPlace, toolNo)
Operation:
subscribe
orreq/res
Parameter:
toolInMag
(string): Magazine numbertoolInPlace
(string): Magazine place to loadtoolNo
(string): Tool to be loaded
Return: status code
Unload Tool
Unload tool from magazine.
Method:
unloadTool
Method signature:
unloadTool (toolInMag, toolInPlace)
Operation:
subscribe
orreq/res
Parameter:
toolInMag
(string): Magazine numbertoolInPlace
(string): Magazine place to unload
Return: status code
On Active Tool Changed
Method provides a notification when the active spindle tool changes.
Method:
onActiveToolChanged
Operation:
notify
Parameter: none
Return
active
(object)actTNumber
(string): Number of active toolactToolIdent
(string): Identifier of active toolactDuploNumber
(string): Duplo number of active toolactDNumber
(string): Number of active tool edge
previous
(object)actTNumber
(string): Number of previous toolactToolIdent
(string): Identifier of previous toolactDuploNumber
(string): Duplo number of previous toolactDNumber
(string): Number of previous tool edge
On Tool Changed
The method provides an event on any essential tool configuration change, i.e. tool is added, altered or removed.
Method:
onToolChanged
Operation:
notify
Parameter: none
Return
toolNo
(string): Tool number of changed toolfields
(object): Tool configuration (see return ofgetTool
)previousFields
(object): Previous tool configuration (see return ofgetTool
)
On Tool Complete Changed
The method provides an event on any complete tool configuration change, i.e. tool is added, altered or removed.
Method:
onToolCompleteChanged
Operation:
notify
Parameter: none
Return
toolNo
(string): Tool number of changed toolfields
(object): Tool configuration (see return ofgetToolComplete
)previousFields
(object): Previous tool configuration (see return ofgetToolComplete
)
On Magazine Tool Changed
The method provides an event on any magazine tool change, i.e. when a tool is loaded/unloaded to a magazine.
Method:
onMagazineToolChanged
Operation:
notify
Parameter: none
Return
magNo
(string, -): Magazine numbermagPlace
(string, -): Magazine locationtoolNo
(string, -): Tool number which loaded/unloaded to/from this location
Magazine Information
Get Magazine
Method returns information about a specific magazine.
Method:
getMagazine
Method signature:
object magazine = getMagazine (magNo)
Operation:
subscribe
orreq/res
Parameter:
magNo
(string): Magazine number to read
Return
magNo
(string, -): Magazine numbermagActPlace
(string, $TC_MAP8): Current magazine positionmagNrPlaces
(string, -): Number of real locations (in chain magazine) or number of slots (in box magazine)magCmdState
(string, -): Command state of the magazinemagIdent
(string, $TC_MAP1): Identifier of the magazinemagKind
(string, $TC_MAP1): Type of the magazinemagState
(string, $TC_MAP3): State of the magazine
Get Magazines
Method returns information about all available magazine.
Method:
getMagazines
Method signature:
object magazines = getMagazines ()
Operation:
subscribe
orreq/res
Parameter: none
Return
object of
getMagazine
objects. Key is the magazine number.
File System
Read File
Read a file from the Sinumerik file system.
Method:
readFile
Method signature:
{ path, data } = readFile (path)
Operation:
subscribe
orreq/res
Parameter:
path (string): File path including filename, addressable either as absolute or relative path (e.g. “Sinumerik/FileSystem/Sub Program/foobar.SPF” or “Sub Program/foobar.SPF”)
Return
path
(string): Absolute file pathdata
(string): Base64 encoded file content
Write File
Write file to Sinumerik file system. Directories are created automatically from given file path if non existing on the Sinumerik. By default, existing files are not overwritten. If you require files to be overwritten, specify the overwrite
flag.
Method:
writeFile
Method signature:
writeFile (filepath, data, overwrite)
Operation:
subscribe
orreq/res
Parameter:
path
(string): File path including filename, addressable either as absolute or relative path (e.g. “Sinumerik/FileSystem/Sub Program/foobar.SPF” or “Sub Program/foobar.SPF”)data
(string): Base64 encoded file dataoverwrite
(bool): Optional, default: false. Overwrite existing file.
Return: status code
Read Directory
Get list of files and subdirectories from directory.
Method:
readDirectory
Method signature:
{ path, entries } = readDirectory(path)
Operation:
subscribe
orreq/res
Parameter:
path
(string): Directory path, addressable either as absolute or relative path (e.g. “Sinumerik/FileSystem/Sub Program” or “Sub Program”)
Return
path
: (string) Absolute directory pathentries
: (array) Directory entries
Delete Directory
Delete directory. By default, directories that have any content (files/subdirectories) are not deleted. If you require to delete directories including content recursively, specify the recursive
flag (use with care!).
Method:
deleteDirectory
Method signature:
deleteDirectory (directoryPath, recursive)
Operation:
subscribe
orreq/res
Parameter:
path
(string): Directory path, addressable either as absolute or relative path (e.g. “Sinumerik/FileSystem/Sub Program” or “Sub Program”)recursive
(bool): Optional, default: false. Delete directories including any content recursively.
Return: Status code
Access Rights Management
Get User Access Rights
Read OPC UA access rights of the current OPC UA user.
Method:
getMyAccessRights
Operation:
subscribe
orreq/res
Parameter: none
Return: Access rights
Give User Access
Set accesss rights for current OPC UA user. Please note that all driver methods automatically set their required access rights.
Method:
giveUserAccess
Operation:
subscribe
orreq/res
Parameter:
level
(string): User access level
Return: Status code
Examples
The examples are using the Sinumerik Reference Device File below. Thus, the MQTT topics might differ in your application but the payload needs to be the same (as long as no JSONata rules are being used).
Get Tool Complete
Example showing how to read the complete tool configuraton of tool number 1.
Method:
getToolComplete
Operation:
req/res
Request on MQTT topic “sinumerik-opcua/<machine-ip>/getToolComplete/req”
Example response on MQTT topic “sinumerik-opcua/<machine-ip>/getToolComplete/res”
Set Tool
Example showing how to create a new tool and to set its configuration. In the example we do not require to set a specific tool number but rather let the driver choose the next available tool number automatically.
Method:
setTool
Operation:
req/res
Request on MQTT topic “sinumerik-opcua/<machine-ip>/setTool/req”
Example response on MQTT topic “sinumerik-opcua/<machine-ip>/setTool/res”
Here the driver successfully created a new tool using the next available tool number 2.
Reference Device File
Sinumerik OPC UA Reference File.
Download: