

Sinumerik Adapter

Introduction¶

The SinumerikAdapter is an application used to connect the SINUMERIK Edge to a SINUMERIK machine and provide data and service connectivity to SINUMERIK Edge applications.

Structural overview¶

In this chapter, the provided features of the SinumerikAdapter are documented. General information about configuration and usage of the datasource services are documented in the service documentation:

Please refer to the APP-SDK documentation for the corresponding service, which can be found here.

In addition, refer to the APP-SDK delivery for example applications.

Remarks & Version Restrictions¶

Precondition: The SinumerikAdapter requires a installed SINUMERIK HMI-OA license (6FC5800-0AP60-0YB0) on the connected machine.
Restriction: The maximum amount of active parameter requests is 50 in parallel.
Restriction: The SinumerikAdapter only supports the connection to a single NCU. Multi-NCU scenarios are not supported.
Restriction: Only english language is supported in the alarmList report.
Restriction: The alarmList report does not include HMI alarms.

datasource Configuration¶

connection settings¶

Please review the user documentation to find information how to configure the SinumerikAdapter.

parameter-service¶

The SinumerikAdapter offers data access to a connected SINUMERIK device by implementing a parameter-service/v1 provider instance. General information how to use the parameter-service/v1 API can be found here: parameter-service/v1

SinumerikAdapter-specific return codes¶

Code (hex)	Code (dec)	Meaning	Explanation
0x800	2048	Parameter or index not found	Possible example: "/channel/parameter/r[u1,10,#3]" 1) Does the parameter "/channel/parameter/r" not exist? 2) Does the index "10" → "/channel/parameter/r10" exist?
0x801	2049	Convert error	An internal error occurred at "value_type" conversion. Example: You would like to write a string-converted value of type DateTime but the ParameterService failed converting it.
0x802	2050	Copy error (for file handles)	The SinumerikAdapter has detected a copy file error.
0x803	2051	Buffer error	Wrong parameter length given or the SinumerikAdapter is working at a high load and needs some time for computation (too many requests or not enough resources).
0x804	2052	Connection error - wait for machine connect	The SinumerikAdapter cannot connect to the control unit.
0x805	2053	Function or value is not supported	Non existing function or function with a non existent parameter was called.
0x806	2054	Initialisation error	An initialization problem occurred in the SinumerikAdapter. This error will also occur if the wrong version of the HF_Probe is installed in the SINUMERIK controller, or if the HF_Probe is not installed at all.
0x807	2055	Wrong state	The function is not available in the current internal state of the SinumerikAdapter.
0x808	2056	Function exists but is not implemented	This function is not implemented by the SinumerikAdapter.
0x809	2057	Parameter(s) blocked	Parameter(s) is/are blocked.

Provided value types¶

The SinumerikAdapter utilizes the ParameterValueObject which is defined by the AdapterFramework library. This object represents a parameter value and its type. The "value_type" describes the original data type and needs to be used for decoding. See the table below for a list of value types. The "value" is always encoded as an array of strings.

Value Types¶

code (hex)	code (dec)	meaning
0x0	0	Invalid
0x1	1	Boolean
0x2	2	Char
0x3	3	UChar / Byte
0x4	4	Int
0x5	5	UInt
0x6	6	Long
0x7	7	ULong
0x8	8	LongLong
0x9	9	ULongLong
0xa	10	Double
0xb	11	String
0xc	12	Array of objects
0xd	13	DateTime (ISO standard 8601)

Note: The accuracy of the provided datatypes depends on the connected SINUMERIK controller. Please review the Datatype definitions of the NC-Programming Manual of your connected controller version, which can be found at https://support.industry.siemens.com/

Function reference¶

This section describes the SinumerikAdapter's specific usage of the ParameterValueObject.

ReadDeviceParameter¶

Read a single parameter from the machine.

Parameter:

parameter	Datatype	Description
parameter	String	The unique name of the parameter that is requested. The parameter must be defined in btss syntax. Please read the btss syntax definition in the SINUMERIK documentation for further information on btss strings. Example: "/CHANNEL/PARAMETER/R[u1,1,#2]"
index	Integer	Not used – value will be ignored. Index for array access is specified by btss syntax.
length	Integer	Not used – value will be ignored. Length for array access is specified by btss syntax.

returns: ReturnObject<ParameterValueObject>

Returns a ParameterValueObject. For array access, you will receive an array of values with the same valuetype. Different valuetypes in one array are currently not supported. The "value_type" represents the type of the elements inside the "value" array.

On error, the ParameterValueObject provides "value_type" equals "0" which means "invalid". The "value" array contains the detailed error code and name of the requested "parameter" with format error:<code>|param:<parameter>.

Note: A "value_type" of "12" (object array) is not yet supported.

ReadMultiDeviceParameter¶

Read multiple parameters from the machine.

Parameter:

parameter	datatype	Description
parameter	string[]	A string array which includes the unique parameter names to be read. This parameter request will return a consistent set of parameter values. Each parameter must be defined in btss syntax. Please read the btss syntax definition in the SINUMERIK documentation for further information on btss strings.

returns: ReturnObject<ParameterValueObject[]>

Attention: The maximum amount of possible parameter in a consistent read depends on the actual machine ressources of the connected machine.

Attention: It is not possible to read consistent parameters from different devices. So you cannot read PLC and NCK parameters in one ReadMultiDeviceParameter call. Because of this, it is not possible to combine PLC parameters with the CYCLE counter in one consistent read.

Returns an array of ParameterValueObjects with parameter values. The "value_type" represents the type of the elements inside the "value" array.

If an error occurs, the ParameterValueObject provides "value_type" = "0" which means "invalid". The "value" array contains the detailed error code and name of the requested "parameter" with format error:<code>|param:<parameter>.

Hint: If one parameter of a ReadMultiParameter request is not available, the return_code will be set as error. Anyway, the return_value object will include the values of all available parameters. In this case, the value_type of the error parameter is set to 0.

Example:

{
     "return_code":2048
    ,"return_value":
        [
            {
                 "value":["error:2057|param:/NC/channel/rparam"] 
                ,"value_type":0
            },
            {
                 "value":["6F99999-9999-0AB0"] 
                ,"value_type":11
            }
        ]
}

in this example, the first parameter does not exist.

WriteDeviceParameter¶

Write a value to the machine via the provided parameter.

Parameter:

parameter	datatype	Description
parameter	String	The unique name of the parameter which should be written to the target machine. The parameter must be defined in btss syntax. Please read the btss syntax definition in SINUMERIK documentation for further information on btss strings.
index	Integer	Not used – value will be ignored. Index for array access is specified by btss syntax.
length	Integer	Not used – value will be ignored. Index for array access is specified by btss syntax.
value	ParameterValueObject	The Value Object to write (including the type of value). Attention: The "value_type" attribute of the ParameterValueObject is not used. The SinumerikAdapter converts the value to the destination format of the addressed parameter.

returns: ReturnObject<bool>

Returns a bool. The return_value will be true if the write operation is successful.

Firewall permissions¶

The WriteDeviceParameter function filters parameter access with a whitelist. All parameter write requests will be denied unless they are whitelisted. Consumer applications need to use an accessType configuration of "w" to grant writing access to the required parameters.

subscription-service¶

The SinumerikAdapter publishes data from a SINUMERIK by implementing a subscription-service/v1 provider instance. General information how to use the subscription-service/v1 API can be found here: subscription-service/v1

The subscription-service provides databus messages in different qualities. Details about the message format can be found in the section: Databus message structure of data packages

For a list of available datapoints, please refer to the subscription-service definition of the providedDatasource in the metaconfig file of the sinumerikadapter indapp. This can be found under an installed sinumerikadapter instance in the backend.

The SinumerikAdapter provides two messages with different quality:

"sinumerik_hf_data" for high quality data
"sinumerik_lf_data" for a subscription to asynchronous information on changing BTSS parameter values (data_event).

high quality frequential data¶

"quality": "hf"

"messageId": "sinumerik_hf_data"

The SinumerikAdapter provides a databus message with high frequency datapoints. This message is defined with the messageId "sinumerik_hf_data" and quality "hf" in the metaconfig of the SinumerikAdapter indapp. The SinumerikAdapter can deliver different high frequency datapoints.

The SinumerikAdapter can be configured to deliver a maximum of 100 values in high frequential quality. If the position control clock on the SINUMERIK NCU is less than 1ms, the maximum is reduced to 50. Sporadic data lost may occur if this limit is exceeded.

Remark: The total amount of subscribed data is the sum of the subscriptions of all the installed applications.

Remark: Data values in HF quality are always metric - even if the machine is configured to provide inc values. Attention: Depending on the machine configuration, subscriptions in data-event quality or btss parameter requests will provide also values in inc.

Valid datapoints for SINUMERK high frequency data capture¶

The following table lists the available datapoints. These datapoints can also be found in the SinumerikAdapter metaconfig file.

parameter	description	normalization
CYCLE	Can not be subscribed and is delivered automatically! The actual cycle counter which will be increased on every Position control cycle. This is an ID for the timeslice. Details of usage can be found under the topic: "messages with hf quality"	limited: (2^32/2)-1 values: 0 - 2147483647
ENC_POS	actual position of the active encoder	mm or degree
DES_POS	position command after the fine interpolator (correspond to cmdContrPos in btss, but without filter and compensation values)	mm or degree
CTRL_POS	position at the input of the position controller ( includes the filters and the feed forward symmetrization )	mm or degree
CTRL_DIFF	position controller input difference including compensation of DSC effects ( same value as the system trace offers in btss trackErrContr)	mm or degree
CTRL_DIFF2	position controller input difference without DSC compensation ( available in HFProbe only )	mm or degree
CONT_DEV	contour difference ( lag – lag-model correspond to btss trackErrDiff)	mm or degree
VEL_FFW	velocity feed forward to be added to the position controller output	mm/s or degree/s
TORQUE_FFW	torque/force feed forward the NC sends to the drive	Nm or N
CMD_SPEED	speed command the NC sends to the drive	mm/s or degree/s
ENC1_POS	actual position of encoder 1	mm or degree
ENC2_POS	actual position of encoder 2	mm or degree
TORQUE	drive momentum setpoint ( $VA_TORQUE, aaTorque )	Nm or N
POWER	drive actual power ( $VA_POWER, aaPower )	W
CURRENT	drive actual current ( $VA_CURR, aaCurr )	A
LOAD	drive load ( $VA_LOAD, aaLoad )	%
A_DBD	A_DBD Read a out of the Synchronous Action variable $A_DBD[]. This can be used, to read values from the PLC by using the FB {} in your PLC program. Give the varIndex as the byte address of the 32bit integer in the "A_DB" DB. The varIndex must be a multiple of 4 within the range 0 … 4092. Attention: Don’t use this variable for time critical usecases. Depending on the amount data written by the PLC program, a new value may need several bus cycles to get updated. Attention: Subscribing to PLC parameters will lead to more NC load.	32-bit signed integer
A_DBR	A_DBR Read a out of the Synchronous Action variable $A_DBR[]. This can be used, to read values from the PLC by using the FB {} in your PLC program. Give the varIndex as the byte address of the 32bit integer in the "A_DB" DB. The varIndex must be a multiple of 4 within the range 0 … 4092. Attention: Don’t use this variable for time critical usecases. Depending on the amount data written by the PLC program, a new value may need several bus cycles to get updated. Attention: Subscribing to PLC parameters will lead to more NC load.	32-bit IEEE float
A_DLD	A_DLD[] reads a NCU-link variable. Give the index as the byte address of the 32bit integer in the "A_DB" DB. The varIndex must be a multiple of 4 within the range 0…$MN_MM_SIZEOF_LINKVAR_DATA. Attention: Don’t use this variable for time critical usecases. Depending on the amount data written by the PLC program, a new value may need several bus cycles to get updated. Attention: Subscribing to PLC parameters will lead to more NC load.	32-bit signed integer
A_DLR	A_DLR[] reads a NCU-link variable. Give the index as the byte address of the 32bit integer in the "A_DB" DB. The varIndex must be a multiple of 4 within the range 0…$MN_MM_SIZEOF_LINKVAR_DATA. Attention: Don’t use this variable for time critical usecases. Depending on the amount data written by the PLC program, a new value may need several bus cycles to get updated. Attention: Subscribing to PLC parameters will lead to more NC load.	32-bit IEEE float
DPIO_IN2	Read a value from one of the NC "DPIO" Profibus/Profinet input ranges. must be a multiple of the value type bytecount (2 for 16 bit int). Interprete it like this: the thousands position specifies the DPIO range index [ 0 … 31 ] the three lower positions specify the byte offset within the range [ 0 … 126 ] e.g.: 15042 specifies a variable starting at byte offset 42 within the DPIO range index 15. The same information can be read from the Synchronous Action variable $A_DPSW_IN[15,42] ( but this is updated in the IPO-cycle only ). This variable can be used e.g. for reading values from analog sensors that are converted using an ET200 module connected to the NC via Profinet IRT. Attention: Don’t use this variable for time critical usecases. Depending on the amount data written by the PLC program, a new value may need several bus cycles to get updated. Attention: Subscribing to PLC parameters will lead to more NC load.	16-bit signed integer
DPIO_IN4	Read a value from one of the NC "DPIO" Profibus/Profinet input ranges. must be a multiple of the value type bytecount (2 for 16 bit int). Interprete it like this: the thousands position specifies the DPIO range index [ 0 … 31 ] the three lower positions specify the byte offset within the range [ 0 … 126 ] e.g.: 15042 specifies a variable starting at byte offset 42 within the DPIO range index 15. The same information can be read from the Synchronous Action variable $A_DPSW_IN[15,42] ( but this is updated in the IPO-cycle only ). This variable can be used e.g. for reading values from analog sensors that are converted using an ET200 module connected to the NC via Profinet IRT. Attention: Don’t use this variable for time critical usecases. Depending on the amount data written by the PLC program, a new value may need several bus cycles to get updated. Attention: Subscribing to PLC parameters will lead to more NC load.	32-bit signed integer

Hint: The metric units shown here can also be imperial, depending on the settings in the SINUMERIK NCK.

data events¶

"quality": "data_event"

"messageId": "sinumerik_lf_data"

The SinumerikAdapter provides a subscription to BTSS parameters of the SINUMERIK. The SinumerikAdapter will create a databus message for every value change of a subscribed datapoint.

Details about the message format of data_event messages can be found in the section: Databus message structure of data packages.

Subscribing to sinumerik_lf_data messages offers the second best quality after cyclic messages, and as such are better than simply polling the parameter-service.

A subscription to sinumerik_lf_data can include multiple datapoints. In this case, you will receive a single databus message that includes all subscribed parameters, even those that are unchanged. It is best practice, however, to subscribe to a single message for every required datapoint.

example consumer configuration:

"subscription-service/v1":{
    "subscriptions": [{
        "messageId": "sinumerik_lf_data",
        "messageName": "param_1_changed",
        "quality": "data_event",
        "datapoints": [ { "address":"/channel/parameter/someParam1[u1,1,#1]"}]
    },
    {
        "messageId": "sinumerik_lf_data",
        "messageName": "param_2_changed",
        "quality": "data_event",
        "datapoints": [
              { "address":"/channel/parameter/someParam2[u1,2,#1]" }
            , { "address":"/channel/parameter/someParam2[u1,2,#2]" }
        ]
    }]
}

Hint: By using a subscription to a data_event, you will not receive the initial value of the subscribed parameter. Only value changes will be published. To initialize your application with the actual value, you should read it by using the parameter-service.

switch from parameter polling to data event subscription¶

If an application needs to be informed about a specific parameter change of the NCU, it is recommended to use a data_event subscription instead of a cyclic parameter BTSS request. To do so, please take note of the following differences:

parameter request:

The app defines the BTSS address of the required parameter at runtime.
The app gets a synchronous response and must store the state to recognize changes.
The parameter value object includes the value-type of the parameter value. The value is a string and must be transformed to the given type.
The parameter value does not include a timestamp.
The communication load at the SinumerikAdapter is high; the request may be in competition with many other parameter requests.

subscription to data event:

The app defines the BTSS address of the required parameter at configuration time. (Attention! arrays are not supported)
The app registers a callback to get asynchronous events for changed parameter values.
The correct value-type is already provided by the JSON specification.
Data event subscriptions stay active during application runtime. Additionally, the application can decide to unregister the callback to those events.
The data event includes a timestamp - details can be found here.
The communication load at the SinumerikAdapter is lower than using synchronous parameter requests.

Hint: You can not subscribe to an array of values. data-events for BTSS parameters which address multiple indizes of an array are not supported.

Note: AppSDK package contains a sample application named "LFDataEventApp" which is subscribing to some lf parameters by using data events. It can be found here

generic configuration¶

The SinumerikAdapter provides a set of wildcards which can be used to help create a generic metaconfiguration. The application developer may define the wildcards to meet his application's requirements. Wildcards are further explained in the subscription-service documentation. Wildcards can be found in the datasourceConfig section of the SinumerikAdapter metaconfig file. It is recommended to copy those into the metaconfiguration of the client application and use them to define the required subscriptions.

instance specific configuration¶

When an instance of an application is created on a SINUMERIK Edge, all wildcards must be replaced by specific parameters on the connected machine. To help the operator configure those parameters, the app developer has several options:

In the documentation: - You can specify the configuration details and provide this to the operator in the documentation

In the metaconfiguration file: - By wildcard descriptions: define wildcards in the requiredDatasource section, including descriptive text and regex rules. - By message descriptions: provide a description for each message to inform the operator what information the message entails.

"subscriptions":[ {                                         
    "messageId" : "sinumerik_hf_data",        
    "quality" : "hf",
    "messageName" : "MyDiagnosticDataMessage1",
    "description" : "This app needs data from the X axis.", ...

By datapoint descriptions: provide a description for each subscribed datapoint to tell the operator details about the required data.

"datapoints":[ {
"address":"ENC_POS|($axis)", 
"description":"$axis wildcard has to be the replaced with the ID of the X axis"
} ]

*Attention: * Unless explicitly stated, do not change the datasource configuration of the SinumerikAdapter.

information-service¶

The SinumerikAdapter provides status information of a connected SINUMERIK device by implementing an information-service/v1 provider instance. General information how to use the information-service/v1 API can be found here: information-service/v1

Function reference¶

GetReport¶

Parameter:

parameter	Datatype	Description
report_id	String	String to define the required report.
meta	String	Depends on the report_id - an additional possibility to specialize the request

returns: ReturnObject<ReportObject<>>

returncodes¶

Value	Meaning
0x0	SUCCESS
0x1	UNDEFINED
0x2	PERMISSION_DENIED
0x803	Buffer error - to many requests – not enough resources. The SinumerikAdapter is working at a high load and needs some time for computation.
0x804	Connection error - waiting for connection to SINUMERIK NCU. Please try again, check the configured IP address and physical connection.
0x805	The requested report-ID is not supported. Please refer to the list of provided reports.
0x806	An initialization problem occurred in the SinumerikAdapter. This error will also occur if the wrong version of the HF_Probe is installed in the SINUMERIK controller, or if the HF_Probe is not installed at all.
0x807	The function is not available in the current internal state of the SinumerikAdapter.

This version of the SinumerikAdapter provides report-ID's as follows:

report_id	description
alarmList	Includes a list of SINUMERIK alarms (PLC, NCK, Drive alarms)

alarmList¶

meta: The "meta" parameter is not used by the SinumerikAdapter for the alarmList report.

alarmList response object¶

The returned alarmList contains one alarmObject for every alarm in the SINUMERIK's alarm list, and is limited to the last 1000 alarms.

In the development environment mentioned here, you can find a schema definition file "alarmlist.json" under the path "services/southbound/datasources/SINUMERIK/v1/schemas/reports/alarmlist-v1.json".

structure:

{
    "report": [                    
        {                    
            "id": 0,                   
            "instanceId" : 0,
            "message": {
                "eng": { 
                    "text" : "String", 
                    "parameters": [                      
                        "String",                           
                        "String",                           
                        "String",                           
                        "String"
                        ]
                }
            },
            "source": 0,
            "timestamp": "String",  
            "category": 0,
            "priority": 0,
            "state": 0
        }
    ] 
    ,"type": "alarmList"
}

id: uint64 - used to identify a specific alarm.

instanceId: Alarm IDs can be duplicated in the list. This uint64 ID is used to identify a specific alarm instance.

message: Defines the delivered language code and alarm text. Currently only english "eng" is supported.

source: The ID of the alarm source:

10000 HMI
0: NCK - including all drive alarms of the standard machine
1: part program message source of NCK channel 1 of the standard machine
2: part program message source of NCK channel 2 of the standard machine
3: part program message source of NCK channel 3 of the standard machine
4: part program message source of NCK channel 4 of the standard machine
5: part program message source of NCK channel 5 of the standard machine
6: part program message source of NCK channel 6 of the standard machine
7: part program message source of NCK channel 7 of the standard machine
8: part program message source of NCK channel 8 of the standard machine
9: part program message source of NCK channel 9 of the standard machine
10: NC part program message source of NCK channel 10 of the standard machine
50: diagnosis buffer alarm source of the PLC of the standard machine
51: MQS buffer alarm source for ALARM_S(Q) of the PLC of the standard machine
52: MQS buffer alarm source for ALARMs of the 828d-PLC
55: MQS buffer alarm source for ALARMs of the OMSp-PLC

timestamp: (optional) Timestamp of the alarm event in date-time format (ISO standard 8601) - based on the local time of the alarm source. Some alarm events may have no timestamp.

category: The category of the alarm.

0: NONE (no category definition)
1: SINUMERIK (SINUMERIK alarm)
2: PRATPROG_MESSAGE (part grogram message)

priority: The priority of the alarm.

state: The state of the alarm event

-1: UNKNOWN
0x00000001: ALARM_STATE_ACTIVE
0x00000002: ALARM_STATE_ACKED
0x00000004: ALARM_STATE_ENABLED
0x00000010: ALARM_CHANGE_ACTIVE
0x00000020: ALARM_CHANGE_ACKED
0x00000040: ALARM_CHANGE_ENABLED
0x00000080: ALARM_ACK_REQUIRED
0x00000100: ALARM_HMI_CANCEL_BTN
0x00000200: ALARM_HMI_CANCEL_TIME
0x00000201: ALARM_COMING
0x00000202: ALARM_CAME_GOING
0x00000203: ALARM_HMI_CANCEL_BTN_COMING
0x00000204: ALARM_HMI_CANCEL_BTN_CAME_GOING
0x00000205: ALARM_HMI_CANCEL_TIME_COMING
0x00000206: ALARM_HMI_CANCEL_TIME_CAME_GOING
0x00000207: ALARM_COMING_TOACK
0x00000208: ALARM_CAME_GOING_TOACK
0x00000209: ALARM_CAME_GONE_ACKING
0x0000020a: ALARM_CAME_ACKING
0x0000020b: ALARM_CAME_ACKED_GOING

Databus message structure of data packages¶

Subscribed messages are sent to the databus in a specific format which is outlined below.

Message Schema¶

In the development environment mentioned here, you can find a schema definition file "datapointmessage.json" under the path "services/southbound/datasources/SINUMERIK/v1/schemas/payload/datapointmessage-v1.json". This schema is used for all databus messages which are provided by the SinumerikAdapter.

The data payload contains head and body sections as follows:

{
  "header": {

  },
  "body": {

  }
}

The header includes message_type, key and source_id:

"header" : {
  "message_type": "dataobject",
  "key": "dataobject", 
  "source_id": "sinumerik_adapter_840Dsl"
}

The body section includes the following fields for addresses (data points) such as CYCLE, ENC1_POS|1 : - timestamp: Shows timestamp of acquired data - quality_mode: Available qualities can be found in the metaconfig of the datasource provider or the corresponding app. (SinumerikAdapter) - period_ms: How frequently data should be fetched in terms of millisecond; -1, if the message is an event - content: Subscribed information as an array of datapoints

messages with hf quality¶

The SinumerikAdapter enables subscriptions to high frequencial data. This data is provided in databus messages with some specifics.

The subscription to messages with hf (high frequencial) quality is using the "merge" feature of the subscription-service/v1. The effect is, that a received message can include more datapoints than subscribed.
There will always be one additional datapoint attached to a message. The "CYCLE" datapoint includes a "counter" that can be used to calculate the timestamps of all other values in the package. Starting at an initial value, each following number in the CYCLE array is incremented by 1. If there are missing numbers in the array, it means that data is missing for the corresponding CYCLE number.

Attention: Do not use the timestamp to identify datapoint values. Through this timestamp might have a gitter, you should use the CYCLE datapoint instead.

The body section of the data package includes an array of datapoints. Every datapoint in the array starts with the same initial timestamp ("timestamp"). Each datapoint contains an array of data values as floating point numbers.
The order of the data values within the datapoint represents the timeslice in which they were fetched from the machine. The timestamp of each data value is calculated by using the datapoint’s initial timestamp and the period_ms, or duration between one value to the next. To get the data values of a specific timestamp throughout the package, you can use the same index of the "value" array in every datapoint.

{
  "body": {
    "datapoint": [
      {
        "address": " ENC1_POS|1 ",
        "quality_mode": "hf",
        "period_ms": 1.0000000,
        "timestamp": "2015-04-09T11:40:59.011739",
        "content": [
          {
            "value": [
              0,
              3.12,
              -1.2,
              0,
              5.3,
              2.8,
              3.7
            ]
          }
        ]
      },
      {
        "address": "CYCLE",
        "quality_mode": "hf",
        "period_ms": 1.0000000,
        "timestamp": "2015-04-09T11:40:59.011739",
        "content": [
          {
            "value": [
              0,
              1,
              2,
              3,
              4,
              5,
              6
            ]
          }
        ]
      }
    ]
  }
}

In this example, the timestamp of value -1.2, which is the 3^rd index of the timeseries data array of ENC1_POS|1, is calculated by adding 2*period_ms to timestamp which is 2015-04-09T11:40:59.011739. Timestamps are ISO standard 8601.

High_performance_event¶

The body section also includes events such as the "high_performance_event" that can be used to interpret the package’s datapoints. Events can be linked to a specific timestamp by using the value of "column_index". This value corresponds to the index number within a datapoint’s value array. As such, the time at which the event occurred corresponds to the timestamp of the data value at that index. The "description" names the event. Events are described in more detail in the following section.

{
  "high_performance_event": [
    {
      "column_index": 0,
      "description": "event text"
    }
  ]
}

Types of high_performance_event¶

Events showing a sub-program call or a return from subprogram¶

The first transfer of an executable block within a called sub-program and the first block transfer following the return of a sub-program call are preceded by an output section that shows the modification of the call stack. Starting from the lowest stack level where a line change occurred, each stack level is sent as a high performance event like the following example:

"description"="# CH1: tick=13 callStackL=0 seekOffset=22 "/_N_MPF_DIR/_N_COOL_MPF""
"description"="# CH1: tick=13 callStackL=1 seekOffset=5 "/_N_SPF_DIR/_N_COOL_SUB_SPF""

Attention: There is no guarantee that every sub-program-call is recorded as an event by HF-Probe. If sub-program-calls are missing, there are two possible reasons:

Intellectual property protection will prevent tracing of sensitive information.
Sub-programs that do not contain movement commands will be missing.
Even if the sub-program contains movement commands, it may be lost if they are dropped or modified by the motion-preprocessing step of the NCK.

Value	Meaning	Comment
CH	points to the channel where the block transfer happened	CH1 is channel 1 in the example
tick	details the position control clock cycle counter	Use the cycle counter to correlate the event data to cyclic datapoint data
callStackL	the stack level	The main program level is denoted by "callStackL=0".
seekOffset	is the line number within the file
"/_N_MPF_DIR/_N_MYPROG_MPF"	is the complete path of the sub-program in double quotation marks	The event offers a maximum of 51 characters for the NC path name seen at the end of the line. If more than 75% of available internal memory is used, the number of characters is reduced to 16 and three dots are appended to show that the path information has been concatenated.

Remark: The reporting of call stack changes may be incomplete due to the fact that the changes are only detected by line number changes in the top eight levels of the call stack. For example, the repeated call of the same sub-program on the same line in a "for" loop may not be detected because the line number in this main program does not change between subsequent calls of the sub-program.

Events indicating an NC block transfer to the IPO¶

NC blocks with executable contents (motion, dwell time, auxiliary function output etc.) have a reference to a programmed NC block when they are transferred to the IPO for real-time execution. These programmed NC blocks are sent as high performance events like the following example:

"description"="# CH1: tick=5045 seekOffset=6 laBuf=48 tool=0(0) ipoGC=G1 "G91 G64 X0.01 F10000""

Attention: There is no guarantee that every NC-block of the original NC program is recorded as an event by HF-Probe. If NC-block events are missing, there are two possible reasons:

Blocks which do not contain movement commands will be missing.
Even if the NC block does contain movement commands, it may be lost if it is dropped or modified by the motion-preprocessing step of the NCK. While the motion-preprocessing is deterministic, it is too complex to formulate useful rules to guarantee that a specific block appears.

However, the number of missing blocks should usually be small compared to the overall number of movement blocks. If an application needs to trigger functionality based on the NC program, this application should use a >= or <= comparison on the NC program line number ( for example: seekOffset >= (line number) ).

Value	Meaning	Comment
CH	points to the channel where the block transfer happened	CH1 is channel 1 in the example
tick	details the position control clock cycle counter	Use the CYCLE counter to correlate the event data to cyclic datapoint data
seekOffset	is the absolute line number of the programmed block within the main- or sub-program that is actually being executed.
laBuf	is the number of blocks that are actually available in the look-ahead buffer.	Corresponds to what can be read from the Synchronous Action variable $AC_IPO_BUF.
toolv	is the programmed tool number followed by the actual tool number enclosed in parentheses.
ipoGC	is the actually effective G-Code in the first G-Code group (interpolation type)
"G91 G64 X0.01 F10000"	the NC-block in double quotation marks	The event stores a maximum of 110 characters of an NC-block in double quotes. If the internal memory is filled up to more than 75%, the number of recorded characters is reduced to 11 and three dots are appended showing that the block information has been shortened. Special characters that may be present in the NC block are not treated special. (Thus the line might contain more than two double quote-signs if the NC block itself contains double-quote signs.)

Remark: It depends on details of the NCK-implementation which block is referenced in case internal NC blocks have been condensed (compressor function) or inserted (some types of corner rounding). All those blocks that do not contain realtime-executable contents like - variable calculations (R1=sin( $AA_IM[C]) - pure change of modal information (G1 F10000) - control structures (for LOOPCOUNT = 1 to 100)

and many more will not show up in the IPO block transfer.

Furthermore, the NC blocks are not sent as events when the active NC programm is protected by data encryption.

messages with data-event quality¶

Every datapoint array in the body section contains a single value for data-events. Data-event messages are not cyclic data. As such, their period_ms is "-1" The timestamp is local SINUMERIK Edge time upon receiving the data event.

example

{
  "body": {
    "datapoint": [
      {
        "address": "/NC/_N_CH_GD3_ACX/MY_SINGLE_VALUE_STR_VAR",
        "quality_mode": "data_event",
        "period_ms": -1.00000000,
        "timestamp": "2019-04-09T11:40:59.011739",
        "content": [
          {
            "value": [3.12]
          }
        ]
      }
    ]
  }
}

Timing behavior of data with different qualities¶

The SinumerikAdapter provides different methods for data access, which use different sources and qualities regarding the timestamp information.
The format of the timestamp data complies with the ISO standard 8601.

hf-data: Data messages with the quality "hf" use the local time on the NCU.
data-event: Data messages with the quality "data-event" use the local time of the SINUMERIK Edge.
parameter request: Parameter requests do not include time information. Local time of the SINUMERIK Edge can be retrieved via the AppSDK

Attention: Please be cautious when using timestamps to verify consistency. The timestamp provided by the hf data may contain a jitter and might not be accurate enough for verification.

FAQ¶

1) Is it possible to access drive parameters?

As of today, the following SINAMICS drive data can be read using the parameter-service of the sinumerikadapter. Please be aware that certain descriptions and the units listed below consider both rotatory as well as linear machine axes.”

parameter	description	unit
r0020	Speed or velocitysetpoint smoothed	rpm, mm/min
r0021	Actual speed or velocity smoothed	rpm, mm/min
r0026	DC link voltage smoothed	V
r0027	Absolute actual current smoothed	A rms
r0033	Torque or Forceutilization smoothed	%
r0034	Motor utilization thermal	%
r0035	Motor temperature resp.Temperature input (infeed module)	°C
r0078	Current actual value torque- orforce-generating resp. Active current actual value (infeed module)	A rms
r0081	Torque or Forceutilization	%

Depending on the type of the drive object, those parameters can be accessed in /DriveVsa/Drive/ or /DriveVsa/DC/ BTSS area.

Example: BTSS address of motor temperature for SINAMICS axis 1: /DriveVsa/Drive/r0035[u1]

2) What can be done to combine data of different qualities?

You can perform a "ReadMultiDeviceParameter" call to the parameters CYCLE: (/NCK/HF_PROBE/recordingServoCounter) and NCU time (/Nck/State/sysTimeBCD) and combine this information with an AppSDK function call to get the local SINUMERIK Edge time. This will provide all the information needed to calculate an offset and attach SINUMERIK Edge timestamps to hf data timestamps – with a shift of some miliseconds.

3) How to enter serial number in correct format?

Serial number should be entered as String in configuration editor not to encounter parsing problems on SINUMERIK Edge side. Please refer to chapter Configuring Application Instance for detailed information.

4) How to request initial values of data_event subscriptions?

It is possible that the Application misses the initial value of a data_event message. This is, because the SinumerikAdapter is not able to recognize the startup or restart of a consumer application. It is proposed, to initial request the value of the subscribed datapoints by using a reading parameter request of the parameter-service. Please always configure and use the parameter-service/v1 when you subscribe to datapoints in quality data_event.

5) How to read and write plc parameters with symbolic addresses?

Access to plc variables with symbolic addresses is only supported with Sinumerik ONE. You need to create a plc programm containing variables with symbolic addresses. Afterwards you are able to access theses variables via their symbolic address with the following syntax: "". for example: "My_Datablock".Variable_LReal

the following datatypes are supported:

Bool
Byte
Word
DWord
LInt
LReal
LDword
Date
Time
Date_and_Time
Tim_of_Day
S5Time
LTime
LTime_of_Day
Array_of_Byte
Array_of_LInt

6) How to read and write Date_and_Time values?

The value of the datatype Date_and_Time needs to follow the ISO standard 8601 syntax: YYYY-MM-DDTHH:MM:SS.μs for example: 2021-01-01T01:02:03.000000

Any questions left?

Ask the community

Except where otherwise noted, content on this site is licensed under the The Siemens Inner Source License - 1.1.