System Software

KUKA Sunrise.OS 1.17

KUKA Sunrise.Workbench 1.17
Operating and Programming Instructions for System Integrators

Issued: 18.03.2021
KUKA Sunrise.OS 1.17 SI V2
KUKA Deutschland GmbH
KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

© Copyright 2021
KUKA Deutschland GmbH
Zugspitzstraße 140
D-86165 Augsburg
Germany

This documentation or excerpts therefrom may not be reproduced or disclosed to third parties
without the express permission of KUKA Deutschland GmbH.
Other functions not described in this documentation may be operable in the controller. The user
has no claims to these functions, however, in the case of a replacement or service work.
We have checked the content of this documentation for conformity with the hardware and soft-
ware described. Nevertheless, discrepancies cannot be precluded, for which reason we are not
able to guarantee total conformity. The information in this documentation is checked on a regu-
lar basis, however, and necessary corrections will be incorporated in the subsequent edition.
Subject to technical alterations without an effect on the function.
KIM-PS5-DOC
Translation of the original documentation

Publication: Pub KUKA Sunrise.OS 1.17 SI (PDF) en

PB15313

Book structure: KUKA Sunrise.OS 1.17 SI V1.1

BS13843

Version: KUKA Sunrise.OS 1.17 SI V2

2/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Contents

1 Introduction.............................................................................................. 19
1.1 Target group.......................................................................................................... 19
1.2 Industrial robot documentation.............................................................................. 19
1.3 Representation of warnings and notes................................................................. 19
1.4 Trademarks............................................................................................................ 20
1.5 Terms used............................................................................................................ 20
1.6 Licenses................................................................................................................. 22

2 Product description................................................................................. 23
2.1 Overview of the industrial robot............................................................................ 23
2.2 Overview of the software components................................................................. 23
2.3 Overview of KUKA Sunrise.OS............................................................................. 24
2.4 Overview of KUKA Sunrise.Workbench................................................................ 25
2.5 Intended use of the system software................................................................... 26

3 Safety......................................................................................................... 27
3.1 General.................................................................................................................. 27
3.1.1 Liability................................................................................................................... 27
3.1.2 EC declaration of conformity and declaration of incorporation............................ 27
3.1.3 Terms in the “Safety” chapter............................................................................... 28
3.2 Personnel............................................................................................................... 30
3.3 Workspace, safety zone and danger zone........................................................... 31
3.4 Triggers for safety-oriented stop reactions........................................................... 32
3.5 Safety functions..................................................................................................... 34
3.5.1 Safety-oriented functions....................................................................................... 34
3.5.1.1 EMERGENCY STOP device................................................................................. 35
3.5.1.2 Enabling device..................................................................................................... 36
3.5.1.3 “Operator safety” signal......................................................................................... 37
3.5.1.4 External EMERGENCY STOP device.................................................................. 37
3.5.1.5 External safety stop 1 (path-maintaining) ........................................................... 37
3.5.1.6 External enabling device....................................................................................... 37
3.5.1.7 External safe operational stop.............................................................................. 38
3.5.2 Non-safety-oriented functions................................................................................ 38
3.5.2.1 Mode selection...................................................................................................... 38
3.5.2.2 Velocity monitoring in T1....................................................................................... 39
3.5.2.3 Software limit switches.......................................................................................... 40
3.6 Additional protective equipment............................................................................ 40
3.6.1 Jog mode............................................................................................................... 40
3.6.2 Labeling on the industrial robot............................................................................ 40
3.6.3 External safeguards............................................................................................... 40
3.7 Safety measures.................................................................................................... 41
3.7.1 General safety measures...................................................................................... 41
3.7.2 IT security.............................................................................................................. 43
3.7.3 Transportation........................................................................................................ 43
3.7.4 Start-up and recommissioning.............................................................................. 43
3.7.5 Manual mode......................................................................................................... 46
3.7.6 Automatic mode..................................................................................................... 47

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 3/667

KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

3.7.7 Maintenance and repair........................................................................................ 47

3.7.8 Decommissioning, storage and disposal.............................................................. 48
3.7.9 Safety measures for “single point of control”....................................................... 48

4 Installing KUKA Sunrise.Workbench..................................................... 51

4.1 PC system requirements....................................................................................... 51
4.2 Installing Sunrise.Workbench................................................................................ 51
4.3 Uninstalling Sunrise.Workbench............................................................................ 51

5 Operation of KUKA Sunrise.Workbench............................................... 53

5.1 Starting Sunrise.Workbench.................................................................................. 53
5.2 Overview of the user interface of Sunrise.Workbench......................................... 53
5.2.1 Repositioning the views........................................................................................ 55
5.2.2 Closing views and files......................................................................................... 55
5.2.3 Displaying perspectives......................................................................................... 55
5.2.4 Toolbar of the Programming perspective.............................................................. 56
5.3 Creating a Sunrise project with a template.......................................................... 57
5.4 Sunrise applications.............................................................................................. 60
5.4.1 Creating a new Java package.............................................................................. 60
5.4.2 Creating a robot application with a package........................................................ 61
5.4.3 Creating a robot application for an existing package.......................................... 61
5.4.4 Creating a new background application............................................................... 61
5.4.4.1 Creating a background application with a package............................................. 62
5.4.4.2 Creating a background application for an existing package................................ 62
5.4.5 Setting the robot application as the default application....................................... 63
5.5 Workspace............................................................................................................. 63
5.5.1 Creating a new workspace................................................................................... 63
5.5.2 Switching to an existing workspace...................................................................... 64
5.5.3 Switching between the most recently opened workspaces................................. 64
5.5.4 Archiving projects.................................................................................................. 64
5.5.5 Loading projects from archive to the workspace................................................. 64
5.5.6 Loading projects from the directory to the workspace......................................... 65
5.6 Sunrise projects with referenced Java projects................................................... 66
5.6.1 Creating a new Java project................................................................................. 66
5.6.1.1 Inserting robot-specific class libraries in a Java project...................................... 66
5.6.2 Referencing Java projects..................................................................................... 67
5.6.3 Canceling the reference to Java projects............................................................. 67
5.7 Renaming an element in the Package Explorer.................................................. 68
5.7.1 Renaming a project or Java package.................................................................. 68
5.7.2 Renaming a Java file............................................................................................ 68
5.8 Removing an element from Package Explorer.................................................... 68
5.8.1 Deleting an element from a project...................................................................... 68
5.8.2 Removing a project from Package Explorer........................................................ 68
5.8.3 Deleting a project from the workspace................................................................. 69
5.9 Activating the automatic change recognition........................................................ 69
5.10 Displaying release notes....................................................................................... 69

6 Operating the KUKA smartPAD............................................................. 71

6.1 KUKA smartPAD teach pendant........................................................................... 71
6.1.1 smartPAD............................................................................................................... 71

4/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

6.1.1.1 Front of smartPAD................................................................................................. 71

6.1.1.2 Rear of smartPAD................................................................................................. 73
6.1.2 smartPAD-2............................................................................................................ 74
6.1.2.1 Front of smartPAD-2............................................................................................. 74
6.1.2.2 Rear of smartPAD-2.............................................................................................. 76
6.2 Disconnecting and connecting the smartPAD...................................................... 77
6.2.1 Disconnecting the smartPAD................................................................................ 77
6.2.2 Connecting the smartPAD..................................................................................... 78
6.3 Update of the smartPAD software........................................................................ 79
6.4 KUKA smartHMI user interface............................................................................. 80
6.4.1 Navigation bar....................................................................................................... 81
6.4.2 Status display........................................................................................................ 82
6.4.3 Keypad................................................................................................................... 83
6.4.4 Station level........................................................................................................... 83
6.4.5 Robot level............................................................................................................. 85
6.5 Calling the main menu.......................................................................................... 87
6.6 Setting the user interface language...................................................................... 89
6.7 User groups........................................................................................................... 90
6.7.1 Changing user group............................................................................................. 91
6.8 CRR mode – controlled robot retraction.............................................................. 91
6.9 Changing the operating mode.............................................................................. 92
6.10 Activating the user keys........................................................................................ 93
6.11 Resuming the safety controller............................................................................. 94
6.12 Coordinate systems............................................................................................... 95
6.13 “Override” window................................................................................................. 96
6.14 “Jogging type” window.......................................................................................... 97
6.15 Jogging the robot.................................................................................................. 99
6.15.1 “Jogging options” window...................................................................................... 99
6.15.2 Setting the jog override......................................................................................... 101
6.15.3 Axis-specific jogging with the jog keys................................................................. 102
6.15.4 Cartesian jogging with the jog keys..................................................................... 103
6.15.4.1 Null space motion.................................................................................................. 103
6.16 Manually guiding the robot.................................................................................... 104
6.17 Frame management.............................................................................................. 105
6.17.1 “Frames” view........................................................................................................ 105
6.17.2 Creating a frame................................................................................................... 107
6.17.3 Reteaching frames................................................................................................ 108
6.17.4 Teaching a frame with the hand guiding device.................................................. 110
6.17.5 Manually addressing frames................................................................................. 110
6.18 Program execution................................................................................................ 111
6.18.1 Selecting a robot application................................................................................. 111
6.18.2 Setting the program run mode.............................................................................. 113
6.18.2.1 Program run modes.............................................................................................. 114
6.18.3 Setting the manual override.................................................................................. 114
6.18.4 Starting a robot application forwards (manually).................................................. 115
6.18.5 Starting a robot application forwards (automatically)........................................... 115
6.18.6 Resetting a robot application................................................................................ 116
6.18.7 Repositioning the robot after leaving the path..................................................... 116
6.18.8 Starting/stopping a background application manually.......................................... 117

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 5/667

KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

6.18.8.1 Stopping a background application manually....................................................... 117

6.18.8.2 Starting a background application manually......................................................... 118
6.19 Display functions................................................................................................... 118
6.19.1 Displaying the end frame of the motion currently being executed...................... 118
6.19.2 Displaying the axis-specific actual position.......................................................... 119
6.19.3 Displaying the Cartesian actual position.............................................................. 120
6.19.4 Displaying axis-specific torques............................................................................ 121
6.19.5 Displaying an I/O group and changing the value of an output........................... 121
6.19.6 Displaying information about the robot and robot controller................................ 124
6.20 Backup Manager................................................................................................... 124
6.20.1 “Backup Manager” view........................................................................................ 125
6.20.2 Backing up data manually..................................................................................... 128
6.20.3 Restoring data manually....................................................................................... 128
6.20.4 Configuring the network path for restoration........................................................ 128

7 Start-up and recommissioning............................................................... 131

7.1 Switching the robot controller on/off..................................................................... 131
7.1.1 Switching on the robot controller.......................................................................... 131
7.1.2 Switching the robot controller off.......................................................................... 131
7.2 Performing a PDS firmware update...................................................................... 131
7.3 Position mastering................................................................................................. 132
7.3.1 Performing mastering without a tool..................................................................... 133
7.3.2 Mastering with tool: Teach offset.......................................................................... 134
7.3.3 Performing mastering with a tool.......................................................................... 136
7.3.4 Checking mastering............................................................................................... 137
7.3.5 Manually unmastering axes.................................................................................. 139
7.4 Calibration.............................................................................................................. 140
7.4.1 Tool calibration....................................................................................................... 140
7.4.1.1 TCP calibration: XYZ 4-point method................................................................... 141
7.4.1.2 Defining the orientation: ABC 2-point method...................................................... 143
7.4.1.3 Defining the orientation: ABC world method........................................................ 145
7.4.2 Base calibration: 3-point method ......................................................................... 146
7.5 Determining tool load data.................................................................................... 148

8 Brake test.................................................................................................. 153

8.1 Overview of the brake test.................................................................................... 153
8.2 Creating the brake test application from the template......................................... 156
8.2.1 Adapting the brake test application for testing against the minimum holding
torque..................................................................................................................... 158
8.2.2 Changing the motion sequence for torque value determination.......................... 159
8.2.3 Changing the starting position for the brake test................................................. 159
8.3 Programming interface for the brake test............................................................. 160
8.3.1 Evaluating torques and determining the maximum absolute value..................... 160
8.3.2 Requesting the evaluation result of the maximum absolute torques.................. 161
8.3.3 Creating an object for the brake test................................................................... 163
8.3.4 Starting execution of the brake test..................................................................... 164
8.3.5 Evaluating the brake test...................................................................................... 165
8.3.5.1 Requesting the result of the brake test................................................................ 167
8.4 Performing a brake test........................................................................................ 169
8.4.1 Evaluation results of the maximum absolute torques (display)........................... 170

6/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

8.4.2 Result of the brake test (display)......................................................................... 170

9 Project management................................................................................ 173

9.1 Overview of a Sunrise project.............................................................................. 173
9.2 Frame management.............................................................................................. 173
9.2.1 Creating a frame for an application...................................................................... 174
9.2.2 Designating a frame as a base............................................................................ 175
9.2.3 Moving a frame..................................................................................................... 176
9.2.4 Deleting a frame.................................................................................................... 176
9.2.5 Displaying/editing frame properties....................................................................... 177
9.2.5.1 Frame properties – General tab........................................................................... 178
9.2.5.2 Frame properties – Transformation tab................................................................ 178
9.2.5.3 Frame properties – Redundancy tab.................................................................... 178
9.2.5.4 Frame properties – Teach information tab........................................................... 178
9.2.5.5 Frame properties – Measurement tab.................................................................. 179
9.2.6 Inserting a frame in a motion instruction.............................................................. 179
9.3 Object management.............................................................................................. 180
9.3.1 Geometric structure of tools.................................................................................. 180
9.3.2 Geometric structure of workpieces....................................................................... 181
9.3.3 Creating a tool or workpiece................................................................................. 181
9.3.4 Entering load data................................................................................................. 182
9.3.5 Displaying/editing object properties...................................................................... 183
9.3.5.1 Object properties – General tab........................................................................... 183
9.3.5.2 Object properties – Load data tab........................................................................ 183
9.3.6 Creating a frame for a tool or workpiece............................................................. 184
9.3.7 Displaying/editing frame properties....................................................................... 185
9.3.7.1 Frame properties – General tab........................................................................... 185
9.3.7.2 Frame properties – Transformation tab................................................................ 185
9.3.7.3 Frame properties – Measurement tab.................................................................. 186
9.3.7.4 Frame properties – Safety tab.............................................................................. 186
9.3.8 Defining a default motion frame........................................................................... 187
9.3.9 Copying an object template.................................................................................. 188
9.3.10 Configuring a safety-oriented tool......................................................................... 188
9.3.10.1 Tool properties – Load data tab........................................................................... 191
9.3.10.2 Frame properties – Transformation tab................................................................ 191
9.3.10.3 Frame properties – Safety tab.............................................................................. 192
9.3.10.4 Tool properties – Safety tab.................................................................................. 192
9.3.11 Safety-oriented use of workpieces........................................................................ 193
9.3.11.1 Entering workpiece load data............................................................................... 195
9.3.11.2 Workpiece properties – Load data tab................................................................. 195
9.3.11.3 Configuring the mass of the heaviest workpiece................................................. 196
9.4 User administration................................................................................................ 196
9.4.1 Overview of Sunrise.RolesRights.......................................................................... 197
9.4.2 Changing and activating the password................................................................ 198
9.5 Project synchronization......................................................................................... 199
9.5.1 Transferring a project to the robot controller........................................................ 200
9.5.2 Updating the project.............................................................................................. 201
9.6 Loading the project from the robot controller....................................................... 202

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 7/667

KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

10 Station configuration and installation................................................... 205

10.1 Station configuration overview.............................................................................. 205
10.2 Adapting the network settings............................................................................... 206
10.3 “Software” tab........................................................................................................ 207
10.3.1 Eliminating errors in the software catalog............................................................ 207
10.4 “Configuration” tab................................................................................................. 208
10.4.1 IP address range for KUKA Line Interface (KLI)................................................. 208
10.4.2 Allow debugging of applications........................................................................... 209
10.4.3 Handguiding Support............................................................................................. 209
10.4.4 General safety settings......................................................................................... 209
10.4.5 I/O handling: Disable I/O access in EMERGENCY STOP.................................. 210
10.4.6 Show confirmation dialog on installation.............................................................. 210
10.4.7 Configuration parameters for calibration............................................................... 211
10.4.8 Media flange.......................................................................................................... 211
10.4.9 Configuration parameters for Backup Manager................................................... 212
10.5 “Installation” tab..................................................................................................... 213
10.5.1 Installing system software on the robot controller............................................... 213
10.6 Loading an old project and converting the safety configuration.......................... 216
10.7 Option packages.................................................................................................... 217
10.7.1 Installing the option package................................................................................ 217
10.7.2 Installing or updating the virus scanner............................................................... 219
10.7.3 Installing a language package.............................................................................. 219
10.7.4 Uninstalling the option package............................................................................ 220
10.7.4.1 Instructions for uninstallation of safety options.................................................... 221
10.7.4.2 Removing an option package from the robot controller...................................... 221

11 Bus configuration.................................................................................... 223

11.1 Overview: Configuration and I/O mapping in WorkVisual.................................... 223
11.2 Overview of field buses......................................................................................... 223
11.3 Creating a new I/O configuration.......................................................................... 224
11.4 Opening an existing I/O configuration.................................................................. 224
11.5 Creating Sunrise I/Os............................................................................................ 225
11.5.1 “Create I/O signals” window.................................................................................. 226
11.5.2 Creating an I/O group and inputs/outputs within the group................................. 228
11.5.3 Editing an I/O group.............................................................................................. 228
11.5.4 Deleting an I/O group............................................................................................ 229
11.5.5 Changing an input/output of a group.................................................................... 229
11.5.6 Deleting an input/output of a group...................................................................... 229
11.5.7 Exporting an I/O group as a template.................................................................. 230
11.5.8 Importing an I/O group from a template............................................................... 230
11.6 Mapping the bus I/Os............................................................................................ 231
11.6.1 I/O Mapping window.............................................................................................. 231
11.6.2 Buttons in the “I/O Mapping” window................................................................... 232
11.6.3 Mapping Sunrise I/Os............................................................................................ 233
11.7 Exporting the I/O configuration to the Sunrise project......................................... 233

12 External control........................................................................................ 235

12.1 Overview of external controller............................................................................. 235
12.2 Configuring the external controller via the I/O system........................................ 235

8/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

12.3 Configuring the external controller via the UDP interface................................... 236
12.4 External controller input signals............................................................................ 236
12.5 External controller output signals.......................................................................... 237
12.6 Signal diagrams..................................................................................................... 238
12.7 Configuring the external controller in the project settings................................... 239
12.7.1 Input/output parameters of the I/O interface........................................................ 241
12.7.2 Input/output parameters of the UDP interface..................................................... 241
12.8 Formatting of the UDP data packets.................................................................... 241
12.8.1 Status messages of the robot controller.............................................................. 242
12.8.2 Controller messages of the external client........................................................... 244
12.9 External control via UDP – Start-up example...................................................... 245
12.9.1 Starting up the external controller........................................................................ 245
12.9.2 Programming the external controller..................................................................... 246
12.10 Configuring the signal outputs for a project that is not externally controlled...... 248
12.10.1 Output parameters of the I/O interface................................................................ 249
12.10.2 Output parameters of the UDP interface.............................................................. 249

13 Safety configuration................................................................................ 251

13.1 Safety concept....................................................................................................... 251
13.2 Safety-oriented reactions....................................................................................... 253
13.2.1 Time response of safety-oriented outputs............................................................ 254
13.3 Safety interfaces.................................................................................................... 254
13.4 Permanent Safety Monitoring................................................................................ 255
13.5 Event-driven Safety Monitoring............................................................................. 256
13.6 Atomic Monitoring Functions................................................................................. 257
13.6.1 Standard AMFs...................................................................................................... 258
13.6.2 Parameterizable AMFs.......................................................................................... 259
13.6.3 Extended AMFs..................................................................................................... 261
13.6.4 Availability of the AMFs depending on the kinematic system............................. 262
13.7 Worst-case reaction times of the safety functions in the case of a single fault. 263
13.7.1 Worst-case reaction times of the LBR iiwa monitoring functions........................ 264
13.8 Deactivation of safety functions via an input....................................................... 268
13.9 Safety configuration (SafetyConfiguration.sconf file)............................................ 269
13.9.1 Overview: Safety configuration and start-up........................................................ 269
13.9.2 Opening the safety configuration.......................................................................... 270
13.9.2.1 Evaluating the safety configuration....................................................................... 271
13.9.2.2 Overview of the graphical user interface for the safety configuration................. 271
13.9.3 Configuring the safety functions of the PSM mechanism.................................... 273
13.9.3.1 Opening the Customer PSM table........................................................................ 273
13.9.3.2 Creating safety functions for the PSM mechanism.............................................. 274
13.9.3.3 Deleting safety functions of the PSM mechanism............................................... 275
13.9.3.4 Editing existing safety functions of the PSM mechanism.................................... 275
13.9.4 Configuring the safe states of the ESM mechanism........................................... 276
13.9.4.1 Creating a new ESM state.................................................................................... 276
13.9.4.2 Creating a safety function for the ESM state....................................................... 279
13.9.4.3 Editing an existing safety function of an ESM state............................................ 279
13.9.4.4 Deleting a safety function of an ESM state......................................................... 280
13.9.4.5 Deleting an ESM state.......................................................................................... 280
13.9.4.6 Deactivating the ESM mechanism........................................................................ 281

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 9/667

KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

13.9.4.7 Switching between ESM states............................................................................ 281

13.9.5 Mapping safety-oriented tools............................................................................... 282
13.10 Activating the safety configuration........................................................................ 284
13.10.1 Activating the safety configuration........................................................................ 284
13.10.2 Restoring the safety configuration........................................................................ 285
13.10.3 Deactivating the safety configuration.................................................................... 285
13.11 Using and parameterizing the AMFs.................................................................... 285
13.11.1 Evaluating the safety equipment on the KUKA smartPAD.................................. 286
13.11.2 Evaluating the operating mode............................................................................. 287
13.11.3 Evaluating the motion enable............................................................................... 287
13.11.4 Monitoring of safety-oriented inputs...................................................................... 288
13.11.5 Manual guidance with enabling device and velocity monitoring.......................... 289
13.11.5.1 Monitoring of enabling switches on hand guiding devices.................................. 289
13.11.5.2 Monitoring functions during manual guidance...................................................... 291
13.11.5.3 Velocity monitoring during manual guidance........................................................ 291
13.11.6 Evaluating the position referencing....................................................................... 292
13.11.7 Evaluation of axis torque referencing................................................................... 293
13.11.8 Velocity monitoring functions................................................................................. 293
13.11.8.1 Defining axis-specific velocity monitoring............................................................. 294
13.11.8.2 Defining Cartesian velocity monitoring................................................................. 294
13.11.8.3 Direction-specific monitoring of Cartesian velocity............................................... 297
13.11.9 Monitoring spaces................................................................................................. 300
13.11.9.1 Defining Cartesian workspaces............................................................................. 302
13.11.9.2 Defining Cartesian protected spaces.................................................................... 304
13.11.9.3 Defining axis-specific monitoring spaces.............................................................. 307
13.11.10 Monitoring the tool orientation.............................................................................. 308
13.11.11 Standstill monitoring (safe operational stop)........................................................ 311
13.11.12 Activation delay for safety function....................................................................... 312
13.11.13 Monitoring of forces and axis torques.................................................................. 313
13.11.13.1 Axis torque monitoring.......................................................................................... 313
13.11.13.2 Collision detection................................................................................................. 314
13.11.13.3 TCP force monitoring............................................................................................ 316
13.11.13.4 Direction-specific monitoring of the external force on the TCP........................... 317
13.12 Example of a safety configuration........................................................................ 322
13.12.1 Task........................................................................................................................ 322
13.12.2 Requirements......................................................................................................... 322
13.12.3 Suggested solution for the task............................................................................ 323
13.13 Position and axis torque referencing.................................................................... 325
13.13.1 Position referencing with internal mastering sensors in kinematic systems....... 326
13.13.2 Axis torque referencing......................................................................................... 327
13.13.3 Creating a referencing application........................................................................ 329
13.13.4 External position referencing................................................................................. 329
13.13.4.1 Configuring the input for external position referencing........................................ 330
13.14 Safety acceptance overview................................................................................. 330
13.14.1 Basic properties of the safety configuration......................................................... 331
13.14.2 Tool selection table................................................................................................ 334
13.14.3 Safety-oriented tools.............................................................................................. 336
13.14.3.1 Pickup frame of fixed tools................................................................................... 336
13.14.3.2 Pickup frames of activatable tools........................................................................ 337

10/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

13.14.3.3 Tool orientation...................................................................................................... 338

13.14.3.4 Points and orientation for tool-related velocity component.................................. 339
13.14.3.5 Geometry data of the tool..................................................................................... 339
13.14.3.6 Load data of the tool............................................................................................. 340
13.14.4 Rows used in Customer PSM table..................................................................... 341
13.14.5 Rows used in the ESM states.............................................................................. 342
13.14.5.1 Non-used ESM states........................................................................................... 343
13.14.6 AMFs used in PSM tables and ESM states........................................................ 343
13.14.6.1 AMF smartPAD Emergency Stop......................................................................... 344
13.14.6.2 AMF smartPAD enabling switch inactive.............................................................. 344
13.14.6.3 AMF smartPAD enabling switch panic active....................................................... 344
13.14.6.4 AMF Hand guiding device enabling inactive........................................................ 344
13.14.6.5 AMF Hand guiding device enabling active........................................................... 345
13.14.6.6 AMF Test mode..................................................................................................... 345
13.14.6.7 AMF Automatic mode............................................................................................ 345
13.14.6.8 AMF Reduced-velocity mode................................................................................ 346
13.14.6.9 AMF High-velocity mode....................................................................................... 346
13.14.6.10 AMF Motion enable............................................................................................... 346
13.14.6.11 AMF Input signal................................................................................................... 346
13.14.6.12 Standstill monitoring of all axes AMF................................................................... 346
13.14.6.13 Axis torque monitoring AMF................................................................................. 347
13.14.6.14 AMF Axis velocity monitoring................................................................................ 347
13.14.6.15 AMF Position referencing...................................................................................... 347
13.14.6.16 AMF Torque referencing........................................................................................ 348
13.14.6.17 Axis range monitoring AMF.................................................................................. 348
13.14.6.18 Cartesian velocity monitoring AMF....................................................................... 348
13.14.6.19 AMF Cartesian workspace monitoring / Cartesian protected space monitoring. 349
13.14.6.20 Collision detection AMF........................................................................................ 350
13.14.6.21 TCP force monitoring AMF................................................................................... 350
13.14.6.22 Base-related TCP force component AMF............................................................ 351
13.14.6.23 AMF Time delay.................................................................................................... 352
13.14.6.24 Tool orientation AMF............................................................................................. 352
13.14.6.25 Tool-related velocity component AMF................................................................... 354
13.14.7 General safety settings......................................................................................... 355
13.14.7.1 smartPAD unplugging allowed.............................................................................. 355
13.14.7.2 Allow muting via input........................................................................................... 356
13.14.7.3 Allow external position referencing....................................................................... 356
13.14.7.4 Mass of the heaviest workpiece........................................................................... 357
13.14.8 Creating a safety configuration report.................................................................. 357

14 KUKA Sunrise.SafetyVisualization......................................................... 359

14.1 Overview of KUKA Sunrise.SafetyVisualization 1.0............................................. 359
14.1.1 3D visualization..................................................................................................... 359
14.1.1.1 Visualizing the monitoring spaces........................................................................ 362
14.1.1.2 Filter settings......................................................................................................... 364
14.1.2 Color coding.......................................................................................................... 367
14.1.3 Highlighting monitoring spaces............................................................................. 369
14.1.4 Orbiting, zooming, panning the 3D visualization.................................................. 370

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 11/667

KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

15 Basic principles of motion programming............................................. 373

15.1 Overview of motion types..................................................................................... 373
15.2 PTP motion type.................................................................................................... 373
15.3 LIN motion type .................................................................................................... 374
15.4 CIRC motion type.................................................................................................. 374
15.5 SPL motion type.................................................................................................... 375
15.6 Spline motion type................................................................................................. 375
15.6.1 Velocity profile for spline motions......................................................................... 376
15.6.2 Modifications to spline blocks............................................................................... 378
15.6.3 LIN-SPL-LIN transition........................................................................................... 380
15.7 Manual guidance motion type............................................................................... 381
15.8 Approximate positioning........................................................................................ 382
15.9 Orientation control with LIN, CIRC, SPL.............................................................. 384
15.9.1 Orientation control reference system for CIRC.................................................... 387
15.9.2 Combination of reference system and orientation type for CIRC........................ 387
15.10 Redundancy information........................................................................................ 389
15.10.1 Redundancy angle................................................................................................. 390
15.10.2 Status..................................................................................................................... 390
15.10.3 Turn........................................................................................................................ 391
15.11 Singularities........................................................................................................... 392
15.11.1 Kinematic singularities........................................................................................... 392
15.11.2 System-dependent singularities............................................................................ 394

16 Programming............................................................................................ 397
16.1 Java Editor............................................................................................................. 397
16.1.1 Opening a robot application in the Java Editor................................................... 397
16.1.2 Structure of a robot application............................................................................ 397
16.1.3 Edit functions......................................................................................................... 398
16.1.3.1 Renaming variables............................................................................................... 398
16.1.3.2 Auto-complete........................................................................................................ 399
16.1.3.3 Templates – Fast entry of Java statements......................................................... 399
16.1.3.4 Creating user-specific templates........................................................................... 400
16.1.3.5 Extracting methods................................................................................................ 400
16.1.4 Displaying Javadoc information............................................................................ 401
16.1.4.1 Configuration of the Javadoc browser.................................................................. 403
16.2 Symbols and fonts................................................................................................. 406
16.3 Data types............................................................................................................. 406
16.3.1 Declaration............................................................................................................. 407
16.3.2 Initialization............................................................................................................ 408
16.3.2.1 Primitive data types............................................................................................... 408
16.3.2.2 Complex data types.............................................................................................. 408
16.3.3 Dependency injection............................................................................................ 409
16.3.3.1 Dependency injection for Sunrise types............................................................... 410
16.3.3.2 Dependency injection for dedicated types............................................................ 412
16.4 Requesting individual values of a vector.............................................................. 415
16.5 Network communication via UDP and TCP/IP..................................................... 416
16.6 Motion programming: PTP, LIN, CIRC................................................................. 416
16.6.1 Synchronous and asynchronous motion execution.............................................. 416

12/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.6.2 PTP........................................................................................................................ 417

16.6.3 LIN......................................................................................................................... 418
16.6.4 CIRC...................................................................................................................... 418
16.6.5 LIN REL................................................................................................................. 419
16.6.6 MotionBatch........................................................................................................... 420
16.7 Motion programming: spline.................................................................................. 421
16.7.1 Programming tips for spline motions.................................................................... 421
16.7.2 Creating a CP spline block................................................................................... 422
16.7.3 Creating a JP spline block.................................................................................... 423
16.7.4 Using spline in a motion instruction..................................................................... 424
16.8 Overview of motion parameters (PTP, LIN, CIRC, SPL, Spline)......................... 424
16.8.1 Programming axis-specific motion parameters..................................................... 426
16.9 Programming manual guidance............................................................................ 427
16.9.1 Overview of motion parameters (manual guidance)............................................ 430
16.9.2 Axis limitation for manual guidance...................................................................... 431
16.9.3 Velocity limitation for manual guidance................................................................ 432
16.10 Using tools and workpieces in the program......................................................... 433
16.10.1 Integrating tools and workpieces.......................................................................... 434
16.10.2 Attaching tools and workpieces to the robot........................................................ 435
16.10.2.1 Attaching a tool to the robot flange...................................................................... 436
16.10.2.2 Attaching a workpiece to other objects................................................................ 436
16.10.2.3 Detaching objects.................................................................................................. 438
16.10.3 Moving tools and workpieces................................................................................ 439
16.10.4 Integrating dedicated object classes with dependency injection......................... 440
16.10.5 Transferring workpiece load data to the safety controller.................................... 443
16.11 Using inputs/outputs in the program..................................................................... 445
16.11.1 Integrating an I/O group........................................................................................ 447
16.11.2 Reading inputs/outputs.......................................................................................... 447
16.11.3 Setting outputs....................................................................................................... 448
16.12 Requesting axis torques........................................................................................ 449
16.13 Reading Cartesian forces and torques................................................................. 451
16.13.1 Requesting external Cartesian forces and torques.............................................. 451
16.13.2 Requesting forces and torques individually.......................................................... 452
16.13.3 Checking the reliability of the calculated values.................................................. 453
16.14 Requesting the robot position............................................................................... 455
16.14.1 Requesting the axis-specific robot position.......................................................... 455
16.14.2 Requesting the Cartesian actual or setpoint position.......................................... 456
16.14.3 Requesting the Cartesian setpoint/actual value difference.................................. 457
16.15 HOME position...................................................................................................... 459
16.15.1 Changing the HOME position............................................................................... 459
16.16 Requesting system states..................................................................................... 460
16.16.1 Requesting the HOME position............................................................................ 460
16.16.2 Requesting the mastering state............................................................................ 461
16.16.3 Checking “ready for motion”................................................................................. 461
16.16.3.1 Reacting to changes in the “ready for motion” signal......................................... 462
16.16.4 Checking the robot activity.................................................................................... 462
16.16.5 Requesting the state of safety signals................................................................. 463
16.16.5.1 Requesting the referencing state.......................................................................... 466
16.16.5.2 Reacting to a change in state of safety signals.................................................. 467

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 13/667

KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.17 Changing and requesting the program run mode................................................ 468

16.18 Changing and requesting the override................................................................. 469
16.18.1 Reacting to an override change........................................................................... 470
16.19 Overview of conditions.......................................................................................... 471
16.19.1 Complex conditions............................................................................................... 473
16.19.2 Axis torque condition............................................................................................. 474
16.19.3 Force condition...................................................................................................... 475
16.19.3.1 Condition for Cartesian force from all directions.................................................. 476
16.19.3.2 Condition for normal force.................................................................................... 477
16.19.3.3 Condition for shear force...................................................................................... 479
16.19.4 Force component condition................................................................................... 481
16.19.5 Condition for Cartesian torque.............................................................................. 483
16.19.5.1 Condition for Cartesian torque from all directions............................................... 485
16.19.5.2 Condition for torque............................................................................................... 485
16.19.5.3 Condition for tilting torque..................................................................................... 486
16.19.6 Torque component condition................................................................................. 487
16.19.7 Path-related condition............................................................................................ 489
16.19.8 Distance condition................................................................................................. 491
16.19.8.1 Distance component condition.............................................................................. 492
16.19.9 Condition for Boolean signals............................................................................... 493
16.19.10 Condition for the range of values of a signal...................................................... 494
16.20 Break conditions for motion commands............................................................... 495
16.20.1 Defining break conditions...................................................................................... 495
16.20.2 Evaluating the break conditions............................................................................ 496
16.20.2.1 Requesting a break condition............................................................................... 497
16.20.2.2 Requesting the robot position at the time of termination..................................... 498
16.20.2.3 Requesting a terminated motion (spline block, MotionBatch).............................. 499
16.21 Path-related switching actions (trigger)................................................................ 499
16.21.1 Programming triggers............................................................................................ 500
16.21.2 Programming a path-related switching action...................................................... 500
16.21.3 Evaluating trigger information............................................................................... 502
16.22 Monitoring of processes........................................................................................ 503
16.22.1 Listener for monitoring conditions......................................................................... 504
16.22.2 Creating a listener object to monitor the condition.............................................. 505
16.22.3 Registering a listener for notification of change in state..................................... 506
16.22.4 Activating or deactivating the notification service for listeners............................ 507
16.22.5 Programming example for monitoring................................................................... 508
16.23 Blocking wait for condition.................................................................................... 508
16.24 Recording and evaluating data............................................................................. 510
16.24.1 Creating an object for data recording................................................................... 510
16.24.2 Specifying data to be recorded............................................................................. 511
16.24.3 Starting data recording.......................................................................................... 513
16.24.4 Ending data recording........................................................................................... 515
16.24.5 Requesting states from the DataRecorder object................................................ 515
16.24.6 Example program for data recording.................................................................... 516
16.25 Defining user keys................................................................................................. 517
16.25.1 Creating a user key bar........................................................................................ 518
16.25.2 Adding user keys to the bar................................................................................. 519
16.25.3 Defining the function of a user key...................................................................... 521

14/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.25.4 Labeling and graphical assignment of the user key bar...................................... 523
16.25.4.1 Assigning a text element....................................................................................... 524
16.25.4.2 Assigning an LED icon.......................................................................................... 525
16.25.5 Identifying safety-critical user keys....................................................................... 526
16.25.6 Publishing a user key bar..................................................................................... 527
16.26 Message programming.......................................................................................... 528
16.26.1 Programming user messages............................................................................... 528
16.26.2 Programming user dialogs.................................................................................... 529
16.27 Program execution control.................................................................................... 531
16.27.1 Pausing an application.......................................................................................... 531
16.27.2 Terminating an application.................................................................................... 532
16.27.3 Pausing motion execution..................................................................................... 532
16.27.4 Canceling a motion command.............................................................................. 532
16.27.5 FOR loop............................................................................................................... 534
16.27.6 WHILE loop........................................................................................................... 535
16.27.7 DO WHILE loop..................................................................................................... 536
16.27.8 IF ELSE branch..................................................................................................... 537
16.27.9 SWITCH branch.................................................................................................... 539
16.27.10 Examples of nested loops..................................................................................... 542
16.28 Continuing a paused application in Automatic mode (recovery)......................... 543
16.29 Error treatment...................................................................................................... 545
16.29.1 Handling of failed motion commands................................................................... 545
16.29.2 Handling of failed synchronous motion commands............................................. 545
16.29.3 Handling of failed asynchronous motion commands........................................... 547
16.29.4 Unhandled exceptions........................................................................................... 550

17 Background tasks.................................................................................... 551

17.1 Using background tasks........................................................................................ 551
17.2 Cyclic background task......................................................................................... 553
17.3 Non-cyclic background task.................................................................................. 556
17.4 Data exchange between tasks.............................................................................. 556
17.4.1 Declaring task functions........................................................................................ 558
17.4.2 Implementing task functions.................................................................................. 558
17.4.3 Creating the providing task................................................................................... 560
17.4.4 Using task functions.............................................................................................. 562

18 KUKA Sunrise.EnhancedVelocityControl.............................................. 567

18.1 Overview of KUKA Sunrise.EnhancedVelocityControl 1.0................................... 567
18.1.1 “Brake” safety reaction.......................................................................................... 568
18.1.2 Cartesian velocity limitation via application.......................................................... 570
18.1.2.1 Setting and deactivating velocity limitation........................................................... 570
18.1.2.2 Requesting information about velocity limitation functions.................................. 571

19 KUKA Sunrise.StatusController............................................................. 575

19.1 Overview of KUKA Sunrise.StatusController........................................................ 575
19.1.1 Predefined status groups...................................................................................... 576
19.1.2 Creating status and status groups........................................................................ 577
19.1.3 Using the IStatusController interface.................................................................... 578
19.1.4 Setting and deleting the status via the status monitor........................................ 579
19.1.5 Implementing a status listener.............................................................................. 580

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 15/667

KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

20 Programming with a compliant robot................................................... 585

20.1 Sensors and control.............................................................................................. 585
20.2 Overview of controllers.......................................................................................... 585
20.3 Using controllers in robot applications.................................................................. 586
20.3.1 Creating a controller object................................................................................... 586
20.3.2 Defining controller parameters.............................................................................. 586
20.3.3 Transferring the controller object as a motion parameter.................................... 587
20.4 Position controller.................................................................................................. 587
20.5 Cartesian impedance controller............................................................................ 587
20.5.1 Calculation of the forces on the basis of Hooke’s law........................................ 588
20.5.2 Parameterization of the Cartesian impedance controller..................................... 590
20.5.2.1 Representation of Cartesian degrees of freedom................................................ 590
20.5.2.2 Defining controller parameters for individual degrees of freedom....................... 591
20.5.2.3 Controller parameters specific to the degrees of freedom.................................. 592
20.5.2.4 Controller parameters independent of the degrees of freedom........................... 593
20.6 Cartesian impedance controller with overlaid force oscillation............................ 596
20.6.1 Overlaying a simple force oscillation.................................................................... 596
20.6.2 Overlaying superposed force oscillations (Lissajous curves)............................... 597
20.6.3 Parameterization of the impedance controller with overlaid force oscillation...... 598
20.6.3.1 Controller parameters specific to the degrees of freedom.................................. 599
20.6.3.2 Controller parameters independent of the degrees of freedom........................... 601
20.7 Static methods for impedance controller with superposed force oscillation........ 603
20.7.1 Overlaying a constant force.................................................................................. 604
20.7.2 Overlaying a simple force oscillation.................................................................... 604
20.7.3 Overlaying a Lissajous oscillation......................................................................... 605
20.7.4 Overlaying a spiral-shaped force oscillation......................................................... 607
20.8 Axis-specific impedance controller........................................................................ 608
20.8.1 Parameterization of the axis-specific impedance controller................................. 608
20.8.2 Methods of the axis-specific impedance controller.............................................. 609
20.9 Holding the position under servo control.............................................................. 610

21 Diagnosis.................................................................................................. 613
21.1 Field bus diagnosis............................................................................................... 613
21.1.1 Displaying general field bus errors....................................................................... 613
21.1.2 Displaying the error state of I/Os and I/O groups............................................... 613
21.2 Displaying a log..................................................................................................... 613
21.2.1 “Log” view.............................................................................................................. 614
21.2.2 Filtering log entries................................................................................................ 616
21.3 Displaying error messages.................................................................................... 617
21.4 Displaying messages of the virus scanner........................................................... 619
21.5 Collecting diagnostic information for error analysis at KUKA.............................. 620
21.5.1 Creating a diagnosis package with the smartHMI............................................... 620
21.5.2 Creating a diagnosis package with the smartPAD............................................... 620
21.5.3 Creating a diagnosis package with Sunrise.Workbench...................................... 621
21.5.4 Loading existing diagnosis packages from the robot controller........................... 621

22 Remote debugging.................................................................................. 623

22.1 Debugging session sequence............................................................................... 624
22.1.1 Remote debugging of tasks.................................................................................. 624

16/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

22.1.2 Starting the debugging session............................................................................ 625

22.1.3 Ending the debugging session.............................................................................. 626
22.2 Debugging tasks.................................................................................................... 627
22.2.1 Remote debugging of a robot application............................................................ 628
22.2.2 Remote debugging of a background task............................................................ 629
22.3 Fundamentals of remote debugging..................................................................... 630
22.3.1 Overview of user interface – “Debugging” perspective........................................ 630
22.3.2 Break points........................................................................................................... 631
22.3.2.1 Creating and deleting break points....................................................................... 631
22.3.2.2 Deactivating and activating break points.............................................................. 633
22.3.2.3 Editing the properties of the break points............................................................ 633
22.3.2.4 Overview of the “Break points” view.................................................................... 633
22.3.2.5 Conditional break point......................................................................................... 635
22.3.2.6 Suspend thread property....................................................................................... 637
22.3.3 Command pointer.................................................................................................. 637
22.3.4 Overview of the “Debugging” view....................................................................... 638
22.3.5 Overview of the toolbar in the “Debugging” view................................................ 640
22.3.5.1 Continuing execution (Resume)............................................................................ 641
22.3.5.2 Jump into the method (Step in)............................................................................ 641
22.3.5.3 Executing a method completely (Step over)........................................................ 642
22.3.5.4 Terminating the executed method (Step back).................................................... 643
22.3.5.5 Executing code sections again (Back to frame).................................................. 644
22.3.5.6 Defining the code section to be executed (Execution to line)............................. 645
22.3.5.7 Debugging: pausing threads (Pause)................................................................... 646
22.3.6 Variables view........................................................................................................ 646
22.3.6.1 Displaying and modifying variables...................................................................... 648
22.3.6.2 Advanced context help for variables.................................................................... 649
22.3.7 Monitoring processes............................................................................................ 650
22.3.7.1 Adding new monitoring expressions..................................................................... 651
22.3.7.2 Deleting monitoring expressions........................................................................... 652
22.3.7.3 Evaluating monitoring expressions....................................................................... 652
22.3.8 Modifying source code.......................................................................................... 653
22.3.8.1 Impermissible modification of the source code.................................................... 654
22.3.8.2 Permissible modification of the source code........................................................ 654

23 Appendix................................................................................................... 655
23.1 Compatibility and migration of projects................................................................ 655
23.1.1 Modified task functions – adapting the programming.......................................... 655

24 KUKA Service........................................................................................... 657

24.1 Requesting support............................................................................................... 657
24.2 KUKA Customer Support...................................................................................... 657

Index 659

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 17/667

KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

18/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Introduction
1 Introduction

1.1 Target group

This documentation is aimed at users with the following knowledge and

skills:
• Advanced knowledge of the robot controller system
• Advanced Java programming skills

For optimal use of KUKA products, we recommend the training courses

offered by KUKA College. Information about the training program can be
found at www.kuka.com or can be obtained directly from our subsidia-
ries.

1.2 Industrial robot documentation

The industrial robot documentation consists of the following parts:

• Documentation for the robot arm

• Documentation for the robot controller
• Documentation for the smartPAD-2 (if used)
• Operating and programming instructions for the System Software
• Instructions for options and accessories
• Spare parts overview in KUKA Xpert
Each of these sets of instructions is a separate document.

1.3 Representation of warnings and notes

Safety

These warnings are provided for safety purposes and must be observed.
DANGER
These warnings mean that it is certain or highly probable that death or
severe injuries will occur, if no precautions are taken.

WARNING
These warnings mean that death or severe injuries may occur, if no
precautions are taken.

CAUTION
These warnings mean that minor injuries may occur, if no precautions
are taken.

NOTICE
These warnings mean that damage to property may occur, if no precau-
tions are taken.

These warnings contain references to safety-relevant information or gen-

eral safety measures.
These warnings do not refer to individual hazards or individual precau-
tionary measures.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 19/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

This warning draws attention to procedures which serve to prevent or rem-

Introduction

edy emergencies or malfunctions:

SAFETY INSTRUCTION
The following procedure must be followed exactly!

Procedures marked with this warning must be followed exactly.

Notices

These notices serve to make your work easier or contain references to

further information.
Tip to make your work easier or reference to further information.

1.4 Trademarks

Java is a trademark of Sun Microsystems (Oracle Corporation).

Windows is a trademark of Microsoft Corporation.

EtherCAT® is a registered trademark and patented technolo-

gy, licensed by Beckhoff Automation GmbH, Germany.

1.5 Terms used

Term Description

AMF Atomic Monitoring Function

Smallest unit of a monitoring function

API Application Programming Interface

Interface for programming applications

ESM Event-Driven Safety Monitoring

Safety monitoring functions which are activated using defined
events

EtherCAT Ethernet for Control Automation Technology

Ethernet-based field bus that is suitable for real-time requirements
(Ethernet interface).

EVC Enhanced Velocity Control

Option for limitation of the Cartesian robot velocity
EVC automatically adapts the robot velocity so that safety-oriented
and application-specific Cartesian velocity limits are adhered to.

Exception Exception or exceptional situation

An exception describes a procedure for forwarding information
about certain program statuses, mainly error states, to other pro-
gram levels for further processing.

Frame 3-dimensional coordinate system that is described by its position

and orientation relative to a reference system
Points in space can be easily defined using frames. Frames are of-
ten arranged hierarchically in a tree structure.

20/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Introduction
FSoE Fail Safe over EtherCAT
Protocol for transferring safety-relevant data via EtherCAT. An FSoE
master and an FSoE slave are used for this.

GMS German acronym for joint torque sensor

Sensitive robots of type LBR have a joint torque sensor in each ax-
is. The torques on the output side in each axis are measured using
these sensors.
Note: This sensor is referred to as the axis torque sensor in the
documentation.

Javadoc Javadoc is a documentation generated from specific Java com-

ments.

JRE Java Runtime Environment

Runtime environment of the Java programming language

KLI KUKA Line Interface

Ethernet interface of the robot controller for external communication

KMP KUKA Mobile Platform

Driverless transport vehicle

KUKA RoboticsAPI Java programming interface for KUKA robots

KUKA RoboticsAPI is an object-oriented Java interface for control-
ling robots and peripheral devices.

KUKA smartHMI see “smartHMI”

KUKA smartPAD see “smartPAD”

KUKA smartPAD-2 see “smartPAD”

KUKA Sunrise Control hardware for operating industrial robots

Cabinet

KUKA Sunrise.OS KUKA Sunrise.Operating System

System software for industrial robots which are operated with KU-
KA Sunrise Cabinet

HRC Human-robot collaboration

PROFINET Ethernet-based field bus (Ethernet interface)

PROFIsafe PROFINET-based safety interface for connecting a safety PLC to

the robot controller (PLC = master, robot controller = slave)

PSM Permanent Safety Monitoring

Safety monitoring functions which are permanently active

smartHMI smart Human-Machine Interface

User interface on the smartPAD

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 21/667

Introduction KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

smartPAD Teach pendant

The smartPAD has all the operator control and display functions re-
quired for operation of the robot. 2 models exist:

• smartPAD
• smartPAD-2
In turn, for each model there are variants, e.g. with different lengths
of connecting cables.
The designation “KUKA smartPAD” or “smartPAD” refers to both
models unless an explicit distinction is made.

PLC Programmable Logic Controller

Sunrise project A Sunrise project is a specialization of a Java project. All Sunrise-

specific functions are only possible in Sunrise projects and not in
conventional Java projects. These functions include, for example:

• Creation of a safety configuration

• Creation of an I/O configuration
• Creation of robot and background applications
• Configuration of the Automatic External interface

TCP Tool Center Point

Working point of a tool and origin of the corresponding tool coordi-
nate system

1.6 Licenses

KUKA Sunrise.OS uses open-source software. The license terms are stor-
ed in the licenses folder in the installation directory of KUKA Sun-
rise.Workbench.
Further information about open-source licenses can be requested from
the following address: opensource@kuka.com

22/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Product description
2 Product description

2.1 Overview of the industrial robot

The industrial robot consists of the following components:

• Manipulator
• Robot controller
• Teach pendant
• Connecting cables
• Software
• Options, accessories

Fig. 2-1: Example of an industrial robot

1 Connecting cable to KUKA smartPAD

2 KUKA smartPAD teach pendant
3 Manipulator
4 Connecting cable to the robot controller
5 Robot controller

2.2 Overview of the software components

The following software components are used:

• KUKA Sunrise.OS 1.17
• KUKA Sunrise.Workbench 1.17
• WorkVisual 5.0

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 23/667

Product description KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

2.3 Overview of KUKA Sunrise.OS

Description

KUKA Sunrise.OS is a system software package for industrial robots in

which programming and operator control tasks are strictly separated from
one another.
• Robot applications are programmed with KUKA Sunrise.Workbench.
• A robot cell (station) is operated using the KUKA smartPAD control
panel.
• A station consists of a robot controller, a manipulator and further devi-
ces.
• A station may carry out multiple applications (tasks).

Fig. 2-2: Separation of operator control and programming

1 Development computer with KUKA Sunrise.Workbench (connection

via the KLI of the robot controller)
2 KUKA Sunrise Cabinet robot controller
3 Manipulator
4 KUKA smartPAD teach pendant

The development computer is not included in the scope of supply of the

industrial robot.

Division of tasks

KUKA Sunrise.Workbench is the tool for starting up a station and develop-

ing robot applications. WorkVisual is used for bus configuration and bus
mapping.
In the start-up phase, the smartPAD is only required for tasks that cannot
be performed with KUKA Sunrise.Workbench for practical or safety rea-
sons. The smartPAD is used, for example, for mastering axes, calibrating
tools and teaching points.
After start-up and application development, the operator can carry out sim-
ple maintenance work and operating tasks using the smartPAD. The oper-
ator cannot change the station and safety configuration or the program-
ming.

24/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Product description
Overview

Task WorkVisual Workbench smartPAD

Station configuration

Software installation

Bus configuration/diagnosis

Bus mapping

Configuring safety settings

Activating the safety configuration

Programming

Remote debugging

Managing/editing process data

Creating frames

Teaching frames

Operating mode selection

Jog mode

Mastering

Calibration

Load data determination

Setting outputs

Polling inputs/outputs

Starting/stopping robot applications

Starting/stopping background applications

Creating a diagnosis package

2.4 Overview of KUKA Sunrise.Workbench

KUKA Sunrise.Workbench is the development environment for the robot

cell (station). It offers the following functionalities for start-up and applica-
tion development:

Start-up

• Installing the system software

• Configuring the robot cell (station)
• Editing the safety configuration
• Creating the I/O configuration
• Transferring the project to the robot controller

Application development

• Programming robot applications in Java

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 25/667

Product description KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

• Managing projects and programs

• Editing and managing runtime data
• Project synchronization
• Remote debugging (fault location and elimination)
‒ Setting break points
‒ Program execution in single-step operation (stop after each pro-
gram line)
‒ Displaying and modifying application variables during program exe-
cution
‒ Modifying a program during execution

2.5 Intended use of the system software

Use

The KUKA Sunrise.OS System Software is intended exclusively for the op-
eration of KUKA axes in an industrial setting in conjunction with KUKA
Sunrise Cabinet. KUKA axes include, for example, industrial robots and
mobile platforms.
Each version of the System Software may be operated exclusively in ac-
cordance with the specified system requirements.

Misuse

Any use or application deviating from the intended use is deemed to be

misuse and is not allowed. KUKA Deutschland GmbH is not liable for any
damage resulting from such misuse. The risk lies entirely with the user.
Examples of such misuse include:
• Operating axes that are not KUKA axes
• Operation of the System Software not in accordance with the specified
system requirements
• Use of any debugger other than that provided by Sunrise.Workbench
• Use for non-industrial applications for which specific product require-
ments/standards exist (e.g. medical applications)

26/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety
3 Safety

3.1 General

3.1.1 Liability

The device described in this document is either an industrial robot or a

component thereof.
Components of the industrial robot:

• Manipulator
• Robot controller
• Teach pendant
• Connecting cables
• Software
• Options, accessories
The industrial robot is built using state-of-the-art technology and in accord-
ance with the recognized safety rules. Nevertheless, misuse of the indus-
trial robot may constitute a risk to life and limb or cause damage to the
industrial robot and to other material property.
The industrial robot may only be used in perfect technical condition in ac-
cordance with its intended use and only by safety-conscious persons who
are fully aware of the risks involved in its operation. Use of the industrial
robot is subject to compliance with this document and with the declaration
of incorporation supplied together with the industrial robot. Any functional
disorders, especially those affecting safety, must be rectified immediately.

Safety information

Information about safety may not be construed against the manufacturer.

Even if all safety instructions are followed, this is not a guarantee that the
industrial robot will not cause personal injuries or material damage.
No modifications may be carried out to the industrial robot without the au-
thorization of the manufacturer. Unauthorized modifications will result in
the loss of warranty and liability claims.
Additional components (tools, software, etc.), not supplied by the manufac-
turer, may be integrated into the industrial robot. The user is liable for any
damage these components may cause to the industrial robot or to other
material property.
In addition to the Safety chapter, this document contains further safety in-
structions. These must also be observed.

3.1.2 EC declaration of conformity and declaration of incorporation

The industrial robot constitutes partly completed machinery as defined by

the EC Machinery Directive. The industrial robot may only be put into op-
eration if the following preconditions are met:
• The industrial robot is integrated into a complete system.
or: The industrial robot, together with other machinery, constitutes a
complete system.
or: All safety functions and safeguards required for operation in the
complete machine as defined by the EC Machinery Directive have
been added to the industrial robot.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 27/667

Safety KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

• The complete system complies with the EC Machinery Directive. This

has been confirmed by means of a conformity assessment procedure.

EC declaration of conformity

The system integrator must issue an EC declaration of conformity for the

complete system in accordance with the Machinery Directive. The EC dec-
laration of conformity forms the basis for the CE mark for the system. The
industrial robot must always be operated in accordance with the applicable
national laws, regulations and standards.
The robot controller has a CE mark in accordance with the EMC Directive
and the Low Voltage Directive.

Declaration of incorporation

The partly completed machinery is supplied with a declaration of incorpo-

ration in accordance with Annex II B of the Machinery Directive
2006/42/EC. The assembly instructions and a list of essential require-
ments complied with in accordance with Annex I are integral parts of this
declaration of incorporation.
The declaration of incorporation declares that the start-up of the partly
completed machinery is not allowed until the partly completed machinery
has been incorporated into machinery, or has been assembled with other
parts to form machinery, and this machinery complies with the terms of
the EC Machinery Directive, and the EC declaration of conformity is
present in accordance with Annex II A.

3.1.3 Terms in the “Safety” chapter

Term Description

Axis range Range within which the axis may move The axis range must be de-
fined for each axis.

Stopping distance Stopping distance = reaction distance + braking distance

The stopping distance is part of the danger zone.

Workspace Area within which the robot may move. The workspace is derived
from the individual axis ranges.

Automatic (AUT) Operating mode for program execution. The manipulator moves at
the programmed velocity.

User The user of the industrial robot can be the management, employer
or delegated person responsible for use of the industrial robot.

Service life The service life of a safety-relevant component begins at the time
of delivery of the component to the customer.
The service life is not affected by whether the component is used
or not, as safety-relevant components are also subject to aging dur-
ing storage.

Danger zone The danger zone consists of the workspace and the stopping dis-
tances of the manipulator.

28/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety
CRR Controlled Robot Retraction
CRR is an operating mode which can be selected when the indus-
trial robot is stopped by the safety controller for one of the following
reasons:

• Industrial robot violates an axis-specific or Cartesian monitoring

space.
• Orientation of a safety-oriented tool is outside the monitored
range.
• Industrial robot violates a force or axis torque monitoring func-
tion.
• A position sensor is not mastered or referenced.
• An axis torque sensor is not referenced.
After changing to CRR mode, the industrial robot may once again
be moved.

KUKA smartPAD see “smartPAD”

KUKA smartPAD-2 see “smartPAD”

Manipulator The robot arm and the associated electrical installations

Safety zone The safety zone is situated outside the danger zone.

Safety stop The safety stop is triggered by the safety controller, interrupts the
work procedure and causes all robot motions to come to a stand-
still. The program data are retained in the case of a safety stop
and the program can be resumed from the point of interruption.
The safety stop can be executed as a Stop category 0, Stop cate-
gory 1 or Stop category 1 (path-maintaining).
Note: In this document, a safety stop of Stop category 0 is referred
to as safety stop 0, a safety stop of Stop category 1 as safety
stop 1 and a safety stop of Stop category 1 (path-maintaining) as
safety stop 1 (path-maintaining).

smartPAD Teach pendant

The smartPAD has all the operator control and display functions re-
quired for operation of the robot. 2 models exist:

• smartPAD
• smartPAD-2
In turn, for each model there are variants, e.g. with different lengths
of connecting cables.
The designation “KUKA smartPAD” or “smartPAD” refers to both
models unless an explicit distinction is made.

Stop category 0 The drives are deactivated immediately and the brakes are applied.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 29/667

Safety KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Stop category 1 The manipulator is braked and does not stay on the programmed
path. The manipulator is brought to a standstill with the drives. As
soon as an axis is at a standstill, the drive is switched off and the
brake is applied.
The internal electronic drive system of the robot performs safety-ori-
ented monitoring of the braking process. Stop category 0 is execu-
ted in the event of a fault.
Note: Stop category 1 is currently only supported by the LBR iiwa.
For other manipulators, Stop category 0 is executed.

Stop category 1 (path- The manipulator is braked and stays on the programmed path. At
maintaining) standstill, the drives are deactivated and the brakes are applied.
If Stop category 1 (path-maintaining) is triggered by the safety con-
troller, the safety controller monitors the braking process. The
brakes are applied and the drives are switched off after 1 s at the
latest. Stop category 1 is executed in the event of a fault.

System integrator The system integrator is responsible for safely integrating the indus-
(plant integrator) trial robot into a complete system and commissioning it.

T1 Test mode, Manual Reduced Velocity (<= 250 mm/s)

Note: With manual guidance in T1, the velocity is not reduced, but
rather limited through a safety-oriented velocity monitoring in ac-
cordance with the safety configuration.
Note: The maximum velocity of 250 mm/s does not apply to a mo-
bile platform.

T2 Test mode, Manual High Velocity (> 250 mm/s permissible)

3.2 Personnel

The following persons or groups of persons are defined for the industrial
robot:

• User
• Personnel

All persons working with the industrial robot must have read and under-
stood the industrial robot documentation, including the safety chapter.

User

The user must observe the labor laws and regulations. This includes e.g.:

• The user must comply with his monitoring obligations.

• The user must carry out briefing at defined intervals.
• The user must comply with the regulations relating to personal protec-
tive equipment (PSA).

Personnel

Personnel must be instructed, before any work is commenced, in the type

of work involved and what exactly it entails as well as any hazards which
may exist. Instruction must be carried out regularly. Instruction is also re-
quired after particular incidents or technical modifications.

30/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Personnel includes:

Safety
• System integrator
• Operators, subdivided into:
‒ Start-up, maintenance and service personnel
‒ Operating personnel
‒ Cleaning personnel

Installation, exchange, adjustment, operation, maintenance and repair

must be performed only as specified in the operating or assembly in-
structions for the relevant component of the industrial robot and only by
personnel specially trained for this purpose.

System integrator

The industrial robot is safely integrated into a complete system by the sys-
tem integrator.
The system integrator is responsible for the following tasks:

• Installing the industrial robot

• Connecting the industrial robot
• Performing risk assessment
• Implementing the required safety functions and safeguards
• Issuing the EC declaration of conformity
• Attaching the CE mark
• Creating the operating instructions for the system

Operators

The operator must meet the following preconditions:

• The operator must be trained for the work to be carried out.
• Work on the system must only be carried out by qualified personnel.
These are people who, due to their specialist training, knowledge and
experience, and their familiarization with the relevant standards, are
able to assess the work to be carried out and detect any potential
hazards.

Work on the electrical and mechanical equipment of the manipulator

may only be carried out by KUKA Deutschland GmbH.

3.3 Workspace, safety zone and danger zone

Working zones are to be restricted to the necessary minimum size in or-

der to prevent danger to persons or the risk of material damage. Safely
monitored axis limits that limit the motion range of an axis and are re-
quired for personnel protection are configurable.
Further information about configuring safely monitored axis limits is con-
tained in the “Safety configuration” chapter of the operating and pro-
gramming instructions of the system software for system integrators.
(>>> 13 "Safety configuration" Page 251)

The danger zone consists of the workspace and the stopping distances of
the manipulator. In the event of a stop, the manipulator is braked and
comes to a stop within the danger zone. The safety zone is the area out-
side the danger zone.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 31/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The danger zone must be protected by means of physical safeguards,

Safety

e.g. by light barriers, light curtains or safety fences. If there are no physi-
cal safeguards present, the requirements for collaborative operation in ac-
cordance with EN ISO 10218 must be met. There must be no shearing or
crushing hazards at the loading and transfer areas.

Fig. 3-1: Example: axis range A1

1 Workspace 3 Stopping distance

2 Manipulator 4 Safety zone

3.4 Triggers for safety-oriented stop reactions

Stop reactions are triggered in response to operator actions or as a reac-

tion to monitoring functions and errors. The following tables show the dif-
ferent stop reactions according to the operating mode that has been set.

Overview

In KUKA Sunrise a distinction is made between the following triggers:

• Permanently defined triggers

Permanently defined triggers for stop reactions and the associated
stop category are preset by the system and cannot be changed. How-
ever, it is possible for the implemented stop reaction to be stepped up
in the user-specific safety configuration.
• User-specific triggers
In addition to the permanently defined triggers, the user can also con-
figure other triggers for stop reactions including the associated stop
category.

Further information about configuring the safety functions is contained in

the “Safety configuration” chapter of the operating and programming in-
structions of the system software for system integrators. (>>> 13 "Safety
configuration" Page 251)

32/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety
Permanently defined triggers

The following triggers for stop reactions are permanently defined:

Trigger T1, T2, CRR AUT
Operating mode changed Safety stop 1 (path-maintaining)
during operation
Enabling switch released Safety stop 1 (path- -
maintaining)
Enabling switch pressed Safety stop 1 (path- -
fully down (panic position) maintaining)
Local E-STOP pressed Safety stop 1 (path-maintaining)
Error in safety controller Safety stop 1

User-specific triggers

When creating a new Sunrise project, the system automatically generates

a project-specific safety configuration. This contains the following user-
specific stop reaction triggers preconfigured by KUKA (in addition to the
permanently defined triggers):
Trigger T1, CRR T2, AUT
Safety gate opened (op- - Safety stop 1 (path-
erator safety) maintaining)
External E-STOP pressed Safety stop 1 (path-maintaining)
External safety stop Safety stop 1 (path-maintaining)

This default safety configuration is valid for the system software without
additionally installed option packages or catalog elements. If additional
option packages or catalog elements have been installed, the default
safety configuration may be modified.

Triggers for manual guidance

If an enabling device is configured for manual guidance, the following ad-

ditional triggers for stop reactions are permanently defined:
Trigger T1, CRR T2, AUT
Manual guidance ena- Safety stop 1 (path- -
bling switch released maintaining)
Manual guidance ena- Safety stop 1 (path- -
bling switch pressed fully maintaining)
down (panic position)
Maximum permissible ve- Safety stop 1 (path-maintaining)
locity exceeded while
manual guidance ena-
bling signal is set
A maximum permissible velocity of 250 mm/s is preconfigured for manual
guidance. The maximum permissible velocity can be adapted.
The value for the maximum permissible velocity must be determined as
part of a risk assessment.
(>>> 13.11.5.3 "Velocity monitoring during manual guidance" Page 291)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 33/667

Safety KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

3.5 Safety functions

Safety functions are distinguished according to the safety requirements

that they fulfill:
• Safety-oriented functions for the protection of personnel
The safety-oriented functions of the industrial robot meet the following
safety requirements:
‒ Category 3 and Performance Level d in accordance with EN ISO
13849-1
‒ SIL 2 according to EN 62061
The requirements are only met on the following condition, however:
‒ All safety-relevant mechanical and electromechanical components
of the industrial robot are tested for correct functioning during start-
up and at least once every 12 months, unless otherwise deter-
mined in accordance with a workplace risk assessment. These in-
clude:
‒ Local EMERGENCY STOP device on the teach pendant
‒ Enabling device on the teach pendant
‒ Enabling device on the hand guiding device (if present)
‒ External enabling devices (if present)
‒ Mode selector switch on the smartPAD (if used as teach pend-
ant)
‒ Safety-oriented outputs of the discrete safety interface

Details about safety parameters (e.g. PFH, SIL, Performance Level)

are also available as a SISTEMA library. The library can be down-
loaded from the KUKA website.

• Non-safety-oriented functions for the protection of machines

The non-safety-oriented functions of the industrial robot do not meet
specific safety requirements.

DANGER
In the absence of the required operational safety functions and safe-
guards, the industrial robot can cause personal injury or material dam-
age. If the required safety functions or safeguards are dismantled or de-
activated, the industrial robot may not be operated.

Integrate industrial robot into safety system of the overall system

During system planning, the safety functions of the overall system must
be planned and designed. Death, severe injuries or damage to property
may otherwise result.
• The industrial robot must be integrated into the safety system of the
overall system.

3.5.1 Safety-oriented functions

The following safety-oriented functions are present and permanently de-

fined in the industrial robot:
• EMERGENCY STOP device
• Enabling device
The following safety-oriented functions are preconfigured and can be inte-
grated into the system via the safety interface of the robot controller:

34/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety
• Operator safety (= connection for the monitoring of physical safe-
guards)
• External EMERGENCY STOP device
• External safety stop 1 (path-maintaining)
Other safety-oriented functions can also be configured, e.g.:
• External enabling device
• External safe operational stop
• Axis-specific workspace monitoring
• Cartesian workspace monitoring
• Cartesian protected space monitoring
• Velocity monitoring
• Standstill monitoring
• Axis torque monitoring
• Collision detection

Further information about configuring the safety functions is contained in

the “Safety configuration” chapter of the operating and programming in-
structions of the system software for system integrators. (>>> 13 "Safety
configuration" Page 251)

The preconfigured safety functions are described in the following sections

on safety.

3.5.1.1 EMERGENCY STOP device

As standard, the EMERGENCY STOP device of the industrial robot is the

EMERGENCY STOP device on the smartPAD teach pendant. The EMER-
GENCY STOP device must be pressed in the event of a hazardous situa-
tion or emergency.
Reaction of the industrial robot if the EMERGENCY STOP device is
pressed:
• The manipulator stops with a safety stop 1 (path-maintaining).
Before operation can be resumed, the EMERGENCY STOP device must
be turned to release it.
From KUKA Sunrise.OS 2.4 onwards, the inputs for the local EMER-
GENCY STOP can be configured, i.e. a different EMERGENCY STOP
device can be connected and used for the local EMERGENCY STOP.

WARNING
Danger to life and limb due to tools and equipment without EMER-
GENCY STOP
If tools and other equipment connected to the robot are not integrated
into the EMERGENCY STOP circuit, this can result in death, severe in-
juries or damage to property.
• Integrate tools and other equipment into the EMERGENCY STOP
circuit if they could constitute a potential hazard.

If a holder is used for the teach pendant and conceals the EMERGENCY
STOP device on the teach pendant, an external EMERGENCY STOP de-
vice must be installed that is accessible at all times.
(>>> 3.5.1.4 "External EMERGENCY STOP device" Page 37)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 35/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

3.5.1.2 Enabling device

Safety

The enabling devices of the industrial robot are the enabling switches on
the smartPAD teach pendant by default.
• smartPAD: 3 enabling switches
• smartPAD-2: 4 enabling switches

From KUKA Sunrise.OS 2.4 onwards, the inputs of the enabling device
for the teach pendant can be configured, i.e. a different teach pendant
with enabling device can be connected and used.

The enabling switches have 3 positions:

• Not pressed
• Center position
• Fully pressed (panic position)
In operating modes T1, T2 and CRR, the manipulator can only be moved
if one of the enabling switches is held in the central position.
It is possible to hold several enabling switches in the center position si-
multaneously. This makes it possible to adjust grip from one enabling
switch to another one.
In operating modes T1, T2 and CRR, the manipulator can be stopped in
the following ways:
• Press at least one enabling switch down fully.
Fully pressing an enabling switch triggers a safety stop 1 (path-main-
taining).
• Or release all enabling switches.
Releasing all (!) enabling switches held in the center position triggers
a safety stop 1 (path-maintaining).

WARNING
Danger to life and limb due to lack of reaction when an enabling
switch is released
Releasing one of multiple enabling switches held in the center position
does not trigger a stop reaction.
If multiple switches are held in the center position, the robot controller
cannot distinguish whether one of them was intentionally released or if it
was unintentionally released as the result of an accident.
• Create awareness for the hazard.

If an enabling switch malfunctions (e.g. jams in the center position), the

industrial robot can be stopped using one of the following methods:

• Press another enabling switch down fully.

• Actuate the EMERGENCY STOP device.
• Release the Start key.

WARNING
Danger to life and limb due to manipulation of enabling switches
The enabling switches must not be held down by adhesive tape or other
means or tampered with in any other way. Death, severe injuries or
damage to property may result.
• Carry out a visual inspection of the enabling switches.
• Rectify tampering or remove any foreign bodies.

36/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

3.5.1.3 “Operator safety” signal

Safety
The “operator safety” signal is used for monitoring physical safeguards,
e.g. safety gates. In the default configuration, T2 and automatic operation
are not possible without this signal. Alternatively, the requirements for col-
laborative operation in accordance with EN ISO 10218 must be met.
Reaction of the industrial robot in the event of a loss of signal during T2
or automatic operation (default configuration):
• The manipulator stops with a safety stop 1 (path-maintaining).
By default, operator safety is not active in the modes T1 (Manual Re-
duced Velocity) and CRR, i.e. the signal is not evaluated.
WARNING
Following a loss of signal, automatic operation must not be resumed
merely by closing the safeguard; the signal for operator safety must first
be set by an additional device, e.g. by an acknowledge button. It is the
responsibility of the system integrator to ensure this. This is to prevent
automatic operation from being resumed inadvertently while there are
still persons in the danger zone, e.g. due to the safety gate closing ac-
cidentally.
• This additional device must be designed in such a way that an ac-
tual check of the danger zone can be carried out first. Devices that
do not allow this (e.g. because they are automatically triggered by
closure of the safeguard) are not permitted.
• Failure to observe this may result in death to persons, severe inju-
ries or considerable damage to property.

3.5.1.4 External EMERGENCY STOP device

Every operator station that can initiate a robot motion or other potentially
hazardous situation must be equipped with an EMERGENCY STOP de-
vice. The system integrator is responsible for ensuring this.
Reaction of the industrial robot if the external EMERGENCY STOP device
is pressed (default configuration):
• The manipulator stops with a safety stop 1 (path-maintaining).
External EMERGENCY STOP devices are connected via the safety inter-
face of the robot controller. External EMERGENCY STOP devices are not
included in the scope of supply of the industrial robot.

3.5.1.5 External safety stop 1 (path-maintaining)

The external safety stop 1 (path-maintaining) can be triggered via an input

on the safety interface (default configuration). The state is maintained as
long as the external signal is FALSE. If the external signal is TRUE, the
manipulator can be moved again. No acknowledgement is required.

3.5.1.6 External enabling device

External enabling devices are required if it is necessary for more than one
person to be in the danger zone of the industrial robot.
Multiple external enabling devices can be connected via the safety inter-
face of the robot controller. External enabling devices are not included in
the scope of supply of the industrial robot.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 37/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

An external enabling device can be used for manual guidance of the ro-
Safety

bot. When enabling is active, the robot may only be moved at reduced ve-
locity.
For manual guidance, safety-oriented velocity monitoring with a maximum
permissible velocity of 250 mm/s is preconfigured. The maximum permissi-
ble velocity can be adapted.
The value for the maximum permissible velocity must be determined as
part of a risk assessment.

3.5.1.7 External safe operational stop

The safe operational stop is a standstill monitoring function. It does not

stop the robot motion, but monitors whether the robot axes are stationary.
The safe operational stop can be triggered via an input on the safety in-
terface. The state is maintained as long as the external signal is FALSE.
If the external signal is TRUE, the manipulator can be moved again. No
acknowledgement is required.

3.5.2 Non-safety-oriented functions

3.5.2.1 Mode selection

Operating modes

The industrial robot can be operated in the following modes:

• Manual Reduced Velocity (T1)
• Manual High Velocity (T2)
• Automatic (AUT)
• Controlled robot retraction (CRR)

Operating
Use Velocities
mode
T1 Programming, teaching and testing of • Program verification:
programs.
Reduced programmed velocity,
maximum 250 mm/s
• Jog mode:
Jog velocity, maximum 250 mm/s
• Manual guidance:
No limitation of the velocity, but
safety-oriented velocity monitoring
in accordance with the safety con-
figuration
Note: The maximum velocity of
250 mm/s does not apply to a mobile
platform.
T2 Testing of programs • Program verification:
Programmed velocity
• Jog mode: Not possible
AUT Automatic execution of programs • Program operation:
For industrial robots with and without Programmed velocity
higher-level controllers • Jog mode: Not possible

38/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety
Operating
Use Velocities
mode
CRR CRR is an operating mode which can • Program verification:
be selected when the industrial robot
Reduced programmed velocity,
is stopped by the safety controller for
maximum 250 mm/s
one of the following reasons:
• Jog mode:
• Industrial robot violates an axis- Jog velocity, maximum 250 mm/s
specific or Cartesian monitoring
• Manual guidance:
space.
No limitation of the velocity, but
• Orientation of a safety-oriented tool
safety-oriented velocity monitoring
is outside the monitored range.
in accordance with the safety con-
• Industrial robot violates a force or figuration
axis torque monitoring function.
• A position sensor is not mastered
or referenced.
• An axis torque sensor is not refer-
enced.
After changing to CRR mode, the in-
dustrial robot may once again be
moved.

Mode selector switch

The user can change the operating mode via the connection manager.
The connection manager is a view that is called by means of the mode
selector switch on the smartPAD.
The mode selector switch may be one of the following variants:
• With key
It is only possible to change operating mode if the key is inserted.
• Without key

WARNING
Danger to life and limb due to mode selector switch without
access restriction
If the smartPAD is equipped with a mode selector switch without a key,
all persons can operate the mode selector switch, irrespective of their
field of activity or qualifications. Death, severe injuries or damage to
property may result.
• An additional device must be installed to ensure that the mode se-
lector switch can only be operated by a restricted group of people.
• The device itself must not trigger motions of the industrial robot or
other hazards.

3.5.2.2 Velocity monitoring in T1

The reduced velocity in T1 does not constitute a safety-rated reduced

speed in the standard safety configuration, i.e. the maximum permissible
velocity of 250 mm/s in T1 is not subjected to safety-oriented monitoring.
If the application requires safety-oriented velocity monitoring in T1, this
can be added in the safety configuration. The safety option KUKA Sun-
rise.SafeOperation provides the monitoring function Cartesian velocity
monitoring for this purpose.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 39/667

Safety KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Further information about configuring safety-oriented velocity monitoring

for T1 is contained in the “Safety configuration” chapter of the operating
and programming instructions of the system software for system integra-
tors. (>>> 13 "Safety configuration" Page 251)

3.5.2.3 Software limit switches

The axis ranges of all manipulator axes are limited by means of non-safe-
ty-oriented software limit switches. These software limit switches only
serve as machine protection and are preset in such a way that the manip-
ulator is stopped under servo control if the axis limit is exceeded, thereby
preventing damage to the mechanical equipment.

3.6 Additional protective equipment

3.6.1 Jog mode

In the operating modes T1 (Manual Reduced Velocity), T2 (Manual High

Velocity) and CRR, the robot controller can only execute programs in jog
mode. This means that it is necessary to hold down an enabling switch
and the Start key in order to execute a program.
• Releasing the enabling switch on the smartPAD triggers a safety
stop 1 (path-maintaining).
• Pressing fully down on the enabling switch on the smartPAD triggers a
safety stop 1 (path-maintaining).
• Releasing the Start key triggers a stop of Stop category 1 (path-main-
taining).

3.6.2 Labeling on the industrial robot

All plates, labels, symbols and marks constitute safety-relevant parts of

the industrial robot. They must not be modified or removed.
Labeling on the industrial robot consists of:
• Identification plates
• Warning signs
• Safety symbols
• Designation labels
• Cable markings
• Rating plates

Further information is contained in the technical data of the operating in-

structions or assembly instructions of the components of the industrial
robot.

3.6.3 External safeguards

The access of persons to the danger zone of the industrial robot must be
prevented by means of safeguards. Alternatively, the requirements for col-
laborative operation in accordance with EN ISO 10218 must be met. It is
the responsibility of the system integrator to ensure this.
Physical safeguards must meet the following requirements:

• They meet the requirements of EN ISO 14120.

40/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety
• They prevent access of persons to the danger zone and cannot be
easily circumvented.
• They are sufficiently fastened and can withstand all forces that are
likely to occur in the course of operation, whether from inside or out-
side the enclosure.
• They do not, themselves, represent a hazard or potential hazard.
• The prescribed minimum clearance from the danger zone is main-
tained.
Safety gates (maintenance gates) must meet the following requirements:

• They are reduced to an absolute minimum.

• The interlocks (e.g. safety gate switches) are linked to the configured
operator safety inputs of the robot controller.
• Switching devices, switches and the type of switching conform to the
requirements of Performance Level d and category 3 according to EN
ISO 13849-1.
• Depending on the risk situation: the safety gate is additionally safe-
guarded by means of a locking mechanism that only allows the gate
to be opened if the manipulator is safely at a standstill.
• The device for setting the signal for operator safety, e.g. the button for
acknowledging the safety gate, is located outside the space limited by
the safeguards.

Further information is contained in the corresponding standards and reg-

ulations. These also include EN ISO 14120.

Other safety equipment

Other safety equipment must be integrated into the system in accordance

with the corresponding standards and regulations.

3.7 Safety measures

3.7.1 General safety measures

The industrial robot may only be used in perfect technical condition in ac-
cordance with its intended use and only by safety-conscious persons. Op-
erator errors can result in personal injury and damage to property.
It is important to be prepared for possible movements of the industrial ro-
bot even after the robot controller has been switched off and locked out.
Incorrect installation (e.g. overload) or mechanical defects (e.g. brake de-
fect) can cause the manipulator to sag. If work is to be carried out on a
switched-off industrial robot, the manipulator must first be moved into a
position in which it is unable to move on its own, whether the payload is
mounted or not. If this is not possible, the manipulator must be secured
by appropriate means.
DANGER
Risk of fatal injury due to non-operational safety functions or exter-
nal safeguards
In the absence of operational safety functions or safeguards, the indus-
trial robot can cause death, severe injuries or damage to property.
• If safety functions or safeguards are dismantled or deactivated, do
not operate the industrial robot.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 41/667

Safety KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

WARNING
Standing underneath the robot arm can cause death or serious injuries.
Especially if the industrial robot is moving objects that can become de-
tached (e.g. from a gripper). For this reason, standing underneath the
robot arm is prohibited!

HRC

In the case of collaborative operation (HRC), the system must be equip-

ped with a visual display indicating when the robot is in collaborative op-
eration.

smartPAD

The user must ensure that the industrial robot is only operated with the
smartPAD by authorized persons.
If more than one smartPAD is used in the overall system, it must be en-
sured that each smartPAD is unambiguously assigned to the correspond-
ing industrial robot. It must be ensured that 2 smartPADs are not inter-
changed.
As standard, the smartPAD is unpluggable.
WARNING
Risk of fatal injury due to non-operational EMERGENCY STOP de-
vice
If the smartPAD is disconnected, the system can no longer be switched
off by means of the EMERGENCY STOP device on the smartPAD.
Measures must be taken to prevent operational and non-operational
EMERGENCY STOP devices from being mixed up.
Death, injuries or damage to property may result.
• If unplugging of the smartPAD is to be allowed, connect at least one
external EMERGENCY STOP device that is accessible at all times
to the robot controller.
• Immediately remove the unplugged smartPAD from the system and
store it out of sight and reach.

If unplugging of the smartPAD is not to be allowed, this can be configured

in the station configuration.

Modifications

After modifications to the industrial robot, checks must be carried out to

ensure the required safety level. The valid national or regional work safety
regulations must be observed for this check. The correct functioning of all
safety functions must also be tested.
New or modified programs must always be tested first in Manual Reduced
Velocity mode (T1).
After modifications to the industrial robot, existing programs must always
be tested first in Manual Reduced Velocity mode (T1). This applies to all
components of the industrial robot and includes modifications to the soft-
ware and configuration settings.
The robot may not be connected and disconnected when the robot con-
troller is running.

Faults

The following tasks must be carried out in the case of faults in the indus-
trial robot:

42/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety
• Switch off the robot controller and secure it (e.g. with a padlock) to
prevent unauthorized persons from switching it on again.
• Indicate the fault by means of a label with a corresponding warning
(tagout).
• Keep a record of the faults.
• Eliminate the fault and carry out a function test.

3.7.2 IT security

KUKA products must only be used in perfect technical condition in accord-

ance with their intended use and only by safety-conscious persons.
In particular, safety-conscious use includes being operated in an IT envi-
ronment which meets the current security-relevant standards and for
which there is an overall concept for IT security.
Take measures to ensure IT security
IT security involves not only aspects of information and data processing
as such, but also affects at least the following areas:
• Technology, organization, personnel, infrastructure
KUKA urgently recommends that users implement an information securi-
ty management system for their products which designs, coordinates
and monitors the tasks related to information security.

Sources for information about IT security for companies include:

• Independent consulting firms
• National cyber security authorities
National authorities often make their recommendations available on the In-
ternet. In addition to their official language, some national authorities pro-
vide their information in English.

3.7.3 Transportation

Manipulator

The prescribed transport position of the manipulator must be observed.

Transportation must be carried out in accordance with the operating in-
structions or assembly instructions of the robot.
Avoid vibrations and impacts during transportation in order to prevent
damage to the manipulator.

Robot controller

The prescribed transport position of the robot controller must be observed.

Transportation must be carried out in accordance with the operating in-
structions or assembly instructions of the robot controller.
Avoid vibrations and impacts during transportation in order to prevent
damage to the robot controller.

3.7.4 Start-up and recommissioning

Before starting up systems and devices for the first time, a check must be
carried out to ensure that the systems and devices are complete and op-
erational, that they can be operated safely and that any damage is detec-
ted.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 43/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The valid national or regional work safety regulations must be observed

Safety

for this check. The correct functioning of all safety functions must also be
tested.
Prior to start-up, the passwords for the user groups must be modified by
the administrator, transferred to the robot controller in an installation pro-
cedure and activated. The passwords must only be communicated to
authorized personnel. (>>> 9.4.2 "Changing and activating the pass-
word" Page 198)

DANGER
The robot controller is preconfigured for the specific industrial robot. If
cables are interchanged, the manipulator may receive incorrect data and
can thus cause personal injury or material damage. If a system consists
of more than one manipulator, always connect the connecting cables to
the manipulators and their corresponding robot controllers.

Do not impair safety functions

Additional components (e.g. cables and hoses) not supplied by KUKA
may be integrated into the industrial robot. If the safety functions are not
taken into consideration, this may result in death, severe injuries or
damage to property.
• Additional components must not impair or disable safety functions.

NOTICE
Damage to property due to condensation
If the internal cabinet temperature of the robot controller differs greatly
from the ambient temperature, condensation can form. This may result
in damage to property.
• Wait until the internal cabinet temperature has adapted to the ambi-
ent temperature in order to avoid condensation.

Function test

The following tests must be carried out before start-up and recommission-
ing:
General test:
It must be ensured that:

• The industrial robot is correctly installed and fastened in accordance

with the specifications in the documentation.
• There are no foreign bodies or defective or loose parts on the industri-
al robot.
• All required safety equipment is correctly installed and operational.
• The power supply ratings of the industrial robot correspond to the
local supply voltage and mains type.
• The ground conductor and the equipotential bonding cable are suffi-
ciently rated and correctly connected.
• The connecting cables are correctly connected and the connectors are
locked.
Test of the safety functions:
A function test must be carried out for all the safety-oriented functions to
ensure that they are working correctly.
(>>> 13.14 "Safety acceptance overview" Page 330)
Test of the safety-relevant mechanical and electromechanical compo-
nents:

44/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The following tests must be performed prior to start-up and at least once

Safety
every 12 months unless otherwise determined in accordance with a work-
place risk assessment:
• Function of all connected EMERGENCY STOP devices
Press the EMERGENCY STOP device. A message must be displayed
on the teach pendant indicating that the EMERGENCY STOP has
been actuated. At the same time, no error message may be displayed
about the EMERGENCY STOP device.
• Function of the enabling switches of all connected enabling devices
Move the robot in Test mode and release the enabling switch. The ro-
bot motion must be stopped. At the same time, no error message may
be displayed on the teach pendant about the enabling device.
The test must always be carried out for all enabling switches of a con-
nected enabling device.
If the state of the enabling device is configured at an output, the test
can also be performed via the output.
• Panic function of the enabling switches of all connected enabling devi-
ces
Move the robot in test mode, press the enabling switch down and hold
in the panic position for 3 seconds. The robot motion must be stop-
ped. At the same time, no error message may be displayed on the
teach pendant about the enabling device.
The test must always be carried out for all enabling switches of a con-
nected enabling device.
If the state of the enabling device is configured at an output, the test
can also be performed via the output.
• Function of the mode selector switch on the smartPAD (if used as
teach pendant)
Turn the mode selector switch to the right and then back again. There
must be no error message displayed on the smartPAD.
• Switch-off capability of the safety-oriented outputs
Switch robot controller off and then on again. After it is switched on,
no error message relating to a safety-oriented output may be dis-
played on the teach pendant.

In the case of incomplete start-up of the system, additional substitute

measures for minimizing risk must be taken and documented, e.g. in-
stallation of a safety fence, attachment of a warning sign, locking of the
main switch. Start-up is incomplete, for example, if not all safety func-
tions have yet been implemented, or if a function test of the safety func-
tions has not yet been carried out.

Test of the functional capability of the brakes:

For the industrial robot, a brake test is available which can be used to
check whether the brake of each axis applies sufficient braking torque.
The brake test ensures that any impairment of the braking function is de-
tected, e.g. due to wear, overheating, fouling or damage, thereby eliminat-
ing avoidable risks.
The brake test must be performed regularly, unless an application-specific
risk assessment has established that a malfunction of the mechanical
brakes will not result in inadmissibly high risks. Determination of the inter-
val at which the brake test is to be performed also constitutes part of the
risk assessment.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 45/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

In the absence of a corresponding risk assessment, the following applies:

Safety

• The brake test must be carried out for each axis during start-up and
recommissioning of the industrial robot.
• The brake test must be performed daily during operation.

3.7.5 Manual mode

General

Manual mode is the mode for setup work. Setup work is all the tasks that
have to be carried out on the industrial robot to enable automatic opera-
tion. Setup work includes:
• Jog mode
• Teaching
• Program verification
The following must be taken into consideration in manual mode:
• New or modified programs must always be tested first in Manual Re-
duced Velocity mode (T1).
• The manipulator and its tooling must never touch or project beyond
the safety fence.
• Workpieces, tooling and other objects must not become jammed as a
result of the industrial robot motion, nor must they lead to
short-circuits or be liable to fall off.
• All setup work must be carried out, where possible, from outside the
safeguarded area.

Setup work in T1

If it is necessary to carry out setup work from inside the safeguarded

area, the following must be taken into consideration in the operating mode
Manual Reduced Velocity (T1):
• If it can be avoided, there must be no other persons inside the safe-
guarded area.
If it is necessary for there to be several persons inside the safeguar-
ded area, the following must be observed:
‒ Each person must have an enabling device.
‒ All persons must have an unimpeded view of the industrial robot.
‒ Eye-contact between all persons must be possible at all times.
• The operator must be so positioned that he can see into the danger
area and get out of harm’s way.
• Unexpected motions of the manipulator cannot be ruled out, e.g. in
the event of a fault. For this reason, an appropriate clearance must be
maintained between persons and the manipulator (including tool).
Guide value: 50 cm.
The minimum clearance may vary depending on local circumstances,
the motion program and other factors. The minimum clearance that is
to apply for the specific application must be decided by the user on
the basis of a risk assessment.

Setup work in T2

If it is necessary to carry out setup work from inside the safeguarded

area, the following must be taken into consideration in the operating mode
Manual High Velocity (T2):

46/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety
• This mode may only be used if the application requires a test at a ve-
locity higher than that possible in T1 mode.
• Teaching is not permissible in this operating mode.
• Before commencing the test, the operator must ensure that the ena-
bling devices are operational.
• The operator must be positioned outside the danger zone.
• There must be no-one present inside the safeguarded area. It is the
responsibility of the operator to ensure this.

3.7.6 Automatic mode

Automatic mode is only permissible in compliance with the following safety

measures:

• All safety equipment and safeguards are present and operational.

• There are no persons in the system, or the requirements for collabora-
tive operation in accordance with EN ISO 10218 have been met.
• The defined working procedures are adhered to.
If the manipulator comes to a standstill for no apparent reason, the
danger zone must not be entered until an EMERGENCY STOP has been
triggered.

3.7.7 Maintenance and repair

After maintenance and repair work, checks must be carried out to ensure
the required safety level. The valid national or regional work safety regula-
tions must be observed for this check. The correct functioning of all safety
functions must also be tested.
The purpose of maintenance and repair work is to ensure that the system
is kept operational or, in the event of a fault, to return the system to an
operational state. Repair work includes troubleshooting in addition to the
actual repair itself.
The following safety measures must be carried out when working on the
industrial robot:
• Carry out work outside the danger zone. If work inside the danger
zone is necessary, the user must define additional safety measures to
ensure the safe protection of personnel.
• Switch off the industrial robot and secure it (e.g. with a padlock) to
prevent it from being switched on again. If it is necessary to carry out
work with the robot controller switched on, the user must define addi-
tional safety measures to ensure the safe protection of personnel.
• If it is necessary to carry out work with the robot controller switched
on, this may only be done in operating mode T1.
• Label the system with a sign indicating that work is in progress. This
sign must remain in place, even during temporary interruptions to the
work.
• The EMERGENCY STOP devices must remain active. If safety func-
tions or safeguards are deactivated during maintenance or repair work,
they must be reactivated immediately after the work is completed.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 47/667

Safety KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

DANGER
Danger to life and limb due to live parts
The robot system must be disconnected from the mains power supply
prior to work on live parts. It is not sufficient to trigger an EMERGENCY
STOP or safety stop, because parts remain live. Death or severe inju-
ries may result.
• Before commencing work on live parts, turn off the main switch and
secure it against being switched on again.
If the controller variant in question does not have a main switch
(e.g. KR C5 micro), turn off the device switch then disconnect the
power cable and secure it so it cannot be reconnected.
• Then check to ensure that the system is deenergized.
• Inform the individuals involved that the robot controller is switched
off. (e.g. by affixing a warning sign)

Faulty components must be replaced using new components with the

same article numbers or equivalent components approved by KUKA
Deutschland GmbH for this purpose.
Cleaning and preventive maintenance work is to be carried out in accord-
ance with the operating instructions.

Robot controller

Even when the robot controller is switched off, parts connected to periph-
eral devices may still carry voltage. The external power sources must
therefore be switched off if work is to be carried out on the robot control-
ler.
The ESD regulations must be adhered to when working on components in
the robot controller.
Voltages in excess of 60 V can be present in various components for sev-
eral minutes after the robot controller has been switched off! To prevent
life-threatening injuries, no work may be carried out on the industrial robot
in this time.
Water and dust must be prevented from entering the robot controller.

3.7.8 Decommissioning, storage and disposal

The industrial robot must be decommissioned, stored and disposed of in

accordance with the applicable national laws, regulations and standards.

3.7.9 Safety measures for “single point of control”

Overview

If certain components in the industrial robot are operated, safety measures

must be taken to ensure complete implementation of the principle of “sin-
gle point of control” (SPOC).
Components:

• Tools for configuration of bus systems with online functionality

The implementation of additional safety measures may be required. This

must be clarified for each specific application; this is the responsibility of
the user of the system.

48/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Since only the system integrator knows the safe states of actuators in the

Safety
periphery of the robot controller, it is his task to set these actuators to a
safe state.

T1, T2, CRR

In modes T1, T2 and CRR, a robot motion can only be initiated if an ena-
bling switch is held down.

Tools for configuration of bus systems

If these components have an online functionality, they can be used with

write access to modify programs, outputs or other parameters of the robot
controller, without this being noticed by any persons located inside the
system.
Such tools include:
• KUKA Sunrise.Workbench
• WorkVisual from KUKA
• Tools from other manufacturers
Safety measure:

• In the test modes, programs, outputs or other parameters of the robot

controller must not be modified using these components.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 49/667

Safety KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

50/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Installing KUKA Sunrise.Workbench

4 Installing KUKA Sunrise.Workbench

4.1 PC system requirements

Hardware

Minimum requirements
• PC with Pentium IV processor, min. 1500 MHz
• 2 GB RAM
• 200 MB free hard disk space
• DirectX-compatible graphics card with a resolution of 1024x768 pixels
Recommended specifications
• PC with Pentium IV processor or higher and 2500 MHz
• 4 GB RAM
• 1 GB free hard disk space
• DirectX-compatible graphics card with a resolution of 1280x1024 pixels

Software

• Windows 7 or 10
Both the 32-bit version and the 64-bit version can be used.
The following software is required for bus configuration:

• WorkVisual 5.0

4.2 Installing Sunrise.Workbench

Preparation

If an older version of Sunrise.Workbench is already installed:

• Uninstall the old version first.

Precondition

• Local administrator rights

Procedure

1. Start the program SunriseWorkbench-[…]-Setup.exe. A window

opens.
2. Select the language for the installation procedure and confirm with
OK.
The language selection only applies to the installation and not to Sun-
rise.Workbench itself. The default user interface language for Sun-
rise.Workbench is German.
3. An installation wizard opens. Follow the instructions in the wizard.

4.3 Uninstalling Sunrise.Workbench

Description

When Sunrise.Workbench is uninstalled, all program files are removed

from the computer. User-specific files are retained, e.g. the workspace
with the Sunrise projects.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 51/667

Installing KUKA Sunrise.Workbench KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Precondition

• Local administrator rights

Procedure

1. Call the list of installed programs in the Windows Control Panel.

2. In the list, select the program Sunrise Workbench and uninstall it.

Alternative procedure

• Right-click on the program in the Windows Start menu and select Un-
install from the context menu.

52/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operation of KUKA Sunrise.Workbench

5 Operation of KUKA Sunrise.Workbench

5.1 Starting Sunrise.Workbench

Description

There are various ways of starting the Sunrise.Workbench program, e.g.:

• Double-clicking on the desktop link to the program
• Clicking on the program in the Windows Start menu
• Double-clicking on the program in the installation directory

Procedure

1. Start the program. The Workspace Launcher window opens.

2. In the Workspace box, specify the directory for the workspace in
which projects are to be saved.
• A default directory is suggested. The directory can be changed by
clicking on the Browse… button.
• If the workspace should not be queried the next time Sun-
rise.Workbench is started, activate the option Use this as the de-
fault value[…] (set check mark).
Confirm the settings with OK.
3. A welcome screen opens the first time Sunrise.Workbench is started.
There are different options here.
• Click on Workbench to open the user interface of Sunrise.Work-
bench.
(>>> 5.2 "Overview of the user interface of Sunrise.Workbench"
Page 53)
• Click on New Sunrise project to create a new Sunrise project di-
rectly. The project creation wizard opens.
(>>> 5.3 "Creating a Sunrise project with a template" Page 57)

5.2 Overview of the user interface of Sunrise.Workbench

The user interface of KUKA Sunrise.Workbench consists of several views.

The combination of several views is called a perspective. KUKA Sun-
rise.Workbench offers various preconfigured perspectives.
The Programming perspective is opened by default. Additional perspec-
tives can be displayed.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 53/667

Operation of KUKA Sunrise.Workbench KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 5-1: Overview of user interface – “Programming” perspective

Item Description
1 Menu bar
2 Toolbars
(>>> 5.2.4 "Toolbar of the Programming perspective" Page 56)
3 Editor area
Opened files, e.g. robot applications, can be displayed and edi-
ted in the editor area.
4 Application data view
This view displays the frames created for a project in a tree
structure.
5 Object templates view
This view displays the geometrical objects, tools and workpie-
ces created for a project in a tree structure.
6 Perspective selection
It is possible to switch between different perspectives that are
already in use by clicking on the name of the desired perspec-
tive or selecting it via the Open perspective icon.
(>>> 5.2.3 "Displaying perspectives" Page 55)
7 Package Explorer view
This view contains the projects created and their corresponding
files.

54/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operation of KUKA Sunrise.Workbench

Item Description
8 Tasks view
The tasks that a user has created are displayed in this view.
Javadoc view
The Javadoc comments about the selected elements of a Java
application are displayed in this view.
Properties view
The properties of the object, e.g. project, frame or tool, selected
in a different view, are displayed in this view.

5.2.1 Repositioning the views

Procedure

1. Grip the view by the title bar while holding down the left mouse button
and move it to the desired position on the user interface.
The possible positions for the view are indicated here by a gray frame.
2. Release the mouse button when the desired position for the view is
selected.

5.2.2 Closing views and files

Procedure

• Click on the “X” at the top right of the corresponding tab.

5.2.3 Displaying perspectives

Description

The user interface can be displayed in different perspectives. These can

be selected via the menu sequence Window > Open Perspective or by
clicking on the Open Perspective icon.
The perspectives are tailored to different types of work:
Perspective Center of gravity
Programming This perspective has views suitable for editing
Sunrise projects, e.g. for the station configura-
tion, safety configuration and application devel-
opment.
Debug This perspective has views suitable for locating
faults and eliminating programming faults.
Perspectives can be adapted to the needs of the user. Examples:
• Creating own perspectives
• Showing/hiding views
• Showing/hiding menus
• Showing/hiding menu items
It is possible to save the adapted perspective as a default setting for the
perspective or under a separate name of its own.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 55/667

Operation of KUKA Sunrise.Workbench KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Procedure

To display views in the current perspective:

• Select the menu sequence Window > Show View and the desired
view.
Further views can be selected by clicking the menu item Other….
To reset the current perspective to the default setting:

• Select the menu sequence Window > Reset Perspective… and an-
swer the request for confirmation with Yes.
To save user-defined perspectives:

1. Select the menu sequence Window > Save Perspective As....

2. In the Name box, enter a name for the perspective and confirm it with
OK.
If an existing perspective is selected and overwritten, the perspective will
be opened with these settings in the future.

5.2.4 Toolbar of the Programming perspective

The buttons available as standard on the toolbar depend on the active

perspective. The buttons of the Programming perspective are described
here.
Icon Name/description
New
Opens the wizard for creating new documents.
The arrow can be used to open the menu with the available
wizards.
Save
Saves the currently opened and selected file.
Save All
Saves all files and projects that have been edited since the
last save.
Print
Opens the menu for printing a file.
Synchronize project
Synchronizes the selected project with the robot controller.
Debug project
Establishes a remote connection to the robot controller in
order to debug an application during ongoing operation.
New Sunrise project
Opens the wizard for creating a new Sunrise project.
New Sunrise application
Opens the wizard for creating a new Sunrise application in
the selected project. The wizard contains templates for all
application types and sample applications suitable for the
project.

56/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operation of KUKA Sunrise.Workbench

Icon Name/description
New Java package
Opens the wizard for creating a new Java package in the
selected project.
New Java class
Opens the wizard for creating a new Java class in the se-
lected project.
The arrow can be used to open the menu with the available
Java classes.
Search
Opens the wizard to search for words or text modules.
Last Edit Location
Switches to the last edit location in the currently opened
and selected file.
Back to ...
Switches back to the previous edit steps.
Forward to ...
Switches forward again to the subsequent edit steps.

5.3 Creating a Sunrise project with a template

Procedure

1. Select the menu sequence File > New > Sunrise project. The wizard
for creating a new Sunrise project is opened.
2. Enter the IP address of the robot controller to be created for the Sun-
rise project in the IP address of controller: box.
It is possible to change the address again during subsequent project
configuration.
The following IP address ranges are used by default by the robot
controller for internal purposes. IP addresses from these ranges can-
not therefore be assigned.
‒ 169.254.0.0 … 169.254.255.255
‒ 172.16.0.0 … 172.16.255.255
‒ 172.17.0.0 … 172.17.255.255
‒ 192.168.0.0 … 192.168.0.255

3. Retain the Create new project (offline) setting.

Press Next > to switch to the next page.
4. Enter a name for the Sunrise project in the Project name: box.
5. The default directory for projects is given in the Location: box.
A different directory can be selected: to do so, remove the check mark
at Use default location and select Browse…. Then use the Browse
for Folder dialog to select the desired file path and confirm with OK.
Press Next > to switch to the next page.
6. Select a template from the Topology template list.
The template determines which elements are subsequently
preselected in the station configuration on the Topology tab. Irrespec-
tive of the template that is selected here, all elements are always

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 57/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

available on the Topology tab and the preselection can be modified

Operation of KUKA Sunrise.Workbench

again as required.
Press Next > to switch to the next page.
7. If the selected template contains a robot with a media flange, select
the appropriate media flange.
If the media flange “MF Inside electrical NE” is used, the entry Me-
dia flange Inside electrical must be selected.

The weight and height of the selected media flange are automatical-
ly taken into consideration by the system software.

8. As standard, the mounting orientation of a floor-mounted robot is set.

(A=0°, B=0°, C=0°)
In the case of a ceiling- or wall-mounted robot, enter the direction of
installation relative to the floor-mounted robot:
a. Rotation about the Z axis in ° (A angle): Rotation of angle A
about the Z axis of the robot base coordinate system (-180° ≤ A ≤
180°).
b. Rotation about the Y axis in ° (B angle): Rotation of angle B
about the Y axis (-90° ≤ B ≤ 90°). The rotation about the Y axis is
relative to the rotated coordinate system from step a.
c. Rotation about the X axis in ° (C angle): Rotation of angle C
about the X axis (-180° ≤ C ≤ 180°). The rotation about the X axis
is relative to the rotated coordinate system from step b.
(>>> 6.12 "Coordinate systems" Page 95)
The mounting orientation of the robot must be entered correctly. An
incorrectly entered mounting orientation can have the following ef-
fects:
‒ Unexpected robot behavior under impedance control
‒ Changed position of previously taught frames
‒ Prevention of motion enable due to collision detection and TCP
force monitoring
‒ Unexpected behavior during jogging in the world or base coordi-
nate system

Press Next > to switch to the next page.

9. A summary of information on the Sunrise project is displayed.
Remove the check mark at Create Sunrise application (starts an-
other wizard) and click on Finish. The Sunrise project is created and
added to the Package Explorer view.
If the check mark has been set at Create Sunrise application (starts
another wizard), the wizard for creation of a new Sunrise application
opens. A first Sunrise application can be created directly for the newly-
created Sunrise project.

Description

The figure shows the structure of a newly created Sunrise project, for
which no Sunrise applications have yet been created or other changes
made. The robot configured for the Sunrise project has a media flange.

58/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operation of KUKA Sunrise.Workbench

Fig. 5-2: Overview of the project structure

Element Description
src Source folder of the project
The created Sunrise applications and Java classes are stored
in the source folder.
The Java package com.kuka.generated.ioAccess contains
the Java class MediaFlangeIOGroup.java. The class already
contains the methods required for programming in order to
access the inputs/outputs of the media flange.
(>>> 16.11 "Using inputs/outputs in the program" Page 445)
The source folder also contains various XML files in which, in
addition to the configuration data, the runtime data are saved,
e.g. the frames and tools created by the user.
The XML files can be displayed but not edited.
JRE System Library System library for Java Runtime Environment
The system library contains the Java class libraries which can
be used for standard Java programming.
Referenced libraries Referenced libraries
The referenced libraries can be used in the project. As stand-
ard, the robot-specific Java class libraries are automatically
added when a Sunrise project is created. The user has the
option of adding further libraries.
generatedFiles Folder with subfolder IODescriptions
The data for the inputs/outputs configured for the media
flange are saved in an XML file.
The XML file can be displayed but not edited.
KUKAJavaLib Folder with special libraries required for robot programming

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 59/667

Operation of KUKA Sunrise.Workbench KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Element Description
IOConfiguration.wvs I/O configuration for the media flange
The I/O configuration contains the complete bus structure of
the media flange, including the I/O mapping.
The I/O configuration can be opened, edited and re-exported
into the Sunrise project in WorkVisual.
Note: The I/O configuration is only carried out automatically
for the inputs/outputs on the media flange. Further EtherCAT
devices connected to the media flange must be configured
with WorkVisual.
(>>> 11 "Bus configuration" Page 223)
SafetyConfiguration.sconf Safety configuration
The file contains the safety functions preconfigured by KUKA.
The configuration can be displayed and edited.
(>>> 13 "Safety configuration" Page 251)
StationSetup.cat Station configuration
The file contains the station configuration for the station (con-
troller) selected when the project was created. The configura-
tion can be displayed and edited.
The system software can be installed on the robot controller
via the station configuration.
(>>> 10 "Station configuration and installation" Page 205)

The generatedFiles folder is used by the system and must not be used
for saving files created by the user.

5.4 Sunrise applications

Sunrise applications are Java programs. They define tasks that are to be
executed in a station. They are transferred to the robot controller with the
Sunrise project and can be selected and executed using the smartPAD.
There are 2 kinds of Sunrise applications:
• Robot applications
Only one robot application can be executed on the robot controller at
any given time.
• Background applications
Multiple background applications can run simultaneously and inde-
pendently of the running robot application.
Sunrise applications are grouped into Java packages. This makes pro-
gramming more transparent and makes it easier to use a Java package
later in other projects.

5.4.1 Creating a new Java package

Description

A Java package can be created independently of a Sunrise application.

The created package does not yet contain any files in this case. An empty
package is indicated by a white package icon. As soon as a package con-
tains files, the icon turns brown.

60/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operation of KUKA Sunrise.Workbench

Procedure

1. Select the desired project in the Package Explorer view.

2. Select the menu sequence File > New > Package. The wizard for
creating a new Java package is opened.
3. Enter a name for the package in the Name: box.
4. Click on Finish. The package is created and inserted into the source
folder for the project.

5.4.2 Creating a robot application with a package

Description

A robot application can be created together with the Java package into
which the application is to be inserted.

Procedure

1. Select the desired project in the Package Explorer view.

2. Select the menu sequence File > New > Sunrise application. The
wizard for creating a new Sunrise application is opened.
3. Select the template RoboticsAPI Application and click on Finish.
The wizard for creating a new robot application is opened.
4. In the Package: box, enter the name of the package in which the ap-
plication should be created.
5. Enter a name for the package in the Name: box.
6. Click on Finish. The application and package are created and inserted
into the source folder of the project. The Name.java application is
opened in the editor area.

5.4.3 Creating a robot application for an existing package

Description

If the Java package into which a robotic application is to be inserted al-

ready exists, the application can be created for the existing package.

Procedure

1. In the Package Explorer view, select the desired package in the

project.
2. Select the menu sequence File > New > Sunrise application. The
wizard for creating a new Sunrise application is opened.
3. Select the template RoboticsAPI Application and click on Finish.
The wizard for creating a new robot application is opened.
4. Enter a name for the package in the Name: box.
5. Click on Finish. The application is created and inserted into the pack-
age. The Name.java application is opened in the editor area.

5.4.4 Creating a new background application

Background applications are Java programs that are executed on the ro-
bot controller parallel to the robot application. For example, they can per-
form control tasks for peripheral devices.
The use and programming of background applications are described here:
(>>> 17 "Background tasks" Page 551)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 61/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The following properties are defined when the application is created:

Operation of KUKA Sunrise.Workbench

• Start type:
‒ Automatic
The background application is automatically started after the robot
controller has booted (default).
‒ Manual
The background application must be started manually via the
smartPAD. (This function is not yet supported.)
• Execution type:
‒ Task template Cyclic background task
Template for background applications that are to be executed cycli-
cally (default)
‒ Task template Non-cyclic background task
Template for background applications that are to be executed once

5.4.4.1 Creating a background application with a package

Description

A background application can be created together with the Java package

into which the application is to be inserted.

Procedure

1. Select the desired project in the Package Explorer view.

2. Select the menu sequence File > New > Sunrise application. The
wizard for creating a new Sunrise application is opened.
3. Select the template Background task and click on Finish. The wizard
for creating a new background application is opened.
4. In the Package: box, enter the name of the package in which the ap-
plication should be created.
5. Enter a name for the package in the Name: box.
6. Click on Next > and select the desired start type.
7. Click on Next > and select the desired execution type (task template).
8. Click on Finish. The application and package are created and inserted
into the source folder of the project. The Name.java application is
opened in the editor area.

5.4.4.2 Creating a background application for an existing package

Description

If the Java package into which a background application is to be inserted

already exists, the application can be created for the existing package.

Procedure

1. In the Package Explorer view, select the desired package in the

project.
2. Select the menu sequence File > New > Sunrise application. The
wizard for creating a new Sunrise application is opened.
3. Select the template Background task and click on Finish. The wizard
for creating a new background application is opened.
4. Enter a name for the package in the Name: box.
5. Click on Next > and select the desired start type.

62/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operation of KUKA Sunrise.Workbench

6. Click on Next > and select the desired execution type (task template).
7. Click on Finish. The application is created and inserted into the pack-
age. The Name.java application is opened in the editor area.

5.4.5 Setting the robot application as the default application

Description

A default application can be defined for every Sunrise project; it is auto-

matically selected after a reboot of the robot controller or synchronization
of the project.
In the case of an externally controlled project, it is essential to define a
default application. This is automatically selected when the operating
mode is switched to Automatic.

Procedure

• Right-click on the desired robot application in the Package Explorer

view and select Sunrise > Set as default application from the con-
text menu.
The robot application is indicated as the default application in the
Package Explorer view and automatically set as the default applica-
tion in the project settings.

Example

Fig. 5-3: Default application MainApp.java

5.5 Workspace

The directory in which the created projects and user-defined settings for
KUKA Sunrise.Workbench are saved is called the workspace. The directo-
ry for the workspace must be defined by the user when Sunrise.Work-
bench is started for the first time. It is possible to create additional work-
spaces in KUKA Sunrise.Workbench and to switch between them.

5.5.1 Creating a new workspace

Procedure

1. Select the menu sequence File > Switch Workspace > Other.... The
Workspace Launcher window opens.
2. In the Workspace box, manually enter the path to the new project di-
rectory.
Alternative:
• Click on Browse... to navigate to the directory where the new
workspace should be created.
• Create the new project directory by clicking on Create new folder.
Confirm with OK.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 63/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The path to the new project directory is inserted in the Workspace

Operation of KUKA Sunrise.Workbench

box.
3. Click on OK to confirm the new workspace. Sunrise.Workbench re-
starts and the welcome screen opens.

5.5.2 Switching to an existing workspace

Precondition

• Other workspaces are available.

Procedure

1. Select the menu sequence File > Switch Workspace > Other.... The
Workspace Launcher window opens.
2. Navigate to the desired workspace using Browse… and select it.
3. Confirm with OK. The path to the new project directory is applied in
the Workspace Launcher window.
4. Confirm the selected workspace with OK. Sunrise.Workbench restarts
and opens the selected workspace.

5.5.3 Switching between the most recently opened workspaces

Precondition

• Other workspaces are available.

Procedure

1. Select the menu sequence File > Switch Workspace. The most re-
cently used workspaces are displayed in a list (max. 4).
2. Select the desired workspace from the list. KUKA Sunrise.Workbench
restarts and opens the selected workspace.

5.5.4 Archiving projects

Procedure

1. Select the menu sequence File > Export.... The file export wizard
opens.
2. In the General folder, select the Archive File option and click on Next
>.
3. All the projects in the workspace are displayed in a list in the top left-
hand area of the screen. Select the projects to be archived (set check
mark).
4. Click on Browse… to navigate to the desired file location, enter the
file name for the archive and click on Save.
5. Click on Finish. The archive file is being created.

5.5.5 Loading projects from archive to the workspace

Precondition

• An archive file (e.g. a ZIP file) with the projects to be loaded is availa-
ble.

64/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operation of KUKA Sunrise.Workbench

• The workspace does not contain any project with the name of the
project to be loaded.

Procedure

1. Select the menu sequence File > Import…. The file import wizard
opens.
2. In the General folder, select the Existing Projects into Workspace
option and click on Next >.
3. Activate the Select archive file radio button, click on Browse… to
navigate to the desired archive file and select it.
4. Click on Open. All the projects in the archive are displayed in a list
under Projects.
5. Select projects to be loaded to the workspace.
The following options specify the selection (set the check mark as re-
quired):

• Search for embedded projects

The projects from the archive are searched for embedded projects.
• Copying projects to the workspace
The project is copied into the workspace of Sunrise.Workbench
(and thus duplicated). The original project remains unchanged.
Without this option (no check mark), the project remains in the
original directory and is modified by Sunrise.Workbench.
• Hiding projects already in the workspace
If there are already projects of the same name in the workspace,
these projects are hidden.
6. Click on Finish. The selected projects are loaded.

5.5.6 Loading projects from the directory to the workspace

Precondition

• One or more projects are available in any directory.

• The workspace does not contain any project with the name of the
project to be loaded.

Procedure

1. Select the menu sequence File > Import…. The file import wizard
opens.
2. In the General folder, select the Existing Projects into Workspace
option and click on Next >.
3. Activate the Select root directory radio button, click on Browse… to
navigate to the desired directory and select it.
4. Click on OK. All the projects in the selected directory are displayed in
a list under Projects.
5. Select projects to be loaded to the workspace (check mark must be
set).
6. Click on Finish. The selected projects are loaded.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 65/667

Operation of KUKA Sunrise.Workbench KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

5.6 Sunrise projects with referenced Java projects

One or more Java projects can be referenced within a Sunrise project.

The referencing of Java projects allows them to be used in any number of
Sunrise projects and thus on different robot controllers.
The referenced Java projects can in turn reference further Java projects.
Only one Sunrise project may exist among all the cross-referenced
projects.
When Sunrise projects are synchronized, referenced Java projects are
also transferred onto the robot controller. If a further Sunrise project is
referenced within a Sunrise project, synchronization is aborted with an
error message.

5.6.1 Creating a new Java project

Procedure

1. Select the menu sequence File > New > Project.... The project crea-
tion wizard opens.
2. In the Java folder, select the Java Project option and click on Next >.
3. Enter the name of the Java project in the Project name box.
4. In the JRE area, select the JRE version that corresponds to the JRE
version of the Sunrise project. This is generally JavaSE-1.6.
5. Click on Next > and then on Finish.
6. The first time a Java project is created in the workspace – or if the
user’s preference has not yet been specified in previous Java projects
– a query is displayed asking whether the Java perspective should be
opened.
• Select Yes or No as appropriate.
• If the query should not be displayed when the next Java project is
created in the workspace, activate the Remember my decision
option (set check mark).

In the Java projects, all classes which should be referenced externally

must be stored in a defined Java package. If referenced classes are
created in the standard package, they cannot be found in the Sunrise
project.

5.6.1.1 Inserting robot-specific class libraries in a Java project

Description

If a Java project is used for robot programming, the specific KUKA libra-
ries required for this purpose must be inserted into the project. As stand-
ard, these libraries are not contained in a Java project.
The KUKA libraries must be copied from a compatible Sunrise project.
Ideally, this should be a Sunrise project in which the Java project is refer-
enced or will be referenced. The precondition for compatibility of refer-
enced projects is that the RoboticsAPI versions match.

Precondition

• At least one compatible Sunrise project is available in the workspace.

66/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operation of KUKA Sunrise.Workbench

Procedure

1. Copy the KUKAJavaLib folder of a compatible Sunrise project: Right-

click on the folder in the Package Explorer and select Copy from the
context menu.
2. Insert the KUKAJavaLib folder into the Java project: Right-click on
the desired Java project in the Package Explorer and select Insert
from the context menu.
3. Right-click again on the Java project and select Build Path > Config-
ure Build Path… from the context menu. The Properties for Project
window opens.
4. Select the Libraries tab in the Java Build Path and click on the Add
JARs… button. The JAR Selection window opens.
5. All the projects in the workspace are displayed in a list. Expand the
Java project where the referenced libraries are to be inserted.
6. Expand the KUKAJavaLib folder and select the existing JAR files.
7. Confirm the selection with OK. The JAR files are inserted on the Li-
braries tab of the build path.
8. Close the window by clicking on OK. The referenced libraries are in-
serted into the Java project.

5.6.2 Referencing Java projects

Precondition

• The referenced classes are saved in a defined Java package (not in

the standard package).
• For Java projects which use referenced KUKA libraries: In the refer-
enced projects, the RoboticsAPI versions must match.

Procedure

1. In the Package Explorer, right-click on the project which is to be ref-

erenced for the Java project.
2. Select Build Path > Configure Build Path… from the context menu.
The Properties for Project window opens.
3. Select the Projects tab in the Java Build Path and click on the Add
… button. The Required Project Selection window opens.
4. All the projects in the workspace are displayed in a list. Select the
Java projects to be referenced (set check mark).
5. Confirm your selection with OK. The selected projects are inserted on
the Projects tab of the build path.
6. Close the window by clicking on OK.

5.6.3 Canceling the reference to Java projects

Description

References to inadvertently added projects or projects that are not re-

quired (any longer) can be removed.

Procedure

1. In the Package Explorer, right-click on the project from which refer-

enced projects should be removed.
2. Select Properties from the context menu. The Properties for Project
window opens.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 67/667

Operation of KUKA Sunrise.Workbench KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

3. Select the Projects tab in the Java Build Path.

4. Select the projects that are not required and click on Remove.
5. Close the window by clicking on OK.

5.7 Renaming an element in the Package Explorer

In the Package Explorer view, the names of inserted elements can be

changed, e.g. the names of projects, Java packages and Java files.

5.7.1 Renaming a project or Java package

Procedure

1. Right-click on the desired project or Java package. Select Refactoring

> Rename in the context menu. The Rename Java Project or Re-
name Java Package window opens.
2. In the New name box, enter the desired name. Confirm with OK.

5.7.2 Renaming a Java file

Procedure

1. Right-click on the desired Java file. Select Refactoring > Rename in

the context menu. The Rename Compilation Unit window opens.
2. In the New name box, enter the desired name. Click on Finish.
3. Possible conflicts are indicated before the renaming is completed. Af-
ter acknowledging and checking these, click on Finish once more.

5.8 Removing an element from Package Explorer

In the Package Explorer view, inserted elements can be removed again,

e.g. entire projects or individual Java packages and Java files of a project.

5.8.1 Deleting an element from a project

Description

Elements created for a project can be deleted again. The elements are
permanently deleted from the workspace and cannot be restored.
It is also possible to remove some – but not all – of the default elements
of a project.

Procedure

1. Right-click on the element. Select Delete in the context menu.

2. Answer the request for confirmation with OK. The element is deleted.

5.8.2 Removing a project from Package Explorer

Description

With this procedure, a project is only removed from the Package

Explorer and is retained in the directory for the workspace on the data
storage medium.

68/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

If required, the project can be reloaded from the directory into the work-

Operation of KUKA Sunrise.Workbench

space. The project is then available again in the Package Explorer.
(>>> 5.5.6 "Loading projects from the directory to the workspace"
Page 65)

Procedure

1. Right-click on the desired project. Select Delete in the context menu.

A request for confirmation is displayed, asking if the project is really to
be deleted.
2. The check box next to Delete project content on disk (cannot be
undone) is activated by default. Leave it like this.
3. Confirm the request for confirmation with OK.

5.8.3 Deleting a project from the workspace

Description

With this procedure, a project is removed from the Package Explorer and
permanently deleted from the directory for the workspace on the data stor-
age medium. The project cannot be restored.

Procedure

1. Right-click on the desired project. Select Delete in the context menu.

A request for confirmation is displayed, asking if the project is really to
be deleted.
2. Activate the check box next to Delete project content on disk (can-
not be undone).
3. Confirm the request for confirmation with OK.

5.9 Activating the automatic change recognition

Description

The automatic change recognition is activated as standard in Sun-

rise.Workbench. If it has been deactivated, this could mean, for example,
that the Java classes and files required for use of the signals may not be
created in when exporting an I/O configuration from WorkVisual.

Procedure

1. Select the menu sequence Window > User definitions. The User
definitions window is opened.
2. Select General > Workspace in the directory in the left area of the
window.
3. Activate the check box Update via native hooks or polling to acti-
vate the automatic change recognition.

5.10 Displaying release notes

Description

The release notes contain information about the versions of the system
software, e.g. new functions or system requirements. They can be dis-
played in the editor.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 69/667

Operation of KUKA Sunrise.Workbench KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Procedure

• Select the menu sequence Help > Sunrise.OS Release Notes.

70/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

6 Operating the KUKA smartPAD

6.1 KUKA smartPAD teach pendant

The smartPAD is the hand-held control panel for the industrial robot.
The smartPAD has all the operator control and display functions required
for operation.
2 models exist:
• smartPAD
• smartPAD-2
In this documentation, the designation “KUKA smartPAD” or “smartPAD”
refers to both models unless an explicit distinction is made.

6.1.1 smartPAD

6.1.1.1 Front of smartPAD

The smartPAD has a touch screen: the smartHMI can be operated with a
finger or stylus. An external mouse or external keyboard is not necessary.

Fig. 6-1: Front of smartPAD

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 71/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Item Description
1 Button for disconnecting the smartPAD
(>>> 6.2 "Disconnecting and connecting the smartPAD" Page 77)
2 Mode selector switch. The switch may be one of the following variants:

• With key
It is only possible to change operating mode if the key is inserted.
• Without key
The mode selector switch is used to call the connection manager. The connection
manager is used to change the operating mode.
(>>> 6.9 "Changing the operating mode" Page 92)
3 EMERGENCY STOP device: stops the robot in hazardous situations. The EMERGEN-
CY STOP device locks itself in place when it is pressed.
4 6D mouse: no function
5 Jog keys: for jogging the robot
(>>> 6.15.3 "Axis-specific jogging with the jog keys" Page 102)
(>>> 6.15.4 "Cartesian jogging with the jog keys" Page 103)
6 Key for setting the override
(>>> 6.15.2 "Setting the jog override" Page 101)
(>>> 6.18.3 "Setting the manual override" Page 114)
7 Main menu key: The main menu key shows and hides the main menu on the smartH-
MI.
(>>> 6.5 "Calling the main menu" Page 87)
8 User keys: the function of the user keys is freely programmable. Uses of the user
keys include controlling peripheral devices or triggering application-specific actions.
(>>> 6.10 "Activating the user keys" Page 93)
9 Start key: the Start key is used to start a program. The Start key is also used to man-
ually address frames and to move the robot back onto the path.
(>>> 6.18 "Program execution" Page 111)
10 Start backwards key: no function
11 STOP key: the STOP key is used to stop a program that is running.
12 Keyboard key: no function

The following applies to the jog keys, the user keys and the Start, Start
backwards and STOP keys:
• The current function is displayed next to the key on the smartHMI.
• If there is no display, the key is currently without function.

72/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

6.1.1.2 Rear of smartPAD

Operating the KUKA smartPAD

Fig. 6-2: Rear of smartPAD

Item Description
1 Enabling switches
The enabling switches have 3 positions:

• Not pressed
• Center position
• Fully pressed (panic position)
In operating modes T1, T2 and CRR, the manipulator can only be moved if one of
the enabling switches is held in the central position.
In the Automatic operating mode, the enabling switches have no function.
2 Start key (green): the Start key is used to start a program.
The Start key is also used to manually address frames and to move the robot back
onto the path.
3 Enabling switches
4 USB connection: for FAT32-formatted USB sticks
5 Enabling switches
6 Identification plate

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 73/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

6.1.2 smartPAD-2

6.1.2.1 Front of smartPAD-2

The smartPAD-2 has a capacitive touch screen: the smartHMI can be op-
erated with a finger or capacitive stylus. An external mouse or external
keyboard is not necessary.

Fig. 6-3: Front of smartPAD-2

Item Description
1 2 USB 2.0 interfaces with cover: for NTFS and FAT32-formatted USB sticks
2 Button for disconnecting the smartPAD
(>>> 6.2 "Disconnecting and connecting the smartPAD" Page 77)
3 Mode selector switch. The switch may be one of the following variants:

• With key
It is only possible to change operating mode if the key is inserted.
• Without key
The mode selector switch is used to call the connection manager. The connection
manager is used to change the operating mode.
(>>> 6.9 "Changing the operating mode" Page 92)
4 EMERGENCY STOP device: stops the robot in hazardous situations. The EMERGEN-
CY STOP device locks itself in place when it is pressed.

74/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

Item Description
5 6D mouse: no function
6 Jog keys: for jogging the robot
(>>> 6.15.3 "Axis-specific jogging with the jog keys" Page 102)
(>>> 6.15.4 "Cartesian jogging with the jog keys" Page 103)
7 Hand straps with Velcro fastener: when the hand straps are not in use, they can be
pulled in completely.
8 Key for setting the override
(>>> 6.15.2 "Setting the jog override" Page 101)
(>>> 6.18.3 "Setting the manual override" Page 114)
9 Connecting cable
10 User keys: the function of the user keys is freely programmable. Uses of the user
keys include controlling peripheral devices or triggering application-specific actions.
(>>> 6.10 "Activating the user keys" Page 93)
11 Start key: the Start key is used to start a program. The Start key is also used to man-
ually address frames and to move the robot back onto the path.
(>>> 6.18 "Program execution" Page 111)
12 Start backwards key: no function
13 STOP key: the STOP key is used to stop a program that is running.
14 Keyboard key: no function
15 Main menu key: the main menu key shows and hides the main menu on the smartH-
MI.
(>>> 6.5 "Calling the main menu" Page 87)

The following applies to the jog keys, the user keys and the Start, Start
backwards and STOP keys:
• The current function is displayed next to the key on the smartHMI.
• If there is no display, the key is currently without function.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 75/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

6.1.2.2 Rear of smartPAD-2

Operating the KUKA smartPAD

Fig. 6-4: Rear of smartPAD-2

Item Description
1 Press studs for fastening the (optional) carrying strap
2 Strap, dome
3 Left-hand dome: holding the smartPAD with the right hand
4 Enabling switches
The enabling switches have 3 positions:

• Not pressed
• Center position
• Fully pressed (panic position)
In operating modes T1, T2 and CRR, the manipulator can only be moved if one of
the enabling switches is held in the central position.
In the Automatic operating mode, the enabling switches have no function.
5 Start key (green): the Start key is used to start a program.
The Start key is also used to manually address frames and to move the robot back
onto the path.
6 Enabling switches
7 Hand straps with Velcro fastener: when the hand straps are not in use, they can be
pulled in completely.

76/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

Item Description
8 Cover (connection cable cover)
9 Enabling switches
10 Right-hand dome: holding the smartPAD with the left hand
11 Identification plate

6.2 Disconnecting and connecting the smartPAD

The information is applicable for both the smartPAD and the smartPAD-2.
The “smartPAD” and “smartPAD-2” models are compatible with one an-
other, i.e. if one model has been disconnected, then the other model
can then be plugged in.

6.2.1 Disconnecting the smartPAD

Description

If disconnection of the smartPAD is configured as allowed in the station

configuration of the project that is active on the robot controller, the smart-
PAD can be disconnected while the robot controller is running.
WARNING
Risk of fatal injury due to non-operational EMERGENCY STOP de-
vice
If the smartPAD is disconnected, the system can no longer be switched
off by means of the EMERGENCY STOP device on the smartPAD.
Measures must be taken to prevent operational and non-operational
EMERGENCY STOP devices from being mixed up.
Death, injuries or damage to property may otherwise result.
• If unplugging of the smartPAD is to be allowed, connect at least one
external EMERGENCY STOP device that is accessible at all times
to the robot controller.
• Immediately remove the unplugged smartPAD from the system and
store it out of sight and reach.
• Do not disconnect the smartPAD with the EMERGENCY STOP
pressed, as the EMERGENCY STOP will remain active in this case
until the robot controller is rebooted:
‒ Do not use disconnection of the smartPAD to prevent the EMER-
GENCY STOP device on the smartPAD from being released.
‒ If an EMERGENCY STOP is to be active with the smartPAD dis-
connected, always trigger this EMERGENCY STOP via an exter-
nal EMERGENCY STOP device.

Precondition

• Disconnection of the smartPAD is allowed.

• The EMERGENCY STOP device on the smartPAD has been released.

Procedure

1. Press the disconnect button on the smartPAD.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 77/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 6-5: Disconnecting the smartPAD button

A message and a counter are displayed on the smartHMI. The

counter runs for 25 s. During this time, the smartPAD can be discon-
nected from the robot controller.
If the counter expires without the smartPAD having been
disconnected, this has no effect. The disconnect button can be press-
ed again at any time to display the counter again.
2. Disconnect the smartPAD from the robot controller.

If the smartPAD is disconnected without the counter running, this trig-

gers an EMERGENCY STOP. The EMERGENCY STOP can be can-
celed by reconnecting the smartPAD.

6.2.2 Connecting the smartPAD

Description

A smartPAD can be connected at any time. The connected smartPAD as-

sumes the current operating mode of the robot controller. The smartHMI is
automatically displayed again.
The user connecting a smartPAD to the robot controller must
subsequently check whether the smartPAD is operational once again. The
smartPAD is not operational in the following cases:
• smartHMI is not displayed again.
It may take more than 30 seconds before the smartHMI is displayed
again.
• An error message is displayed in the Safety tile, indicating that there
is a connection error to the smartPAD.

WARNING
Risk of fatal injury due to non-operational EMERGENCY STOP de-
vice
If a non-operational smartPAD remains connected, there is the danger
that the user will attempt to activate a non-operational EMERGENCY
STOP. Death, injuries or damage to property may result.
• Disconnect a non-operational smartPAD and remove it from the sys-
tem immediately.

Procedure

1. Connect the smartPAD to the robot controller.

• The EMERGENCY STOP and enabling switches are operational
again 30 s after connection.

78/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

• The smartHMI is automatically displayed again. (This may take
longer than 30 s.)
• The connected smartPAD assumes the current operating mode of
the robot controller.
2. Check the functions. The following checks must be performed:
• Function test of EMERGENCY STOP
• Function test for the enabling switches
• Check whether the smartHMI is displayed again. (This may take
longer than 30 s.)
3. If the smartPAD is no longer operational, disconnect it and remove it
from the system.

6.3 Update of the smartPAD software

This update mechanism is only applicable for the smartPAD model with
3 enabling switches, not for the smartPAD-2. The update of the smart-
PAD-2 software is described in the smartPAD-2 operating instructions.

Description

The smartPAD software version is checked automatically in the following

cases:
• Reboot of robot controller
• Connection of smartPAD to a running robot controller
If the version check reveals a conflict between the smartPAD software and
the system software on the robot controller, the update of the smartPAD
software is started automatically.
If the smartPAD is connected to the robot controller with the EMER-
GENCY STOP pressed, the running application is paused in AUT mode.
To resume the application:
1. Release EMERGENCY STOP device.
2. Press the Start key.

NOTICE
Material damage due to interruption of the software update
If the software update is interrupted, this may result in damage to the
smartPAD.
• Do not disconnect the smartPAD from the robot controller during the
update.
• Do not disconnect the robot controller from the power supply during
the update.

Procedure

1. No user input may be entered during the smartPAD update.

2. In the case of a successful update, the smartPAD is automatically re-
booted.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 79/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

6.4 KUKA smartHMI user interface

Fig. 6-6: KUKA smartHMI user interface

Item Description
1 Navigation bar: main menu and status display
(>>> 6.4.1 "Navigation bar" Page 81)
2 Display area
Display of the level selected in the navigation bar, here the Sta-
tion level
3 Jogging options button
Displays the current coordinate system for jogging with the jog
keys. Touching the button opens the Jogging options window,
in which the reference coordinate system and further parame-
ters for jogging can be set.
(>>> 6.15.1 "“Jogging options” window" Page 99)

80/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

Item Description
4 Jog keys display
If axis-specific jogging is selected, the axis numbers are dis-
played here (A1, A2, etc.). If Cartesian jogging is selected, the
coordinate system axes are displayed here (X, Y, Z, A, B, C). In
the case of an LBR, the elbow angle (R) for executing a null
space motion is additionally displayed.
(>>> 6.15 "Jogging the robot" Page 99)
5 Override button
Indicates the current override. Touching the button opens the
Override window, in which the override can be set.
(>>> 6.13 "“Override” window" Page 96)
6 Life sign display
A steadily flashing life sign indicates that the smartHMI is ac-
tive.
7 Language selection button
Indicates the currently set language. Touching the button opens
the Language selection menu, in which the language of the
user interface can be changed.
8 User group button
Indicates the currently logged-on user group. Touching the but-
ton opens the Login window, in which the user group can be
changed.
(>>> 6.7.1 "Changing user group" Page 91)
9 User key selection button
Touching the button opens the User key selection window, in
which the currently available user key bars can be selected.
(>>> 6.10 "Activating the user keys" Page 93)
10 Clock button
The clock displays the system time. Touching the button dis-
plays the system time in digital format, together with the current
date.
11 Jogging type button
Displays the currently set mode of the Start key. Touching the
button opens the Jogging type window, in which the mode can
be changed.
(>>> 6.14 "“Jogging type” window" Page 97)
12 Back button
Return to the previous view by touching this button.

6.4.1 Navigation bar

The navigation bar is the main menu of the user interface and is divided
into 4 levels. It is used for navigating between the different levels.
Some of the levels are divided into two parts:
• Lower selection list: opens a list for selecting an application, a robot or
an I/O group, depending on the level.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 81/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

• Upper button: if a selection has been made in the list, this button can
be used to display the selected application, robot or I/O group.
Alternatively, the main menu can be called using the main menu key on
the smartPAD. The main menu contains further menus which cannot be
accessed from the navigation bar.
(>>> 6.5 "Calling the main menu" Page 87)

Overview

Fig. 6-7: KUKA smartHMI navigation bar

Item Description
1 Station level
Displays the controller name and the selected operating mode
(>>> 6.4.4 "Station level" Page 83)
2 Applications level
Displays the selected robot application
(>>> 6.18.1 "Selecting a robot application" Page 111)
All robot and background applications are listed under Applica-
tions.
3 Robot level
Displays the selected robot
(>>> 6.4.5 "Robot level" Page 85)
4 I/O groups level
Displays the selected I/O group
(>>> 6.19.5 "Displaying an I/O group and changing the value of
an output" Page 121)

6.4.2 Status display

The status of the system components is indicated by colored circles on

the smartHMI.
The “collective status” is displayed in the lower part of the navigation bar.
The status of each of the selected components is displayed in the upper
part. For example, it is possible for one application to be executed while
another application is in the error state.

82/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

Status Description
Serious error
The system component cannot be used. The reason for this
may be an operator error or an error in the system compo-
nent.
Warning
There is a warning for the system component. The operability
of the component may be restricted. It is therefore advisable
to remedy the problem.
For applications, the yellow status indicator means that the
application is paused.
Status OK
There are no warnings or faults for the system component.
Status unknown
The status of the system component cannot be determined.

6.4.3 Keypad

There is a keypad on the smartHMI for entering letters and numbers. The
smartHMI detects when the entry of letters or numbers is required and au-
tomatically displays the appropriate keypad.

Fig. 6-8: Example of keypad

SYM must be pressed to activate the secondary characters assigned to

the keys, e.g. the “=” character on the “S” key. The key remains activa-
ted for one keystroke. In other words, it does not need to be held down.

6.4.4 Station level

The Station level provides access to information and functionalities which

affect the entire station.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 83/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 6-9: Station level

Item Description
1 Process data tile
Opens the Process data view.
2 Safety tile
Indicates the safety status of the station and opens the Safety
sublevel. The sublevel contains the following tiles:

• Activation
Opens the Activation view for activating and deactivating
the safety configuration. A precondition for activation/deacti-
vation is the user group “Safety maintenance”.
• State
Opens the State view and displays error messages relating
to the safety controller.
3 Frames tile
Opens the Frames view. The view contains the frames created
for the station.
(>>> 6.17.1 "“Frames” view" Page 105)

84/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

Item Description
4 Robot controller tile
Indicates the status of the robot controller and opens a suble-
vel. The sublevel contains the following tiles:

• Boot state
Indicates the boot status of the robot controller.
• Field buses
Indicates the status of the field buses. The tile is only dis-
played if I/O groups have been created and corresponding
signals have been mapped with WorkVisual.
• Backup Manager
Opens the Backup Manager view. The tile is only displayed
if the Backup Manager has been installed.
(>>> 6.20 "Backup Manager" Page 124)
• Virus scanner
Opens the Virus scanner view. The tile is only displayed if
the virus scanner has been installed.
(>>> 21.4 "Displaying messages of the virus scanner"
Page 619)
5 HMI state tile
Displays the connection status between the smartHMI and the
robot controller.
6 Information tile
Opens the Information view and displays system information,
e.g. the IP address of the robot controller.
(>>> 6.19.6 "Displaying information about the robot and robot
controller" Page 124)
7 Log tile
Opens the Log view and displays the logged events and
changes in state of the system. The display can be filtered
based on various criteria.
(>>> 21.2 "Displaying a log" Page 613)

6.4.5 Robot level

The Robot level gives access to information and functionalities which af-
fect the selected robot.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 85/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 6-10: Robot level

Item Description
1 Axis position tile
Opens the Axis position view. The axis-specific actual position
of the robot is displayed.
(>>> 6.19.2 "Displaying the axis-specific actual position"
Page 119)
2 Cartesian position tile
Opens the Cartesian position view. The Cartesian actual posi-
tion of the robot is displayed.
(>>> 6.19.3 "Displaying the Cartesian actual position"
Page 120)
3 Axis torques tile
Opens the Axis torques view. The axis torques of the robot
are displayed.
(>>> 6.19.4 "Displaying axis-specific torques" Page 121)
4 Mastering tile
Opens the Mastering view. The mastering status of the robot
axes is displayed. The axes can be mastered or unmastered in-
dividually.
(>>> 7.3 "Position mastering" Page 132)

86/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

Item Description
5 Load data tile
Opens the Load data view for automatic load data determina-
tion.
(>>> 7.5 "Determining tool load data" Page 148)
6 Motion enable tile
Displays whether the robot has received the motion enable.
7 Log tile
Opens the Log view and displays the logged events and
changes in state of the system. The display can be filtered
based on various criteria. As standard, the Source(s) filter is al-
ready set on the robot in question.
(>>> 21.2 "Displaying a log" Page 613)
8 Device state tile
Indicates the status of the drive system of the robot.
9 Calibration tile
Opens a sublevel. This contains the following tiles:

• Base calibration
(>>> 7.4.2 "Base calibration: 3-point method " Page 146)
• Tool calibration
(>>> 7.4.1 "Tool calibration" Page 140)

6.5 Calling the main menu

Procedure

• Press the main menu key on the smartPAD. The Main menu view
opens.

Description

Properties of the Main menu view:

• The main menu is displayed in the left-hand column.

The first 4 buttons are identical to the levels in the navigation bar.
• Touching a button that contains an arrow opens the relevant areas for
the level, e.g. Station.
Further navigation options are described in the following table.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 87/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 6-11: Example view of the main menu

Item Description
1 Back button
Touch this button to return to the view which was visible before
the main menu was opened.
2 Home button
Closes all opened areas.
3 Button for closing the level
Closes the lowest opened level.
4 The views most recently opened from the main menu are dis-
played here (maximum 3).
By touching the view in question, it is possible to switch to
these views again without having to navigate the main menu.

88/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

6.6 Setting the user interface language

Description

The user interface on the smartHMI is available in the following languag-

es:
Language Language abbreviation
Chinese (simplified) zh
Danish da
German de
English en
Finnish fi
French fr
Greek el
Italian it
Japanese ja
Korean ko
Dutch nl
Polish pl
Portuguese pt
Romanian ro
Russian ru
Swedish sv
Slovak sk
Slovenian sl
Spanish es
Czech cs
Turkish tr
Hungarian hu

Language selection button

The Language selection button on the side panel of the smartHMI (bot-
tom left) can be used to select a different language. The button is labeled
with the abbreviated name of the active language.

Fig. 6-12: Language selection button

1 Language selection button

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 89/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Procedure

1. Touch the Language selection button. The Language selection

menu is opened.
2. Select the desired language.

6.7 User groups

Description

Different functions can be executed on the robot controller, depending on

the user group.
The following user groups are available as standard:
• Operator
The user group “Operator” is the default user group.
• Safety maintenance technician
The user “Safety maintenance” is responsible for starting up the safety
equipment of the robot. Only he can modify the safety configuration on
the robot controller.
The user group is protected by means of a password.
If the option Sunrise.RolesRights is used, there is a further user group:
• Expert
The user group “Expert” can perform protected functions that can no
longer be performed by the “Operator”.
The user group is protected by means of a password.

User privileges

If the user group “Expert” is installed, the user rights of the operator are
restricted. The user rights are then assigned as follows:
Safety mainte-
Function Operator Expert
nance
Selecting/deselecting an application

Pausing an application

Moving the robot manually

Selecting an operating mode (T1,

T2, CRR, AUT)
Activating/deactivating/resetting the
safety configuration
Changing the value of an output

Teaching frames

Creating a new frame

Robot mastering/unmastering

90/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

6.7.1 Changing user group

Description

When the robot controller is rebooted, the default user group is selected.
The User group button on the side panel of the smartHMI (bottom left)
can be used to switch to a different user group. The button is labeled with
the abbreviated name of the active user group.

Fig. 6-13: User group button

1 User group button

If no actions are carried out on the user interface within 5 minutes, the ro-
bot controller switches to the default user group for safety reasons.

Procedure

Logging on a user group:

1. Touch the User group button. The Login window opens.
2. Select the desired user group.
If a functionality is called for which the currently logged-on user
group has insufficient rights, the Login window opens automatically.
The required user group is then preset in the window.

3. Enter the password and confirm with Login. The Login window closes
and the selected user group is active.
Logging off a user group:
1. Touch the User group button. The Login window opens.
2. Touch the Log off button. The Login window closes and the default
user group is active again.

6.8 CRR mode – controlled robot retraction

Description

CRR is an operating mode to which the system can be switched when the
robot is stopped by the safety controller for one of the following reasons:
• Robot violates an axis-specific or Cartesian monitoring space.
• Orientation of a safety-oriented tool is outside the monitored range.
• Robot violates a force or axis torque monitoring function.
• A position sensor is not mastered or referenced.
• An axis torque sensor is not referenced.
Once the operating mode has been switched to CRR, the robot can be
moved again.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 91/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Use

CRR mode can be used, for example, to retract the robot in the case of a
space or force monitoring violation or to master the robot with a Cartesian
velocity monitoring function active.
If the cause of the stop is no longer present and if no further stop is re-
quested for 4 seconds by one of the specified causes, the operating mode
automatically changes to T1.

Motion velocity

The motion velocity of the set working point in CRR mode corresponds to
the jog velocity in T1 mode:
• Program mode: Reduced programmed velocity, maximum 250 mm/s
• Jog mode: Jog velocity, maximum 250 mm/s
• Manual guidance: No limitation of the velocity, but safety-oriented ve-
locity monitoring functions in accordance with the safety configuration

6.9 Changing the operating mode

Description

It is possible to change the operating mode while an application is running

on the robot controller. The industrial robot then stops with a safety stop 1
and the application is paused. Once the new operating mode has been
set, the application can resume.

Precondition

• If the mode selector switch is the variant with a key: the key is inser-
ted in the switch.

Procedure

1. Turn the mode selector switch on the smartPAD. The connection man-
ager is displayed.
2. Select the operating mode.
(>>> 3.5.2.1 "Mode selection" Page 38)
3. Return the mode selector switch to its original position.
The selected operating mode is now active and is displayed in the
navigation bar of the smartHMI.

92/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

Operating
Use Velocities
mode
T1 Programming, teaching and testing of • Program verification:
programs.
Reduced programmed velocity,
maximum 250 mm/s
• Jog mode:
Jog velocity, maximum 250 mm/s
• Manual guidance:
No limitation of the velocity, but
safety-oriented velocity monitoring
in accordance with the safety con-
figuration
Note: The maximum velocity of
250 mm/s does not apply to a mobile
platform.
T2 Testing of programs • Program verification:
Programmed velocity
• Jog mode: Not possible
AUT Automatic execution of programs • Program operation:
For industrial robots with and without Programmed velocity
higher-level controllers • Jog mode: Not possible
CRR CRR is an operating mode which can • Program verification:
be selected when the industrial robot
Reduced programmed velocity,
is stopped by the safety controller for
maximum 250 mm/s
one of the following reasons:
• Jog mode:
• Industrial robot violates an axis- Jog velocity, maximum 250 mm/s
specific or Cartesian monitoring
• Manual guidance:
space.
No limitation of the velocity, but
• Orientation of a safety-oriented tool
safety-oriented velocity monitoring
is outside the monitored range.
in accordance with the safety con-
• Industrial robot violates a force or figuration
axis torque monitoring function.
• A position sensor is not mastered
or referenced.
• An axis torque sensor is not refer-
enced.
After changing to CRR mode, the in-
dustrial robot may once again be
moved.

6.10 Activating the user keys

Description

The user keys on the smartPAD can be assigned functions. All the user
key functions of a running application are available to the operator. In or-
der to be able to use the desired functions, the operator must activate the
corresponding user key bar.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 93/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Procedure

1. Touch the User key selection button on the left side panel of the
smartHMI.
The User key selection window opens. The user key bars currently
available are displayed.
2. Select the desired user key bar by pressing the corresponding name
button.
The text or image on the smartHMI next to the user keys changes ac-
cording to the bar selected. The user keys now have the correspond-
ing functions.
3. Touch the User key selection button or an area outside the window.
The User key selection window closes.

Example

Fig. 6-14: “User key selection” window

1 User key selection button

2 Currently active user key bar
3 Available user key bars

6.11 Resuming the safety controller

Description

If there are connection or periphery errors, the safety controller is paused

(after one or more occurrences depending on the error). Pausing the safe-
ty controller causes the robot to stop and all safe outputs to be switched
off. The application can resume once the error has been eliminated.

Procedure

1. Select the Safety > State tile at the Station level. The State view
opens.
The cause of the error is displayed in the view. The Resume safety
controller button is not active.
2. Eliminate the error. The Resume safety controller button is now acti-
vated.

94/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

3. Touch the Resume safety controller button. The safety controller is
resumed.

6.12 Coordinate systems

Coordinate systems or frames determine the position and orientation of an

object in space.

Overview

The following coordinate systems are relevant for the robot controller:
• World
• Robot base
• Base
• Flange
• Tool

Description

World coordinate system

The world coordinate system is a permanently defined Cartesian coordi-
nate system. It is the root coordinate system for all other coordinate sys-
tems, in particular for base coordinate systems and the robot base coordi-
nate system.
By default, the world coordinate system is located at the robot base.
Robot base coordinate system
The robot base coordinate system is a Cartesian coordinate system,
which is always located at the robot base. It defines the position of the ro-
bot relative to the world coordinate system.
By default, the robot base coordinate system is identical to the world co-
ordinate system. It is possible to define a rotation of the robot relative to
the world coordinate system by changing the mounting orientation in Sun-
rise.Workbench. By default, the mounting orientation of the floor-mounted
robot is set (A=0°, B=0°, C=0°).
Base coordinate system
In order to define motions in Cartesian space, a reference coordinate sys-
tem (base) must be specified.
As standard, the world coordinate system is used as the base coordinate
system for a motion. Additional base coordinate systems can be defined
relative to the world coordinate system.
(>>> 7.4.2 "Base calibration: 3-point method " Page 146)
Flange coordinate system
The flange coordinate system describes the current position and orienta-
tion of the robot flange center point. It does not have a fixed location and
is moved with the robot.
The flange coordinate system is used as an origin for coordinate systems
which describe tools mounted on the flange.
Tool coordinate system
The tool coordinate system is a Cartesian coordinate system which is lo-
cated at the working point of the mounted tool. This is called the TCP
(Tool Center Point).
Any number of frames can be defined for a tool and can be selected as
the TCP. The origin of the tool coordinate system is generally identical to
the flange coordinate system.
(>>> 9.3.1 "Geometric structure of tools" Page 180)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 95/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The tool coordinate system is offset to the tool center point during calibra-
Operating the KUKA smartPAD

tion.
(>>> 7.4.1 "Tool calibration" Page 140)
Position and orientation
In order to determine the position and orientation of an object, translation
and rotation relative to a reference coordinate system are specified. 6 co-
ordinates are used for this purpose.

Translation

Coordinate Description
Distance X Translation along the X axis of the reference system
Distance Y Translation along the Y axis of the reference system
Distance Z Translation along the Z axis of the reference system

Rotation

Coordinate Description
Angle A Rotation about the Z axis of the reference system
Angle B Rotation about the Y axis of the reference system
Angle C Rotation about the X axis of the reference system

6.13 “Override” window

Procedure

To open the Override window:

• Touch the Override button.

To close the Override window:

• Touch the Override button or an area outside the window.

Description

Fig. 6-15: Override window

96/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

Item Description
1 Override button
The display on the button depends on the selected option.
2 Set the jog velocity.
(>>> 6.15.2 "Setting the jog override" Page 101)
3 Display of application override
If an application override set by the application is programmed,
this is displayed during program execution.
4 Set the manual override.
(>>> 6.18.3 "Setting the manual override" Page 114)
If no application override is active, the manual override that can
be set here corresponds to the effective program override.
5 Display of effective program override
The following buttons are available:
Option Button Description
When the Set jog override option is selected, the Override
button displays the hand icon and the jog override currently
set.
When the Set manual override option is selected, the Over-
ride button displays the program icon and the manual over-
ride currently set.

6.14 “Jogging type” window

Procedure

Open the Jogging type window:

• Touch the Jogging type button next to the Start key.

Close the Jogging type window.

• Touch the Jogging type button or an area outside the window.

Description

The functionality of the Start key can be configured in the Jogging type
window.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 97/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 6-16: “Jogging type” window

Item Description
1 Jogging type button
The display on the button depends on the selected jogging
type.
2 Application mode jogging type
In this jogging mode an application can be started by means of
the Start key.
Note: When switching to T2 or Automatic mode, Application
mode is set automatically.
3 Changing program run mode
(>>> 6.18.2 "Setting the program run mode" Page 113)
4 Frame name display
The name of the frame is displayed if a frame has been selec-
ted in the Frames view.
5 Move PTP jogging type
A taught frame can be addressed with a PTP motion by means
of the Start key.
(>>> 6.17.5 "Manually addressing frames" Page 110)
The button for selecting the jogging type is only active if a
frame has been selected in the Frames view.
Note: In the Move PTP jogging type, the Status of the end
frame is taken into consideration. This can cause the axes to
move, even if the end point has already been reached in Carte-
sian form.

98/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

Item Description
6 Move LIN jogging type
A taught frame can be addressed with a LIN motion by means
of the Start key.
(>>> 6.17.5 "Manually addressing frames" Page 110)
The button for selecting the jogging type is only active if a
frame has been selected in the Frames view.
Note: In the Move LIN jogging type, the Status of the end
frame is not taken into consideration.
7 Open frames view button
Press the button to switch to the Frames view.

Icons

The following icons are displayed on the Jogging type button depending
on the set jogging type:
Icon Description
Application mode jogging type

Move PTP jogging type

Move LIN jogging type

6.15 Jogging the robot

Overview

There are 2 ways of jogging the robot:

• Cartesian jogging
The set TCP is jogged in the positive or negative direction along the
axes of a coordinate system or rotated about these axes.
• Axis-specific jogging
Each axis can be moved individually in the positive or negative direc-
tion.

6.15.1 “Jogging options” window

Procedure

Open the Jogging options window:

• Touch the Jogging options button.

Close the Jogging options window.

• Touch the Jogging options button or an area outside the window.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 99/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Description

All parameters for jogging the robot can be set in the Jog options win-
dow.

Fig. 6-17: “Jogging options” window

Item Description
1 Jogging options button
The icon displayed depends on the programmed jogging type.
2 Select the jogging type.
Axis-specific jogging or Cartesian jogging of the robot in differ-
ent coordinate systems is possible. The selected jogging type is
indicated in green and displayed on the Jogging options but-
ton.

• Axes: The robot is moved by axis-specific jogging.

• World: The selected TCP is moved in the world coordinate
system by means of Cartesian jogging.
• Base: The selected TCP is moved in the selected base co-
ordinate system by means of Cartesian jogging.
• Tool: The selected TCP is moved in its own tool coordinate
system by means of Cartesian jogging.
3 Select the robot flange or mounted tool. Not possible while an
application is being executed.
The frames of the selected tool can be selected as the TCP for
Cartesian jogging. The set load data of the tool are taken into
consideration.
If a robot application is paused, the tool currently being used in
the application is available under the name Application tool.
(>>> "Application tool" Page 101)

100/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

Item Description
4 Select the TCP.
All the frames of the selected tool are available as the TCP.
The TCP set here is retained. This is also the case if a different
TCP is active in a paused application.
Exception: If a robot application is paused and the application
tool is set, the manually set TCP is not retained when the appli-
cation is resumed. The TCP changes according to the TCP cur-
rently used in the application.
(>>> "Application tool" Page 101)
5 Base selection. Only possible when the jogging type Base is
selected.
All frames which were designated in Sunrise.Workbench as a
base are available as a base.

Application tool

The application tool consists of all the frames located below the robot
flange during the runtime. These can be the frames of a tool or work-
piece, for example, that are connected to the robot flange with the attach-
To command. They may also include frames generated in the application
and linked directly or indirectly to the flange during the runtime.
The application tool is then only available in the jogging options when a
robot application is paused, and if a motion command was sent to the ro-
bot controller prior to pausing.
• If the application tool is set in the jogging options, all frames located
hierarchically under the flange coordinate system during the runtime
can be selected as the TCP for jogging. The origin frame of the appli-
cation tool on the robot flange is available under the name Applica-
tionTool(Root) for selection as the TCP for jogging.
• If the application tool is set in the jogging options and the application
resumed, the following occurs: the frame with which the current motion
command is executed in the application is automatically set as the
TCP.

6.15.2 Setting the jog override

Description

The jog override determines the velocity of the robot during jogging. The
velocity actually achieved by the robot with a jog override setting of 100%
depends on various factors, including the robot type. However, the velocity
of the set working point cannot exceed 250 mm/s.

Procedure

1. Touch the Override button. The Override window is opened.

(>>> 6.13 "“Override” window" Page 96)
2. Activate the Set jog override option if it is not already active.
Option Description

Set jog override option activated

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 101/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

3. Set the desired jog override. It can be set using either the plus/minus
keys or by means of the slider.
• Plus/minus keys: The override can be set in steps to the following
values: 100%, 75%, 50%, 30%, 10%, 5%, 3%, 1%, 0%.
• Slider: The override can be adjusted in 1% steps.
4. Touch the Override button or an area outside the window to close the
window.

Alternative procedure

Alternatively, the override can be set using the plus/minus key on the right
of the smartPAD.
The value can be set in the following steps: 100%, 75%, 50%, 30%, 10%,
5%, 3%, 1%.

6.15.3 Axis-specific jogging with the jog keys

Description

Each robot axis can be moved individually in the positive or negative di-
rection using the jog keys.

Fig. 6-18: Axis-specific jogging

The positive direction of rotation of the robot axes can be determined us-
ing the right-hand rule. Imagine the cable bundle which runs inside the ro-
bot from the base to the flange. Mentally close the fingers of your right
hand around the cable bundle at the axis in question. Keep your thumb
extended while doing so. Your thumb is now positioned on the cable bun-
dle so that it points in the same direction as the cable bundle runs inside
the axis on its way to the flange. The other fingers of your right hand
point in the positive direction of rotation of the robot axis.

102/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

Precondition

• Axes is selected as the jogging type in the jogging options.

• The desired jog override is set.
• T1 mode

Procedure

1. Press and hold down the enabling switch.

When motion is enabled, the axis designations next to the jog keys
are highlighted in white.
2. Press the plus or minus jog key of the relevant axis to move the robot
in the positive or negative direction.

6.15.4 Cartesian jogging with the jog keys

Description

The robot can be moved in a Cartesian sense in the world, base or tool
coordinate system using the jog keys.

Precondition

• World, Base or Tool is selected as the jogging type in the jogging op-
tions.
• In the jogging options, the tool and the desired TCP are selected.
• Only in the case of jogging type Base: the desired base is set in the
jogging options.
All frames which were designated in Sunrise.Workbench as a base
are available as a base.
(>>> 9.2.2 "Designating a frame as a base" Page 175)

• The desired jog override is set.

• T1 mode

Procedure

1. Press and hold down the enabling switch.

When motion is enabled, the designations next to the jog keys are
highlighted in white.
• X, Y, Z: jog keys for linear motions along the X, Y or Z axis of the
set coordinate system
• A, B, C: jog keys for rotational motions about the X, Y or Z axis of
the set coordinate system
• R: jog key for null space motion
(>>> 6.15.4.1 "Null space motion" Page 103)
2. Press your chosen plus or minus jog key to move the robot in the
positive or negative direction.

6.15.4.1 Null space motion

Description

A lightweight robot with 7 axes is kinematically redundant. This means

that theoretically, it can move to every point in the work envelope with an
infinite number of axis configurations.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 103/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Due to the kinematic redundancy, a so-called null space motion can be

Operating the KUKA smartPAD

carried out during Cartesian jogging. In the null space motion, the axes
are rotated in such a way that the position and orientation of the set TCP
are retained during the motion.

Fig. 6-19: Null space motion

Properties

• The null space motion is carried out via the “elbow” of the robot arm.
• The position of the elbow is defined by the elbow angle (R).
• In Cartesian jogging with the jog keys, the position of the elbow angle
(R) can be modified.

Areas of application

• The optimal axis configuration can be set for a given position and ori-
entation of the TCP. This is especially useful in a limited working
space.
• When a software limit switch is reached, you can attempt to move the
robot out of the range of the limit switches by changing the elbow an-
gle.

6.16 Manually guiding the robot

Description

The robot can be guided using a hand guiding device.

Examples of hand guiding devices:

• Media flange "Touch"

• Foot switch as an enabling device
It is possible to use manual guidance as standard in all operating modes
except CRR. In the station configuration, however, it is possible to config-
ure manual guidance as not allowed in Automatic mode and/or in the test
modes.

104/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

CAUTION
In manual guidance, incorrectly selected parameters (e.g. incorrect load
data, incorrect tool) or incorrect information (e.g. from defective axis tor-
que sensors) can be interpreted as external forces. This can result in
unpredictable motions of the robot.

CAUTION
If the robot is manually guided, an EMERGENCY STOP device must be
installed. It must always be within reach of the operator.

Precondition

• A hand guiding device with safety-oriented enabling device (enabling

switch) is present and configured.
• Manual guidance is configured as allowed in the set operating mode.
(>>> 10.4.3 "Handguiding Support" Page 209)
• No application is selected or the application has been paused.
An application is paused if it has one of the following states:
‒ Selected
‒ Motion paused
‒ Error

If the enabling signal for manual guidance is issued while the

application is active, this enabling signal results in the application being
paused.

Procedure

1. Press and hold down the enabling switch on the hand guiding device.
2. Guide the TCP to the desired position.
3. Once the position has been reached, release the enabling switch.

6.17 Frame management

6.17.1 “Frames” view

Procedure

To open the view:

• Select Frames at the Station level. The Frames view opens.

Description

The view contains the frames created for the station. Additional frames
can be created and the frames taught here. The position and orientation
of a frame in space and the associated redundancy information are recor-
ded during teaching.
• Taught frames can be addressed manually.
• Taught frames can be used as end points of motions. If an application
is run and the end frame of a motion is addressed, this is selected in
the Frames view.
(>>> 6.19.1 "Displaying the end frame of the motion currently being
executed" Page 118)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 105/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 6-20: Frames view

Item Description
1 Frame path
Path to the frames of the currently displayed hierarchy level:
Goes from World to the direct parent frame (here Box)
2 Frames of the current hierarchy level
A frame can be selected by touching it. The frame selected
here is marked with a hand icon. The hand icon means that
this frame can be used as the base for jogging and can be cali-
brated.
3 Properties of the selected frame

• Name of the frame

• Comment
• Tool used while teaching the frame
• Date and time of the last modification
4 Create frame button
Creates a frame at the currently displayed hierarchy level.
5 Create child frame button
The button can be used to create a child frame for a selected
frame. If no frame is selected, the button is disabled.

106/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

Item Description
6 Set base for jogging button
The button sets the selected frame as the base for jogging in
the jogging options.
(>>> 6.15.1 "“Jogging options” window" Page 99)
The button is only active if the Base jogging type is selected
from the jogging options and the selected frame is marked as
the base in Sunrise.Workbench.
7 Touchup button
A selected frame can be taught. If no frame is selected, the
button is disabled.
8 Display child frames button
The button displays the direct child elements of a frame.
The button is only active if a frame has child elements.
9 Frame coordinates with reference to the parent frame
10 Magnifying glass button
The magnifying glass button is only active if an application is
running and the end frame of a motion is being addressed. Use
the button to switch to this end frame if it is not yet displayed.

6.17.2 Creating a frame

Description

If the desired TCP is moved to the position of a new frame, the frame is
taught directly on creation. In other words, when a frame is created, the
position and orientation of the TCP that is currently selected in the jogging
options are automatically applied as frame coordinates.

Precondition

• The tool with the desired TCP is set in the jogging options.
(>>> 6.15.1 "“Jogging options” window" Page 99)
The application tool is only available in the jogging options if the ro-
bot application is paused. For this reason, use of the application tool
for teaching frames is not recommended.
The tool corresponding to the current application tool (object tem-
plate of the tool) is also available for selection in the jogging op-
tions. Teaching can be carried out with this tool instead of the appli-
cation tool.

• T1 mode

Procedure

Creating a new frame:

1. Move the TCP to the desired position of the new frame.
2. Press the Create frame button. The current TCP coordinates are ap-
plied for the frame.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 107/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

In extreme poses, i.e. if an axis is situated at the edge of, or out-

side, the permissible axis range, no frame can be created. A corre-
sponding error message is displayed. In this case, move the axis
out of the extreme position and address the desired position again.

3. If a child frame is to be created directly for the newly-created frame,

move the TCP to the desired position of the new child frame.
4. Press the Create child frame button. The current TCP coordinates
are applied for the child frame.
Creating a new child frame:
1. Select the frame for which a child frame is to be created.
2. Move the TCP to the desired position of the new child frame.
3. Press the Create child frame button. The current TCP coordinates
are applied for the child frame.
In extreme poses, i.e. if an axis is situated at the edge of, or out-
side, the permissible axis range, no frame can be created. A corre-
sponding error message is displayed. In this case, move the axis
out of the extreme position and address the desired position again.

6.17.3 Reteaching frames

Description

The coordinates of a frame can be modified on the smartHMI. This is

done by moving to the new position of the frame with the desired TCP
and teaching the frame. In the process, the new position and orientation
are applied.
Once the frames have been taught, it is advisable to synchronize the
project immediately in order to update the frame data in the correspond-
ing project in Sunrise.Workbench.

Precondition

• The tool with the desired TCP is set in the jogging options.
(>>> 6.15.1 "“Jogging options” window" Page 99)
The application tool is only available in the jogging options if the ro-
bot application is paused. For this reason, use of the application tool
for teaching frames is not recommended.
The tool corresponding to the current application tool (object tem-
plate of the tool) is also available for selection in the jogging op-
tions. Teaching can be carried out with this tool instead of the appli-
cation tool.

• T1 mode

Procedure

1. Move the TCP to the desired position of the frame.

2. In the Frames view, select the frame whose position is to be taught.
3. Press Touchup to apply the current TCP coordinates to the selected
frame.
4. The coordinates and redundancy information of the taught point are
displayed in the Apply touchup data dialog. Press Apply to save the
new values.

108/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

If a frame is changed, the change affects all applications in which the
frame is used. Modified programs must always be tested first in Manual
Reduced Velocity mode (T1).

Fig. 6-21: Apply touchup data

Item Description
1 Values saved up to now
2 New values
3 Changes between the values saved until now and new values
4 Base for jogging
All coordinate values of the frame which are displayed in the di-
alog refer to the jogging base set in the jogging options. These
values generally differ from the coordinate values of the frame
with respect to its parent frame.
(>>> 6.15.1 "“Jogging options” window" Page 99)
5 Information on the robot and tool used during teaching
These frame properties are adopted by Sunrise.Workbench
when the project is synchronized.
6 Redundancy informationon on the taught point
These frame properties are adopted by Sunrise.Workbench
when the project is synchronized.
7 Cartesian distance between the current and new position of the
frame

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 109/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

6.17.4 Teaching a frame with the hand guiding device

Description

Frames can be taught using a hand guiding device. Here, the TCP is
moved by hand to the desired position.
Manual guidance is supported as standard in all operating modes except
CRR mode. In the station configuration, it is possible to configure manual
guidance as not allowed in Test mode and/or Automatic mode.
CAUTION
In manual guidance, incorrectly selected parameters (e.g. incorrect load
data, incorrect tool) or incorrect information (e.g. from defective torque
sensors) can be interpreted as external forces. This can result in unpre-
dictable motions of the robot.

CAUTION
If the robot is manually guided, an EMERGENCY STOP device must be
installed. It must always be within reach of the operator.

Precondition

• Hand guiding device with safety-oriented enabling device (enabling

switch) is present and configured.
• The tool with the desired TCP is set in the jogging options.
• No robot application is selected or the robot application has one of the
following states:
‒ Selected
‒ Motion paused
‒ Error
• The Frames view is open.
• The frames to be taught have been created.
• Manual guidance is allowed in the set operating mode.

Procedure

1. Press and hold down the enabling switch on the hand guiding device.
2. Guide the TCP to the desired position.
3. Once the position has been reached, release the enabling switch.
4. In the Frames view, select the frame whose position is to be taught.
5. Press Touchup to apply the current TCP coordinates to the selected
frame.
The coordinates and redundancy information of the taught point are
displayed in the Apply touchup data dialog (>>> Fig. 6-21).
6. Press Apply to save the new values.

6.17.5 Manually addressing frames

Description

Taught frames can be manually addressed with a PTP or LIN motion. In a

PTP motion, the frame is approached by the quickest route, whereas in a
LIN motion it is approached on a predictable path.
When a frame is being addressed, a warning message is displayed in the
following cases:

110/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

• The selected tool does not correspond to the tool with which the
frame was taught.
• The selected TCP does not correspond to the TCP with which the
frame was taught.
• The transformation of the TCP frame has been modified.
If the frame can still be reached, it is possible to move to it.

Precondition

• The frame has been taught.

• The frame can be addressed with the selected TCP.
• Operating mode T1

Procedure

1. Select the desired frame in the Frames view.

2. Select the desired jogging type in the Jogging type window.
3. Press and hold down the enabling switch.
4. Press the Start key and hold it down until the frame is reached.

If the selected working point is already at the end position or if the

frame cannot be reached with the current settings, the robot will not ex-
ecute any motion.

6.18 Program execution

6.18.1 Selecting a robot application

Procedure

• Select the desired robot application in the navigation bar under Appli-
cations.
The Applications view opens and the robot application goes into the
Selected state.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 111/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Description

Fig. 6-22: Applications view – robot application selected

Item Description
1 Current status of the robot application
The status is displayed as text and as an icon.
(>>> "Status display" Page 112)
2 Display of robot application
The name of the selected robot application is displayed, here
Motions.
3 Message window
Error messages and user messages programmed in the robot
application are displayed here.

Status display

The robot application can have the following states:

Icon State Description
Selected The application is selected.

Start The application is initialized.

112/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

Icon State Description
Running The application is executed.

Motion paused The application is paused.

If the application is paused using the smart-
PAD, for example by pressing the STOP key,
only motion execution is stopped. Other com-
mands, e.g. switching of outputs, are execu-
ted in the Motion paused state until a syn-
chronous motion command is reached.
Error An error occurred while the application was
running.

Repositioning The robot is repositioned. The application is

paused because the robot has left the path.

Stopping The application is reset to the start of the pro-

gram and goes into the Selected state.

Start key

An icon on the side panel of the smartHMI indicates the function that can
be executed using the Start key.
Icon Description
Start application.
A selected application can be started or a paused appli-
cation can be continued.
Reposition robot.
If the robot has left the path, it must be repositioned in
order to continue the application.

STOP key

An icon on the side panel of the smartHMI indicates the function that can
be executed using the STOP key.
Icon Description
Pause application.
A running application can be paused in Automatic mode.

If a robot application is paused, the robot can be jogged. The tool and
TCP currently used in the paused application are not automatically set
as the tool and TCP for Cartesian jogging.
(>>> 6.15.1 "“Jogging options” window" Page 99)

6.18.2 Setting the program run mode

Precondition

• No robot application is selected or the robot application has one of the

following states:
‒ Selected

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 113/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

‒ Motion paused
‒ Error
• T1 or T2 mode

Procedure

1. Open the Jogging type window.

2. Set the desired program run mode using the button under Debug op-
tions.
• Check box not active: Program execution in standard mode
• Check box active: Program execution in Step mode
(>>> 6.18.2.1 "Program run modes" Page 114)

6.18.2.1 Program run modes

Button Description
Standard mode
The program is executed through to the end without
stopping.
Step mode
The program is executed with a stop after each motion
command. The Start key must be pressed again for each
motion command.

• The end point of an approximated motion is not ap-

proximated but rather addressed with exact position-
ing.
Exception: Approximated motions which were sent to
the robot controller asynchronously before Step mode
was activated and which are waiting there to be exe-
cuted will stop at the approximate positioning point.
For these motions, the approximate positioning arc
will be executed when the program is resumed.
• In a spline motion, the entire spline block is executed
as one motion and then stopped.
• In a MotionBatch, the entire batch is not executed but
rather exact positioning is carried out after each indi-
vidual motion of the batch.

The program run mode can also be set and requested in the source
code of the application. (>>> 16.17 "Changing and requesting the pro-
gram run mode" Page 468)

6.18.3 Setting the manual override

Description

The manual override determines the velocity of the robot during program
execution.
The manual override is specified as a percentage of the programmed ve-
locity. In T1 mode, the maximum velocity is 250 mm/s, irrespective of the
override that is set.

114/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

If no application override set by the application is active, the manual over-

Operating the KUKA smartPAD

ride corresponds to the effective program override with which the robot ac-
tually moves.
If an application override set by the application is active, the effective pro-
gram override is calculated as follows:
Effective program override = manual override · application override

Precondition

• Robot application has been selected.

Procedure

1. Touch the Override button. The Override window is opened.

(>>> 6.13 "“Override” window" Page 96)
2. Activate the Set manual override option if it is not already active.
Option Description

Set manual override option activated

3. Set the desired manual override. It can be set using either the plus/
minus keys or by means of the slider.
• Plus/minus keys: The override can be set in steps to the following
values: 100%, 75%, 50%, 30%, 10%, 5%, 3%, 1%, 0%.
• Slider: The override can be adjusted in 1% steps.
4. Touch the Override button or an area outside the window to close the
window.

Alternative procedure

Alternatively, the override can be set using the plus/minus key on the right
of the smartPAD.
The value can be set in the following steps: 100%, 75%, 50%, 30%, 10%,
5%, 3%, 1%.

6.18.4 Starting a robot application forwards (manually)

Precondition

• Robot application has been selected.

• T1 or T2 mode

Procedure

1. Select the program run mode.

2. Press and hold down the enabling switch.
3. Press Start key and hold it down. The robot application is executed.
To pause a robot application that has been started manually, release the
Start key. If the robot application is paused, it can be reset.

6.18.5 Starting a robot application forwards (automatically)

Precondition

• Robot application has been selected.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 115/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

• Automatic mode
• The project is not controlled externally.

Procedure

• Press the Start key. The robot application is executed.

To pause a robot application that has been started in Automatic mode,
press the STOP key. If the robot application is paused, it can be reset.

6.18.6 Resetting a robot application

Description

In order to restart a paused robot application from the beginning, it must

be reset. On resetting, the robot application is reset to the start of the pro-
gram and goes into the Selected state.
The button for resetting the application is available under Applications in
the navigation bar:
Button Description
Reset button
The button is only active when the robot application is
paused.

Precondition

• Robot application is paused.

Alternative procedure

• Select the Reset button in the navigation bar under Applications.

6.18.7 Repositioning the robot after leaving the path

Description

The following events can cause the robot to leave its planned path:
• Triggering of a non-path-maintaining stop
• Jogging during a paused application
The robot can be repositioned using the Start key. Repositioning means
that the robot is returned to the Cartesian position at which it left the path.
The application can then be resumed from there.
Characteristics of the motion which is used to return to the path:
• A PTP motion is executed.
The path used to return to the path is different than that taken when
leaving the path.
• The robot is moved at 20% of the maximum possible axis velocity and
the effective program override (effective program override = manual
override application override).
The currently set jog override is irrelevant for repositioning.

• The robot is moved with the load data which were set when the appli-
cation was interrupted.

116/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

• The robot is moved with the controller mode which was set when the
application was interrupted.
Additional forces or force oscillations overlaid by an impedance con-
troller are withdrawn during repositioning.

NOTICE
Repositioning a robot under impedance control may result in
unexpected robot motions. The robot is always repositioned to the com-
mand position; this means that, in the case of a robot under impedance
control, the actual position after repositioning does not necessarily corre-
spond to the actual position at which it left the path. This can lead to
unexpectedly high forces in contact situations.
This behavior can be avoided by moving the impedance-controlled robot
manually, prior to repositioning, to a position as close as possible to the
position at which it left the path.

NOTICE
Repositioning may only be carried out if there is no risk of a collision
while it is returning to the path. If this is not assured, first move the ro-
bot into a suitable position from which it can be safely repositioned.

Procedure

1. In “T1” or “T2” mode: press and hold down the enabling switch.
2. Press Start key and hold it down. The robot returns to the path.

6.18.8 Starting/stopping a background application manually

Background applications can be manually stopped and restarted via the

smartPAD at any time without the need to press an enabling switch.
CAUTION
Background applications can be used to control and monitor peripheral
devices, e.g. grippers. Background applications also switch outputs if no
robot application is currently being executed or if the robot application is
paused due to an EMERGENCY STOP or missing enabling signal. This
can result in a gripper closing or opening, even though the EMERGEN-
CY STOP device has been actuated.
If work is being carried out on an operational robot or there are persons
in the danger zone, additional safety measures must be taken.

6.18.8.1 Stopping a background application manually

Precondition

• Background application is running.

Procedure

• In the navigation bar under Applications touch the button with the
background application to be stopped.

Buttons

The button of a stoppable background application shows the Stop icon.

The status indicator is green.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 117/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Icon Status Description

Background application is running.

6.18.8.2 Starting a background application manually

Precondition

• Background application has been stopped or has finished.

Procedure

• In the navigation bar under Applications touch the button with the
background application to be started.

Buttons

The button of a startable background application shows the Start icon.

The status indicator can be gray or red.
Icon Status Description
Background application has been stopped
or has finished.
Background has terminated with an error.

6.19 Display functions

6.19.1 Displaying the end frame of the motion currently being executed

Description

If a frame from the frame tree is addressed in an application, this is indi-

cated in the Frames view. If the end frame of the motion currently being
executed is located at the displayed hierarchy level, the frame name is
marked with an arrow icon (3 arrowheads):

Fig. 6-23: The arrow icon marks the current end frame

If the end frame is located hierarchically below a displayed frame, the Dis-
play child frames button is marked with an additional arrow icon (3 ar-
rowheads):

Fig. 6-24: The button switches to the current end frame

You can switch directly to the current end frame using the magnifying
glass button in the upper right-hand area of the Frames view:

118/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

Fig. 6-25: The magnifying glass button switches directly to the cur-
rent end frame

The magnifying glass button is inactive if no frame is being addressed.

Precondition

• Robot application has been selected.

• Application status Running or Motion paused
• The motion uses an end frame created in the application data.

Procedure

1. Select Frames at the Station level. The Frames view opens.

2. Switch to the end frame using the Display child frames button or the
magnifying glass button.

6.19.2 Displaying the axis-specific actual position

Procedure

• Select the Axis position tile at the Robot level.

Description

The current position of axes A1 to A7 is displayed. In addition, the range

within which each axis can be moved (limitation by end stops) is indicated
by a white bar.
The actual position can also be displayed while the robot is moving.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 119/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 6-26: Axis-specific actual position

6.19.3 Displaying the Cartesian actual position

Procedure

1. Select the Cartesian position tile at the Robot level.

2. Set the TCP and base in the Jogging options window.

Description

The Cartesian actual position of the selected TCP is displayed. The val-
ues refer to the base set in the jogging options.
The display contains the following data:
• Current position (X, Y, Z)
• Current orientation (A, B, C)
• Current redundancy information: Status, Turn, redundancy angle (E1)
• Current tool, TCP and base
The actual position can also be displayed while the robot is moving.

Fig. 6-27: Cartesian actual position

120/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

6.19.4 Displaying axis-specific torques

Procedure

• Select the Axis torques tile at the Robot level.

Description

The current torque values for axes A1 to A7 are displayed. In addition,

the sensor measuring range for each axis is displayed (white bar).
If the maximum permissible torque on a joint is exceeded, the dark gray
area of the bar for the axis in question turns orange. Only the violated
area is indicated in color (either the negative or positive part).
The refresh rate of the displayed values is limited. Briefly occurring peak
values are therefore not displayed under certain circumstances.

The display contains the following data:

• Current absolute torques
• Current external torques
The external torques are only displayed correctly if the correct tool
has been specified.

• Current tool
The axis-specific torques can also be displayed while the robot is moving.

Fig. 6-28: Axis-specific torques

6.19.5 Displaying an I/O group and changing the value of an output

Precondition

To change an output:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 121/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

• Operating mode T1, T2 or CRR

• If Disable I/O access in EMERGENCY STOP is configured, no safety
stop, e.g. EMERGENCY STOP, may be active.
(>>> 10.4.5 "I/O handling: Disable I/O access in EMERGENCY STOP"
Page 210)

Procedure

1. In the navigation bar, select the desired I/O group from I/O groups.
The inputs/outputs of the selected group are displayed.
2. Select the output to be changed.
3. An input box is displayed for numeric outputs. Enter the desired value.
4. Press and hold down the enabling switch. Change the value of the in-
put with the appropriate button.

Description

Fig. 6-29: Inputs/outputs of an I/O group

122/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

Item Description
1 Name of the input/output
2 Type of input/output
3 Value of the input/output
The value is displayed as a decimal number.
4 Buttons for changing the selected output
The buttons available depend on the output type. (>>> "But-
tons" Page 123)
If the selected output cannot be set, the buttons are grayed out.
For example, if Disable I/O access in EMERGENCY STOP is
configured and a safety stop is active.
5 Signal properties
The properties and the current value of the selected input or
output are displayed.
6 Signal direction
The icons indicate whether the signal is an input or an output.

Buttons

The following buttons are available, depending on the type of output se-
lected:
Button Description
Sets the Boolean output to the value True (1).

Sets the Boolean output to the value False (0).

Set Sets the numeric output to the value entered.

Signal direction

The following icons indicate the direction of a signal:

Icon Description
Icon for an output

Icon for an input

I/O types

The following icons indicate the type of input/output:

Icon Description
Icon for an analog signal

Icon for a binary signal

Icon for a signed digital signal

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 123/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Icon Description
Icon for an unsigned digital signal

6.19.6 Displaying information about the robot and robot controller

Procedure

• Select the Information tile at the Station level.

Description

The information is required, for example, when requesting help from KU-
KA Customer Support.
The following information is displayed under the individual nodes:
Node Description
Station Station information

• Software version: Version of the installed

System Software
• Station server IP: IP address of the robot
controller
• Serial number of controller: Serial num-
ber of the robot controller
User interface Information about the smartHMI

• Connection IP
• Connection state
<Robot name>/Type Robot information
plate
• Serial number: Serial number of the con-
nected robot
• Connected robot: Type of the connected
robot
• Installed robot: Robot type specified in the
station configuration of Sunrise.Workbench
• Operating time [h]
The operating hours meter is running as
long as the drives are switched on.

6.20 Backup Manager

Overview

Once the Backup Manager has been installed on the robot controller, a
tile for the Backup Manager is available on the smartHMI.
The Backup Manager makes it possible to back up and restore robot con-
troller data manually. Automatic backup of data at a predefined interval
can also be preconfigured in the station configuration.
The following data are backed up and restored:
• Project data
• Catalogs of the installed software
• User-specific files (directory: C:\KRC\UserData)

124/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The target directory for backups and the source directory for restorations

Operating the KUKA smartPAD

is preconfigured:
• Directory D:\ProjectBackup on the robot controller
• OR: Shared network directory

If the target directory for backups is on a network drive, it is advisable

to perform a connection test during start-up.
Test by carrying out a manual backup. If this fails, e.g. because the tar-
get directory in the network is not accessible due to a defective configu-
ration, this is indicated in an error message.

User privileges

As standard, no special authorization is required for backing up and re-

storing data. If the user group “Expert” is installed, the default user may
no longer execute these functions. The user must be logged on as “Ex-
pert” or higher.
Safety mainte-
Function Operator Expert
nance
Backing up data manually

Restoring data manually

6.20.1 “Backup Manager” view

Precondition

• Backup Manager is installed.

Procedure

To open the view:

• Select the robot controller tile at the Station level and then the Back-
up Manager tile.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 125/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Description

Fig. 6-30: Backup Manager view

Item Description
1 Status indicator of the backup

• Deactivated: automatic backup is not configured

• Ready: automatic backup is activated
• Running: a backup is in progress (started manually or auto-
matically)
2 Information about the next automatic backup (if activated)

• Date and time

• Target directory

126/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

Item Description
3 “Manual backup/restoration” area
When the view is opened for the first time, only this area and
the status indicator are displayed. This is the default view.
The area contains the following buttons:

• Backup now
(>>> 6.20.2 "Backing up data manually" Page 128)
• Restore
The button cannot be activated until the backup copy that is
to be restored has been selected using the magnifying glass
button.
(>>> 6.20.3 "Restoring data manually" Page 128)
• Configure source path
Displays the “Configure source path” area. After this the but-
ton is inactive.
• Cancel
Hides the “Configure source path” area again. The button is
inactive in the default view.
4 Information about the most recent successful backup

• Date and time

• Target directory
5 “Configure source path” area
The source directory from which restoration is to be carried out
can be defined here. As standard, the source directory defined
in the station configuration is preset.
The following source directories are available for selection:

• Local from D:\ProjectBackup: the source directory is the

directory D:\ProjectBackup on the robot controller
• Network: the source directory is located on a network drive
The network path to the source directory can be configured.
(>>> 6.20.4 "Configuring the network path for restoration"
Page 128)
6 Information about the backup copy selected for restoration

• Project name
• Date and time of the backup
7 Magnifying glass button
Opens a dialog in which the backup copy to be restored can be
selected. The dialog displays all backup copies contained in the
configured source directory.
8 Load data set button
Opens a dialog which can be used to select and apply ready-
made restoration configurations.
The button is only active if the file for restoration configurations
is configured in the station configuration and the file is saved
under the configured path on the robot controller.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 127/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

6.20.2 Backing up data manually

Description

The backup copies are saved in the target directory in the following folder
structure:
• IP address_Project name\BACKUP_No.

Element Description
IP address IP address of the robot controller
Project Name of the project installed on the robot controller
name
No. Number of the backup copy
The BACKUP folder with the highest number always con-
tains the most recent backup copy.

Precondition

• No data backup is in progress.

Procedure

• Touch the Backup now button in the Backup Manager view. The
backup is carried out.

6.20.3 Restoring data manually

Precondition

• No application is selected.
• Robot is not being jogged or manually guided.
• No data backup is in progress.

Procedure

1. Touch the Configure source path button in the Backup Manager

view.
2. If not already preset, select the source from which restoration is to be
carried out. If required, configure the desired network path for restora-
tion.
(>>> 6.20.4 "Configuring the network path for restoration" Page 128)
3. Touch the magnifying glass button. A dialog is opened. The backup
copies available in the specified source directory are listed.
4. Select the desired backup copy and touch the Select button. The dia-
log is closed and information about the selected backup copy is dis-
played.
5. Touch the Restore button. Restoration commences.
A progress bar indicates how far the process is. Following an automat-
ic reboot of the robot controller, restoration is completed.

6.20.4 Configuring the network path for restoration

Description

The network parameters can be entered manually or loaded from a pre-

configured data set:

128/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Operating the KUKA smartPAD

Parameter Description
Network path Network path to source directory, e.g. \\192.168.40.171\Backup\Re-
store
Server user name User name for the network path
The parameter is only relevant if authentication is required for network
access.
Server password Password for the network path
The parameter is only relevant if authentication is required for network
access.
IP address IP address of the robot controller to be restored
Subnet Mask Subnet mask in which the IP address of the robot controller is located

The IP addresses of the robot controller and the server must be located
in the same range. IP address and subnet mask of the robot controller
to be restored must be selected accordingly.

Precondition

For loading from a data set:

• The file for restoration configurations is configured in the station con-

figuration.
• The file is saved under the configured path on the robot controller.

Procedure

1. Touch the Configure source path button in the Backup Manager

view.
2. Select Network as the source if this is not already preset.
3. Enter network parameters or load them from a data set.
To load a data set, proceed as follows:
a. Touch the Load data set button. The Available restoration con-
figurations dialog opens. All available configurations are listed.
Every entry contains the name of the robot controller that is to be
restored. The network path is indicated below this.
b. The selection can be reduced by filtering the entries by the name
of the robot controller. To do so, enter the name or part of the
name in the dialog. e.g. *Controller.
c. Select the desired entry and touch the Import button.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 129/667

Operating the KUKA smartPAD KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

130/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Start-up and recommissioning

7 Start-up and recommissioning
The robot controller is supplied with an operational version of the System
Software. Therefore, no installation is required during initial start-up.
Installation becomes necessary, for example, if the station configuration
changes.
(>>> 10 "Station configuration and installation" Page 205)

7.1 Switching the robot controller on/off

NOTICE
If an application is still running when the robot controller is switched off,
active motions are stopped. This can result in the robot being damaged.
For this reason, the robot controller must only be switched off when no
more applications are running and the robot is stationary.

7.1.1 Switching on the robot controller

Description

When the robot controller is switched on, the system software starts auto-
matically.
The robot controller is ready for operation when the status indicator for
the boot state of the robot controller lights up green:
• Boot state tile at the Station level under the robot controller tile.

Procedure

• Turn the main switch on the robot controller to the “I” position.

7.1.2 Switching the robot controller off

Precondition

• No application is running on the robot controller.

• The robot is at a standstill.

Procedure

• Turn the main switch on the robot controller to the “0” position.

7.2 Performing a PDS firmware update

Description

If the robot controller is rebooted or the drive bus connection restored, the
system checks for every connected PDS whether the current PDS firm-
ware version matches the firmware version on the robot controller. If the
firmware version of at least one of the PDSs is older than the version on
the robot controller, a PDS firmware update must be performed.
The following error message is displayed under the Device state tile:
Firmware update is required. Select "Diagnosis" > "PDS firmware update"
in the main menu in order to update the firmware.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 131/667

Start-up and recommissioning KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Procedure

• In the main menu, select Diagnosis > PDS firmware update.

The update is started and a blocking dialog is displayed. No user input
may be entered during the smartPAD update.
NOTICE
The update may take up to 5 hours and must not be interrupted:
• Do not disconnect the robot from the robot controller during the up-
date.
• Do not disconnect the robot controller from the power supply during
the update.
If the update is interrupted, it is possible that the robot controller may
enter the error state with the result that the robot can no longer be
moved. This fault can only be rectified by KUKA Service.

Once the update has been successfully completed, the dialog is closed.

7.3 Position mastering

Description

During position mastering, a defined mechanical robot axis position is as-

signed to a motor angle. Only with a mastered robot is it possible for
taught positions to be addressed with high repeatability. An unmastered
robot can only be moved manually with axis-specific jogging in T1 or CRR
mode.

Procedure

An LBR has a Hall effect mastering sensor in every axis. The mastering
position of the axis (zero position) is located in the center of a defined
series of magnets. It is automatically detected by the mastering sensor
when it passes over the series of magnets during a rotation of the axis.
1. Before the actual mastering takes place, an automatic search run is
performed in order to find a defined premastering position.
2. If the search run is successful, the axis is moved into the premaster-
ing position.
3. Starting from the premastering position, the axis is moved in such a
way that the mastering sensor passes over the series of magnets. The
motor position at the moment when the mastering position of the axis
is detected is saved as the zero position of the motor.
If the search run or the mastering fails, the process is aborted and the ro-
bot stops.

Overview

During mastering, the mastering position is addressed automatically. It is

possible to perform mastering with various tools provided that a tool offset
has been taught once for these tools.

132/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Start-up and recommissioning

Step Description
1 Mastering without tool
Mastering is performed without a tool, workpiece or supple-
mentary load mounted.
2 Mastering with tool: Teach offset
An offset can be taught for each tool. The difference from
the mastering without a tool is saved on the robot. The
taught offset is retained if mastering is lost and the robot
controller can calculate the mastering of the robot.
3 Mastering with tool
If the offset for a tool has been taught, mastering can be
performed in the case of a loss of mastering without the
need to remove the tool.
4 Check mastering
The current mastering can be checked.
Area of application:

• Remastering without tool

• Remastering with tool
• Reteaching tool offset
An axis can be remastered or a new offset can be taught
without the need to unmaster the axis.

Following remastering, the position of an axis is not referenced. This

event does not lead to a violation of the safe position-based safety func-
tions. The robot can be moved, but the safety integrity of the safety
functions is no longer assured.
If safe position-based safety functions are used, position referencing
must thus be carried out for every remastered axis. Otherwise, the safe-
ty functions may behave differently from how they were configured, cre-
ating additional hazards in the system.

7.3.1 Performing mastering without a tool

Description

The LBR is delivered in the mastered state. For this reason, no mastering
without tool is required during initial start-up.
Following an update of the system software on a robot controller that
was previously operated with a Sunrise.OS version <= 1.15, mastering
must be performed again without a tool. Otherwise, mastering with a
tool is not possible.

Precondition

• There is no tool, workpiece or supplementary load mounted on the ro-

bot.
• Axes are unmastered.
• Operating mode T1 or CRR

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 133/667

Start-up and recommissioning KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The repeatability and reproducibility of mastering are only guaranteed if

the procedure is always identical. The following rules must be observed
during mastering:
• When one axis is being mastered, all axes should be in the vertical
stretch position. If this is not possible, mastering must always be
carried out in the same axis position.
• Always master the individual axes in the same order.

The mastering velocity is independent of the set jog override.

Procedure

1. Select the Mastering tile at the Robot level. The Mastering view
opens.
2. Select No tool in the tool selection.
3. Press and hold down the enabling switch.
4. Press the Master button for the unmastered axis.
First of all, the premastering position is located by means of a search
run. The mastering run is then performed. Once mastering has been
carried out successfully, the axis moves to the calculated mastering
position (zero position).
5. Repeat steps 3 and 4 to master further axes.

7.3.2 Mastering with tool: Teach offset

Description

If a tool is mounted on the robot, the mastering position shifts. This tool
offset can be taught for every tool. The difference from the mastering with-
out a tool is saved on the robot.
As soon as the tool offset has been taught for all axes, the tool can be
used for mastering without the need to remove the tool.
In the case of tools that pick up heavy workpieces, the offset should be
taught not for the tool alone, but also for the tool with the workpiece
picked up. A corresponding tool must be created for this in Sun-
rise.Workbench as an object template.

The tool offsets are stored directly on the robot. The available memory
is sufficient for up to 128 different tools. If additional tool offsets are to
be taught, tool offsets that are no longer required must be deleted first.
This is done by removing the corresponding tool from the object tem-
plate in Sunrise.Workbench.

134/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Start-up and recommissioning

Fig. 7-1: Teach tool offset

1 Message window 3 Axes with taught offset

2 Tool selection 4 Axes without taught offset

Precondition

• All axes are mastered.

If an axis is unmastered and the tool offset has not yet been taught
for all axes, the Teach tool offset button is no longer available for
these axes.

• The tool is mounted on the robot.

• The tool has been created in the object templates in Sunrise.Work-
bench and transferred to the robot controller by means of synchroniza-
tion.
• Operating mode T1 or CRR

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 135/667

Start-up and recommissioning KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The repeatability and reproducibility of mastering are only guaranteed if

the procedure is always identical. The following rules must be observed
during mastering with tool:
• For teaching the tool offset, all axes should first be moved to the
cannon position in order to enable optimal determination of the load-
dependent tool offset.
• Mastering with tool must always be carried out in the same axis po-
sition as the teaching of the tool offset.
• Always master the individual axes in the same order.

The mastering velocity is independent of the set jog override.

Procedure

1. Select the Mastering tile at the Robot level. The Mastering view
opens.
2. Select the tool that is mounted on the robot.
NOTICE
Always perform mastering with the tool that is mounted on the robot.
If a tool is selected that does not correspond to the mounted tool,
the robot may move in an unexpected manner. This may result in
damage to components, the tool or the robot.

3. Press and hold down the enabling switch.

4. Press the Teach tool offset button for the mastered axis.
First of all, the premastering position is located by means of a search
run. The mastering run is then performed. Once mastering has been
carried out successfully, the robot controller calculates the tool offset
and moves the axis to the mastering position (zero position).
5. Repeat steps 3 and 4 to teach further offsets.

7.3.3 Performing mastering with a tool

Description

If the offset for a tool has been taught, mastering can be performed in the
case of a loss of mastering without the need to remove the tool.

Precondition

• The tool is mounted on the robot.

• The offset for the tool has been taught.
• Axes are unmastered.
• Operating mode T1 or CRR

The repeatability and reproducibility of mastering are only guaranteed if

the procedure is always identical. The following rules must be observed
during mastering with tool:
• Mastering with tool must always be carried out in the same axis po-
sition as the teaching of the tool offset. The recommended axis po-
sition for this is the cannon position.
• Always master the individual axes in the same order.

The mastering velocity is independent of the set jog override.

136/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Start-up and recommissioning

Procedure

1. Select the Mastering tile at the Robot level. The Mastering view
opens.
2. Select the tool that is mounted on the robot.
NOTICE
Always perform mastering with the tool that is mounted on the robot.
If a tool is selected that does not correspond to the mounted tool,
the robot may move in an unexpected manner. This may result in
damage to components, the tool or the robot.

3. Press and hold down the enabling switch.

4. Press the Master button for the unmastered axis.
First of all, the premastering position is located by means of a search
run. The mastering run is then performed. Once mastering has been
carried out successfully, the axis moves to the calculated mastering
position (zero position).
5. Repeat steps 3 and 4 to master further axes.

7.3.4 Checking mastering

Description

When checking a mastered axis, a mastering run is performed and the dif-
ference from the currently saved mastering is displayed on the smartHMI.
If mastering with a tool has been checked, the difference from the current-
ly saved tool offset is also displayed.
The differences found can be used to assess whether the saved master-
ing position or the taught tool offset must be updated or whether both val-
ues can be retained (Cancel).
NOTICE
In the case of an update of the mastering data of the robot, frames that
have already been taught are no longer addressed correctly. Frames
that have already been taught must therefore be taught again following
an update. Failure to observe this precaution may result in damage to
property.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 137/667

Start-up and recommissioning KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 7-2: Update mastering data

Item Description
1 Display of the mastering data of the robot
2 Display of the tool offset data
The offset data are only displayed if mastering with tool has
been checked.
3 Tool offset button
The button is only displayed if mastering with tool has been
checked.
4 Previously saved values for the robot mastering or tool offset
5 Newly determined values for the robot mastering or tool offset
6 Difference between the previously saved and newly determined
values for robot mastering or tool offset

Precondition

• For checking mastering with tool: a tool for which Teach tool offset
has been carried out is mounted on the robot.
• Axes are mastered.
• Operating mode T1 or CRR

The repeatability and reproducibility of mastering are only guaranteed if

the procedure is always identical. The following rules must be observed
during mastering:
• Mastering must always be carried out in the same axis position. The
vertical stretch position is recommended for mastering without a tool,
the cannon position for mastering with a tool.
• Always master the individual axes in the same order.

The mastering velocity is independent of the set jog override.

138/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Start-up and recommissioning

Procedure

1. Select the Mastering tile at the Robot level. The Mastering view
opens.
2. In the tool selection, select No tool if checking mastering without a
tool, or select the tool that is mounted on the robot.
NOTICE
Always perform mastering with the tool that is mounted on the robot.
If a tool is selected that does not correspond to the mounted tool,
the robot may move in an unexpected manner. This may result in
damage to components, the tool or the robot.

3. Press and hold down the enabling switch.

4. Press the Check button for the mastered axis.
First of all, the premastering position is located by means of a search
run. The mastering run is then performed. The calculated difference
from the currently saved mastering is displayed in the Update master-
ing data dialog.
5. Check the mastering data and perform the desired action:
• Only possible if mastering with tool has been checked: Press Tool
offset to save the new offset data.
• Press Robot mastering to save the new mastering data.
• Press Cancel to retain the currently saved values for the master-
ing and tool offset.
6. A dialog indicates that the checked axis is being moved to the master-
ing position (zero position) in order to complete the mastering. Confirm
with OK.
7. Press and hold down an enabling switch until the motion has been
completed.
8. Repeat steps 3 to 7 to check further axes.

7.3.5 Manually unmastering axes

Description

The saved mastering position of an axis can be deleted. This unmasters

the axis. No motion is executed during unmastering.

Precondition

• Operating mode T1

Procedure

1. Select the Mastering tile at the Robot level. The Mastering view
opens.
2. Press the Unmaster button for the mastered axis. The axis is unmas-
tered.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 139/667

Start-up and recommissioning KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

7.4 Calibration

7.4.1 Tool calibration

Description

During tool calibration, the user assigns a Cartesian coordinate system

(tool coordinate system) to a tool mounted on the mounting flange.
The tool coordinate system has its origin at a point defined by the user.
This is called the TCP (Tool Center Point). The TCP is generally situated
at the working point of the tool. A tool can have multiple TCPs.
Advantages of tool calibration:

• The tool can be moved in a straight line in the tool direction.

• The tool can be rotated about the TCP without changing the position
of the TCP.
• In program mode: The programmed velocity is maintained at the TCP
along the path.

Fig. 7-3: TCP calibration principle

Overview

Tool calibration consists of the following steps:

140/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Start-up and recommissioning

Step Description
1 Define the origin of the tool coordinate system
The following methods are available:

• XYZ 4-point
(>>> 7.4.1.1 "TCP calibration: XYZ 4-point method"
Page 141)
2 Define the orientation of the tool coordinate system
The following methods are available:

• ABC 2-point
(>>> 7.4.1.2 "Defining the orientation: ABC 2-point
method" Page 143)
This method is not available for safety-oriented tools.
• ABC world
(>>> 7.4.1.3 "Defining the orientation: ABC world meth-
od" Page 145)

Once calibration has been completed, it is advisable to synchronize the

project immediately in order to update the calibration data in the corre-
sponding project in Sunrise.Workbench.

7.4.1.1 TCP calibration: XYZ 4-point method

Description

The TCP of the tool to be calibrated is moved to a reference point from 4

different directions. The reference point can be freely selected. The robot
controller calculates the TCP from the different flange positions.
The 4 flange positions with which the reference point is addressed must
maintain a certain minimum distance between one another. If the points
are too close to one another, the position data cannot be saved. A corre-
sponding error message is generated.
The quality of the calibration can be assessed by means of the transla-
tional calculation error which is determined during calibration. If this error
exceeds a defined limit value, it is advisable to calibrate the TCP once
more.
The minimum distance and the maximum calculation error can be
modified in Sunrise.Workbench. (>>> 10.4.7 "Configuration parameters for
calibration" Page 211)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 141/667

Start-up and recommissioning KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 7-4: XYZ 4-point method

Precondition

• The tool to be calibrated is mounted on the mounting flange.

• The tool to be calibrated and the frame used as the TCP have been
created in the object templates of the project and transferred to the ro-
bot controller by means of synchronization.
• T1 mode

Procedure

1. Select the Calibration> Tool calibration tile at the Robot level. The
Tool calibration view opens.
2. Select the tool to be calibrated and the corresponding TCP.
3. Select the TCP calibration(XYZ 4-point) method. The measuring
points of the method are displayed as buttons:
• Measurement point 1 ... Measurement point 4
In order to be able to record a measuring point, it must be selected
(button is orange).
4. Move the TCP to any reference point. Press Record calibration
point. The position data are applied and displayed for the selected
measuring point.
5. Move the TCP to the reference point from a different direction. Press
Record calibration point. The position data are applied and
displayed for the selected measuring point.
6. Repeat step 5 two more times.
7. Press Determine tool data. The calibration data and the calculation
error are displayed in the Apply tool data dialog.
8. If the calculation error exceeds the maximum permissible value, a
warning is displayed. Press Cancel and recalibrate the TCP.

142/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Start-up and recommissioning

9. If the calculation error is below the configured limit, press Apply to
save the calibration data.
10. Either close the Calibration view or define the orientation of the tool
coordinate system with the ABC 2-point or ABC World method.
(>>> 7.4.1.2 "Defining the orientation: ABC 2-point method" Page 143)
(>>> 7.4.1.3 "Defining the orientation: ABC world method" Page 145)
11. Synchronize the project in order to save the calibration data in Sun-
rise.Workbench.

7.4.1.2 Defining the orientation: ABC 2-point method

Description

The robot controller is notified of the axes of the tool coordinate system
by addressing a point on the X axis and a point in the XY plane.
The points must maintain a defined minimum distance from one another. If
the points are too close to one another, the position data cannot be
saved. A corresponding error message is generated.
The minimum distance can be modified in Sunrise.Workbench.
(>>> 10.4.7 "Configuration parameters for calibration" Page 211)
This method is used for tools with edges and corners which can be used
for orientation purposes. Furthermore, it is used if it is necessary to define
the axis directions with particular precision.
This method is not available for safety-oriented tools.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 143/667

Start-up and recommissioning KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 7-5: ABC 2-point method

Precondition

• The tool to be calibrated is not a safety-oriented tool.

• The tool to be calibrated is mounted on the mounting flange.
• The TCP of the tool has already been measured.
• T1 mode

Procedure

1. Only if the Calibration view was closed following TCP calibration:

Select the Calibration> Tool calibration tile at the Robot level. The
Tool calibration view opens.
2. Only if the Calibration view was closed following TCP calibration:
Select the mounted tool and the corresponding TCP of the tool.
3. Select the Defining the orientation (ABC 2-point) method. The
measuring points of the method are displayed as buttons:
• TCP
• Negative X axis
• Positive Y value on XY plane

144/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

In order to be able to record a measuring point, it must be selected

Start-up and recommissioning

(button is orange).
4. Move the TCP to any reference point. Press Record calibration
point. The position data are applied and displayed for the selected
measuring point.
5. Move the tool so that the reference point on the X axis has a negative
X value (i.e. move against the tool direction). Press Record calibra-
tion point. The position data are applied and displayed for the selec-
ted measuring point.
6. Move the tool so that the reference point in the XY plane has a posi-
tive Y value. Press Record calibration point. The position data are
applied and displayed for the selected measuring point.
7. Press Determine tool data. The calibration data are displayed in the
Apply tool data dialog.
8. Press Apply to save the calibration data.
9. Synchronize the project in order to save the calibration data in Sun-
rise.Workbench.

7.4.1.3 Defining the orientation: ABC world method

Description

The user aligns the axes of the tool coordinate system parallel to the axes
of the world coordinate system. This communicates the orientation of the
tool coordinate system to the robot controller.
There are 2 variants of this method:
• 5D: The user communicates the tool direction to the robot controller.
The default tool direction is the X axis. The orientation of the other ax-
es is defined by the system and cannot be influenced by the user.
The system always defines the orientation of the other axes in the
same way. If the tool subsequently has to be calibrated again, e.g. af-
ter a crash, it is therefore sufficient to define the tool direction again.
Rotation about the tool direction need not be taken into consideration.
• 6D: The user communicates the direction of all 3 axes to the robot
controller.
This method is used for tools that do not have corners which the user can
employ for orientation, e.g rounded tools such as adhesive or welding
nozzles.

Precondition

• The tool to be calibrated is mounted on the mounting flange.

• The TCP of the tool has already been measured.
• T1 mode

Procedure

1. Only if the Calibration view was closed following TCP calibration:

Select the Calibration> Tool calibration tile at the Robot level. The
Tool calibration view opens.
2. Only if the Calibration view was closed following TCP calibration:
Select the mounted tool and the corresponding TCP of the tool.
3. Select the Defining the orientation(ABC world) method.
4. Select the ABC World 5D or ABC world 6D option.
5. If ABC World 5D is selected:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 145/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Align +XTOOL parallel to -ZWORLD. (+XTOOL = tool direction)

Start-up and recommissioning

If ABC world 6D is selected:

Align the axes of the tool coordinate system as follows.
• +XTOOL parallel to -ZWORLD. (+XTOOL = tool direction)
• +YTOOL parallel to +YWORLD.
• +ZTOOL parallel to +XWORLD.
6. Press Determine tool data. The calibration data are displayed in the
Apply tool data dialog.
7. Press Apply to save the calibration data.
8. Synchronize the project in order to save the calibration data in Sun-
rise.Workbench.

7.4.2 Base calibration: 3-point method

Description

During base calibration, the user assigns a Cartesian coordinate system

(base coordinate system) to a frame selected as the base. The base co-
ordinate system has its origin at a user-defined point.
Advantages of base calibration:

• The TCP can be jogged along the edges of the work surface or work-
piece.
• Points can be taught relative to the base. If it is necessary to offset
the base, e.g. because the work surface has been offset, the points
move with it and do not need to be retaught.
The origin and 2 further points of a base are addressed with the 3-point
method. These 3 points define the base.
The points must maintain a defined minimum distance from the origin and
minimum angles between the straight lines (origin – X axis and origin –
XY plane). If the points are too close to one another or if the angle be-
tween the straight lines is too small, the position data cannot be saved. A
corresponding error message is generated.
The minimum distance and angles can be modified in Sunrise.Workbench.
(>>> 10.4.7 "Configuration parameters for calibration" Page 211)

146/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Start-up and recommissioning

Fig. 7-6: 3-point method

Precondition

• A previously calibrated tool is mounted on the mounting flange.

• The frame to be calibrated has been selected as the base in the ap-
plication data of the project and transferred to the robot controller by
means of synchronization.
• T1 mode

Procedure

1. Select Calibration > Base calibration at the Robot level. The Base
calibration view opens.
2. Select the base to be calibrated.
3. Select the mounted tool and the TCP of the tool with which the meas-
uring points of the base are addressed.
The measuring points of the 3-point method are displayed as buttons:
• Origin
• Positive X axis
• Positive Y value on XY plane

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 147/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

In order to be able to record a measuring point, it must be selected

Start-up and recommissioning

(button is orange).
4. Move the TCP to the origin of the base. Press Record calibration
point. The position data are applied and displayed for the selected
measuring point.
5. Move the TCP to a point on the positive X axis of the base. Press Re-
cord calibration point. The position data are applied and displayed
for the selected measuring point.
6. Move the TCP to a point in the XY plane with a positive Y value.
Press Record calibration point. The position data are applied and
displayed for the selected measuring point.
7. Press Determine base data. The calibration data are displayed in the
Apply base data dialog.
8. Press Apply to save the calibration data.
9. Synchronize the project in order to save the calibration data in Sun-
rise.Workbench.

7.5 Determining tool load data

Description

During load data determination, the robot first performs various measure-
ment runs using the wrist axes (A5, A6 and A7). The load data are then
calculated from the data recorded during the measurement runs.
The mass and the position of the center of mass of the tool mounted on
the robot flange can currently be determined. It is also possible to specify
the mass and to determine the position of the center of mass on the basis
of the mass that is already known.
• At the start of the load data determination, axis A7 is moved to the
zero position. Additionally, axis A5 is positioned in such a way that ax-
is A6 is aligned perpendicular to the weight.
• During the measurement runs, axes A6 and A7 require a certain axis
range for their motions:
‒ As standard, axis A6 moves between -95° and +95°.
If the workspace is insufficient for a motion in this axis range, e.g.
due to the dimensions of the mounted tool, the motion range can
be limited further. A check box is provided for this in the Load da-
ta view on the smartHMI.
If the motion range is limited, axis A6 moves 30°, or to be more
precise between -15° and +15° relative to its starting position. If
the distance to one of the software limit switches of the axis is
less than 15°, the difference is added to the angle in the opposite
direction.
‒ Axis A7 moves from 0° to -90°.
• Axes A1 to A4 are not moved during load data determination.

148/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Start-up and recommissioning

Fig. 7-7: Motion range of axis A6

1 Unrestricted motion range for A6

2 Restricted motion range for A6

Quality

The quality of the load data determination may be influenced by the fol-
lowing constraints:
• Mass of the tool
Load data determination becomes more reliable as the mass of the
tool increases. This is because measurement uncertainties have a
greater influence on a smaller mass.
Load data determination cannot yet be used reliably for masses of
less than one kilogram.

• Supplementary loads
Supplementary loads mounted on the robot, e.g. dress packages, lead
to incorrect load data.
• Start position from which load data determination is started
A suitable start position should be determined first and meet the fol-
lowing criteria:
‒ Axes A1 to A5 are as far away as possible from singularity posi-
tions.
The criterion is relevant if the mass is to be determined during
load data determination. If load data determination is only possible
in poses for which axes A1 to A5 are close to singularity positions,
the mass can be specified. If only the center of mass is to be de-
termined on the basis of the specified mass, the criterion of axis
position is irrelevant.
‒ The suitability of the start position for load data determination in
the case of a robot for which automatic load data determination is
to be carried out must be checked before the load that is to be de-
termined is mounted on the robot.
A robot pose is suitable as a start position for load data determi-
nation if there are only very slight external torques (ideally

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 149/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

< 0.5 Nm) acting on the load-free robot in this position. This can
Start-up and recommissioning

be checked via the display of the external axis torques.

(>>> 6.19.4 "Displaying axis-specific torques" Page 121)
If the mass is to be determined during load data determination, all
external axis torques are relevant and should be checked where
possible in advance for the load-free robot. If only the center of
mass is to be determined on the basis of a specified mass, only
the external axis torque of axis A6 is relevant.
• Interference torques during the measurement runs
‒ During the measurement runs, no interference torques may be ap-
plied, e.g. by pulling or pushing the robot.
‒ Moving parts, e.g. dress packages, generate interference torques
that shift the center of mass during the measurement run.
‒ Installation on a mobile or vibrating platform can result in signifi-
cant interference torques.
The best results are achieved if the installation platform is firmly
anchored to the floor. If the robot is fastened to a mobile platform,
e.g. an assembly cart with a simple wheel brake and without an-
chor bolts, the system may start to oscillate due to the motion of
the robot.

The application of interference torques during load data determination

results in falsified load data.

WARNING
Danger to life and limb due to incorrect loads
Operating a robot with incorrect loads may result in death, severe inju-
ries or damage to property. For example, the braking procedure may
take too long with incorrect load data.
• Use only loads that are permissible for the robot.
• Use correct load data.

Safety-oriented tools

For the load data determination for safety-oriented tools, it must be ensur-
ed that the modified load data are not automatically transferred to the
safety configuration located on the robot controller. (>>> 9.3.10 "Configur-
ing a safety-oriented tool" Page 188)
The load data determined for a safety-oriented tool must first be updated
in Sunrise.Workbench by means of project synchronization. This changes
the safety configuration of the project in Sunrise.Workbench; the project
must then be re-transferred to the robot controller by synchronizing the
project again.
If a changed safety configuration is activated on the robot controller, the
safety maintenance technician must carry out safety acceptance.
(>>> 13.14 "Safety acceptance overview" Page 330)
To avoid spending unnecessary time performing verifications, it is advis-
able to mark a tool as safety-oriented only when the load data have
been correctly entered or determined and have been transferred to Sun-
rise.Workbench.

Preparation

• Determine the start position from which load data determination is to

be started.

150/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Start-up and recommissioning

Precondition

• The tool is mounted on the mounting flange.

• The tool has been created in the object templates of the project and
transferred to the robot controller by means of synchronization.
• The robot is in the desired start position.
• There is a sufficiently large workspace available in the wrist axis
range.
• T1, T2 or AUT mode

NOTICE
If parts of the mounted tool project behind the flange plane (in the neg-
ative Z direction relative to the flange coordinate system), there is a risk
of the tool colliding with the manipulator during the measurement runs.
If the motion of the axes during load data determination is unknown to
the operator, or if a collision between the tool and manipulator cannot
be ruled out (e.g. for the initial load data determination for a tool), it is
advisable to determine the load data in T1 mode. This does not affect
the quality of the measurement results.

Procedure

1. Select the Load data tile at the Robot level. The Load data view
opens.
2. Select the mounted tool from the selection list.
3. If required, activate the check box next to Restricted motion range
for axis 6.
4. If T1 or T2 mode is set, press and hold down the enabling switch until
load data determination has been completed.
5. Press Determining the load data.
6. If the tool already has a mass, the operator will be asked if the mass
is to be redetermined.
• Select Use existing mass if the currently saved mass is to be re-
tained.
• Select Redetermine mass if the mass is to be determined again.

If the currently saved mass is to be retained in the load determina-

tion, it must be ensured that the specified mass value is correct.
Otherwise, the center of mass cannot be determined accurately.

7. The robot starts the measurement runs and the load data are deter-
mined. A progress bar is displayed.
If the motion enable signal is withdrawn during load data determina-
tion, e.g. by an EMERGENCY STOP or by releasing the enabling
switch (T1, T2), the load data determination is aborted and must be
restarted.

Once load data determination has been completed, the determined

load data are displayed in the Apply load data dialog.
Press Apply to save the determined load data.
8. Synchronize the project so that the load data are saved in Sun-
rise.Workbench.
9. When the load data for a safety-oriented tool have been determined,
the safety configuration changes as a result of the project synchroniza-
tion.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 151/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Synchronize the project in order to transfer the changed safety config-

Start-up and recommissioning

uration to the robot controller.

Load data view

Fig. 7-8: Load data view

Item Description
1 Tool selection list
The tools created in the object templates are available for se-
lection here.
2 Load data display
Displays the current load data of the selected tool.
3 Display of axes used
Displays the axes that are moved for load data determination.
4 Option Restricted motion range for axis 6

• Check box active: the motion range of axis A6 is limited to

30° (+/-15° relative to the starting position).
• Check box not active: the motion range of axis A6 is not
limited and is 190° (between -95° and +95° in the axis
range).
5 Determining the load data button
Starts load data determination.
The button is only active if a tool has been selected and the
motion enable signal has been issued.

152/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Brake test
8 Brake test

8.1 Overview of the brake test

Description

Each robot axis has a holding brake integrated into the drive train. The
brakes have 2 functions:
• Stopping the robot when the servo control is deactivated or the robot
is de-energized.
• Switching the robot to the safe state “Standstill” in the event of a fault.
The brake test checks whether the brake holding torque applied by each
brake is high enough, i.e. whether it exceeds a specific reference holding
torque. This reference holding torque can be specified by the user or read
from the motor data.
Unless otherwise determined by a risk assessment, the brake test must
be performed regularly:
• The brake test must be carried out for each axis during start-up and
recommissioning of the industrial robot.
• The brake test must be performed daily during operation.
The user can carry out a risk assessment to determine whether the
brake test is required for the specific application and, if so, how often it
is to be performed.

Execution

A precondition for execution of the brake test is that the robot is at oper-
ating temperature.
The brake test is manually executed by means of an application. A pre-
pared brake test application for the LBR iiwa is available from Sun-
rise.Workbench.
In this brake test application, the robot is moved prior to the actual brake
test and the resulting maximum absolute torque is determined for each ax-
is. The torque determined is then communicated to the brake test as the
reference holding torque.
The determination of the maximum absolute torques is referred to in the
following as torque value determination.
It is advisable to remove the torque value determination from the appli-
cation and to test the brakes against the minimum brake holding torque.

If the brakes are tested against a torque specified by the user, a risk
assessment must be carried out before the test. It must be determined
whether there are any hazards if the brakes show a lower torque than
the minimum brake holding torque.

Procedure

When a brake is tested, the following steps are carried out as standard:
1. The axis moves at constant velocity over a small axis angle of max.
5° (on the output side). The gravitation and friction are determined
during this motion.
2. When the axis has returned to its starting position and the axis drive
is stationary, the brake is closed.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 153/667

Brake test KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

3. One of the following values is used as the holding torque to be tested:

The calculated reference holding torque, the minimum brake holding
torque or the motor holding torque.
The holding torque to be tested is defined internally by the system ac-
cording to the following rules:
a. If the reference holding torque is greater than the lowest value of
the minimum brake and motor holding torques, then the lowest val-
ue of the minimum brake and motor holding torques is used as the
holding torque to be tested.
b. If the reference holding torque is lower than 20% of the lowest val-
ue of the minimum brake and motor holding torques, then 20% of
the lowest value of the minimum brake and motor holding torques
is used as the holding torque to be tested.
c. In all other cases, the reference holding torque is used.
At the start of the brake test, with the brake closed, the setpoint tor-
que of the drive is set to 80% of the holding torque to be tested.
The minimum and maximum brake holding torques are saved in the
motor data. The motor holding torque is derived from the motor da-
ta.

4. The drive torque is gradually increased until a change in position is

detected or the maximum brake holding torque (derived from the mo-
tor data) is reached. The brake test ends when the maximum brake
holding torque is reached.
5. The torque applied against the brake when a change in position is de-
tected is measured. This is the measured holding torque.
6. The measured holding torque is evaluated relative to the holding tor-
que to be tested.
The brake test is successful if the measured holding torque lies within
the following range:
• ≥ 105% of the holding torque to be tested … ≤ maximum brake
holding torque
If the measured holding torque lies below the holding torque to be tes-
ted, the brake test has failed, i.e. the brake is identified as being de-
fective.
The test result is displayed on the smartHMI.
(>>> 8.4.2 "Result of the brake test (display)" Page 170)
7. When the brake test has ended and the robot is stationary, the brake
is briefly opened and closed again. This releases any remaining ten-
sion in the brake and prevents undesired robot motions.

If the application is paused during the brake test or if a safety stop is

triggered, e.g. by an EMERGENCY STOP, the brake test is aborted.
The brake test for the axis is repeated when the application is resumed.

The brake test does not depend on the loads mounted on the robot, as
gravitation and friction are taken into consideration when the test is car-
ried out.

Overview

The following describes the steps for executing the brake test with the
template available in Sunrise.Workbench.
The brake test application can be adapted and expanded. The comments
contained in the template must be observed.

154/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Brake test
NOTICE
If a brake is defective, the corresponding axis may slip during the brake
test and the robot may sag. The brake test must be executed in a posi-
tion in which no damage could result from potential sagging. The start-
ing position for the brake test must be selected accordingly.

NOTICE
If the brake test fails for an axis (brake is defective), the application
must ensure that the robot is automatically moved to a safe position. A
position is considered safe if the robot is supported in such a way that it
either cannot sag or cannot cause damage in the event of sagging.

Step Description
1 Create the brake test application from a template.
(>>> 8.2 "Creating the brake test application from the tem-
plate" Page 156)
2 In the brake test application, remove or adapt determination
of the application-specific maximum absolute torques.
At the start of the brake test application, 2 predefined axis
positions are addressed as standard. These positions are
addressed in order to determine the maximum absolute tor-
que for each axis and transfer it to the brake test as the
reference holding torque.
It is advisable to test the brakes against the minimum brake
holding torque, which is stored in the motor data. To do so,
the prepared brake test application must be adapted.
(>>> 8.2.1 "Adapting the brake test application for testing
against the minimum holding torque" Page 158)
If the brake test requires the maximum absolute torques
which occur when a user-specific robot application is execu-
ted, the user-specific robot application can be added to the
brake test application. Since the brakes are not tested
against the minimum brake holding torque in this case, a
risk assessment must be carried out before the test.
(>>> 8.2.2 "Changing the motion sequence for torque value
determination" Page 159)
3 Change the starting position for the brake test.
The default starting position is the vertical stretch position.
If required, a different starting position can be selected.
(>>> 8.2.3 "Changing the starting position for the brake
test" Page 159)
4 If necessary, make further user-specific adaptations in the
brake test application.
Examples:

• Setting the output for a failed brake test.

• Saving the test results in a file.
(>>> 8.3 "Programming interface for the brake test"
Page 160)
5 Synchronize the project in order to transfer the brake test
application to the robot controller.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 155/667

Brake test KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Step Description
6 Execute the brake test application.
(>>> 8.4 "Performing a brake test" Page 169)

8.2 Creating the brake test application from the template

Procedure

1. In the Package Explorer view, select the desired project or package

in which the application is to be created.
2. Select the menu sequence File > New > Sunrise application. The
wizard for creating a new Sunrise application is opened.
3. In the folder Application examples > LBR iiwa, select the application
Application for the brake test of LBR iiwa and click on Finish.
The BrakeTestApplication.java application is created in the source
folder of the project and opened in the editor area of Sunrise.Work-
bench.

Description

In the run() method of the BrakeTestApplication.java application (limited

here to the relevant command lines), the execution of the brake test is im-
plemented for all axes of the LBR iiwa.
An optional data evaluation preceding the actual brake test is also imple-
mented. 2 predefined axis positions are addressed in order to determine
the maximum absolute torque for each axis.

1 public void run() {

2 // ...
3 lbr_iiwa.move(ptpHome());
4 // ...
5 TorqueEvaluator evaluator = new TorqueEvaluator(lbr_iiwa);
6 // ...
7 evaluator.setTorqueMeasured(false);
8
9 evaluator.startEvaluation();
10 // ...
11 lbr_iiwa.move(new PTP(new JointPosition(
12 0.5, 0.8, 0.2, 1.0, -0.5, -0.5, -1.5))
13 .setJointVelocityRel(relVelocity));
14 lbr_iiwa.move(new PTP(new JointPosition(
15 -0.5, -0.8, -0.2, -1.0, 0.5, 0.5, 1.5))
16 .setJointVelocityRel(relVelocity));
17 // ...
18 TorqueStatistic maxTorqueData = evaluator.stopEvaluation();
19
20 boolean allAxesOk = true;
21
22 for (int axis : axes) {
23 try {
24 BrakeTest brakeTest = new BrakeTest(axis,
25 maxTorqueData.getMaxAbsTorqueValues()[axis]);
26 IMotionContainer motionContainer = lbr_iiwa.move(brakeTest);
27 BrakeTestResult brakeTestResult =
28 BrakeTest.evaluateResult(motionContainer);
29 switch(brakeTestResult.getState().getLogLevel())
30 {
31 case Info:

156/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Brake test
32 getLogger().info(brakeTestResult.toString());
33 break;
34 case Warning:
35 getLogger().warn(brakeTestResult.toString());
36 break;
37 case Error:
38 getLogger().error(brakeTestResult.toString());
39 allAxesOk = false;
40 break;
41 default:
42 break;
43 }
44 catch (CommandInvalidException ex) {
45 // ...
46 allAxesOk = false;
47 }
48 }
49
50 if (allAxesOk){
51 getLogger().info("Brake test was successful for all axes.");
52 }
53 else{
54 getLogger().error("Brake test failed for at least one axis.");
55 }
56 }

Line Description
3 Address the starting position from which the robot is moved
to determine the maximum absolute torque for each axis.
The default starting position is the vertical stretch position.
5 Prepare the data evaluation.
In order to perform an axis-specific evaluation of the tor-
ques determined during a motion sequence, an instance of
the TorqueEvaluator class must be created.
7 Select the torques to be used for the data evaluation.
The measured torques are not used, but instead the tor-
ques that are calculated using the robot model during the
motion sequence. Measurements are susceptible to mal-
functions. The calculation of the torque values ensures that
no interference torques resulting from dynamic effects (e.g.
robot acceleration) are incorporated into the data evalua-
tion.
9 Start the data evaluation.
The data evaluation is started with the startEvaluation()
command of the TorqueEvaluator class.
11 … 16 Carry out the motion sequence to determine the maximum
absolute torques
2 predefined axis positions are each addressed with a PTP
motion.
18 End the data evaluation and request the data.
The stopEvaluation() command of the TorqueEvaluator
class ends the data evaluation and returns the result as a
value of type TorqueStatistic. The result is saved in the var-
iable maxTorqueData.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 157/667

Brake test KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Line Description
20 Variable for the evaluation of the brake test
The result of the brake test is saved for later evaluation via
the variable allAxesOk. It is set to the value “false” if the
brake test of an axis fails or is aborted due to an error.
Otherwise it retains the value “true”.
22 … 54 Execute the brake test
The brakes are tested one after the other, starting with the
brake of axis A1.

• Lines 24, 25: An object of type BrakeTest is created.

In the process, the corresponding axis and the previous-
ly determined maximum absolute torque are transferred
as the reference holding torque.
• Line 26: The brake test is executed as a motion com-
mand.
• Lines 27 ... 54: The result of the brake test is evaluated
and displayed on the smartHMI.

8.2.1 Adapting the brake test application for testing against the minimum
holding torque

Description

The brake test checks whether the brakes apply the minimum brake hold-
ing torque. It is therefore advisable to adapt the prepared brake test appli-
cation in accordance with the following description.
If the brake test is to be executed without reference holding torques being
determined and made available to the brake test, all the command lines
relevant for torque value determination must be removed from the brake
test application. The brake test application then starts with the motion to
the starting position.
In addition, when creating the BrakeTest instance, the parameter with
which the reference torque is transferred must be removed.

Fig. 8-1: Transferring the reference torque for the brake test

1 Constructor of the class BrakeTest with transfer of reference tor-

que

Procedure

1. Open the brake test application in Sunrise.Workbench.

2. Make the following changes to the run() method of the application:
• Delete all command lines which are relevant for torque value de-
termination.
• When calling the constructor of the BrakeTest class, delete the
following parameters:
maxTorqueData.getMaxAbsTorqueValues()[axis]
The following code remains in the line:

158/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Brake test
BrakeTest brakeTest = new brakeTest(axis);
3. Save changes.

8.2.2 Changing the motion sequence for torque value determination

Description

The brake test application created from the template contains a prepared
motion sequence for determining the maximum absolute torques gener-
ated in each axis.
As standard, the robot is moved from the vertical stretch position. A differ-
ent starting position can be selected.
2 predefined axis positions are each addressed from the starting position
with a PTP motion. In order to determine the maximum absolute torques
that arise in a specific robot application, and to use these as reference
holding torques for the brake test, application-specific motion sequences
must be inserted into the brake test application.

Fig. 8-2: Motion sequence for torque value determination

1 Motion to starting position ptpHome()

2 Predefined motion sequence for torque value determination

Procedure

1. Open the brake test application in Sunrise.Workbench.

2. If necessary, make the following changes to the run() method of the
application:
• Replace the motion that brings the robot to the starting position
ptpHome() with a motion to the desired starting position.
• Replace the predefined motion sequence with the appropriate ap-
plication code.
3. Save changes.

8.2.3 Changing the starting position for the brake test

As standard, the brake test application created from the template executes
the brake test to the end position of the motion sequence in order to de-
termine the maximum absolute torque. If this position is not suitable for
the brake test, a motion to the desired starting position must be program-
med before the brake test is executed.
To determine the gravitation and friction, the axes of the LBR are
moved towards the mechanical zero position. The maximum travel is 5°
on the output side.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 159/667

Brake test KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

8.3 Programming interface for the brake test

With the BrakeTest class, the RoboticsAPI offers a programming interface

for the execution of the brake test. The brake test is executed as a
motion command.
In addition, using the TorqueEvaluator class, the torques occurring during
a motion sequence can be evaluated and the maximum absolute torque
for each axis can be determined. This torque can be used as the refer-
ence holding torque for the brake test.

8.3.1 Evaluating torques and determining the maximum absolute value

Description

In order to perform an axis-specific evaluation of the torques determined

during a motion sequence, an object of the TorqueEvaluator class must
first be created. The LBR instance for whose axes the maximum absolute
torque values are to be determined is transferred to the constructor of the
TorqueEvaluator class.
The evaluation can be started and then ended with the following methods
of the TorqueEvaluator class:
• startEvaluation(): Starts the evaluation.
Once the method has been called, the motion sequence to be evalu-
ated must be commanded.
• stopEvaluation(): Ends the evaluation.
The method returns an object of type TorqueStatistic. The result of the
evaluation can be requested via this object.
The torques generated during the motion sequence can be determined in
different ways:
• Measured torques: The torques measured by the axis torque sensors
are used.
• Static torques (model-based): The torques calculated using the static
robot model are used.
The setTorqueMeasured(…) method of the TorqueEvaluator class can be
used to define whether the measured or static (model-based) torques are
to be used for the evaluation.

Syntax

TorqueEvaluator evaluator = new TorqueEvaluator(lbr);

evaluator.setTorqueMeasured(isTorqueMeasured);
evaluator.startEvaluation();
//Motion sequence
TorqueStatistic maxTorqueData = evaluator.stopEvaluation();

160/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Brake test
Explanation of the syntax

Element Description
evaluator Type: TorqueEvaluator
Variable to which the created TorqueEvaluator instance is
assigned. The evaluation of the torques during a motion
sequence is started and ended via the variable.
isTorque Type: boolean
Measured
Input parameter of the setTorqueMeasured(…) method:
Defines whether the measured torque values or the val-
ues calculated using the static robot model are to be
used for the evaluation.

• true: measured torques are used

• false: static torques (model-based) are used
Note: When using the static (model-based) torques, dy-
namic effects, e.g. those arising from acceleration of the
robot, have no influence on the determined values.
lbr Type: LBR
Instance of the robot used in the application, for which
the maximum absolute torques are to be determined.
maxTorque Type: TorqueStatistic
Data
Variable for the return value of stopEvaluation(). The re-
turn value contains the determined maximum absolute
torque values and further information for the evaluation.

8.3.2 Requesting the evaluation result of the maximum absolute torques

When the evaluation of the maximum absolute torque values has ended,
the result of the evaluation can be requested.

Overview

The following methods of the TorqueStatistic class are available:

Method Description
getMaxAbs Return value type: double[]; unit: Nm
TorqueValues()
Returns a double array containing the determined maximum absolute
torque values (output side) for all axes.
getSingleMaxAbs Return value type: double; unit: Nm
TorqueValue(...)
Returns the maximum absolute torque value (output side) for the axis
which is transferred as the parameter (type: JointEnum).
areDataValid() Return value type: boolean
The system checks whether the determined data are valid (= true).
The data are valid if no errors occur during command processing.
getStartTimestamp() Return value type: java.util.Date
Returns the time at which the evaluation was started.
getStopTimestamp() Return value type: java.util.Date
Returns the time at which the evaluation was ended.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 161/667

Brake test KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Method Description
isTorqueMeasured() Return value type: boolean
Checks whether the measured torques or the torques calculated using
the static robot model were used for evaluating the maximum abso-
lute torque.

• true: Measured torques are used

• false: Static torques (model-based) are used

Example

The maximum torques which occur during a joining task are to be used
as reference torques in a brake test. For this purpose, the torques which
are measured during the execution of the joining task are evaluated, and
the maximum absolute torque for each axis is determined.
Once the evaluation has been started, the motion commands of the join-
ing process are executed. When the joining process is completed, the
evaluation is ended and the result of the evaluation for axes A2 and A4
are saved in the process data. If the determined data are invalid, an out-
put is set.

private LBR testLBR;

private BrakeTestIOGroup brakeTestIOs;
private Tool testGripper;
private Workpiece testWorkpiece;
// ...
public void run() {

testGripper.attachTo(testLBR.getFlange());
testWorkpiece.attachTo(testGripper.getFrame("/GripPoint"));

// create TorqueEvaluator
TorqueEvaluator testEvaluator = new TorqueEvaluator(testLBR);

// select measured torque values

testEvaluator.setTorqueMeasured(true);

// start evaluation
testEvaluator.startEvaluation();

// performs assembly task

testAssemblyTask();

// finish evaluation and store result in variable testMaxTrqData

TorqueStatistic testMaxTrqData = testEvaluator.stopEvaluation();

// get maximum absolute measured torque value for joint 2

double maxTrqA2 = testMaxTrqData.getSingleMaxAbsTorqueValue(JointEnum.J2);

// save result
getApplicationData().getProcessData("maxTrqA2").setValue(maxTrqA2);

// get maximum absolute measured torque value for joint 4

double maxTrqA4 = testMaxTrqData.getSingleMaxAbsTorqueValue(JointEnum.J4);

// save result
getApplicationData().getProcessData("maxTrqA4").setValue(maxTrqA4);

// check if evaluated data is valid

162/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Brake test
boolean areDataValid = testMaxTrqData.areDataValid();
if (areDataValid == false) {
// if data is not valid, set output signal
brakeTestIOs.setEvaluatedTorqueInvalid(true);
}
// ...
}

public void exampleAssemblyTask() {

testLBR.move(ptp(getFrame("/StartAssembly")));

ForceCondition testForceCondition =
ForceCondition.createNormalForceCondition(
testWorkpiece.getDefaultMotionFrame(), CoordinateAxis.Z, 15.0);
testWorkpiece.move(linRel(0.0, 0.0, 100.0).breakWhen(testForceCondition));

CartesianSineImpedanceControlMode testAssemblyMode =
CartesianSineImpedanceControlMode.createLissajousPattern(
CartPlane.XY, 5.0, 10.0, 500.0);

testWorkpiece.move(positionHold(testAssemblyMode, 3.0, TimeUnit.SECONDS));

openGripper();
testWorkpiece.detach();

testGripper.move(linRel(0.0, 0.0, -100.0));

}

8.3.3 Creating an object for the brake test

Description

In order to be able to execute the brake test, an object of the BrakeTest

class must first be created. The index of the axis for which the brake test
is to be executed is transferred to the constructor of the BrakeTest class.
Optionally, the torque parameter can be used to transfer a reference hold-
ing torque, e.g. the maximum absolute axis torque which occurs in a spe-
cific application.
As a general rule, the brake test must check whether the brakes apply the
minimum brake holding torque. It is therefore advisable not to specify the
torque parameter.

Syntax

BrakeTest brakeTest = new BrakeTest(axis, <torque>);

Explanation of the syntax

Element Description
brakeTest Type: BrakeTest
Variable to which the created BrakeTest instance is as-
signed. The execution of the brake test is commanded
via the variable as a motion command.
axis Type: int
Index of the axis whose brake is to be tested.

• 0 … 6: Axes A1 … A7

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 163/667

Brake test KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Element Description
torque Type: double; unit: Nm
Reference holding torque (output side) specified by the
user, e.g. the maximum absolute torque that has been
determined beforehand for an axis-specific motion se-
quence.
If no reference holding torque is specified, the brake test
uses the lowest of the following values as the holding
torque: minimum brake holding torque or motor holding
torque.
If a reference holding torque is specified, one of the fol-
lowing values is used as the holding torque to be tested:
the specified reference holding torque (torque), the mini-
mum brake holding torque or the motor torque.
The holding torque to be tested is defined internally by
the system according to the following rules:

1. If the reference holding torque is greater than the

lowest value of the minimum brake and motor holding
torques, then the lowest value of the minimum brake
and motor holding torques is used as the holding tor-
que to be tested.
2. If the reference holding torque is lower than 20% of
the lowest value of the minimum brake and motor
holding torques, then 20% of the lowest value of the
minimum brake and motor holding torques is used as
the holding torque to be tested.
3. In all other cases, the reference holding torque is
used.
Note: The minimum and maximum brake holding torques
are saved in the motor data. The motor holding torque is
derived from the motor data.

8.3.4 Starting execution of the brake test

Description

The brake test is executed by a motion command which is made available

via the BrakeTest class. In order to execute the brake test, the move(…)
or moveAsync(…) method is called with the robot instance used in the ap-
plication, and the object created for the brake test is transferred.
In order to evaluate the result of the brake test, the return value of the
motion command must be saved in a variable of type IMotionContainer.
If an error is detected while the brake test is being executed, the brake
test is aborted. In order to be able to react to errors in the program, it is
advisable to command the execution and evaluation of the brake test with-
in a try block and to deal with the CommandInvalidException arising from
the error.

Syntax

try {
BrakeTest brakeTest = ...;
IMotionContainer brakeTestMotionContainer =
robot.moveΙmoveAsync(brakeTest);

164/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

...

Brake test
} catch(CommandInvalidException ex {
...
}

Explanation of the syntax

Element Description
brakeTest Type: BrakeTest
Variable to which the created BrakeTest instance is as-
signed. The instance defines the axis for which the brake
test is to be executed and can optionally define a refer-
ence holding torque specified by the programmer.
brakeTest Type: IMotionContainer
Motion
Variable for the return value of the move(…) or moveA-
Container
sync(…) motion command used to carry out the brake
test. When the brake test has ended, the result can be
evaluated using the variable.
robot Type: Robot
Instance of the robot used in the application. The brake
test is to be performed on the axes of this robot.
ex Type: CommandInvalidException
Exception which occurs when the brake test is aborted
due to an error. It is advisable to treat the exception with-
in the catch block in such a way that an aborted brake
test for a single brake does not cancel the entire brake
test application.

8.3.5 Evaluating the brake test

Description

When the brake test has ended, the result can be evaluated. For this pur-
pose, the return value of the motion command used to carry out the brake
test must be assigned to a variable of type IMotionContainer.
In order to evaluate the brake test, the IMotionContainer instance of the
corresponding motion command is transferred to the static method evalua-
teResult(…). The method belongs to the BrakeTest class and returns an
object of type BrakeTestResult. Various information concerning the execu-
ted brake test can be requested from this object.

Syntax

IMotionContainer brakeTestMotionContainer =
robot.moveΙmoveAsync(brakeTest);
BrakeTestResult result =
BrakeTest.evaluateResult(brakeTestMotionContainer);

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 165/667

Brake test KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Explanation of the syntax

Element Description
brakeTest Type: IMotionContainer
Motion
Variable for the return value of the move(…) or moveA-
Container
sync(…) motion command used to carry out the brake
test.
result Type: BrakeTestResult
Variable for the return value of evaluateResult(…). The
return value contains the results of the brake test and
further information concerning the brake test which can
be requested via the variable.

Overview

The following methods of the BrakeTestResult class are available for eval-
uating the brake test:
Method Description
getAxis() Return value type: int
Returns the index of the axis whose brake has been tested. The in-
dex starts with 0 (= axis A1).
getBrakeIndex() Return value type: int
Returns the index of the tested brake of the motor (starting with 0). In
a brake test for the LBR iiwa, the value 0 is always returned.
getFriction() Return value type: double; unit: Nm
Returns the frictional torque (output side) determined during the test
motion.
getGravity() Return value type: double; unit: Nm
Returns the gravitational torque (output side) determined during the
test motion.
getMaxBrake Return value type: double; unit: Nm
HoldingTorque()
Returns the torque (output side) determined from the motor data
which the brake must not exceed. (= maximum brake holding torque)
getMeasuredBrake Return value type: double; unit: Nm
HoldingTorque()
Returns the holding torque (output side) measured during the brake
test. This value is compared with the holding torque to be tested.
getMinBrake Return value type: double; unit: Nm
HoldingTorque()
Returns the minimum brake torque (output side) that can be reached,
as determined from the motor data. (= minimum brake holding torque)
getMotor Return value type: double; unit: Nm
HoldingTorque()
Returns the motor holding torque (output side) determined from the
motor data.
getMotorIndex() Return value type: int
Returns the index of the tested motor of the drive (starting with 0). In
a brake test for the LBR iiwa, the value 0 is always returned.
getMotor Return value type: double; unit: Nm
MaximalTorque()
Returns the maximum motor torque (output side) determined from the
motor data.

166/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Brake test
Method Description
getState() Return value type: Enum of type BrakeState
Returns the results of the brake test.
(>>> 8.3.5.1 "Requesting the result of the brake test" Page 167)
getTestedTorque() Return value type: double; unit: Nm
Returns the test holding torque with which the holding torque (output
side) applied and measured during the brake test is compared.
getTimestamp() Return value type: java.util.Date
Returns the time at which the brake test was started.

8.3.5.1 Requesting the result of the brake test

Description

The test result is requested via the BrakeTestResult method getState(). An

enum of type BrakeState is returned; its values describe the possible test
results.
The possible test results are assigned to specific log levels. The log level
corresponding to the test result can be requested with getLogLevel().

Syntax

BrakeTestResult result = ...;

BrakeState state = result.getState();
LogLevel logLevel = state.getLogLevel();

Explanation of the syntax

Element Description
result Type: BrakeTestResult
Variable for the return value of the static method evalua-
teResult(...) which provides the BrakeTest class for evalu-
ation of the brake test. The return value contains the re-
sults of the brake test and further information concerning
the brake test which can be requested via the variable.
state Type: Enum of type BrakeState
Variable for the return value of getState(). The return val-
ue contains the test result.
(>>> "BrakeState" Page 168)
logLevel Type: Enum of type LogLevel
Variable for the return value of getLogLevel(). The return
value contains the log level of the test result.

• LogLevel.Error: the brake test could not be executed

or has failed.
• LogLevel.Info: the brake test has been executed
successfully.
• LogLevel.Warning: the holding torque to be tested
has been reached, but problems occurred while the
brake test was being carried out.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 167/667

Brake test KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

BrakeState

The enum of type BrakeState has the following values:

Value Description
BrakeUntested The brake test has not yet been performed.
Log level: Error
BrakeUnknown The brake test could not be performed due to faults
or was aborted.
Log level: Error
BrakeError The brake test has failed. The measured holding tor-
que falls below the holding torque to be tested. The
brake is defective.
Log level: Error
BrakeWarning The measured holding torque is less than 5% above
the holding torque to be tested. The brake has
reached the wear limit. It will soon be identified as
defective.
Log level: Warning
BrakeExcessive The measured holding torque is greater than the
maximum brake holding torque. Stopping by means
of the brake can cause damage to the machine.
Log level: Warning
BrakeMax The holding torque to be tested has been reached,
Unknown but the brake could not be tested against the maxi-
mum brake holding torque.
Log level: Info
BrakeReady The measured holding torque exceeds the holding
torque to be tested by more than 5%. The brake is
fully operational.
Log level: Info

Example

A brake test is executed for axis A2. If the brake test is aborted, this is in-
dicated by a corresponding output signal. If the brake test is fully execu-
ted, a message containing the measured holding torque is generated and
the test result are requested. Depending on whether the measured holding
torque is too low, within the tolerance range or in the ideal range, a corre-
sponding output is also set in each case.

private LBR exampleLBR_iiwa;

private BrakeTestIOGroup brakeTestIOs;
// ...
public void run() {
// ...

try {
int indexA2 = 1;
BrakeTest exampleBrakeTest = new BrakeTest(indexA2);

IMotionContainer exampleBrakeTestMotionContainer =
exampleLBR_iiwa.move(exampleBrakeTest);

BrakeTestResult resultA2 = BrakeTest.evaluateResult(

168/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Brake test
exampleBrakeTestMotionContainer);

double measuredTorque =
resultA2.getMeasuredBrakeHoldingTorque();

getLogger().info("Measured torque for A2: "

+ measuredTorque);

BrakeState state = resultA2.getState();

if (state == BrakeState.BrakeError)
brakeTestIOs.setA2_BrakeError(true);
else if (state == BrakeState.BrakeWarning)
brakeTestIOs.setA2_BrakeWarning(true);
else if (state == BrakeState.BrakeReady)
brakeTestIOs.setA2_BrakeOK(true);

} catch (CommandInvalidException ex) {

brakeTestIOs.setBrakeTest_Aborted(true);
ex.printStackTrace();
}
}

8.4 Performing a brake test

Description

If the brake test application is paused while a brake is being tested, e.g.
by pressing the Start button on the smartPAD or due to a stop request,
the brake test of the axis is aborted.
If the brake test application is resumed, the aborted brake test will be re-
peated for the axis in question. If the axis is no longer in the position in
which the aborted brake test was started, it must be repositioned by
pressing the Start key. Only then can the application be resumed.

Precondition

• The brake test application is configured and available on the robot

controller.
• There are no persons or objects in the range of motion of the robot.
• Program run mode Continuous (default mode)
• The robot is at operating temperature.

Procedure

• Select and start the brake test application.

1. If configured (optional LBR iiwa): the torques measured during a
motion sequence are evaluated for each axis, and the maximum
absolute torque for each axis is determined.
The result of the evaluation is displayed on the smartHMI.
2. The brakes are tested one after the other, starting with axis A1.
The brake test results are displayed individually for each axis on
the smartHMI.

WARNING
If the functional capability of a brake is not guaranteed and the drives
are switched off, the robot can sag. If, during the brake test, a brake is
identified as being defective (test result = “Failed”), the robot must be
taken out of operation immediately.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 169/667

Brake test KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

8.4.1 Evaluation results of the maximum absolute torques (display)

Fig. 8-3: Results of an evaluation of the maximum absolute torques

Item Description
1 Validity
Indicates whether the determined data are valid. The data are
valid if no errors occur during command processing.
2 Time indications
Start time, end time and overall duration of the evaluation.
3 Determined data
The maximum absolute torque determined from the evaluation
is displayed for each axis.

8.4.2 Result of the brake test (display)

Fig. 8-4: Results of a brake test for axis A2

Item Description
1 Log level
Depending on the result of the brake test, the message is gen-
erated with a specific log level.

• Info: the brake test has been executed successfully.

• Warning: the holding torque to be tested has been reached,
but the brake no longer brakes so well or it brakes exces-
sively.
• Error: the brake test could not be executed or has failed.
2 Tested axis

170/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Brake test
Item Description
3 Time stamp
Time stamp at which the brake test was started for the axis.
4 Holding torque to be tested
5 Measured holding torque
6 Result of the brake test

• Untested: the brake test has not yet been performed.

Log level: Error
• Unknown: the brake test could not be performed due to
faults or was aborted.
Log level: Error
• Failed: the brake test has failed. The measured holding tor-
que falls below the holding torque to be tested. The brake
is defective.
Log level: Error
• Warning: the measured holding torque is less than 5%
above the holding torque to be tested. The brake has
reached the wear limit and will soon be identified as defec-
tive.
Log level: Warning
• Excessive: the measured holding torque is greater than the
maximum brake holding torque. Stopping by means of the
brake can cause damage to the machine.
Log level: Warning
• Maximum unknown: the holding torque to be tested has
been reached, but the brake could not be tested against the
maximum brake holding torque. The brake test was suc-
cessful!
Log level: Info
• Successful: the measured holding torque exceeds the hold-
ing torque to be tested by more than 5 %. The brake is fully
operational.
Log level: Info

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 171/667

Brake test KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

172/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Project management
9 Project management

9.1 Overview of a Sunrise project

A Sunrise project contains all the data which are required for the opera-
tion of a station. A Sunrise project comprises:
• Station configuration
The station configuration describes the static properties of the station.
Examples include hardware and software components.
• Sunrise applications
Sunrise applications contain the source code for executing a task for
the station. They are programmed in Java with KUKA Sunrise.Work-
bench and are executed on the robot controller. A Sunrise project can
have any number of Sunrise applications.
• Runtime data
Runtime data are all the data which are used by the Sunrise applica-
tions during the runtime. These include, for example, end points for
motions, tool data and process parameters.
• Safety configuration
The safety configuration contains the configured safety functions.
• I/O configuration (optional)
The I/O configuration contains the inputs/outputs of the used field
buses mapped in WorkVisual. The inputs/outputs can be used in the
Sunrise applications.
Sunrise projects are created and managed with KUKA Sunrise.Work-
bench.
(>>> 5.3 "Creating a Sunrise project with a template" Page 57)
There may only be 1 Sunrise project on the robot controller at any given
time. This is transferred from Sunrise.Workbench to the robot controller by
means of project synchronization.
(>>> 9.5 "Project synchronization" Page 199)

9.2 Frame management

Overview

Frames are coordinate transformations which describe the position of

points in space or objects in a station. The coordinate transformations are
arranged hierarchically in a tree structure. In this hierarchy, each frame
has a higher-level parent frame with which it is linked through the transfor-
mation.
The root element or origin of the transformation is the world coordinate
system which is located as standard in the robot base. This means that
all frames are directly or indirectly related to the world coordinate system.
A transformation describes the relative position of 2 coordinate systems to
each other, i.e. how a frame is offset and oriented relative to its parent
frame.
The position of a frame relative to its parent frame is defined by the fol-
lowing transformation data:
• X, Y, Z: Offset of the origin along the axes of the parent frame
• A, B, C: Rotational offset of the axis angles of the parent frame

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 173/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Rotational angle of the frames:

Project management

‒ Angle A: Rotation about the Z axis

‒ Angle B: Rotation about the Y axis
‒ Angle C: Rotation about the X axis
• Redundancy data
‒ Status: Saves the position of axes A4 and A6
‒ Turn: Saves the position of all axes
‒ Redundancy angle: Saves the angle of axis E1
• Calibration data

9.2.1 Creating a frame for an application

Description

Frames can be created in the application data in Sunrise.Workbench.

These frames are project-specific and can be used in every robot applica-
tion of the project.
Once the project has been synchronized, the frames are available on the
smartHMI. There, additional frames can be created and the frames taught
in order to determine the position of the frames in space. Taught frames
can be addressed manually.
(>>> 6.17.1 "“Frames” view" Page 105)

Procedure

1. Select the desired project in the Package Explorer view.

2. Right-click on the desired parent frame in the Application data view
and select Insert new frame from the context menu.
The new frame is created and inserted in the frame tree as a child el-
ement of the parent frame.
3. The system automatically generates a frame name. It is advisable to
change the name in the frame properties. (>>> 9.2.5 "Displaying/edit-
ing frame properties" Page 177)
A descriptive frame name makes both programming and orientation
within the program easier. The frame names must be unique within
the hierarchy level and may not be assigned more than once.

174/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Project management
Example

Fig. 9-1: Application data – frames

Frame1, 2 and 3 are child elements of World and are located on the
same hierarchical level. P1 and P2 are child elements of Frame1 and are
located one level below it.

9.2.2 Designating a frame as a base

Description

Frames created in the application data can be marked as a base: hand

icon on the frame icon:
Only frames marked in this way can be selected and calibrated on the
smartHMI as a base for jogging after synchronization of the project.
(>>> 6.15.1 "“Jogging options” window" Page 99)
(>>> 7.4.2 "Base calibration: 3-point method " Page 146)
It is advisable to assign clear names to these frames to make it easier
for the operator to select the jogging base on the smartPAD.

Procedure

Via the context menu:

• Right-click on the desired frame in the Application data view and se-
lect the hand icon Base from the context menu.
Via the toolbar:
• Select the desired frame in the Application data view and click on
the hand icon Base.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 175/667

Project management KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Example

Fig. 9-2: Designating a frame as a base

1 Base hand icon

2 Base1 and Base2 are designated as the base

9.2.3 Moving a frame

Description

A frame can be moved in the application data and assigned to a new pa-
rent frame. The following points must be taken into consideration:
• The subordinate frames are automatically moved at the same time.
• The absolute position of the moved frames in space is retained. The
relative transformation of the frames to the new parent frame is adap-
ted.
• Frames cannot be inserted under one of their child elements.
• The names of the direct child elements of a frame must be unique.

If a frame is moved, its path changes. If this frame is used in the

source code of an application, the path specification must be corrected
accordingly in the application.

Procedure

1. Click on the desired frame in the Application data view and hold
down the left mouse button.
2. Drag the frame to the new parent frame with the mouse.
3. When the desired new parent frame is selected, release the mouse
button.

9.2.4 Deleting a frame

Description

Frames created in the application data can be removed from the frame
tree again. If a frame has child elements, the following options are availa-
ble:

176/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Project management
• Move children to parent: Only the selected frame is deleted. The
subordinate frames are retained, are moved up a level and assigned
to a new parent frame.
The absolute position of the moved frames in space is retained. The
relative transformation of the frames to the new parent frame is adap-
ted.
If a frame is moved, its path changes. If this frame is used in the
source code of an application, the path specification must be correc-
ted accordingly in the application.

• Delete parent and child frames: Deletes the selected frame and all
subordinate frames.

Procedure

1. Right-click on the frame to be deleted in the Application data view

and select Delete from the context menu.
2. If the frame has no child elements, the system asks whether it really
should be deleted. Answer the query with Delete.
3. If the frame has child elements, the system asks whether these should
also be deleted. Select the desired option:
• Move children to parent
• Delete parent and child frames
4. Only with the option Move children to parent: If a name conflict oc-
curs when moving the child elements, a notification message appears
and the delete operation is canceled.
Remedy: Rename one of the frames in question and repeat the delete
operation.

9.2.5 Displaying/editing frame properties

The position and orientation of a frame is generally defined during

teaching with the robot. However, it is also possible to enter the position
values of a frame manually or to change them at a later stage.
The following points must be taken into consideration:
• Modifying the transformation data not only moves the current frame,
but also all of its subordinate child elements. This affects all applica-
tions in which these frames are used.
• The taught values of Status, Turn and redundancy angle are re-
tained. Under certain circumstances, it may no longer be possible to
address the frame or its child elements.
• After a modification to the transformation data, all programs in which
the frame is used must be tested in Manual Reduced Velocity mode
(T1).

Description

The properties of frames are displayed in the Properties view, distributed

over various tabs. Some of the properties can be edited, others are for
display only.

Procedure

1. Select the desired frame in the Application data view. The properties
of the frame are displayed in the Properties view.
2. Edit the properties as required on the tabs.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 177/667

Project management KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

For physical variables, the values can be entered with the unit. If this is
compatible with the preset unit, the values are converted accordingly,
e.g. cm into mm or ° into rad. If no unit is entered, the preset unit is
used.

9.2.5.1 Frame properties – General tab

The General tab contains general information relating to the frame.

Parameter Description
Name Name of the frame
Comment A comment on the frame can be entered here
(optional).
Project Project in which the frame was created (display
only)
Last modification Date and time of the last modification (display
only)

9.2.5.2 Frame properties – Transformation tab

The Transformation tab contains the transformation data of the frame.

Parameter Description
X, Y, Z Translational offset of the frame relative to its
parent frame
A, B, C Rotational offset of the frame relative to its pa-
rent frame

If the transformation data of a frame that has been calibrated as a base

are edited, the calibration information is deleted.

9.2.5.3 Frame properties – Redundancy tab

The Redundancy tab contains the redundancy information relating to the

frame.
Parameter Description
E1 Value of the redundancy angle
(>>> 15.10.1 "Redundancy angle" Page 390)
Status (>>> 15.10.2 "Status" Page 390)
Turn (>>> 15.10.3 "Turn" Page 391)

9.2.5.4 Frame properties – Teach information tab

The Teach information tab contains information about a taught frame

(display only).
Parameter Description
Device Robot that was used for teaching
TCP Frame path for the TCP that was used for
teaching
Tool Tool that was used for teaching

178/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Project management
Parameter Description
X, Y, Z Translational offset of the TCP relative to the
origin frame of the tool
A, B, C Rotational offset of the TCP relative to the ori-
gin frame of the tool

If a frame that has been calibrated as a base is retaught, the calibration

information is deleted.

9.2.5.5 Frame properties – Measurement tab

The Measurement tab contains information about base calibration (for

frames marked as a base; display only).
Parameter Description
Measurement meth- Method used
od
Last modification Date and time of the last modification

If the data of a calibrated base are saved in Sunrise.Workbench by

means of synchronization, the transformation data of the frame change
in accordance with the calibration. The transformation data of the child
elements of the frame are not changed by the calibration, i.e. only the
position of the frame relative to the world coordinate system changes.
The redundancy information also remains unchanged.

9.2.6 Inserting a frame in a motion instruction

Description

A frame created in the application data can be inserted as the end point
in a motion instruction.

Procedure

1. Program the motion instruction, e.g. robot.move(ptp());.

2. In the Application data view, click on the frame which is to be used
as the end point and hold down the left mouse button.
3. Drag the frame to the editor area with the mouse and position it so
that the mouse pointer is between the brackets of the motion.
4. Release the mouse button. The frame is inserted as the end point of
the motion.

Example

robot.move(ptp(getApplicationData().getFrame("/P2/Target")));

The getApplicationData().getFrame(...) method indicates that a

frame created in the application data has been inserted. The end point of
the motion is the Target frame.
As the transfer parameter, the method receives the path of the frame in
the frame tree. The Target frame is a child element of P2.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 179/667

Project management KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

9.3 Object management

Description

Tools and workpieces can be created and managed as object templates in

Sunrise.Workbench. They belong to the runtime data of a project.

Tools

Properties:
• Tools are mounted on the robot flange.
• Tools can be used as movable objects in the robot application.
• The tool load data affect the robot motions.
• Tools can have any number of working points (TCPs) which are de-
fined as frames.

Workpieces

Characteristics:
• Workpieces can be a wide range of objects which are used, pro-
cessed or moved in the course of a robot application.
• Workpieces can be coupled to tools or other workpieces.
• Workpieces can be used as movable objects in the robot application.
• The workpiece load data affect the robot motions, e.g. when a gripper
grips the workpiece.
• Workpieces can have any number of frames which mark relevant
points, e.g. points on which a gripper grips a workpiece.

9.3.1 Geometric structure of tools

Every tool has an origin frame (root). As standard, the origin of the tool is
defined to match the flange center point in position and orientation when
the tool is mounted on the robot flange. The origin frame is always
present and does not have to be created separately.
A tool can have any number of working points (TCPs), which are defined
relative to the origin frame of the tool (root) or to one of its child elements.

Fig. 9-3: Examples of TCPs of tools

1 Guiding tool with 1 TCP 2 Gripper with 2 TCPs

180/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Project management
The transformation of the frames is static. For active tools, e.g. grippers,
this means that the TCP does not adapt to the current position of jaws
or fingers.

Fig. 9-4: Static TCP on a gripper

1 Gripper closed 2 Gripper open

9.3.2 Geometric structure of workpieces

Every workpiece has an origin frame (root). The origin frame is always
present and does not have to be created separately.
A workpiece can have any number of frames, which are defined relative
to the origin frame of the workpiece (root) or to one of its child elements.

Fig. 9-5: Examples of frames of workpieces

9.3.3 Creating a tool or workpiece

Description

Tools and workpieces created as object templates for a project can be

used in every robot application of the project.
The tools can be selected on the smartHMI for jogging after the project
has been synchronized.
(>>> 6.15.1 "“Jogging options” window" Page 99)

Procedure

1. Select the desired project in the Package Explorer view.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 181/667

Project management KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

2. Select the Object templates view.

3. To create a tool, right-click on the object type Tools and select Insert
new toolfrom the context menu. The object template for the tool is
created.
4. To create a workpiece, right-click on the object type Workpieces and
select Insert new workpiecefrom the context menu. The object tem-
plate for the workpiece is created.
5. The system automatically assigns an object name. It is advisable to
change the name in the object properties. (>>> 9.3.5 "Displaying/edit-
ing object properties" Page 183)
The object names must be unique. A descriptive name makes both
programming and orientation within the program easier.
6. Enter the load data in the object properties.
(>>> 9.3.4 "Entering load data" Page 182)

9.3.4 Entering load data

Description

Load data are all loads mounted on or connected to the robot flange.
They form an additional mass mounted on the robot which must also be
moved together with the robot.
The load data of tools and workpieces can be specified when the corre-
sponding object templates are created. If several tools and workpieces are
connected to the robot, the resulting total load is automatically calculated
from the individual load data.
The load data are integrated into the calculation of the paths and acceler-
ations. Correct load data are an important precondition for the optimal
functioning of the servo control and help to optimize the cycle times.
WARNING
Danger to life and limb due to incorrect loads
Operating a robot with incorrect loads may result in death, severe inju-
ries or damage to property. For example, the braking procedure may
take too long with incorrect load data.
• Use only loads that are permissible for the robot.
• Use correct load data.

Sources

Load data can be obtained from the following sources:

• Manufacturer information
• Manual calculation
• CAD programs
• The load data of tools can be determined automatically.
(>>> 7.5 "Determining tool load data" Page 148)

Procedure

1. In the Object templates view, select the desired tool or workpiece.

2. In the Properties view, select the Load data tab and enter the load
data.
(>>> 9.3.5.2 "Object properties – Load data tab" Page 183)

182/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Project management
9.3.5 Displaying/editing object properties

Description

The properties of object templates are displayed in the Properties view,

distributed over various tabs. Some of the properties can be edited, others
are for display only.

Procedure

1. Select the object template in the Object templates view. The proper-
ties of the object template are displayed in the Properties view.
2. Edit the properties as required on the tabs.

For physical variables, the values can be entered with the unit. If this is
compatible with the preset unit, the values are converted accordingly,
e.g. cm into mm or ° into rad. If no unit is entered, the preset unit is
used.

9.3.5.1 Object properties – General tab

The General tab contains general information about the tool or workpiece.
Parameter Description
Name Name of the tool or workpiece
The name can be edited.
Template class Runtime class of the tool or workpiece
The class of the template can be edited.
Comment Comment for the tool or workpiece (optional)
Frame Frame of the tool or workpiece that is to be
moved as standard
As standard, the origin frame of the tool or
workpiece is used as the standard frame for
motions.
Here, a different frame can be selected as the
standard frame for motions, provided that a
suitable frame has already been created for the
tool or workpiece.
(>>> 9.3.6 "Creating a frame for a tool or work-
piece" Page 184)

9.3.5.2 Object properties – Load data tab

The load data of tools and workpieces can be entered on the Load data
tab.
Parameter Description
Mass Mass of the tool or workpiece
Center of mass Position of the center of mass relative to the
origin frame of the tool or workpiece

• MS X: X coordinate of the center of mass

• MS Y: Y coordinate of the center of mass
• MS Z: Z coordinate of the center of mass

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 183/667

Project management KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Parameter Description
Principal inertia axes Orientation of the principal inertia axes relative
to the origin frame of the tool or workpiece

• MS A: orientation of the Z axis

• MS B: orientation of the Y axis
• MS C: orientation of the X axis
The principal inertia axes run through the cen-
ter of mass.
Principal moments Mass moments of inertia about the principal in-
of inertia ertia axes of the tool or workpiece

• jX: moment of inertia about the X axis

• jY: moment of inertia about the Y axis
• jZ: moment of inertia about the Z axis

Example

Principal moment of inertia jX:

jX is the inertia about the X axis of the principal inertia axes. This is rota-
ted through MS A, MS B and MS C relative to the origin frame of a tool
and shifted in the center of mass.
jY and jZ are the analogous principal moments of inertia about the Y and
Z axes.

9.3.6 Creating a frame for a tool or workpiece

Description

Each frame created for a tool or workpiece can be programmed in the ro-
bot application as the reference point for motions.
After the project is synchronized, the frames of a tool can be selected as
the TCP for Cartesian jogging on the smartHMI.
(>>> 6.15.1 "“Jogging options” window" Page 99)
The frames of a tool (TCPs) can be calibrated with robot relative to the
flange coordinate system.
(>>> 7.4.1 "Tool calibration" Page 140)
If the data of a calibrated tool are saved in Sunrise.Workbench by means
of synchronization, the transformation data of the frame change in accord-
ance with the calibration.
The tool data of the TCP used to execute a Cartesian motion influence
the robot velocity. Incorrectly entered tool data can cause unexpectedly
high Cartesian velocities at the installed tool. The velocity of 250 mm/s
may be exceeded in T1 mode.

Procedure

1. Select the desired project in the Package Explorer view.

2. Right-click on the desired object template in the Object templates
view and select Insert new frame from the context menu. The frame
is created.
At the top hierarchy level, the parent frame of the created frame is the
origin frame of the object.

184/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Project management
3. To insert a new frame under an existing frame of the object, right-click
on this parent frame and select Insert new frame from the context
menu. The frame is created.
4. The system automatically generates a frame name. It is advisable to
change the name in the frame properties. (>>> 9.3.7 "Displaying/edit-
ing frame properties" Page 185)
A descriptive frame name makes both programming and orientation
within the program easier. The frame names must be unique within
the hierarchy level and may not be assigned more than once.
5. In the frame properties, enter the transformation data of the frame rel-
ative to its parent frame:
• Boxes X, Y, Z: offset of the frame along the axes of the parent
frame
• Boxes A, B, C: orientation of the frame relative to the parent frame
(>>> 9.3.7 "Displaying/editing frame properties" Page 185)

9.3.7 Displaying/editing frame properties

Description

The properties of frames are displayed in the Properties view, distributed

over various tabs. Some of the properties can be edited, others are for
display only.

Procedure

1. Select the desired frame in the Object templates view. The properties
of the frame are displayed in the Properties view.
2. Edit the properties as required on the tabs.

For physical variables, the values can be entered with the unit. If this is
compatible with the preset unit, the values are converted accordingly,
e.g. cm into mm or ° into rad. If no unit is entered, the preset unit is
used.

9.3.7.1 Frame properties – General tab

The General tab contains general information relating to the frame.

Parameter Description
Name Name of the frame
Comment A comment on the frame can be entered here
(optional).

9.3.7.2 Frame properties – Transformation tab

The Transformation tab contains the transformation data of the frame.

The value ranges apply to safety-oriented frames. Frames with transfor-
mation data outside this range of values cannot be used as safety-orien-
ted frames.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 185/667

Project management KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Parameter Description
X, Y, Z Translational offset of the frame relative to its
parent frame

• -10,000 mm … +10,000 mm
A, B, C Rotational offset of the frame relative to its pa-
rent frame

• Any

If the transformation data of a frame that is used as the TCP of a cali-

brated tool are edited, the calibration information is deleted.

9.3.7.3 Frame properties – Measurement tab

The Measurement tab contains information about tool calibration (display

only).
Parameter Description
Measurement meth- Method used
od
Calculation error Translational or rotational calculation error
which specifies the quality of the calibration
(unit: mm or °)
Last modification Date and time of the last modification

If the transformation data of a calibrated tool are edited, the calibration

information is deleted.

9.3.7.4 Frame properties – Safety tab

The Safety tab is only available for tools and frames of tools. The follow-
ing properties of safety-oriented tool frames can be configured:
Parameter Description
Radius Radius of the sphere on the safety-oriented
frame

• 25 … 10,000 mm
Provided that the check box for the property
Safety-oriented is activated and the frame be-
longs to a safety-oriented tool, the sphere on
the safety-oriented frame is active and can be
used in the AMFs for monitoring Cartesian
spaces and velocities.
Safety-oriented Activation as safety-oriented frame

• Check box active: Frame is a safety-orien-

ted frame.
• Check box not active: Frame is not a safe-
ty-oriented frame.
Precondition for activating the check box:

• A permissible value has been entered for

the radius.

186/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Project management
Parameter Description
Is point for the tool- Use of the safety-oriented frame as a point for
related velocity com- the Tool-related velocity component AMF
ponent AMF
• Check box active: Frame is used as a point
for the AMF.
• Check box not active: Frame is not used as
a point for the AMF.
Precondition for activating the check box:

• The check mark is set at Safety-oriented.

• The frame belongs to a safety-oriented tool.

9.3.8 Defining a default motion frame

Description

As standard, the origin frame of an object template is used as the default

frame for motions.
Any other suitable frame can be defined as the default frame for motions,
e.g. if a tool or workpiece has a frame with which a large part of the mo-
tions must be executed. This simplifies motion programming.
(>>> 16.10.3 "Moving tools and workpieces" Page 439)
The default frame used for motions is indicated with an icon in the Ob-
ject templates view.

Procedure

Via the context menu:

• Right-click on the desired frame of the object template in the Object
templates view and select Default motion frame from the context
menu.
Via the toolbar:
• Select the desired frame of the object template in the Object tem-
plates view and click on the Default motion frame icon.
In the properties of the object template:
1. Select the object template in the Object templates view.
2. In the Properties view, select the General tab and set the frame that
is to be moved as standard.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 187/667

Project management KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Example

Fig. 9-6: Default frame for motions

1 Default motion frame icon

2 Default frame of the Gripper tool: TCP_1
3 Default frame of the WeldGun tool: Origin frame

9.3.9 Copying an object template

Description

When an object template is copied, a copy of the object templates includ-

ing all frames is created. The properties of the object template and its
frames, with the exception of the safety properties, are included in the
copy.

Procedure

• Right-click on the object template in the Object templates view and

select Create copy from the context menu.

9.3.10 Configuring a safety-oriented tool

Description

Up to 50 safety-oriented tools can be defined in a Sunrise project. Just

like any other tool, a safety-oriented tool can have any number of frames.
In order to configure the safety-oriented tool, suitable frames must be de-
fined as safety-oriented frames (max. 6). The monitoring spheres that
model the safety-oriented tool are configured at these frames:
• The center of the sphere is situated, by definition, at the origin of the
safety-oriented frame.
• The radius of the sphere is defined in the frame properties.

Monitoring functions

Safety-oriented tools are relevant for the following safety monitoring func-
tions:

188/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Project management
• Monitoring of Cartesian spaces
The spheres can be monitored against the limits of activated Cartesian
monitoring spaces.
(>>> 13.11.9 "Monitoring spaces" Page 300)
• Monitoring of the translational Cartesian velocity
The velocity of the sphere center points is monitored.
(>>> 13.11.8 "Velocity monitoring functions" Page 293)
• Collision detection and TCP force monitoring functions
Only correctly specified load data ensure the accuracy of these moni-
toring functions. The load data of safety-oriented tools, in particular the
mass and center of mass of the tools, must be configured. In the case
of tools with comparatively high moments of inertia (> 0.1 kg m2),
these data must also be specified in order to ensure the accuracy of
these monitoring functions.
(>>> 13.11.13.2 "Collision detection" Page 314)
(>>> 13.11.13.3 "TCP force monitoring" Page 316)
(>>> 13.11.13.4 "Direction-specific monitoring of the external force on
the TCP" Page 317)

If workpieces are used that are to be taken into consideration for safety-
oriented Cartesian space or velocity monitoring, e.g. due to the dimen-
sions of the workpieces, the spheres of the safety-oriented tool must be
configured accordingly.

Safety-oriented frames can additionally be defined for the following tool-

specific safety monitoring functions:
• Monitoring of the tool orientation (only available for robots)
One of the safety-oriented frames can be defined as the tool orienta-
tion frame. Safety-oriented monitoring of the orientation of this frame
can be carried out.
(>>> 13.11.10 "Monitoring the tool orientation" Page 308)
• Monitoring of the tool-related velocity component (available for robots
and mobile platforms)
Up to 6 safety-oriented frames of a safety-oriented tool can be defined
as monitoring points for the tool-related velocity monitoring. A safety-
oriented frame can additionally be defined as the orientation for the
monitoring. This orientation frame defines the orientation of the coordi-
nate system in which the velocity of the monitoring points is described.
In tool-related velocity monitoring, a component of this velocity can be
monitored.
(>>> 13.11.8.3 "Direction-specific monitoring of Cartesian velocity"
Page 297)

Precondition

• Tool and corresponding frames have been created.

• When using the AMFs Collision detection, TCP force monitoring and
Base-related TCP force component: The correct load data of the tool,
in particular the mass and center of mass of the tool, are known.

Procedure

1. Select the desired project in the Package Explorer view.

2. In the Object templates view, select the tool that is to be safety-orien-
ted.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 189/667

Project management KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

3. In the Properties view, select the Safety tab and activate the Safety-
oriented check box.
The tool icon in the Object templates view is highlighted in yellow
and marked with a sphere symbol .
4. Select the Load data tab and enter any missing tool load data.
Tools with load data outside the specified range of values cannot be
used as safety-oriented tools.
(>>> 9.3.10.1 "Tool properties – Load data tab" Page 191)
To avoid spending unnecessary time performing verifications, mark a
tool as safety-oriented only when the load data have been correctly
entered or determined and have been transferred to Sunrise.Work-
bench. (>>> 9.3.4 "Entering load data" Page 182)

5. In the Object templates view, select the tool frame that is to be safe-
ty-oriented.
6. In the Properties view, select the Transformation tab and enter any
missing transformation data of the frame with respect to its parent
frame.
Frames with transformation data outside the specified range of values
cannot be used as safety-oriented frames.
(>>> 9.3.10.2 "Frame properties – Transformation tab" Page 191)
7. Select the Safety tab and enter the radius of the monitoring sphere on
the safety-oriented frame.
(>>> 9.3.10.3 "Frame properties – Safety tab" Page 192)
8. Set the check mark at Safety-oriented.
The frame icon in the Object templates view is highlighted in yellow
.
9. If the safety-oriented frame is to be used as a point for the Tool-rela-
ted velocity component AMF, activate the check box next to Is point
for the tool-related velocity component AMF.
Safety-oriented frames that are used for tool-specific safety monitoring
functions are additionally marked with a symbol in the Object tem-
plates view.
10. Repeat steps 5 to 9 to define further safety-oriented tool frames.
11. In the safety properties of the tool, set the safety-oriented frames that
are to be used for the tool-specific safety monitoring functions if re-
quired:
a. Select the safety-oriented tool in the Object templates view.
b. In the Properties view, select the Safety tab.
c. Under Safety properties assign the desired safety-oriented frames
to the tool-specific safety monitoring functions.
(>>> 9.3.10.4 "Tool properties – Safety tab" Page 192)
Safety-oriented frames that are used for tool-specific safety monitoring
functions are additionally marked with a symbol in the Object tem-
plates view.

Alternative procedure

The properties of safety-oriented tools and frames can also be set via the
context menu:
• Right-click on the tool or frame in the Object templates view and se-
lect the desired property from the context menu.

190/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Project management
‒ Safety-oriented
‒ Tool orientation frame
‒ Orientation for tool-related velocity
‒ Point for tool-related velocity
‒ The menu item is only available for frames.

Example

For a safety-oriented gripper, 3 monitoring spheres are configured.

Fig. 9-7: Safety-oriented gripper

9.3.10.1 Tool properties – Load data tab

The Load data tab contains the load data of the tool.
The value ranges apply to safety-oriented tools. Tools with load data out-
side these ranges of values cannot be used as safety-oriented tools.
Parameter Description
Mass Mass of the tool

• 0 … 2,000 kg
MS X, MS Y, MS Z Position of the center of mass relative to the
origin frame of the tool

• -10,000 … +10,000 mm
MS A, MS B, MS C Orientation of the principal inertia axes relative
to the origin frame of the tool

• Any
jX, jY, jZ Mass moments of inertia of the tool

• 0 … 1,000 kg·m2

9.3.10.2 Frame properties – Transformation tab

The Transformation tab contains the transformation data of the frame.

The value ranges apply to safety-oriented frames. Frames with transfor-
mation data outside this range of values cannot be used as safety-orien-
ted frames.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 191/667

Project management KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Parameter Description
X, Y, Z Translational offset of the frame relative to its
parent frame

• -10,000 mm … +10,000 mm
A, B, C Rotational offset of the frame relative to its pa-
rent frame

• Any

If the transformation data of a frame that is used as the TCP of a cali-

brated tool are edited, the calibration information is deleted.

9.3.10.3 Frame properties – Safety tab

The Safety tab is only available for tools and frames of tools. The follow-
ing properties of safety-oriented tool frames can be configured:
Parameter Description
Radius Radius of the sphere on the safety-oriented
frame

• 25 … 10,000 mm
Provided that the check box for the property
Safety-oriented is activated and the frame be-
longs to a safety-oriented tool, the sphere on
the safety-oriented frame is active and can be
used in the AMFs for monitoring Cartesian
spaces and velocities.
Safety-oriented Activation as safety-oriented frame

• Check box active: Frame is a safety-orien-

ted frame.
• Check box not active: Frame is not a safe-
ty-oriented frame.
Precondition for activating the check box:

• A permissible value has been entered for

the radius.
Is point for the tool- Use of the safety-oriented frame as a point for
related velocity com- the Tool-related velocity component AMF
ponent AMF
• Check box active: Frame is used as a point
for the AMF.
• Check box not active: Frame is not used as
a point for the AMF.
Precondition for activating the check box:

• The check mark is set at Safety-oriented.

• The frame belongs to a safety-oriented tool.

9.3.10.4 Tool properties – Safety tab

The safety-oriented tool can be configured on the Safety tab.

192/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Project management
Parameter Description
Safety-oriented Activation as safety-oriented tool

• Check box active: The tool is a safety-oriented tool

• Check box not active: The tool is not a safety-oriented
tool
Tool orientation frame Safety-oriented frame, the orientation of which can be moni-
tored using the AMF Tool orientation.
If no tool orientation frame is defined, the pickup frame of the
tool is used as the tool orientation frame.
(>>> "Pickup frame" Page 193)
Points for the velocity Display of the safety-oriented frames defined in the frame
properties as points for the Tool-related velocity component
AMF.
If no safety-oriented frame has been defined as a point for
the tool-related velocity component, the following entry is dis-
played:

• DEFAULT: /
In this case, the pickup frame of the tool is used and the ve-
locity at the origin of the pickup frame is monitored.
(>>> "Pickup frame" Page 193)
Orientation for the velocity Safety-oriented frame, the orientation of which determines the
directions in which the Cartesian velocity can be monitored
using the Tool-related velocity component AMF.
If no orientation frame is defined for the tool-related velocity
component, the pickup frame of the tool is used. The orienta-
tion of the pickup frame determines the monitoring direction.
(>>> "Pickup frame" Page 193)

Pickup frame

The pickup frame of a tool is dependent on the kinematic system on

which it is mounted and on the tool configuration:
• The tool is mounted on the robot flange: the pickup frame is the
flange coordinate system of the robot.
• The tool is mounted on a mobile platform: the pickup frame is the co-
ordinate system at the center point of the platform.
• The tool is mounted on a fixed tool: the pickup frame is the standard
frame for motions of the fixed tool.

9.3.11 Safety-oriented use of workpieces

Description

Loads picked up by the robot, e.g. a gripped workpiece, exert an addition-

al force on the robot and influence the torques measured by the axis tor-
que sensors.
The following AMFs require the workpiece load data for calculation of the
external forces and torques:
• TCP force monitoring
(>>> 13.11.13.3 "TCP force monitoring" Page 316)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 193/667

Project management KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

• Base-related TCP force component

(>>> 13.11.13.4 "Direction-specific monitoring of the external force on
the TCP" Page 317)
• Collision detection
(>>> 13.11.13.2 "Collision detection" Page 314)

Programming

If one of these load-specific AMFs is active and workpieces are picked up

at the same time, the current workpiece must be transferred to the safety
controller. For this, the KUKA RoboticsAPI offers the method setSafety-
Workpiece().
(>>> 16.10.5 "Transferring workpiece load data to the safety controller"
Page 443)
Once the workpiece has been transferred, the workpiece load data are
taken into consideration by the safety controller. A load change, e.g. if a
workpiece is set down again, must also be communicated with setSafety-
Workpiece(…).

Requirements

The workpiece transferred to the safety controller must meet the following
requirements:
• The workpiece load data must be within the specified limits. If this is
not the case, the load data are invalid and cannot be transferred to
the safety controller.
(>>> 9.3.11.2 "Workpiece properties – Load data tab" Page 195)
• In order to be able to use workpieces as safety-oriented workpieces,
the mass of the heaviest workpiece that could possibly be picked up
by the robot must additionally be configured in the safety-oriented
project settings.
(>>> 9.3.11.3 "Configuring the mass of the heaviest workpiece"
Page 196)
The mass from the workpiece load data must not exceed the config-
ured mass of the heaviest workpiece. Otherwise, load-specific AMFs
are violated.

Workpiece pick-up

The way in which the load data of a workpiece influence the workpiece
load-dependent AMFs depends on how the workpiece is picked up. For a
workpiece, the safety controller requires the origin frame of the workpiece
to be identical to the standard frame for motions of the safety-oriented
tool.

Fig. 9-8: Configuration of workpiece pick-up

194/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Project management
Item Description
1 Safety-oriented tool
2 Standard frame for motions of the safety-oriented tool:
Frame of the safety-oriented tool on which the workpiece must
be picked up. It is not necessary for this frame to be a safety-
oriented frame.
3 Origin frame of the workpiece
Frame of the workpiece on which the safety-oriented tool must
pick up the workpiece.
4 Workpiece
5 Status after transfer of the workpiece to the safety controller
The origin frame of the workpiece is identical to the standard
frame for motions of the safety-oriented tool.

9.3.11.1 Entering workpiece load data

Precondition

• Workpiece has been created.

• When using the AMFs Collision detection, TCP force monitoring and
Base-related TCP force component: The correct load data of the work-
piece, in particular the mass and center of mass of the workpiece, are
known.

Procedure

1. Select the desired project in the Package Explorer view.

2. Select the workpiece in the Object templates view.
3. Select the Load data tab and enter the workpiece load data.
(>>> 9.3.11.2 "Workpiece properties – Load data tab" Page 195)
Once the project has been synchronized, the workpiece can be used in
the application.

9.3.11.2 Workpiece properties – Load data tab

The workpiece load data can be entered on the Load data tab.
The value ranges apply for workpieces that are used as safety-oriented
workpieces. Workpieces with load data outside these ranges of values
cannot be used as safety-oriented workpieces.
Parameter Description
Mass Mass of the workpiece

• 0.001 … 2,000 kg
MS X, MS Y, MS Z Position of the center of mass relative to the
origin frame of the workpiece

• -10,000 … +10,000 mm
MS A, MS B, MS C Orientation of the principal inertia axes relative
to the origin frame of the workpiece

• 0° … 359°

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 195/667

Project management KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Parameter Description
jX, jY, jZ Mass moments of inertia of the workpiece

• 0 … 1,000 kg·m2

9.3.11.3 Configuring the mass of the heaviest workpiece

Description

If the following load-specific AMFs are used, the mass of the heaviest
workpiece that could possibly be picked up by the robot must be config-
ured in the safety-oriented project settings:
• TCP force monitoring
• Base-related TCP force component
• Collision detection
Each of the load-specific AMFs checks whether the workpiece mass trans-
ferred to the safety controller with the load data exceeds the configured
mass of the heaviest workpiece. If the mass of the heaviest workpiece is
not configured, it is initialized with the default value (= 0.0 kg) and the
AMF is violated if the workpiece load data from the safety controller are
used.
Incorrect configuration of the mass of the heaviest workpiece can result
in loss of the safety integrity with the following AMFs:
• TCP force monitoring
• Base-related TCP force component
The configuration must therefore be verified during safety acceptance.
(>>> 13.14.7.4 "Mass of the heaviest workpiece" Page 357)

Procedure

1. Right-click on the desired project in the Package Explorer view and

select Sunrise > Change project settings from the context menu.
The Properties for [Sunrise Project] window opens.
2. Select Sunrise > Safety in the directory in the left area of the window.
3. Enter the mass of the heaviest workpiece under Heaviest workpiece
in the right-hand area of the window:
• 0.0 … 2000.0 kg
4. Click on OK to apply the settings and close the window.

9.4 User administration

Different functions can be executed on the robot controller, depending on

the user group. The passwords of the user groups are managed in the
project settings.
The following user groups are available as standard:
• Administrator
Only available in Sunrise.Workbench. The Administrator manages the
passwords of the user groups.
The user group is protected by means of a password.
The default password is “kuka”.
• Operator
The user group “Operator” is the default user group.

196/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Project management
• Safety maintenance technician
The user “Safety maintenance” is responsible for starting up the safety
equipment of the industrial robot. Only he can modify the safety con-
figuration on the robot controller.
The user group is protected by means of a password.
The default password is “argus”.

Prior to start-up, the passwords for the user groups must be modified by
the administrator, transferred to the robot controller in an installation pro-
cedure and activated. The passwords must only be communicated to
authorized personnel. (>>> 9.4.2 "Changing and activating the pass-
word" Page 198)

If the administrator password is forgotten, KUKA Service must be noti-

fied and restore the default passwords. After this, the passwords must
be reassigned.

9.4.1 Overview of Sunrise.RolesRights

Description

Sunrise.RolesRights is an add-on option package that expands the user

groups available as standard to include the user group Expert. At the
same time, the rights of the user groups are reassigned.

User groups

The following user groups are available with Sunrise.RolesRights:

• Administrator
Only available in Sunrise.Workbench. The Administrator manages the
passwords of the user groups.
The user group is protected by means of a password.
The default password is “kuka”.
• Operator
The user group “Operator” is the default user group.
• Expert
Additional protected functions, that may not be performed by the “Op-
erator”, are available to the user group “Expert”.
The user group is protected by means of a password.
The default password is “kuka”.
• Safety maintenance technician
The user “Safety maintenance” is responsible for starting up the safety
equipment of the industrial robot. All functions of the user group “Ex-
pert” are available to the user group “Safety maintenance”. Users in
this user group can additionally modify the safety configuration on the
robot controller.
The user group is protected by means of a password.
The default password is “argus”.

Prior to start-up, the passwords for the user groups must be modified by
the administrator, transferred to the robot controller in an installation pro-
cedure and activated. The passwords must only be communicated to
authorized personnel. (>>> 9.4.2 "Changing and activating the pass-
word" Page 198)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 197/667

Project management KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Functions

Depending on the installed software, the users can execute the following
functions:
Installation of Sunrise.RolesRights restricts the user rights of the opera-
tor.

Basic software functions in Sunrise.Workbench:

Safety mainte-
Function Operator Expert
nance
Installing the system software on
the robot controller
Synchronizing a project with un-
changed safety configuration
Synchronizing a project with
changed safety configuration
Basic software functions on smartHMI:
Safety mainte-
Function Operator Expert
nance
Confirming installation of the system
software on the robot controller
Selecting/deselecting an application

Pausing an application

Moving the robot manually

Selecting an operating mode (T1,

T2, CRR, AUT)
Activating/deactivating/resetting the
safety configuration
Changing the value of an output

Teaching frames

Creating a new frame

Robot mastering/unmastering

Sunrise.BackupRestore functions on smartHMI:

Safety mainte-
Function Operator Expert
nance
Backing up data manually

Restoring data manually

9.4.2 Changing and activating the password

Description

The passwords for the user groups on the robot controller are defined in
the project settings in Sunrise.Workbench. If these passwords are
changed, they can only be activated by an installation of the system soft-
ware on the robot controller.

198/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Project management
The Administrator merely manages the passwords in Sunrise.Work-
bench. If only the Administrator password is modified, no installation is
required. The modified Administrator password takes effect immediately
and is saved as part of the project on the robot controller.

If the administrator password is forgotten, KUKA Service must be noti-

fied and restore the default passwords. After this, the passwords must
be reassigned.

Precondition

• Administrator user group

• Network connection to the robot controller

Procedure

1. Right-click on the desired project in the Package Explorer view and

select Sunrise > Change project settings from the context menu.
The Properties for [Project] window opens.
2. Select Sunrise > Passwords in the directory in the left area of the
window.
3. Click on Login and enter the Administrator password. Confirm the
password with OK.
4. Select the user group for which the password is to be changed.
5. Enter the new password twice.
For security reasons, the entries are displayed encrypted. Upper and
lower case are distinguished.
The password must consist of at least one character. Only charac-
ters that can be entered via the smartHMI are permissible.

6. Click on Save and close the window.

7. Install the system software on the robot controller. The modified pass-
words are active after the reboot of the robot controller.

9.5 Project synchronization

In project synchronization, project data are transferred between Sun-

rise.Workbench and the robot controller. In the process, the projects are
compared with one another. If there are different projects or version con-
flicts, the user can choose the direction in which to transfer the project da-
ta.
The following cases are distinguished:
• There is no project on the robot controller yet or there is a different
project from the one to be transferred
(>>> 9.5.1 "Transferring a project to the robot controller" Page 200)
• The same project exists on the robot controller and in Sunrise.Work-
bench but in different versions, e.g.:
‒ When the project data are modified in Sunrise.Workbench only
‒ When the project data are modified on the robot controller only
‒ When the project data are modified on both sides
(>>> 9.5.2 "Updating the project" Page 201)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 199/667

Project management KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

9.5.1 Transferring a project to the robot controller

Description

The procedure described here applies if no project is on the robot control-

ler yet or if there is a different project from the one to be transferred.

Precondition

• Network connection to the robot controller

• The system software is installed.
• The installed system software is compatible with the station configura-
tion of the project to be transferred.
• No running or paused application on the robot controller:
• If the Sunrise.RolesRights option package is installed and active on
the robot controller, a user with the right to carry out the installation
must be logged on.
(>>> 9.4.1 "Overview of Sunrise.RolesRights" Page 197)

Procedure

1. Select the desired project in the Package Explorer view.

2. Click on the Synchronize project button.
The system scans the robot controller for existing project data. If the
scan fails, the cause of the error is displayed in a message.
3. If the scan is successful, the Project synchronization window opens.
Click on Execute.

Fig. 9-9: Transferring the project to the controller

4. If a new/modified I/O configuration and/or a new/modified safety con-

figuration is transferred with the project, a dialog opens in which the
following points are indicated, depending on the change:
• Modified I/O configuration: after project deployment, the robot con-
troller must be restarted.
• Modified safety configuration: after project deployment or after the
restart, the new safety configuration must be activated.
To continue the transfer, click on OK.
5. If the Sunrise.RolesRights option package is installed and active on
the robot controller, a dialog opens to authorize the synchronization
procedure.
The required user group is preset. Enter the password and confirm
with OK.
6. The progress of the project transfer is displayed in Sunrise.Workbench
and on the smartPAD.

200/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

If the transfer fails, a corresponding dialog is displayed in Sun-

Project management
rise.Workbench and on the smartPAD. In addition, the cause of the er-
ror is displayed in Sunrise.Workbench.
Close the dialog in Sunrise.Workbench and on the smartPAD with OK.
7. Only in the case of transfer of a modified I/O configuration:
Once the transfer is completed, the robot controller automatically re-
boots.
8. Only in the case of transfer of a modified safety configuration:
Activate the new safety configuration on the robot controller.
(>>> 13.10 "Activating the safety configuration" Page 284)

9.5.2 Updating the project

Description

The procedure described here applies if the same project exists in Sun-
rise.Workbench and on the robot controller, but in different versions.

Precondition

• Network connection to the robot controller

• If a project is transferred to the robot controller: No running or paused
application on the robot controller:
• If the Sunrise.RolesRights option package is installed and active on
the robot controller, a user with the right to carry out the installation
must be logged on.
(>>> 9.4.1 "Overview of Sunrise.RolesRights" Page 197)

Procedure

1. Select the desired project in the Package Explorer view.

2. Click on the Synchronize project button.
The system scans the robot controller for existing project data. If the
scan fails, the cause of the error is displayed in a message.
3. If the project in Sunrise.Workbench is identical to the project on the ro-
bot controller, a dialog indicates that no project synchronization is nec-
essary. Confirm the dialog with OK. Project synchronization is aborted.
4. If the scan is successful, the Project synchronization window opens.

Fig. 9-10: Updating a project

Information is displayed for both projects. As standard, the direction of

synchronization is set to transfer the more recent project version.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 201/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

If modifications have been made to the project data on both sides, the
Project management

system recognizes this as a conflict and displays a warning. The direc-

tion of synchronization can be set:
• Check mark activated at Deploy to controller: the project is trans-
ferred from Sunrise.Workbench to the robot controller.
• Check mark activated at Load to local project: the project is
transferred from the robot controller to Sunrise.Workbench.
5. If required, change the direction of synchronization.
6. Click on Execute.
7. Only in the case of transfer to the robot controller:
If a new/modified I/O configuration and/or a new/modified safety con-
figuration is transferred with the project, a dialog opens in which the
following points are indicated, depending on the change:
• Modified I/O configuration: after project deployment, the robot con-
troller must be restarted.
• Modified safety configuration: after project deployment or after the
restart, the new safety configuration must be activated.
To continue the transfer, click on OK.
8. If the Sunrise.RolesRights option package is installed and active on
the robot controller, a dialog opens to authorize the synchronization
procedure.
The required user group is preset. Enter the password and confirm
with OK.
9. The progress of the project transfer is displayed in Sunrise.Workbench
and on the smartPAD.
If the transfer fails, a corresponding dialog is displayed in Sun-
rise.Workbench and on the smartPAD. In addition, the cause of the er-
ror is displayed in Sunrise.Workbench.
Close the dialog in Sunrise.Workbench and on the smartPAD with OK.
10. Only in the case of transfer to the robot controller with a modified I/O
configuration:
Once the transfer is completed, the robot controller automatically re-
boots.
11. Only in the case of transfer to the robot controller with a modified
safety configuration:
Activate the new safety configuration on the robot controller.
(>>> 13.10 "Activating the safety configuration" Page 284)

9.6 Loading the project from the robot controller

Description

A project can be loaded from the robot controller if the project is not loca-
ted in the workspace of Sunrise.Workbench.

Precondition

• Network connection to the robot controller

• The workspace does not contain any project with the name of the
project to be loaded.

Procedure

1. Select the menu sequence File > New > Sunrise project. The project
creation wizard opens.

202/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Project management
2. Enter the IP address of the robot controller from which the project is
to be loaded in the IP address of controller: box.
The IP address of the robot controller can be displayed on the
smartHMI. (>>> 6.19.6 "Displaying information about the robot and
robot controller" Page 124)

3. Select the Load project from controller option.

4. Click on Next >. The system checks whether there is a project on the
robot controller.
5. If there is a project is on the robot controller and there is no project
with the same name in the workspace, a summary of information on
the project is displayed.
Click on Finish. The project is created in the workspace and then dis-
played in the Package Explorer.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 203/667

Project management KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

204/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Station configuration and installation

10 Station configuration and installation

10.1 Station configuration overview

Description

The file StationSetup.cat contains the station configuration of the project.

The station configuration can be edited and installed using the following
tabs:

Topology

The Topology tab displays the hardware components of the station. The
topology can be restructured or modified.

Software

The Software tab displays the software catalog of Sunrise.Workbench.

Catalog elements to be installed or uninstalled in the project can be selec-
ted here.
The elements that can be selected depend on the topology and the option
packages installed in Sunrise.Workbench.

Configuration

The Configuration tab displays the configuration of the robot controller.

The configuration can be changed. The parameters that can be configured
depend on the topology and the installed option packages.
• IP address and subnet mask of the robot controller
• IP address range for KUKA Line Interface (KLI)
• Application settings
‒ Allow debugging of applications
• Handguiding support
• General safety settings
‒ smartPAD unplugging allowed
• Parameters for calibration
• I/O handling
‒ disable I/O access in EMERGENCY STOP
• Show confirmation dialog on installation
• Type of media flange (if present on robot)
• Mounting orientation (default: floor-mounted installation)

If additional option packages are installed and used in the project, fur-
ther parameters may be added to the Configuration tab.

Installation

The system software is installed on the robot controller via the Installa-
tion tab.

Procedure

Open the station configuration:

1. In the Package Explorer view, open the node of the project that is to
be configured.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 205/667

Station configuration and installation KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

2. Double-click on the file StationSetup.cat. The file is opened in the ed-

itor.

10.2 Adapting the network settings

Description

The development computer with KUKA Sunrise.Workbench is connected

to the robot controller via the KLI. A prerequisite for communication via
the network is that the IP addresses of the development computer and ro-
bot controller are in the same address range. For this, the network set-
tings must be adapted.
Example:

• Robot controller (default): 172.31.1.147

• Laptop/PC: 172.31.1.148
• Subnet mask: 255.255.0.0

Procedure

1. Open the Network and Sharing Center via the Windows Control Panel
or Windows Explorer.
2. In the top left-hand area, click the Change adapter settings entry.
The network connections are displayed.
3. Right-click on Local Area Connection and select Properties in the
context menu. The Local Area Connection Properties window is
opened.
4. Double-click on Internet Protocol Version 4 (TCP/IPv4). The Internet
Protocol Version 4 (TCP/IPv4) Properties window is opened.
5. Carry out the desired IP address settings, e.g.:

Fig. 10-1: IP address settings of the LAN connection

6. Close the window by clicking on OK.

206/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Station configuration and installation

10.3 “Software” tab

10.3.1 Eliminating errors in the software catalog

Description

A software catalog containing errors prevents installation of the System

Software on the robot controller. The errors must be eliminated before in-
stallation.
Possible causes of errors are:

• Missing reference to a catalog element

Some catalog elements are dependent on others. If a catalog element
that is required by another one is deselected in the software catalog
or removed by being uninstalled, the remaining catalog element is
marked in red.
• Catalog element used, but not installed
If a catalog element that is not installed in Sunrise.Workbench is used
in a project, this catalog element is indicated and marked in red.

Example

This example describes the options for elimination of errors.

Fig. 10-2: Error display in the software catalog

1 Missing reference to a catalog element

2 Catalog element used, but not installed

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 207/667

Station configuration and installation KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Item Description
1 The catalog element Handguiding Support is not available be-
cause the catalog element Robotics API has been deselected.
Possible remedies:

• Deselect the catalog element that is not available (deacti-

vate check box) and save the station configuration.
• Select the required catalog element (activate check box)
and save the station configuration.
2 The project uses functions of the safety option KUKA Sun-
rise.HRC. The catalog element Human Robot Collaboration is
not available because the option is not installed in Sun-
rise.Workbench.
Possible remedies:

• Deselect the catalog element that is not available (deacti-

vate check box) and save the station configuration.
• Install the safety option in Sunrise.Workbench (only neces-
sary if the safety configuration has not yet been completed
and AMFs of the safety option are required for the configu-
ration).

10.4 “Configuration” tab

10.4.1 IP address range for KUKA Line Interface (KLI)

Description

The KLI is the Ethernet interface of the robot controller for external com-
munication. In order for external PCs, e.g. the development computer with
KUKA Sunrise.Workbench, to be able to connect to the robot controller via
a network, the KLI must be configured accordingly.
The following IP address ranges are used internally by the robot controller.
• 192.*.*.*
• 172.16.*.*
• 172.17.*.*
If one or more KLI network devices (e.g. the robot controller, bus devices
or other network devices) use IP addresses from one of these ranges, this
IP address range must be set. Sunrise then reconfigures the internal net-
work to ensure that there are no IP address conflicts.
Parameter Description
IP address range for KUKA The following IP address ranges are available:
Line Interface
• 192.*.*.*
• 172.16.*.*
• 172.17.*.*
• Other
Default: Other

Field buses

How the KLI has to be configured depends, among other things, on

whether an Ethernet-based field bus is installed on the robot controller.

208/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Ethernet-based field buses are:

Station configuration and installation

• KUKA Sunrise.PROFINET M/S

10.4.2 Allow debugging of applications

The remote debugging functionality is deactivated by default. In order to

be able to use the functionality, it must be activated in the station configu-
ration.
Configuration parameters under Application settings:
Parameter Description
Allow debugging of applica- Activation of the remote debugging functionality
tions
• True: Functionality is activated.
• False: Functionality is deactivated.
Default: False

10.4.3 Handguiding Support

Robots that have a hand guiding device with a safety-oriented enabling

device can be guided manually if no application is selected or if an appli-
cation is paused.
An application is paused if it has one of the following states:
• Selected
• Motion paused
• Error
Manual guidance is supported as standard in all operating modes except
CRR mode. It is possible to configure manual guidance as not allowed in
Test mode and/or Automatic mode.
Configuration parameters under Handguiding Support:
Parameter Description
Enable manual guidance in Manual guidance in Automatic mode
Automatic mode
• True: Manual guidance is allowed in Automatic mode.
• False: Manual guidance is not allowed in Automatic mode.
Default: True
Enable manual guidance in Manual guidance in Test mode (T1, T2)
the test modes
• True: Manual guidance is allowed in Test mode.
• False: Manual guidance is not allowed in Test mode.
Default: True

In order to be able to use the motion command handGuiding() for man-

ual guidance, the parameter Enable manual guidance in Automatic
mode must be set to False. If the parameter is set to True, manual
guidance is not possible for the running application.

10.4.4 General safety settings

As standard, the robot can be moved with the smartPAD unplugged.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 209/667

Station configuration and installation KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

WARNING
Risk of fatal injury due to non-operational EMERGENCY STOP de-
vice
If the smartPAD is disconnected, the system can no longer be switched
off by means of the EMERGENCY STOP device on the smartPAD.
Measures must be taken to prevent operational and non-operational
EMERGENCY STOP devices from being mixed up.
Death, injuries or damage to property may result.
• If unplugging of the smartPAD is to be allowed, connect at least one
external EMERGENCY STOP device that is accessible at all times
to the robot controller.
• Immediately remove the unplugged smartPAD from the system and
store it out of sight and reach.

Unplugging of the smartPAD is a safety function. The correct functioning

of this safety function must be tested during initial start-up and recommis-
sioning of the industrial robot.
Checklists:

• (>>> 13.14.1 "Basic properties of the safety configuration" Page 331)

• (>>> 13.14.7.1 "smartPAD unplugging allowed" Page 355)
If unplugging of the smartPAD is not to be allowed, this can be configured
in the station configuration.
Configuration parameters under General safety settings:
Parameter Description
smartPAD unplugging al- Unplugging the smartPAD
lowed
• True: Unplugging of the smartPAD is allowed. The robot
can be moved with the smartPAD unplugged.
• False: Unplugging of the smartPAD is not allowed. The ro-
bot cannot be moved with the smartPAD unplugged. An
EMERGENCY STOP is triggered.
Default: True

10.4.5 I/O handling: Disable I/O access in EMERGENCY STOP

Configuration parameters under smartHMI > I/O handling:

Parameter Description
Disable I/O access in Preventing the setting of inputs/outputs in the event of a safe-
EMERGENCY STOP ty stop, e.g. an EMERGENCY STOP

• True: In the event of a safety stop, no inputs/outputs can

be set.
• False: In the event of a safety stop, inputs/outputs can
still be set.
Default: True

10.4.6 Show confirmation dialog on installation

To avoid unintentional installations on the robot controller, it is possible to

configure that installation on the robot controller must be explicitly con-
firmed.
Configuration parameters under smartHMI:

210/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Station configuration and installation

Parameter Description
Show confirmation dialog Confirmation of installation of the system software on the ro-
on installation bot controller

• True: Confirmation that installation may be carried out is

required on the robot controller within 120 seconds.
• False: Installation can be carried out without the need for
confirmation of the installation on the robot controller.
Default: False

• The confirmation dialog is only displayed if the corresponding station

configuration is already installed on the robot controller.
• In the case of installation on a robot controller on which a Sun-
rise.OS software version <= 1.15 is already installed, no
confirmation dialog is displayed.

10.4.7 Configuration parameters for calibration

The parameters for calibration can be modified.

Configuration parameters under smartHMI > Measurement:
Parameter Description
Minimum calibration point Minimum distance which must be maintained between
distance (tool) in mm 2 measuring points (XYZ 4-point and ABC 2-point methods)
during tool calibration

• 0 … 200
Default: 8
Maximum calculation error Maximum translational calculation error during tool calibration
in mm up to which the quality of the calibration is considered suffi-
cient

• 0 … 200
Default: 5
Minimum calibration point Minimum distance which must be maintained between
distance (base) in mm 2 measuring points during base calibration

• 0 … 200
Default: 50
Minimum angle in ° Minimum angle to be maintained between the straight lines
which are defined by the 3 measuring points during base cal-
ibration (3-point method)

• 0 … 360
Default: 2.5

10.4.8 Media flange

Description

The set media flange can be changed under the Media Flange entry of
the configured robot on the Configuration tab of the station configuration.
This is necessary, for example, if the media flange is exchanged. The
System Software must then be reinstalled on the robot controller.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 211/667

Station configuration and installation KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

If the media flange “MF Inside electrical NE” is used, the entry Media
flange Inside electrical must be selected.

10.4.9 Configuration parameters for Backup Manager

If the KUKA Sunrise.BackupRestore option package is installed, the con-

figuration parameters for the Backup Manager are available on the Con-
figuration tab.
Configuration parameters under BackupRestore:
Parameter Description
Automatic backup active/ Activation/deactivation of automatic backup
inactive
• Active: The robot controller automatically carries out
backups.
The following parameters determine the time and the in-
terval:
‒ Time [hh:mm]: Time of backup
Default: 00:00
‒ Time interval [days]: Backup interval in days
Default: 7
Note: If the robot controller was switched off at the config-
ured time, it carries out a data backup as soon as it is
switched on at the next configured time. It only carries out
one backup, even if the time was missed more than once.
• Inactive: No automatic backup.
Default: Inactive
Backup mode Target and source directory for backups and restorations

• Local: The target directory for backups and the source di-
rectory for restorations is the directory D:\ProjectBackup
on the robot controller.
Note: If the backup of the projects and user data takes
up too much memory, the local memory may be full be-
fore the maximum configured number of backup copies
has been reached. In this case, no further backup is pos-
sible.
• Network: The target directory for backups and the source
directory for restorations is a network path:
‒ Network path
If during backup and/or restoration the robot controller
must access the network and an authentication is re-
quired, the user name and password for the network path
must be specified:
‒ User name for network path
‒ Password for network path
Note: Any other network path can be set on the robot
controller for restorations.
Default: Local

212/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Station configuration and installation

Parameter Description
Maximum number of back- Maximum number of backup copies
ups
• 1 … 50
Once the maximum number of backup copies has been
reached, the oldest backup copy is overwritten.
If more backup copies than the permissible number are
present, e.g. because the maximum number has been re-
duced, the excess backup copies will be deleted next time a
backup is made (starting with the oldest).
Default: 1
Restore-configuration file Path to a file with network configurations for restorations
The file must be present in CSV format and copied manually
to the robot controller.
Note: It is advisable to save the file on drive D:\. If it is saved
on C:\, it is not possible to rule out the possibility of it being
overwritten in the case of a restoration or installation.

CSV file

Network configurations for restorations can be entered in a CSV file and

saved on the robot controller. The data set with the network configurations
can then be loaded using the Backup Manager and the source directory
from which the data are to be restored can be selected.
Example of a CSV file:

IP_adress;subnetmask;BM_Username;BM_Password;BM_ProjectRestor
eDirectoryPath;Server
192.168.0.131;255.255.0.0;User41;pwd82p;\\Server\Path
\Restore;Restore3Backup857
192.168.0.239;255.255.0.0;User66;pwd24ppp;\\Server\Path
\Restore;Restore0Remote415
192.168.0.151;255.255.0.0;User38;pwd75ppp;\\Server\Path
\Lokal;Lokal1Restore705
...

The following points must be observed when creating the CSV file:
• The header data set must contain the columns specified in the exam-
ple file.
• The column names must not be modified.
• The columns can be saved in any order.
• Further columns can be added, e.g. to save additional information.

10.5 “Installation” tab

10.5.1 Installing system software on the robot controller

Description

During installation of the Sunrise.OS system software, all configuration da-

ta relevant for operation of the industrial robot are transferred from Sun-
rise.Workbench to the robot controller. These include:
• Station configuration
• Safety configuration

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 213/667

Station configuration and installation KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

• Passwords for user groups

The following points must be observed during installation:
• The robot type and media flange (if present) set in the station configu-
ration must match the robot connected to the robot controller (see
identification plate). If the data do not match, the robot cannot be
moved after installation.
• The safety configuration is not yet active after installation. The robot
cannot be moved until the safety configuration has been activated.
(>>> 13.10 "Activating the safety configuration" Page 284)

Modification installation

If the station configuration or the password for a user group on the robot
controller changes, the Sunrise.OS system software must be reinstalled
on the robot controller:
• Change to the station configuration on the Topology tab
• Change to the station configuration on the Software tab
Examples:

‒ Installation of additional option packages

‒ Incompatible version changes of existing software packages
Incompatible version changes can occur if a project that was cre-
ated with an older version of Sunrise.Workbench is loaded into the
workspace.

Software updates may result in undesired modifications to the Sun-

rise project. If the robot controller is reinstalled following a software
update, all applications must therefore be tested in Manual Reduced
Velocity mode (T1).

• Change to the station configuration on the Configuration tab

• Change of password for a user group on the robot controller

Precondition

• The station configuration is completed.

• Network connection to the robot controller
• No running or paused application on the robot controller:
• If the Sunrise.RolesRights option package is installed and active on
the robot controller, a user with the right to carry out the installation
must be logged on.
(>>> 9.4.1 "Overview of Sunrise.RolesRights" Page 197)

Procedure

1. In the station configuration, select the Installation tab.

As standard, the Installation events window displays the warnings
and errors which occur during installation (check mark next to Show
only warnings and errors.).
2. If all events which occur during installation are to be displayed, re-
move the check mark next to Show only warnings and errors..
3. Click on Install. The installation is prepared and the Installation win-
dow opens.
The Configured IP box is marked in color:
• Marked in green: Network connection is present. Continue with
step 5.

214/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Station configuration and installation

• Marked in red: Network connection is not present.
Possible causes include:
‒ The network cable is not connected correctly.
‒ The configured IP address does not match the IP address of
the robot controller.

Fig. 10-3: The robot controller cannot be reached

4. Only if the Configured IP box is marked in red:
• If the configured IP address matches the actual address of the ro-
bot controller, there is no network connection to the robot control-
ler. Establish network connection.
• If the IP address of the robot controller is different from the config-
ured address, enter the current IP address of the robot controller
in the Actual IP box. To do this, double-click in the box.
5. Only if the IP address in the Actual IP box has been changed: If the
red marking under Configured IP persists or the installation fails,
there is no network connection to the robot controller with this IP ad-
dress.
Establish a network connection and restart the installation process (re-
turn to step 3).
6. Click on OK to start the installation.
7. If the Sunrise.RolesRights option package is installed and active on
the robot controller, a dialog opens to authorize the installation proce-
dure.
The required user group is preset. Enter the password and confirm
with OK.
8. Only if a station configuration in which the display of a confirmation di-
alog is configured is already installed on the robot controller:
• In Sunrise.Workbench, a message is displayed indicating that the
installation on the robot controller must be confirmed within
120 seconds.
• At the same time, a confirmation dialog is displayed on the
smartHMI of the robot controller.
Press Continue in the dialog on the smartHMI to continue the installa-
tion.
9. If the Sunrise.RolesRights option package is installed and active on
the robot controller, and if the logged-on user does not have sufficient
rights, a dialog opens on the smartHMI to authorize the installation
procedure.
The required user group is preset. Enter the password and confirm
with Login.
10. The robot controller is installed and the installation progress is indica-
ted in Sunrise.Workbench and on the smartPAD.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 215/667

Station configuration and installation KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

11. Once all installation files have been transferred, a message is dis-
played in Sunrise.Workbench with a reboot prompt.
Confirm the reboot with OK. The robot controller is rebooted and the
installation is completed.

10.6 Loading an old project and converting the safety configuration

Description

If a new software version of Sunrise.Workbench is installed, a Sunrise

project which was created with an earlier software version can be loaded
to the workspace and continue to be used.
The station configuration changes when the Sunrise project is loaded.
Saving the station configuration will transfer the corresponding safety con-
figuration to the new version.

Error message

The following error message may be generated on saving the station con-
figuration:
Not all parameters could be converted to the current version of the
safety configuration. Please check that the safety configuration is
complete and correct before installation.
This message is displayed if safety settings have been added or removed
in the new software version, e.g.:
• Allow muting via input (available from software version 1.10 or high-
er)
• Allow external position referencing (available from software version
1.11 or higher)
• Safety-oriented workpieces no longer configurable as object templates
(software version 1.12 or higher)
The message is only displayed if at least one safety-oriented work-
piece is configured in the loaded project. Instead, only the mass of the
heaviest workpiece now needs to be specified in the safety-oriented
project settings.

Precondition

• The Sunrise project is archived or saved in any directory.

• New version of Sunrise.Workbench is installed.
• User group Safety maintenance technician

Procedure

1. Load the Sunrise project into the workspace.

2. Open the station configuration of the project (file StationSetup.cat)
and click on Save.
3. The system asks whether the modifications to the project should be
accepted. Click on Save and apply.
4. In the case of an error message indicating that not all parameters
could be converted to the current version of the safety configuration:
Confirm the error message with OK.
5. The safety configuration is updated and its parameters are converted.
When the operation is completed, this is indicated by a message.
Confirm with OK.
6. Further steps are required in order to be able to use the updated
project on the robot controller:

216/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Station configuration and installation

a. In the case of an error message indicating that not all parameters
could be converted to the current version of the safety configura-
tion: Check that the safety configuration is complete and correct
and modify as required.
b. Install the system software on the robot controller.
c. Transfer the updated project to the robot controller by means of
project synchronization.
d. Reactivate the safety configuration.
e. Carry out safety acceptance.

10.7 Option packages

The functionalities of the following option packages are described in this

documentation:
• KUKA Sunrise.AntiVirus
Virus scanner for protection against viruses
(>>> 10.7.2 "Installing or updating the virus scanner" Page 219)
• KUKA Sunrise.BackupRestore
Backup manager for backing up and restoring data
(>>> 6.20 "Backup Manager" Page 124)
The functionalities of the Backup Manager can be configured.
(>>> 10.4.9 "Configuration parameters for Backup Manager"
Page 212)
• KUKA Sunrise.RolesRights
Expansion of the user groups available as standard to include the
user group Expert
(>>> 9.4.1 "Overview of Sunrise.RolesRights" Page 197)
• KUKA Sunrise.SafeOperation
Safety option with additional safety monitoring functions, e.g. velocity
monitoring functions or Cartesian workspace monitoring functions
• KUKA Sunrise.HRC
Safety option with additional safety monitoring functions for HRC appli-
cations, e.g. collision detection or TCP force monitoring
• KUKA Sunrise.SafetyVisualization
Option for the 3D visualization of Cartesian monitoring spaces using a
web browser
(>>> 14 "KUKA Sunrise.SafetyVisualization" Page 359)
• KUKA Sunrise.EnhancedVelocityControl
Option for limitation of Cartesian velocities
(>>> 18 "KUKA Sunrise.EnhancedVelocityControl" Page 567)

10.7.1 Installing the option package

Description

If an option package is supplied together with KUKA Sunrise.Workbench,

it is automatically installed during installation of Sunrise.Workbench. If
Sunrise.Workbench is already installed, the option package must be instal-
led subsequently.
Option packages are provided as ZIP archives for installation. The archive
names have the following composition:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 217/667

Station configuration and installation KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

• Article number;revision number (2-digit);product name;build version

Installation is carried out in 3 parts:
• Installation of the option in Sunrise.Workbench
Depending on the option, the software catalog of Sunrise.Workbench
is expanded by one or more entries.
• Selection of the new software for installation in the station configura-
tion of the project
• Installation of the system software on the robot controller
Once the robot controller has been rebooted, the new software is
available for the station.

Precondition

• Local administrator rights

• Sunrise.Workbench is installed.
• The option package is available as a ZIP archive.

Procedure

1. Select the menu sequence Help > Install new software .... The In-
stall window is opened.
2. To the right of the Work with box, click on Add …. The Add reposi-
tory window is opened.
Alternatively: Drag the ZIP archive of the option into the window, then
continue with step 5.
3. Click on Archive …, navigate to the directory in which the ZIP archive
of the option is located and select the archive.
4. Confirm your selection with Open. The Position box now displays the
installation path. Confirm the path with OK.
5. In the Install window, the installation path is adopted in the Work with
box.
The window now also displays a check box with the name of the op-
tion. Activate the check box.
6. Leave the other settings in the Install window as they are and click on
Next >.
7. An installation details overview is displayed. Click on Next >.
8. A license agreement is displayed. In order to be able to install the
software, the agreement must be accepted. Then click on Finish. The
installation is started.
9. A safety warning concerning unsigned contents is displayed. Confirm
with OK.
10. A message indicates that Sunrise.Workbench must be restarted in or-
der to apply the changes. Click on Restart now.
11. Sunrise.Workbench restarts. This completes installation in Sun-
rise.Workbench.
12. Open the station configuration of the desired project (file StationSet-
up.cat). The new software entries are displayed on the Software tab.
13. If the check mark is set in the Install column for the new entries, the
new software has automatically been selected for installation.
If not, set the check mark for the new entries.
14. Save the station configuration. The system asks whether the modifica-
tions to the project should be accepted. Click on Save and apply.
15. Install the system software on the robot controller. Once the robot con-
troller has been rebooted, the new software is available for the station.

218/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Station configuration and installation

10.7.2 Installing or updating the virus scanner

Description

Once the virus scanner has been installed on the robot controller, a tile
for the virus scanner is available on the smartHMI. This tile can be used,
for example, to display the version of the installed virus scanner and mes-
sages about viruses that have been found.
(>>> 21.4 "Displaying messages of the virus scanner" Page 619)
It is advisable to check what version is currently installed on the robot
controller before updating the virus scanner. Do not perform a down-
grade.

Precondition

• Local administrator rights

• Sunrise.Workbench is installed.
• The option package is available as a ZIP archive.
• In the case of an update on the robot controller: Network connection
without Internet access or with an active firewall
During the update, the virus scanner is briefly inactive.

Procedure

(>>> 10.7.1 "Installing the option package" Page 217)

10.7.3 Installing a language package

Description

The user interface on the smartHMI is available in the following languag-

es:
Language Language abbreviation
Chinese (simplified) zh
Danish da
German de
English en
Finnish fi
French fr
Greek el
Italian it
Japanese ja
Korean ko
Dutch nl
Polish pl
Portuguese pt
Romanian ro
Russian ru
Swedish sv
Slovak sk

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 219/667

Station configuration and installation KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Language Language abbreviation

Slovenian sl
Spanish es
Czech cs
Turkish tr
Hungarian hu
Languages which are only available after software is delivered can be in-
stalled later if required.

Precondition

• Local administrator rights

• Sunrise.Workbench is installed.
• The option package is available as a ZIP archive.

Procedure

(>>> 10.7.1 "Installing the option package" Page 217)

10.7.4 Uninstalling the option package

Description

Option packages that are no longer required can be uninstalled in Sun-

rise.Workbench.
It is advisable to archive all relevant data before uninstalling a software
package.

Precondition

• Option package has been removed from the robot controller.

Procedure

1. Select the menu sequence Help > Install new software .... The In-
stall window is opened.
2. Click on the link by What is already installed?. The Installation de-
tails for Sunrise Workbench window is opened.
3. Select the Installed software tab (if it is not already selected).
4. In the list of installed software, select the option that is no longer re-
quired.
It is possible to select several options simultaneously and uninstall
them together.

5. Click on Uninstall. The Uninstall window is opened. The details of

the software to be uninstalled can be viewed here.
6. Click on Finish. The uninstallation is started.
A progress bar indicates the progress of the uninstallation.
7. A message indicates that Sunrise.Workbench must be restarted in or-
der to apply the changes. Click on Restart now.
8. Sunrise.Workbench restarts. This completes uninstallation in Sun-
rise.Workbench.

220/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

10.7.4.1 Instructions for uninstallation of safety options

Station configuration and installation

The following points must be observed when uninstalling safety options:
• Following uninstallation, the AMFs provided by the uninstalled safety
option are no longer available in newly created projects.
• In the case of existing projects, an AMF that is no longer available is
only displayed in the selection table if a cell that uses the AMF is se-
lected in the safety configuration.
• The safety configuration of existing projects is retained, even if it uses
AMFs of an uninstalled safety option. The user can continue to use it
without restrictions.
• If the existing safety configuration uses AMFs of an uninstalled safety
option, it can no longer be modified. Saving of the configuration is pre-
vented.

10.7.4.2 Removing an option package from the robot controller

Description

In order to remove an option package from the robot controller, the sys-
tem software must be reinstalled.

Precondition

• Network connection to the robot controller

• No application is running on the robot controller.

Procedure

1. In Sunrise.Workbench, open the station configuration of the project on

the robot controller (file StationSetup.cat).
2. On the Software tab, deactivate the check box for the option package
that is to be removed.
3. Save the station configuration. The system asks whether the modifica-
tions to the project should be accepted. Click on Save and apply.
4. Install the system software on the robot controller.
(>>> 10.5.1 "Installing system software on the robot controller"
Page 213)
Once the robot controller has been rebooted, the option package is no
longer present on the robot controller.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 221/667

Station configuration and installation KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

222/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Bus configuration
11 Bus configuration

11.1 Overview: Configuration and I/O mapping in WorkVisual

Step Description
1 Install the Sunrise option package in WorkVisual.
The option package is available as a KOP file and is sup-
plied together with Sunrise.Workbench (file Sunrise.kop in
the directory WorkVisual AddOn).
Note: The option package supplied with Sunrise.Workbench
must always be used. If an old version of Sunrise.Work-
bench is uninstalled and a new version installed, the option
package must also be exchanged in WorkVisual.
2 Terminate WorkVisual and create a new I/O configuration in
Sunrise.Workbench or open an existing I/O configuration.
WorkVisual is started automatically and the WorkVisual
project corresponding to the I/O configuration is opened.
(>>> 11.3 "Creating a new I/O configuration" Page 224)
(>>> 11.4 "Opening an existing I/O configuration" Page 224)
3 Only necessary if devices are used for which no device de-
scription files have yet been imported:

1. Close the WorkVisual project.

2. Import the required device description files.
3. Reopen the WorkVisual project.
4 Configure the field bus.
(>>> 11.2 "Overview of field buses" Page 223)
5 Create the Sunrise I/Os and map them.
(>>> 11.5 "Creating Sunrise I/Os" Page 225)
(>>> 11.6.3 "Mapping Sunrise I/Os" Page 233)
6 Export the I/O configuration to the Sunrise project.
(>>> 11.7 "Exporting the I/O configuration to the Sunrise
project" Page 233)
7 Transfer the I/O configuration to the robot controller by
means of project synchronization and reboot the robot con-
troller.
(>>> 9.5 "Project synchronization" Page 199)

Information about installing and managing option packages can be

found in the WorkVisual documentation.

Information about importing device description files and general informa-

tion about configuring field buses can be found in the WorkVisual doc-
umentation.

11.2 Overview of field buses

The following field buses are supported by Sunrise and can be configured
with WorkVisual:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 223/667

Bus configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Field bus Description

PROFINET An Ethernet-based field bus. Data exchange is car-
ried out on a client-server basis. PROFINET is instal-
led on the robot controller.
PROFIBUS Universal field bus which enables communication be-
tween devices from different manufacturers without
special interface adaptations. Data exchange is car-
ried out on a master-slave basis.
EtherCAT An Ethernet-based field bus suitable for real-time re-
quirements.

For configuration of a field bus, the documentation of the field bus is re-
quired.

The I/O configuration is created automatically for the media flange set in
the project. If a media flange with an EtherCAT output (e.g. media
flange IO pneumatic) is used and additional EtherCAT devices are con-
nected, these must be configured using WorkVisual.

When connecting additional EtherCAT devices to a media flange with an

EtherCAT output, e.g. media flange IO pneumatic, it must be ensured
that the number of available signals on the bus is limited.
If there are too many connected devices, this can result in overloading
of the bus and loss of communication. Under certain circumstances, the
robot can then no longer be moved.

If the robot controller is used as a PROFINET master or device, hard-

ware problems can result in an inability to access bus devices. In this
case, use of a diagnostic tool, such as WorkVisual, Step 7 or Wire-
Shark, is recommended.

11.3 Creating a new I/O configuration

Precondition

• Sunrise project without I/O configuration

Procedure

1. Select the project in the Package Explorer.

2. Select the menu sequence File > New > I/O configuration.
WorkVisual is started and the WorkVisual project corresponding to the
I/O configuration is opened. The file IOConfiguration.wvs is inserted
into the Sunrise project; this can be used to call the corresponding
WorkVisual project.

11.4 Opening an existing I/O configuration

Precondition

• Sunrise project with I/O configuration

Procedure

1. Double-click on the file IOConfiguration.wvs. WorkVisual is started

and the WorkVisual project corresponding to the I/O configuration is
opened.

224/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Bus configuration
2. Right-click on the inactive robot controller on the Hardware tab in the
Project structure window.
3. Select Set as active controller from the context menu. The I/O Map-
ping window opens. The Sunrise I/Os can be edited.

11.5 Creating Sunrise I/Os

Precondition

• Field bus configuration has been completed.

• The robot controller has been set as the active controller.

Procedure

1. Select an input or output module of the configured bus on the Field

buses tab in the top right-hand corner of the I/O Mapping window.
(>>> 11.6.1 "I/O Mapping window" Page 231)
2. Select the Sunrise I/Os tab in the top left-hand corner of the I/O Map-
ping window.
3. In the bottom left-hand corner of the I/O Mapping window, click on the
Creates signals at the provider button. The Create I/O signals win-
dow is opened.
(>>> 11.5.1 "“Create I/O signals” window" Page 226)
4. Create an I/O group and inputs/outputs within the group.
(>>> 11.5.2 "Creating an I/O group and inputs/outputs within the
group" Page 228)
5. Click on OK. The Sunrise I/Os are saved. The Create I/O signals
window is closed.
The created I/O group is displayed on the Sunrise I/Os tab of the I/O
Mapping window. The signals can now be mapped.
(>>> 11.6.3 "Mapping Sunrise I/Os" Page 233)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 225/667

Bus configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

11.5.1 “Create I/O signals” window

Overview

Fig. 11-1: “Create I/O signals” window

The window for creating and editing the Sunrise I/Os and Sunrise I/O
groups consists of the following areas:
Area Description
Edit I/O group In this area, I/O groups are created and edited. It is also pos-
sible to save I/O groups as a template or to import previously
created templates.
Edit I/O signals In this area, the input/output signals of an I/O group are dis-
played.
Edit I/O In this area, the inputs/outputs of an I/O group are created
and edited.

Input boxes are displayed with a red frame if values must be entered or
if incorrect values have been entered. A help text is displayed when the
mouse pointer is moved over the box.

Signal properties

In the Edit I/O area, new signals can be created and the signal properties
defined:

226/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Bus configuration
Property Description
I/O name Name of the input/output
Description Description for the input/output (optional)
Direction Signal direction

• Input: Signal is an input.

• Output: Signal is an output.
Type Signal type

• Analog: Signal is an analog signal.

• Digital: Signal is a digital signal.
Data type Data type of the signal
In WorkVisual, a total of 15 different data types are available
for selection. For use with Java, these data types are mapped
to the following data types:

• integer, long, double, boolean

Bit width Number of bits that make up the signal. With the data type
BOOL, the bit width is always 1.
Note: The value must be a positive integer which does not
exceed the maximum permissible length of the selected data
type.
The following signal properties are only relevant for analog inputs/outputs:
The values to be set for analog inputs/outputs can generally be found in
the data sheet of the field bus module used.

Property Description
Start range The smallest possible value of an analog connection without
a physical unit. This is the value to which the smallest possi-
ble number that can be generated on the bus is mapped.
Note: The start range must be lower than the end range. It is
also possible to enter decimal values.
End range The largest possible value of an analog connection without a
physical unit. This is the value to which the largest possible
number that can be generated on the bus is mapped.
Note: The end range must be greater than the start range. It
is also possible to enter decimal values.
Signed Defines whether the number generated on the bus is interpre-
ted as signed or unsigned.

• Check box active: Signed

• Check box not active: Unsigned

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 227/667

Bus configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Property Description
Examples:

• In the case of an analog output module with a measure-

ment range from 0 to 10 V, 0 must be specified for the
start range and +10 for the end range.
• In the case of an analog input module with a measure-
ment range from 4 to 20 mA, 4 must be specified for the
start range and 20 for the end range.
• In the case of an analog input module with a measure-
ment range of +/-10 V plus 1.76 V overflow, -11.76 must
be specified for the start range and +11.76 for the end
range.

11.5.2 Creating an I/O group and inputs/outputs within the group

Precondition

• The Create I/O signals window is open.

Procedure

1. In the Edit I/O group area, click on Create.

The Create I/O group window is opened.

Fig. 11-2: Create I/O group

2. Enter a name for the I/O group.

3. Enter a description for the I/O group (optional).
It is advisable to enter a description in all cases. This description is
displayed later as a help text in the robot application and on the
smartHMI.

4. Click on Create. The I/O group is created and displayed in the selec-
tion menu I/O group.
5. In the Edit I/O area, enter a name for the input or output of the group
and define the signal properties.
(>>> "Signal properties" Page 226)
6. In the Edit I/O group area, click on Create. The input or output signal
is created and displayed in the Edit I/O Signals area.
7. Repeat steps 5 and 6 to define further inputs/outputs in the group.

11.5.3 Editing an I/O group

Precondition

• The Create I/O signals window is open.

• The inputs/outputs of the group are not mapped.

228/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Bus configuration
Procedure

1. Select the desired I/O group from the I/O group selection menu.
2. Click on Edit. The Rename I/O group window is opened.
3. Change the name of the I/O group and/or the corresponding descrip-
tion (optional). Confirm with Apply.

11.5.4 Deleting an I/O group

Precondition

• The Create I/O signals window is open.

• The inputs/outputs of the group are not mapped.

Procedure

1. Select the desired I/O group from the I/O group selection menu.
2. Click on Delete. If signals have already been created for the I/O
group, a request for confirmation is displayed.
3. Reply to the request for confirmation with Yes. The I/O group is de-
leted.

11.5.5 Changing an input/output of a group

Precondition

• The Create I/O signals window is open.

• The signals that are to be changed are not mapped.

Procedure

1. Select the I/O group of the signal from the I/O group selection menu.
2. In the Edit I/O Signals area, click on the desired input or output.
3. In the Edit I/O area, edit the signal properties as required.
(>>> "Signal properties" Page 226)
All the changes can be discarded by clicking on the Discard button.

4. Click on Change. The changes are saved.

11.5.6 Deleting an input/output of a group

Precondition

• The Create I/O signals window is open.

• The signals that are to be deleted are not mapped.

Procedure

1. Select the I/O group of the signal from the I/O group selection menu.
2. In the Edit I/O Signals area, click on the desired input or output.
3. Click on Delete.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 229/667

Bus configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

11.5.7 Exporting an I/O group as a template

Description

I/O groups can be saved as a template. The template contains all the in-
puts/outputs belonging to the saved I/O group. This enables I/O groups,
once created, to be reused. The mapping of the inputs and outputs is not
saved, however.
After exporting the template, the templates created in WorkVisual are
available in Sunrise.Workbench in the IOTemplates folder of the project.

Precondition

• The Create I/O signals window is open.

Procedure

1. In the Edit I/O group area, select the I/O group that is to be exported
as a template.
2. Click on Export as template. The Save I/O group as template win-
dow is opened.
3. Enter a name for template.
If a template with the same name already exists in the Sunrise
project, it will be overwritten during the export operation.

4. Enter a description for the template (optional).

5. Click on Export. The template is saved.

11.5.8 Importing an I/O group from a template

Precondition

• The Create I/O signals window is open.

• There is at least one I/O group available in Sunrise.Workbench as a
template in the Sunrise project.

Procedure

1. In the Edit I/O group area, click on Import from template. The Im-
port I/O group from template window is opened.
2. In the selection list Used template, select the template to be impor-
ted.
3. Enter a name in the I/O-group name box for the I/O group to be cre-
ated.
4. Click on Import. An I/O group configured in accordance with the tem-
plate is imported and can be edited.

230/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Bus configuration
11.6 Mapping the bus I/Os

11.6.1 I/O Mapping window

Overview

Fig. 11-3: “I/O Mapping” window

Item Description
1 Displays the Sunrise I/O groups
The signals in the I/O group selected here are displayed in the
overviews lower down.
2 Displays the inputs/outputs of the bus modules
The signals in the module selected here are displayed in the
overviews lower down.
3 Connection overview
Displays the mapped signals. These are the signals of the I/O
group selected under Sunrise I/Os, which are mapped to the
bus module selected under Field buses.
4 Signal overview
Here the signals can be mapped.
(>>> 11.6.3 "Mapping Sunrise I/Os" Page 233)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 231/667

Bus configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Item Description
5 The arrow buttons allow the connection and signal overviews to
be collapsed and expanded independently of one another.

• Collapse connection view (left-hand arrow symbol pointing

up)
• Expand connection view (left-hand arrow symbol pointing
down)
• Collapse signal view (right-hand arrow symbol pointing up)
• Expand signal view (right-hand arrow symbol pointing
down)
6 Buttons for creating and editing the Sunrise I/Os
7 Displays how many bits the selected signals contain.

For the I/O mapping in Sunrise, only the Sunrise I/Os and Field buses
tabs are relevant.

11.6.2 Buttons in the “I/O Mapping” window

Some of these buttons are displayed in several places. In such cases,

they refer to the side of the I/O Mapping window on which they are loca-
ted.

Edit

Button Name/description
Creates signals at the provider
Opens the Create I/O signals window.
(>>> 11.5.1 "“Create I/O signals” window" Page 226)
The button is only active if an input or output module is se-
lected on the Field buses tab and a signal of the I/O group
is selected in the signal overview.
Edit signals at the provider
Opens the Edit I/O signals window.
The button is only active if an I/O group is selected on the
Sunrise I/Os tab and a signal of the I/O group is selected
in the signal overview.
Deletes signals at the provider
Deletes all the selected inputs/outputs. If all the inputs/
outputs of a group are selected, the I/O group is also de-
leted.
The button is only active if an I/O group is selected on the
Sunrise I/Os tab and a signal of the I/O group is selected
in the signal overview.

232/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Bus configuration
Mapping

Button Name/description
Disconnect
Disconnects the selected mapped signals. It is possible to
select and disconnect a number of connections simultane-
ously.
Connect
Connects signals which are selected in the signal overview.

11.6.3 Mapping Sunrise I/Os

Description

This procedure is used to map the Sunrise I/Os to the inputs/outputs of

the field bus module. It is only possible to map inputs to inputs and out-
puts to outputs if they are of the same data type. For example, it is possi-
ble to map BOOL to BOOL or INT to INT, but not BOOL to INT or BYTE.

Precondition

• The robot controller has been set as the active controller.

Procedure

1. On the Sunrise I/Os tab in the left-hand half of the window, select the
I/O group for which the I/Os are to be mapped.
The signals of the group are displayed in the bottom area of the I/O
Mapping window.
2. On the Field buses tab in the right-hand half of the window, select
the desired input or output module.
The signals of the selected field bus module are displayed in the bot-
tom area of the I/O Mapping window.
3. Drag the signal of the group onto the input or output of the module.
(Or alternatively, drag the input or output of the device onto the signal
of the group.)
The signals are now mapped. Mapped signals are indicated by green
arrows.
Alternative procedure for mapping:
• Select the signals to be mapped and click on the Connect button.

11.7 Exporting the I/O configuration to the Sunrise project

Description

When exporting an I/O configuration from WorkVisual, a separate Java

class is created for each I/O group in the corresponding Sunrise project.
Each of these Java classes contains the methods required for program-
ming, in order to be able to read the inputs/outputs of an I/O group and
write to the outputs of an I/O group.
The classes and methods are saved in the Java package com.kuka.gen-
erated.ioAccess in the source folder of the Sunrise project.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 233/667

Bus configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The source code of the Java classes of the package com.kuka.gener-

ated.ioAccess must not be changed manually. To expand the function-
ality of an I/O group, it is possible to derive further classes from the
classes created or to continue to use objects from these classes, e.g.
as arrays of their own classes (aggregating).

The structure of the Sunrise project after exporting an I/O configuration is

described here:
(>>> 16.11 "Using inputs/outputs in the program" Page 445)

Precondition

• The robot controller has been set as the active controller.

• The automatic change recognition is activated in Sunrise.Workbench.
(>>> 5.9 "Activating the automatic change recognition" Page 69)

Procedure

1. Select the menu sequence File > Import / Export. The import/export
wizard for files opens.
2. Select Export the I/O configuration to the Sunrise Workbench
project..
3. Click on Next > and then on Finish. The configuration is exported to
the Sunrise project.
4. A message is displayed as to whether the export was successfully
completed. If Sunrise I/Os have not been mapped, this is also indica-
ted.
It is not essential to map all the Sunrise I/Os that have been cre-
ated.

Click Close to terminate the wizard.

5. Close WorkVisual by selecting File > Exit.

234/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

External control
12 External control

12.1 Overview of external controller

If the processes of the station are to be controlled by an external control-

ler in Automatic mode, the Sunrise project on the robot controller must be
configured for external control.

Default application

A default application must be assigned to every project that is to be con-

trolled externally.
The default application has the following characteristics:
• It is automatically selected when the operating mode is switched to
Automatic.
• It can only be started via the input signal App_Start (not by means of
the Start key on the smartPAD).
• It cannot be deselected again in Automatic mode.

Interfaces

External controller and robot controller can communicate via the following
interfaces:
• I/O system of the robot controller
• Network protocol UDP
The input/output signals for communication are predefined:
• The external controller can start, pause and resume the default appli-
cation via the input signals.
(>>> 12.4 "External controller input signals" Page 236)
• The output signals can be used to provide information about the
status of the default application and the station to the external control-
ler.
(>>> 12.5 "External controller output signals" Page 237)

Precondition

In order to be able to start an application, the following preconditions must

be met:
• The robot is mastered (all axes).
• A Sunrise project has been configured for external control.
• AUT mode
• If configured: the input signal App_Enable has a HIGH level or is
TRUE.
• The motion enable signal is present.

12.2 Configuring the external controller via the I/O system

The following steps are required for configuring the external controller via
the I/O system:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 235/667

External control KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Step Description
1 Configure and map inputs/outputs for communication with
the external controller in WorkVisual.
(>>> 12.4 "External controller input signals" Page 236)
(>>> 12.5 "External controller output signals" Page 237)
2 Export I/O configuration from WorkVisual to Sunrise.Work-
bench.
3 Create the default application for the external controller.
4 Configure the external controller in the project settings.
(>>> 12.7 "Configuring the external controller in the project
settings" Page 239)
5 Transfer the project to the robot controller by means of syn-
chronization.

The physical inputs/outputs used for communication with the external

controller must not be multiply mapped.

12.3 Configuring the external controller via the UDP interface

The following steps are required for configuring the external controller via
the UDP network protocol:
Step Description
1 Create the default application for the external controller.
2 Configure the external controller in the project settings.
(>>> 12.7 "Configuring the external controller in the project
settings" Page 239)
3 Transfer the project to the robot controller by means of syn-
chronization.
Use of the UDP is illustrated by the following example:
(>>> 12.9 "External control via UDP – Start-up example" Page 245)

12.4 External controller input signals

App_Start

The input signal is absolutely vital for an externally controlled project.

The default application is started and resumed in Automatic mode by the
external controller by means of a rising edge of the signal (change from
FALSE to TRUE).

App_Enable

The input signal is optionally configurable.

The default application can be paused by the higher-level controller in Au-
tomatic mode using this signal. For this, the signal must have a LOW lev-
el or be FALSE.

Get_State

The input signal is only available if the UDP interface is used.

236/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The external controller can use this signal to request application and sta-

External control
tion statuses from the robot controller. The value of the signal can be
TRUE or FALSE.

System response

The input signal App_Enable has a higher priority than the input signal
App_Start. If the input signal App_Enable is configured, the default appli-
cation can only be started if App_Enable has a HIGH level or is TRUE.
The following table describes the system behavior when the App_Enable
signal is configured.
App_Start App_Enable Application status Reaction
FALSE --> FALSE Selected None
TRUE
FALSE --> FALSE Motion paused None
TRUE
FALSE --> TRUE Selected Application is started.
TRUE
FALSE --> TRUE Motion paused Application is resumed.
TRUE If the path is left: the robot is re-
positioned. The application is
then paused.
Any TRUE --> Running Application is paused.
FALSE
Any TRUE --> Repositioning Application is paused.
FALSE

12.5 External controller output signals

The configuration of these output signals is optional.

AutExt_Active

The output signal has a HIGH level or is TRUE if Automatic mode is ac-
tive and the project on the robot controller can be controlled externally via
the interface.

AutExt_AppReadyToStart

The output signal has a HIGH level or is TRUE if the default application is
ready to start.
The application is ready to start in the following states:
• Selected
• Motion paused

DefaultApp_Error

The output signal has a HIGH level or is TRUE if an error occurred when
the default application was run.

Station_Error

The output signal has a HIGH level or is TRUE if the station is in an error
state.
There is an active error state in the following cases:
• Motion enable signal is not present.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 237/667

External control KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

• Drive error or bus error active.

• At least one robot axis is not mastered and the operating mode is not
set to T1.

NOTICE
It is not permissible to set outputs in a robot application that signal sys-
tem states to the external controller. Failure to observe this precaution
may result in malfunctioning of the external controller and damage to
property.

12.6 Signal diagrams

Fig. 12-1: Automatic system start and normal operation

Fig. 12-2: Restart after user stop

238/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

External control
Fig. 12-3: Restart after external EMERGENCY STOP

12.7 Configuring the external controller in the project settings

Procedure

1. Right-click on the desired project in the Package Explorer view and

select Sunrise > Change project settings from the context menu.
The Properties for [Sunrise Project] window opens.
2. Select Sunrise > External control in the directory in the left area of
the window.
3. Make the settings for external control of the project in the right-hand
area of the window.
• Set the check mark at Project is controlled externally.
• In the Default application area, select the default application.
• Under Input interface:, select the interface for the external com-
munication.
• Configure the input/output parameters for the interface.
(>>> 12.7.1 "Input/output parameters of the I/O interface"
Page 241)
(>>> 12.7.2 "Input/output parameters of the UDP interface"
Page 241)
4. Click on OK to save the settings and close the window.

The selected default application is indicated by the following icon in the

Package Explorer view:
If the default application is renamed, the icon is no longer displayed and
the application must be selected as the default application once again.
(>>> 5.4.5 "Setting the robot application as the default application"
Page 63)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 239/667

External control KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Description

Fig. 12-4: External control

Item Description
1 Directory of the project settings
2 “Default application” area
All robot applications of the project are available for selection as
the default application.
3 “Input configuration” area
The interface for the external communication is selected here:

• IO Groups: I/O interface

• UDP: UDP interface
The configurable input parameters depend on the specific inter-
face.
4 “Output configuration” area
The configurable output parameters are not dependent on the
interface selected for the inputs. The values of the outputs can
also be requested via UDP, for example, if the I/O interface has
been configured for the inputs.
The following buttons are available:

240/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

External control
Button Description
Restoring default Resets the window to the default settings. All
values user settings will be lost.
Apply Saves the user settings. The window remains
open.
OK Saves the user settings and closes the window.
Cancel Closes the window without saving.

12.7.1 Input/output parameters of the I/O interface

If the I/O interface is used, mapped inputs/outputs of an I/O group must

be assigned to the required input/output signals.
The input App_Start is absolutely vital for external control of a project.
The input App_Enable and the signal outputs can optionally be config-
ured.
Column Description
I/O group All I/O groups of the I/O configuration of the project are availa-
ble.
Boolean input All inputs of the I/O group selected in the I/O group column are
available.
Boolean output All outputs of the I/O group selected in the I/O group column
are available.

12.7.2 Input/output parameters of the UDP interface

Parameter Description
with App_Enable suppor- Use of the input signal App_Enable
ted
• Check box not active (default): App_Enable is not evalu-
ated.
• Check box active: App_Enable is evaluated.
IP of controlling client: IP address of the client configured for external control of the
project
IPs of state receivers: List of clients to receive status information (optional)
For each client, the IP address must be specified in the follow-
ing format together with the corresponding port:

• IP_address_1:Port_1;IP_address_2:Port_2;...
Note: It is advisable to specify the IP address and port of the
controlling client in order to inform it of changes of state.

12.8 Formatting of the UDP data packets

Form and length of the UDP data packets for the data exchange are pre-
defined:
• UTF-8 coding
• Data arrays are separated by a semicolon.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 241/667

External control KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

12.8.1 Status messages of the robot controller

Description

In the case of the UDP interface, application and station statuses are
transferred from the robot controller to an external controller by means of
so-called status messages.
In the following cases, the robot controller sends status messages to the
clients that are configured as recipients of status messages in the project
settings:
• Following receipt of the control message from an external client
• Following the change in state of an output signal
The data packet sent by the robot controller consists of the following data
arrays:
Array no. Description
1 Time stamp
Type: Integer (long); unit: ms
The time stamp is the current system time of the robot controller when the sta-
tus message is sent. Corresponds to the time in milliseconds elapsed since mid-
night on 1.1.1970.
2 Data packet counter (packets sent to the client)
When the robot controller sends a new status message, the counter is incre-
mented by 1. The client can use the counter to determine the order in which the
status messages were sent.
3 Data packet counter (valid packets received by the client)
When the robot controller signals to the client that the received packet is valid,
the counter is incremented by 1. The client can use the counter to determine
the controller message to which the robot controller is responding.
The client can request the counter for restoration of a cancelled connection and
then use the requested value+1 as the counter in its next controller message.
4 Error ID
The ID signals to the client whether the received controller message was valid
or defective.
(>>> "Error codes" Page 243)
5 Current status of the output signal AutExt_Active

• TRUE: AUT mode is active and the project on the robot controller can be
controlled externally via UDP.
• FALSE: AUT mode is not active or the project on the robot controller cannot
be controlled externally via UDP.
6 Current status of the output signal AutExt_AppReadyToStart

• TRUE: The default application is ready to start.

• FALSE: The default application cannot be started.
7 Current status of the output signal DefaultApp_Error

• TRUE: An error occurred during execution of the default application.

• FALSE: The default application has not signaled an error.

242/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

External control
Array no. Description
8 Current status of the output signal Station_Error

• TRUE: The station has signaled an error.

• FALSE: The station is running without errors.
9 Current state of the default application

• IDLE: The application is selected.

• RUNNING: The application is executed.
• MOTIONPAUSED: The application is paused.
• REPOSITIONING: The robot is repositioned. The application is still paused
because the robot has left the path.
• ERROR: An error occurred while the application was running.
• STARTING: The application is being initialized to switch to the RUNNING
state.
• STOPPING: The application is being reset to the start of the program. The
application is then in the IDLE state.
10 Current status of the input signal App_Start

• TRUE, FALSE
Status defined by the last valid controller message.
The client can request the current status of the signal for restoration of a can-
celled connection.
11 Current status of the input signal App_Enable

• TRUE, FALSE
Status defined by the last valid controller message; FALSE if no controller mes-
sage has been received in the last 100 ms.
The client can request the current status of the signal for restoration of a can-
celled connection.

Example

1449066055468;7;2;1;true;false;false;false;RUNNING;false;fals
e

Error codes

ID Description
1 No error – internally triggered change of state
The change of state of an output signal was not triggered by a
message from the controlling client, but by an internal event on
the robot controller.
0 No error – valid message received
The most recently received message is valid and is being pro-
cessed.
-1 Incorrect client IP address
The IP address of the client that sent the message does not
match the IP address of the client configured for external con-
trol.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 243/667

External control KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

ID Description
-2 Incorrect message structure
The message could not be decoded, e.g. because it contains
too many or too few data arrays or because the data arrays are
not separated by semicolons.
-3 Incorrect data packet counter
The data packet counter of the current message was not incre-
mented by 1 (relative to the most recently received message).
-4 Incorrect time stamp
The time stamp must be an integer.
-5 Incorrect signal name
The signal name must be App_Start, App_Enable or
Get_State.
-6 Incorrect signal value
The signal value must be TRUE or FALSE.
-7 Timeout error
After App_Enable was set to TRUE, no further valid message
was received for 100 ms. The application is paused.

If more than one fault occurs simultaneously, the fault with the highest
priority is transferred. A fault with the ID -3, for example, has a higher
priority than a fault with the ID -4.

12.8.2 Controller messages of the external client

Precondition

When a controller message is sent, the following target address and port
must always be specified:
• IP address of the robot controller (see Configuration tab in the
station configuration)
• Port 30300 (fixed port of the robot controller)

Description

With the UDP interface, input signals are set via so-called controller mes-
sages that the external controller must send to the robot controller. This
client data packet must contain the following data arrays:
Array no. Description
1 Time stamp
Type: Integer (long); unit: ms
The time stamp should be the current system time of the client when the con-
troller message is sent.
2 Data packet counter (packets sent to the robot controller)
When the client sends a new controller message, the counter must be incre-
mented by 1.

244/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

External control
Array no. Description
4 Name of the input signal

• App_Start
The default application can be started or resumed by means of a change of
state from FALSE to TRUE as long as the output signals AutExt_Active
and AutExt_AppReadyToStart are TRUE.
• App_Enable
If App_Enable is activated in the project settings, the signal must be TRUE
in order to be able to start or resume the default application.
(>>> "App_Enable" Page 245)
• Get_State
With this signal (TRUE or FALSE), the client can request a status message
from the robot controller.
5 Value of the sent input signal

• TRUE, FALSE

Example

1449066055468;1;App_Start;true

App_Enable

If the input signal App_Enable is evaluated, the following points must be

taken into consideration when sending controller messages:
• The application can only be started by the input signal App_Start if
the robot controller has received a message with …App_Ena-
ble;true in the last 100 ms.
• The input signal App_Enable functions like a heartbeat signal.
The application is executed as long as the robot controller receives a
controller message, e.g. …App_Enable;true, at least every 100 ms.
If no message is received, the application is paused.
When sending the controller messages, the client must take the net-
work delay into account.

• If the external client sets the input signal App_Enable from TRUE to
FALSE within the 100 ms, this also pauses the application.

12.9 External control via UDP – Start-up example

The example shows how a robot application can be started from a PC via
UDP and what start-up steps and programming are required for this.
The input signal App_Enable is not used in this example. This example
can thus not be used to pause an application and does not claim to be
comprehensive.

12.9.1 Starting up the external controller

The following steps are required for starting up the external controller:
1. Connect the PC to the robot controller via the Ethernet interface KLI.
2. Assign a fixed network IP address to the PC, e.g. 192.168.0.10.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 245/667

External control KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

It is recommended not to use dynamic IP address assignment via

DCHP.

3. Carry out the required project settings in Sunrise.Workbench.

• Select the application to be started as the default application.
• Select the UDP interface.
• Enter the network IP address of the PC as the IP of the controlling
client.
• Enter the IP address and port via which the PC receives the
status messages from the robot controller (here: port 30333).

Fig. 12-5: Project settings in Sunrise.Workbench

4. Synchronize the project to the robot controller.

5. Select AUT mode.
Once the robot is ready to move, all status indicators on the smartHMI
are green and the application can be started via the UDP interface.

12.9.2 Programming the external controller

On the PC used for external control, there must be a program that can
generate and send UDP data packets.
If a firewall is used, it must be ensured that it does not block the incom-
ing and outgoing UDP data packets.

246/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

External control
Precondition

• The correct target address and port have been assigned to the data
packets that are to be sent:
‒ IP address of the robot controller (see Configuration tab in the
station configuration)
‒ Port 30300 (fixed port of the robot controller)

Description

Following a reboot of the robot controller, the robot application can be

started with a controller message with App_Start:

1457449078435;1;App_Start;true

The first number in the packet is the time stamp that must be used to
document when the packet was sent. Here, and in the following code
examples, this number must always be replaced with a current time
stamp in milliseconds. (When using Java, such a number can be gener-
ated, for example, with java.lang.System.currentTimeMillis().)

Following a reboot of the robot controller, the value 1 must always be

transferred for the data packet counter. For each subsequent data pack-
et, the counter must be incremented by 1.

If the value to be transferred for the counter is not known, a socket on the
PC must be opened that can receive UDP messages at port 30333.
Get_State can then be used to request the current counter value:

1457450539457;1;Get_State;true

In Sunrise.Workbench, port 30333 has been defined in the project set-

tings as the port via which the PC receives the status messages from
the robot controller. If a different port is to be used, it can be entered in
the project settings.

If the socket is now checked for received messages, a status message

should now be present as the answer from the robot controller, e.g.:

1457450539459;4;1337;-3;true;true;false;false;IDLE;false;true

The received message shows that the current value of the data packet
counter is 1337. The counter value 1338 must therefore be transferred in
the next data packet.
In order to restart a robot application, the state of the signal from
App_Start must change from FALSE to TRUE. For this purpose, the fol-
lowing packets are sent:

1457450539511;1338;App_Start;false

1457450539511;1339;App_Start;true

It is advisable to check the socket for received messages after every

data packet that is sent to the robot controller. In this way, it is easy to
check whether an error occurred during processing of a message.
(>>> "Error codes" Page 243)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 247/667

External control KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Java program

1 import java.net.*;
2 class UdpSample
3 {
4 public static void main(String args[]) throws Exception
5 {
6 DatagramSocket mySocket = new DatagramSocket(30333);
7
8 // robot address (please adjust IP!)
9 InetSocketAddress robotAddress =
10 new InetSocketAddress("192.168.0.2", 30300);
11
12 // get robot state
13 byte[] msg = String.format("%d;1;Get_State;true",
14 System.currentTimeMillis()).getBytes("UTF-8");
15 mySocket.send(new DatagramPacket(msg, msg.length, robotAddress));
16
17 // receive answer state message
18 byte[] receiveData = new byte[508];
19 DatagramPacket receivePacket = new DatagramPacket(receiveData,
20 receiveData.length);
21 mySocket.receive(receivePacket);
22
23 // extract counter
24 String[] stateMessage = new String(receivePacket.getData()).split(";");
25 long counter = Long.parseLong(stateMessage[2]);
26
27 // start application by sending a rising edge
28 // (false->true) for App_Start
29 msg = String.format("%d;%d;App_Start;false", System.currentTimeMillis(),
30 ++counter).getBytes("UTF-8");
31 mySocket.send(new DatagramPacket(msg, msg.length, robotAddress));
32 msg = String.format("%d;%d;App_Start;true", System.currentTimeMillis(),
33 ++counter).getBytes("UTF-8");
34 mySocket.send(new DatagramPacket(msg, msg.length, robotAddress));
35 }
36 }

12.10 Configuring the signal outputs for a project that is not externally con-
trolled

Description

The predefined output signals for the external controller can also be used
to signal application and station statuses in projects that are not externally
controlled.
The application statuses always refer to the default application selected in
the project settings.
The selected default application is indicated by the following icon in the
Package Explorer view:
If the default application is renamed, the icon is no longer displayed and
the application must be selected as the default application once again.
(>>> 5.4.5 "Setting the robot application as the default application"
Page 63)

248/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

External control
Precondition

• In the case of communication via the I/O system of the robot control-
ler: The I/O configuration of the project contains the outputs configured
and mapped in WorkVisual.
(>>> 12.5 "External controller output signals" Page 237)

Procedure

1. Right-click on the desired project in the Package Explorer view and

select Sunrise > Change project settings from the context menu.
The Properties for [Sunrise Project] window opens.
2. Select Sunrise > General in the directory in the left area of the win-
dow.
3. Make the general settings for the project in the right-hand area of the
window.
• If application statuses are to be signaled: In the Default applica-
tion area, select the desired default application.
• In the Output configuration area, configure the output parameters
required by the communications interface.
(>>> 12.10.1 "Output parameters of the I/O interface" Page 249)
(>>> 12.10.2 "Output parameters of the UDP interface" Page 249)
4. Click on OK to save the settings and close the window.

12.10.1 Output parameters of the I/O interface

If the I/O interface is used, mapped outputs of an I/O group must be as-
signed to the required output signals.
Column Description
I/O group All I/O groups of the I/O configuration of the project are availa-
ble.
Boolean output All outputs of the I/O group selected in the I/O group column
are available.

12.10.2 Output parameters of the UDP interface

Parameter Description
IPs of state receivers: List of clients to receive status information
For each client, the IP address must be specified in the follow-
ing format together with the corresponding port:

• IP_address_1:Port_1;IP_address_2:Port_2;...

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 249/667

External control KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

250/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
13 Safety configuration
The safety configuration defines the safety-oriented functions in order to
integrate the industrial robot safely into the system. Safety-oriented func-
tions serve to protect human operators when they work with the robot.
The safety configuration is an integral feature of a Sunrise project and is
managed in tabular form. The individual safety functions are grouped in
KUKA Sunrise.Workbench on an application-specific basis. The safety
configuration is then transferred with the project to the controller and acti-
vated there.
WARNING
Serious damage and injury or death can result from incorrect safety
configuration. If a new or changed safety configuration is activated, the
safety maintenance technician must conduct tests to ensure that the
configured safety parameters have been correctly applied and that the
safety functions of the configuration are fully functional (safety accept-
ance).

Configuration of the safety functions, activation and deactivation of the

safety functions and safety acceptance may only be carried out by a
trained safety maintenance technician. The safety maintenance techni-
cian is responsible for ensuring that the safety configuration is only acti-
vated on those robots for which it is intended.
The safety configuration is not checked for plausibility by KUKA Sun-
rise.Workbench.

In the case of incomplete start-up of the system, additional substitute

measures for minimizing risk must be taken and documented, e.g. in-
stallation of a safety fence, attachment of a warning sign, locking of the
main switch. Start-up is incomplete, for example, if not all safety func-
tions have yet been implemented, or if a function test of the safety func-
tions has not yet been carried out.

The system integrator must verify that the safety configuration sufficient-
ly reduces risks during collaborative operation (HRC).
It is advisable to perform this verification in accordance with the informa-
tion and instructions for operating collaborative robots in ISO/TS 15066.

States with various safety settings are defined in the safety

configuration as part of the ESM mechanism (Event-Driven Safety Moni-
toring). It is possible to switch between these in the application. Since
switching between these states is carried out by means of non-safety-
oriented signals, all configured states must be consistent. This means
that each state must ensure a sufficient degree of safety, regardless of
the time or place of activation (i.e. regardless of the current process
step).

13.1 Safety concept

Description

The safety configuration must implement all safety functions which are re-
quired to operate the industrial robot. A safety function monitors the entire
system on the basis of specific criteria. These are described by individual
monitoring functions, so-called AMFs (Atomic Monitoring Functions). To
configure a safety function, several AMFs can be linked to form complex

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 251/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

safety monitoring functions. In addition, the safety function defines a suita-

Safety configuration

ble reaction which is triggered in case of error.

Example: In a specific area of the robot's workspace, the velocity at the
TCP must not exceed 500 mm/s (“Workspace monitoring” and “Velocity
monitoring” monitoring functions). Otherwise, the robot must stop immedi-
ately (reaction in case of error).

PSM and ESM

The Sunrise safety concept provides 2 different monitoring mechanisms:

• Permanent safety-oriented monitoring
The safety functions of the PSM mechanism (Permanent Safety Moni-
toring) are always active. It is only possible to deactivate individual
safety functions by changing the safety configuration.
The PSM mechanism is used to constantly monitor the system. It im-
plements basic safety settings which are independent of the process
step being carried out. These include, for example, EMERGENCY
STOP functions, the enabling switch on the smartPAD, the definition of
a cell area or safety functions that depend on the operating mode.
• Event-dependent safety-oriented monitoring
The ESM mechanism (Event-driven Safety Monitoring) defines safe
states. It is possible to switch between these in the application. A safe
ESM state contains the safety functions required in the corresponding
process step.
Since switching is carried out by means of non-safety-oriented signals,
the defined state must ensure a sufficient degree of safety, regardless
of the time or place of activation.
The ESM mechanism allows specific safety functions to be adapted
for specific processes. This is of particular importance for human-robot
collaboration applications, as these often require various safety set-
tings depending on the situation. The required parameters, such as
permissible velocity, collision values or spatial limits, can be individual-
ly defined for each process step using an ESM state.

AMF

The smallest unit of a safety monitoring function is called an Atomic Moni-

toring Function (AMF).
Each AMF supplies an elementary, safety-relevant item of information, e.g.
whether a safety-oriented input is set or whether the Automatic operating
mode is selected.
Atomic Monitoring Functions can have 2 different states and are LOW-ac-
tive. This means that if a monitoring function is violated, the state
switches from “1” to “0”.
• State “0”: The AMF is violated.
• State “1”: The AMF is not violated.
The AMF smartPAD Emergency Stop is violated, for example, if the
EMERGENCY STOP device on the operator panel is pressed.

Safety function

A safe ESM state is defined with up to 20 safety functions. The safety

functions of the ESM mechanism use exactly one AMF. If this AMF is vio-
lated, the safety function and thus the entire ESM state is considered to
be violated.
For safety functions of the PSM mechanism, up to 3 AMFs are logically
linked to one another. This allows complex safety monitoring functions to

252/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

be implemented. If all AMFs of a safety function of the PSM mechanism

Safety configuration
are violated, the entire safety function is considered to be violated.

13.2 Safety-oriented reactions

A suitable reaction is defined for each safety function. This reaction must
take place in the case of an error and put the system into a safe state.
The following reactions can be configured:
• Safety stop 0 is triggered.
It is advisable to only configure a safety stop 0 if it is necessary to
immediately switch off the drives and apply the brakes as a reaction.

• Safety stop 1 is triggered.

• Safety stop 1 (path-maintaining) is triggered.
This is the recommended stop reaction. It has the lowest impact on
the process, as an application can be resumed without the need to re-
position the robot.
CAUTION
In crushing situations, safety stop 1 and safety stop 1 (path-main-
taining) can result in higher crushing forces due to the controlled
stop on a planned braking path. It is therefore advisable to use safe-
ty stop 0 for safety monitoring functions which recognize crushing
situations (e.g. the AMF Collision detection, TCP force monitoring).

• Brake is triggered.
The manipulator is braked on the path as long as the safety monitor-
ing is violated. The braking process is monitored by the safety control-
ler. Safety stop 1 is executed in the event of a fault.
Unlike the safety stop, the braking process does not lead to a com-
plete standstill or deactivation of the drives. The velocity reduction and
safety-oriented monitoring of the braking process are only carried out
until the safety monitoring is no longer violated.
Conditions for use of the “Brake” safety reaction:
‒ Only available with the KUKA Sunrise.EnhancedVelocityControl op-
tion
‒ Only available for safety functions of the PSM mechanism
‒ Only compatible with safety functions that contain Cartesian veloci-
ty monitoring
‒ Not compatible with safety functions that contain an extended AMF
‒ Only compatible with position-controlled spline motions
(>>> 18.1.1 "“Brake” safety reaction" Page 568)
• Safety-oriented output is set to “0” (LOW level).
Setting a safety-oriented output is a safety reaction that is only availa-
ble for safety functions of the PSM mechanism.
The reactions can be used for any number of safety functions. A reaction
is triggered once one of the safety functions using this reaction is violated.
This makes it possible, for example, to inform a higher-level controller via
a safe output when specific errors occur.
With the PSM mechanism, it is possible to trigger several different reac-
tions when a specific combination of AMFs is violated. For example, a
safety stop can be triggered as well as a safe output. To do so, 2 safety
functions must be configured with identical AMF combinations.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 253/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

If 2 safety functions differ only in the type of stop configured, a violation

Safety configuration

triggers the stronger stop reaction. In other words, it triggers the stop re-
action which causes an earlier safety-oriented disconnection of the drives.
If several safety functions use the same output signal as a reaction, this
signal is set to “0” once one of the safety functions is violated.

13.2.1 Time response of safety-oriented outputs

All the safety-oriented outputs use LOW as a safe state.

If a safety function which uses a safety output as a reaction is violated,
this output is immediately set to LOW.
If the violation state is cancelled, the output is only set to HIGH again
when the following conditions have been met:
• The safety function is not violated for at least 24 ms. The reaction to
cancellation of the violation state is always delayed.
• If an Ethernet safety interface is used:
The output has the LOW level for at least 500 ms beforehand. If the
LOW level has not yet been present for this time, the level change to
HIGH waits until the 500 ms has elapsed.
• If the discrete safety interface is used:
The output has the LOW level for at least 200 ms beforehand. If the
LOW level has not yet been present for this time, the level change to
HIGH waits until the 200 ms has elapsed.

When using safety functions with a safety-oriented output as a reaction,

the following must be taken into consideration:
• It is not necessary to acknowledge the switching of the output from
LOW to HIGH.
• Connection errors (i.e. communication errors) at safety-oriented in-
puts or outputs are automatically acknowledged by the safety con-
troller when the connection is restored. Accordingly, the level of the
output can switch from LOW to HIGH once the connection is re-
stored.
For this reason, the safety maintenance technician must ensure that pe-
ripheral devices do not automatically restart.

13.3 Safety interfaces

Various safety interfaces are available for exchanging safety-oriented sig-

nals between a higher-level controller and a robot controller. The safety-
oriented inputs of these interfaces can be used to connect safety devices,
e.g. external EMERGENCY STOP devices or safety gates, and to evalu-
ate the corresponding input signals. The safety-oriented outputs of these
interfaces can be used to signal the violation of safety functions.
• Ethernet safety interfaces (only slave function available)
‒ PROFINET/PROFIsafe
‒ EtherCAT/FSoE
• Discrete safety interfaces
‒ CIB_SR/X11

Field buses such as PROFINET and EtherCAT can be configured in

WorkVisual. Further information about the concrete configuration of the
field buses is contained in the corresponding field bus documentation.

254/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Further information about interface X11 is contained in the assembly in-
structions of the robot controller.

13.4 Permanent Safety Monitoring

Description

The safety functions of the PSM mechanism (Permanent Safety Monitor-

ing) are permanently active and use the criteria defined by these functions
to ensure that the overall system is constantly monitored.
For a safety function of the PSM mechanism, up to 3 AMFs (Atomic Mon-
itoring Functions) can be linked to one another. The entire safety function
is only considered violated if all of these AMFs are violated. The safety
function also defines a reaction. This is triggered if the entire safety func-
tion is violated.

Fig. 13-1: Safety functions of the PSM mechanism

Categories

For diagnosis in case of error, a category is assigned to each safety func-

tion of the PSM mechanism. Depending on the category, errors are dis-
played on the smartPAD and saved in the LOG file. For this reason, it is
advisable to select these carefully.
The following categories are available:
Category Recommended use
None For safety functions which cannot be assigned a category
Output For safety functions which use setting an output as a reaction
In this category, no diagnostic information is provided in case of viola-
tion.
Enabling device For safety functions which evaluate an enabling switch
In this category, no diagnostic information is provided in case of viola-
tion because enabling is a normal operating state and not an error
state.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 255/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Category Recommended use

Local EMERGENCY For safety functions which evaluate an EMERGENCY STOP triggered
STOP by the EMERGENCY STOP device on the smartPAD
External EMERGEN- For safety functions which evaluate an EMERGENCY STOP triggered
CY STOP by an external EMERGENCY STOP device
Operator safety For safety functions which evaluate the signal for operator safety
Safe operational stop For safety functions which monitor robot standstill
Collision detection For safety functions which are used for collision detection or force
monitoring
Safety stop For safety functions which use a safety stop as a reaction and cannot
be assigned to another category. Example: external safety stop
Velocity monitoring For safety functions which are used for monitoring an axis-specific or
Cartesian velocity
Workspace monitoring For safety functions which are used for monitoring an axis-specific or
Cartesian space

13.5 Event-driven Safety Monitoring

The ESM mechanism (Event-driven Safety Monitoring) makes it possible

to switch between different safe ESM states depending on the situation.
Up to 10 safe states can be defined. Switching between states can be
carried out in the robot application or in a background application.
(>>> 13.9.4.7 "Switching between ESM states" Page 281)
A safe ESM state is defined with up to 20 safety functions which must en-
sure a sufficient degree of safety in every situation. An ESM state be-
comes active when the program switches to this ESM state. As long as
the ESM state is active, all corresponding safety functions are monitored
in addition to the permanently active safety functions.
Use of the ESM mechanism is optional. The ESM mechanism is deactiva-
ted if no ESM state is defined in the safety configuration.
When using the ESM mechanism, exactly one safe state is always active.
It is not possible to switch it off in the application.
The safety functions of an ESM state each contain a single AMF which is
assigned to a suitable stop reaction.
Once a safety function of the active ESM state is violated, a stop is trig-
gered. The type of stop reaction will be the strongest of all the violated
safety functions in all ESM states (either active or inactive). In other
words, it triggers the stop reaction which causes the earliest safety-orien-
ted disconnection of the drives.

256/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Fig. 13-2: Safety functions of the ESM mechanism

13.6 Atomic Monitoring Functions

The smallest unit of a safety function is designated as the Atomic Monitor-

ing Function (AMF). This can be, for example, evaluating the enabling
switch on the smartPAD or monitoring the velocity of an axis.

Categories

Atomic Monitoring Functions are divided into 3 categories:

• Standard AMFs
• Parameterizable AMFs
• Extended AMFs

Overview

KUKA Sunrise contains a basic package of AMFs. These include, for ex-
ample, all standard AMFs. The following safety options are also available
and can be used to install further AMFs:
• KUKA Sunrise.SafeOperation (SOP)
• KUKA Sunrise.HRC: safety option for HRC applications

AMF Basic SOP HRC

Axis range monitoring

Automatic mode

Test mode

High-velocity mode

Reduced-velocity mode

Input signal

Motion enable

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 257/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

AMF Basic SOP HRC

smartPAD Emergency Stop

Position referencing

Time delay

smartPAD enabling switch inactive

smartPAD enabling switch panic active

Axis velocity monitoring

Cartesian workspace monitoring

Cartesian velocity monitoring

Cartesian protected space monitoring

Standstill monitoring of all axes

Tool-related velocity component

Tool orientation

Axis torque monitoring

Base-related TCP force component

Collision detection

Torque referencing

TCP force monitoring

Hand guiding device enabling active

Hand guiding device enabling inactive

13.6.1 Standard AMFs

Description

Standard AMFs provide information about system components or system

states, e.g. the safety equipment on the smartPAD or the active operating
mode. Standard AMFs can be used in any number of safety functions.

Overview

AMFs for evaluating the safety equipment on the smartPAD:

AMF Task
smartPAD Emergency Stop Monitors the EMERGENCY STOP device on the smartPAD
smartPAD enabling switch in- Checks whether the enabling signal has not been issued on
active the smartPAD.
smartPAD enabling switch Checks whether an enabling switch on the smartPAD has
panic active been pressed down fully (panic position).
(>>> 13.11.1 "Evaluating the safety equipment on the KUKA smartPAD"
Page 286)
AMFs for evaluating the operating mode:

258/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
AMF Task
Test mode Checks whether a test operating mode is active (T1, T2,
CRR)
Automatic mode Checks whether the Automatic operating mode is active
(AUT)
Reduced-velocity mode Checks whether an operating mode with reduced velocity is
active (T1, CRR)
Note: In the case of a mobile platform, the velocity is not re-
duced in T1 and CRR mode.
High-velocity mode Checks whether an operating mode with programmed velocity
is active (T2, AUT)
(>>> 13.11.2 "Evaluating the operating mode" Page 287)
AMFs for evaluating the motion enable:
AMF Task
Motion enable Monitors the motion enable signal
Motion enable is withdrawn if a safety stop is active.
Note: The “Brake” safety reaction does not lead to withdrawal
of motion enable.
(>>> 13.11.3 "Evaluating the motion enable" Page 287)

13.6.2 Parameterizable AMFs

Description

In contrast to standard AMFs, parameterizable AMFs additionally have

one or more parameters. These can be configured depending on the val-
ues at which the AMF is to be considered violated (e.g. monitoring limits).
Up to 100 instances are available for each parameterizable AMF. In this
way, differently parameterized versions of the AMF can be configured and
used. The instance of an AMF may be used multiple times in the table in
which the safety functions are configured.

Overview

AMF for evaluating safety-oriented inputs:

AMF Task
Input signal Monitors a safety-oriented input
(>>> 13.11.4 "Monitoring of safety-oriented inputs" Page 288)
AMFs for evaluating the enabling signal on the hand guiding device:
AMF Task
Hand guiding device enabling Checks whether the enabling signal has not been issued on
inactive the hand guiding device.
Hand guiding device enabling Checks whether the enabling signal has been issued on the
active hand guiding device.
The AMF is used to activate further monitoring functions dur-
ing manual guidance with an enabling device.
(>>> 13.11.5 "Manual guidance with enabling device and velocity monitor-
ing" Page 289)
AMFs for evaluating the referencing status:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 259/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

AMF Task
Position referencing Monitors the referencing status of the position sensors of the
axes of a kinematic system
(>>> 13.11.6 "Evaluating the position referencing" Page 292)
Torque referencing Monitors the referencing status of the axis torque sensors of
a kinematic system
(>>> 13.11.7 "Evaluation of axis torque referencing"
Page 293)
AMFs for velocity monitoring:
AMF Task
Axis velocity monitoring Monitors the velocity of an axis
(>>> 13.11.8.1 "Defining axis-specific velocity monitoring"
Page 294)
Cartesian velocity monitoring Monitors the Cartesian translational velocity at defined points
of a kinematic system
(>>> 13.11.8.2 "Defining Cartesian velocity monitoring"
Page 294)
Tool-related velocity compo- Monitors the Cartesian translational velocity in a specific de-
nent fined direction (up to 6 monitoring points can be configured).
(>>> 13.11.8.3 "Direction-specific monitoring of Cartesian ve-
locity" Page 297)
AMFs for space monitoring:
AMF Task
Cartesian workspace monitor- Checks whether a part of the structure of a kinematic system
ing being monitored is located outside of its permissible work-
space
(>>> 13.11.9.1 "Defining Cartesian workspaces" Page 302)
Cartesian protected space Checks whether a part of the structure of a kinematic system
monitoring being monitored is located within a non-permissible protected
space
(>>> 13.11.9.2 "Defining Cartesian protected spaces"
Page 304)
Axis range monitoring Monitors the position of one of the axes of a kinematic sys-
tem
(>>> 13.11.9.3 "Defining axis-specific monitoring spaces"
Page 307)
AMF for monitoring the tool orientation:
AMF Task
Tool orientation Checks whether the orientation of the tool of a kinematic sys-
tem is outside a permissible range
(>>> 13.11.10 "Monitoring the tool orientation" Page 308)
AMFs for monitoring forces and torques (HRC):

260/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
AMF Task
Axis torque monitoring Monitors the measured torque of an axis
(>>> 13.11.13.1 "Axis torque monitoring" Page 313)
Collision detection Monitors the external axis torques of all axes of a kinematic
system
(>>> 13.11.13.2 "Collision detection" Page 314)
TCP force monitoring Monitors the external force acting on the tool or robot flange
of a kinematic system
(>>> 13.11.13.3 "TCP force monitoring" Page 316)
Base-related TCP force com- Monitors a component of the external force acting on the tool
ponent or robot flange of a kinematic system relative to a base coor-
dinate system.
(>>> 13.11.13.4 "Direction-specific monitoring of the external
force on the TCP" Page 317)

13.6.3 Extended AMFs

Description

An extended AMF differs from a standard AMF and a parameterizable

AMF in that monitoring parameters are only defined during operation. The
parameters are set at the time of activation. For the AMF Standstill moni-
toring of all axes, for example, the axis angles are set as reference
angles for monitoring at the time of activation.
An extended AMF is activated if all other AMFs used by the safety func-
tion are violated. As long as at least one of the other AMFs is not viola-
ted, the extended AMF is not active and not evaluated.
Extended AMFs are only evaluated one cycle after they are activated.
This can result in an extension of the reaction time by up to 12 ms.

Up to 100 instances are available for each extended AMF.

If the same instance of an Extended AMF is used in multiple rows of a
PSM table, it is activated and remains activated as long as it is activa-
ted by at least one of these rows.
It is advisable to use the instance of an extended AMF only once in the
safety configuration.

Extended AMFs are not available for the safety functions of the ESM
mechanism.

Overview

AMF for standstill monitoring:

AMF Task
Standstill monitoring of all ax- Monitors the standstill of all axes of a kinematic system.
es
(>>> 13.11.11 "Standstill monitoring (safe operational stop)"
Page 311)
AMF for switching a delay:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 261/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

AMF Task
Time delay Delays the triggering of the reaction of a safety function for a
defined time.
(>>> 13.11.12 "Activation delay for safety function" Page 312)

13.6.4 Availability of the AMFs depending on the kinematic system

Description

Some AMFs are kinematic-specific, i.e. the kinematic system to be moni-

tored can be selected during configuration of these AMFs. (Parameter
Monitored kinematic system with the values First kinematic system …
Fourth kinematic system)
The kinematic system to be monitored must be specified as follows in the
kinematic-specific AMFs:
• First kinematic system: Robot
• Second kinematic system: Mobile platform
• Third kinematic system: No function
• Fourth kinematic system: No function

Overview

Not all kinematic-specific AMFs are available for monitoring a KMP, as the
required sensor information is not available. If an AMF cannot be used, it
is always violated.
AMF LBR KMP
Position referencing

Torque referencing

Axis velocity monitoring

Cartesian velocity monitoring

Tool-related velocity component

Cartesian workspace monitoring

Cartesian protected space monitoring

Axis range monitoring

Tool orientation

Axis torque monitoring

Collision detection

TCP force monitoring

Base-related TCP force component

Standstill monitoring of all axes

262/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
13.7 Worst-case reaction times of the safety functions in the case of a sin-
gle fault

The reaction time describes the time between the following events:
• Time at which the event occurs that is to trigger a safety reaction, e.g.
violation of a monitored axis range or setting of an EMERGENCY
STOP input
• Time at which the safety reaction is initiated, e.g. stop reaction is initi-
ated or an output has been deactivated
The reaction time thus contains fault detection times and delays before in-
itiation of the safety reaction. The worst-case reaction time in the case of
a single fault considers the presence of an individual fault and is thus
greater than the reaction time typically expected for the safety function.
The reaction time does not include the time between initiation of a stop
reaction and the kinematic system coming to a standstill.

Fig. 13-3: Reaction time of a safety function

1 Reaction time
2 Braking time
3 Stopping time = Reaction time + Braking time
v Velocity
t Time
t0 Time at which the triggering event occurs
t1 Time at which the safety reaction is initiated
t2 Time at which the kinematic system comes to a standstill

The reaction time of a safety function depends on the monitoring function

(AMF) used, the linked reaction and the monitored kinematic system.
For the stop reactions, the reaction time for the safety stop 0 is specified
in each case. For safety stop 1 and safety stop 1 (path-maintaining), the
reaction time may be longer in the case of defective stopping with the
drives. This fault is detected by monitoring the braking ramps. The reac-
tion time thus depends on the actual motion up to triggering of the braking
ramp monitoring. Deactivation of the motor power can be delayed by a
maximum of 1 second for safety stop 1 and safety stop 1 (path-maintain-
ing).
Incorrect braking by the drives is also detected by means of braking ramp
monitoring in the case of the “Brake” safety reaction. For this reason, the
reaction time in the event of a fault, as in the case of safety stop 1 and
safety stop 1 (path-maintaining), depends on the actual motion up to trig-
gering of this monitoring function. The limit value for this monitoring is
continuously reduced to 0 mm/s over a period of 1 s.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 263/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

If multiple monitoring functions (AMFs) are combined in a PSM table row,

Safety configuration

the monitoring function with the longest reaction time determines the reac-
tion time of the safety function.

13.7.1 Worst-case reaction times of the LBR iiwa monitoring functions

Axis range monitoring

Reaction Reaction time

Stop 0 27 ms
CIB_SR output 258 ms
PROFIsafe output 49 ms + PROFIsafe master watchdog time
FSoE output 49 ms + FSoE master watchdog time

Input signal CIB_SR

Reaction Reaction time

Stop 0 174 ms
CIB_SR output 328 ms
PROFIsafe output 143 ms + PROFIsafe master watchdog time
FSoE output 143 ms + FSoE master watchdog time

Input signal PROFIsafe

Reaction Reaction time

Stop 0 67 ms + y*
CIB_SR output 245 ms + y*
PROFIsafe output Watchdog time * [2 + Ceil(24 ms / watchdog
time)]
FSoE output 36 ms + y* + FSoE master watchdog time
*: For PROFIsafe inputs, delay y must additionally be taken into consider-
ation. This delay is dependent on the watchdog time of the PROFIsafe
slave and is set by the PROFIsafe master:
y = 24 ms * Floor(slave watchdog time / 12 ms)

Input signal FSoE

Reaction Reaction time

Stop 0 67 ms + y**
CIB_SR output 245 ms + y**
PROFIsafe output 36 ms + y** + PROFIsafe master watchdog
time
FSoE output Watchdog time * [2 + Ceil(24 ms / watchdog
time)]
**: For FSoE inputs, delay y must additionally be taken into consideration.
This delay is dependent on the watchdog time of the FSoE slave and is
set by the FSoE master:
y = 24 ms * Floor(slave watchdog time / 12 ms)

264/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Input signal media flange "Touch"

Reaction Reaction time

Stop 0 174 ms
CIB_SR output 352 ms
PROFIsafe output 143 ms + PROFIsafe master watchdog time
FSoE output 143 ms + FSoE master watchdog time

smartPAD Emergency Stop

Reaction Reaction time

Stop 0 174 ms
CIB_SR output 352 ms
PROFIsafe output 143 ms + PROFIsafe master watchdog time
FSoE output 143 ms + FSoE master watchdog time

smartPAD enabling switch panic active

Reaction Reaction time

Stop 0 174 ms
CIB_SR output 352 ms
PROFIsafe output 143 ms + PROFIsafe master watchdog time
FSoE output 143 ms + FSoE master watchdog time

smartPAD enabling switch inactive

Reaction Reaction time

Stop 0 174 ms
CIB_SR output 352 ms
PROFIsafe output 143 ms + PROFIsafe master watchdog time
FSoE output 143 ms + FSoE master watchdog time

Axis velocity monitoring

Reaction Reaction time

Stop 0 32 ms
CIB_SR output 258 ms
PROFIsafe output 49 ms + PROFIsafe master watchdog time
FSoE output 49 ms + FSoE master watchdog time

Cartesian workspace monitoring

Reaction Reaction time

Stop 0 27 ms
CIB_SR output 258 ms
PROFIsafe output 49 ms + PROFIsafe master watchdog time
FSoE output 49 ms + FSoE master watchdog time

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 265/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Cartesian velocity monitoring

Reaction Reaction time

Stop 0 32 ms
CIB_SR output 258 ms
PROFIsafe output 49 ms + PROFIsafe master watchdog time
FSoE output 49 ms + FSoE master watchdog time

Cartesian protected space monitoring

Reaction Reaction time

Stop 0 27 ms
CIB_SR output 258 ms
PROFIsafe output 49 ms + PROFIsafe master watchdog time
FSoE output 49 ms + FSoE master watchdog time

Standstill monitoring of all axes

Reaction Reaction time

Stop 0 27 ms
CIB_SR output 258 ms
PROFIsafe output 49 ms + PROFIsafe master watchdog time
FSoE output 49 ms + FSoE master watchdog time

Tool-related velocity component

Reaction Reaction time

Stop 0 32 ms
CIB_SR output 258 ms
PROFIsafe output 49 ms + PROFIsafe master watchdog time
FSoE output 49 ms + FSoE master watchdog time

Tool orientation

Reaction Reaction time

Stop 0 27 ms
CIB_SR output 258 ms
PROFIsafe output 49 ms + PROFIsafe master watchdog time
FSoE output 49 ms + FSoE master watchdog time

Axis torque monitoring

Reaction Reaction time

Stop 0 27 ms
CIB_SR output 294 ms
PROFIsafe output 85 ms + PROFIsafe master watchdog time
FSoE output 85 ms + FSoE master watchdog time

266/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Base-related TCP force component

Reaction Reaction time

Stop 0 27 ms + x***
CIB_SR output 258 ms + x***
PROFIsafe output 49 ms + PROFIsafe master watchdog time +
x***
FSoE output 49 ms + FSoE master watchdog time + x***
***: With this monitoring function, an additional detection time x must be
taken into account for collision detection, as the collision forces are not
measured directly. Detection of the actual collision forces is carried out ap-
proximately with a delay of a PT1 element with the time constant
T=1/30 s.

Collision detection

Reaction Reaction time

Stop 0 27 ms + x***
CIB_SR output 258 ms + x***
PROFIsafe output 49 ms + PROFIsafe master watchdog time +
x***
FSoE output 49 ms + FSoE master watchdog time + x***
***: With this monitoring function, an additional detection time x must be
taken into account for collision detection, as the collision forces are not
measured directly. Detection of the actual collision forces is carried out ap-
proximately with a delay of a PT1 element with the time constant
T=1/30 s.

TCP force monitoring

Reaction Reaction time

Stop 0 27 ms + x***
CIB_SR output 258 ms + x***
PROFIsafe output 49 ms + PROFIsafe master watchdog time +
x***
FSoE output 49 ms + FSoE master watchdog time + x***
***: With this monitoring function, an additional detection time x must be
taken into account for collision detection, as the collision forces are not
measured directly. Detection of the actual collision forces is carried out ap-
proximately with a delay of a PT1 element with the time constant
T=1/30 s.

Hand guiding device enabling active

The reaction time depends on the input used to connect the enabling de-
vice on the hand guiding device to the robot controller. The reaction time
corresponds to the reaction time of the corresponding AMF Input signal.

Hand guiding device enabling inactive

The reaction time depends on the input used to connect the enabling de-
vice on the hand guiding device to the robot controller. The reaction time
corresponds to the reaction time of the corresponding AMF Input signal.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 267/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

13.8 Deactivation of safety functions via an input

Description

A safety-oriented input can be configured in the safety-oriented project

settings to allow the deactivation of safety functions. A safety stop trig-
gered by one of the following AMFs can be briefly cancelled:
• Axis range monitoring
• Cartesian workspace monitoring
• Cartesian protected space monitoring
• Tool orientation
• Tool-related velocity component
• Standstill monitoring of all axes
• Position referencing
• Torque referencing
• Axis torque monitoring
• Collision detection
• TCP force monitoring
• Base-related TCP force component

Use

Deactivation of safety functions may be used, for example, for freeing per-
sons in a crushing situation.
• To cancel a safety stop triggered by one of the defined AMFs, the
configured input must be set to HIGH.
• As long as the input is HIGH, the robot can be moved for a maximum
of 5 seconds. Every further safety stop triggered by one of the defined
AMFs in this time does not become active.
• After this time, the input must be reset and set again.

Velocity monitoring

While the safety functions are deactivated, all axis-specific velocity moni-
toring functions and the Cartesian velocity monitoring function remain ac-
tive.
For all kinematic systems, safety-oriented monitoring of the Cartesian ve-
locity of 250 mm/s of the robot and tools is additionally active. This addi-
tional Cartesian velocity monitoring is active irrespective of the operating
mode.

Procedure

1. Right-click on the desired project in the Package Explorer view and

select Sunrise > Change project settings from the context menu.
The Properties for [Sunrise Project] window opens.
2. Select Sunrise > Safety in the directory in the left area of the window.
3. Make the following settings in the right-hand part of the window:
• Set the check mark at Allow muting via input.
• Select the input that is to allow the deactivation of safety functions.
The inputs of the discrete safety interface and of the Ethernet
safety interface can be used as long as they are configured in
WorkVisual.
(>>> 13.3 "Safety interfaces" Page 254)

268/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
The enabling device of the hand guiding device can be used as an
input for deactivating safety functions. In this case, it must be taken
into consideration in the risk assessment that every time the ena-
bling switch on the hand guiding device is used, a safety stop that
is active at the time of the enabling can be cancelled if it was trig-
gered by one of the defined safety functions.

4. Click on OK to save the settings and close the window.

13.9 Safety configuration (SafetyConfiguration.sconf file)

The safety configuration is an integral feature of a Sunrise project. It is

managed in tabular form.
When creating a new Sunrise project, a standard safety configuration is
automatically generated (SafetyConfiguration.sconf file).
The standard safety configuration contains permanently active safety func-
tions predefined by KUKA.
Further information on the standard safety configuration can be found in
the “Safety” chapter.

Further safety functions and safe ESM states can be configured. Safety-
oriented tools can also be mapped.
After the safety configuration has been transferred to the robot controller,
it must be activated and safety acceptance must be carried out.

13.9.1 Overview: Safety configuration and start-up

Step Description
1 Open the safety configuration.
(>>> 13.9.2 "Opening the safety configuration" Page 270)
2 Edit the safety functions in the Customer PSM table or cre-
ate new safety functions.
(>>> 13.9.3 "Configuring the safety functions of the PSM
mechanism" Page 273)
3 If necessary, adapt in the KUKA PSM table the parameters
of the parameterizable AMFs used, e.g. for the Cartesian
velocity monitoring during manual guidance.
(>>> 13.11.5.3 "Velocity monitoring during manual
guidance" Page 291)
4 Configure event-dependent monitoring functions if required.
To do so, create safe ESM states and corresponding safety
functions. Existing ESM states can be changed by adapting
safety functions which are already configured or by adding
new ones.
(>>> 13.9.4 "Configuring the safe states of the ESM mech-
anism" Page 276)
5 If necessary, map safety-oriented tools.
(>>> 13.9.5 "Mapping safety-oriented tools" Page 282)
6 Save safety configuration.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 269/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Step Description
7 When using the ESM mechanism
Program the necessary switch between the safe states in
the robot application and/or background applications.
(>>> 13.9.4.7 "Switching between ESM states" Page 281)
8 When using position-specific AMFs
Configure the position referencing and create an application
for the reference run.
(>>> 13.13 "Position and axis torque referencing"
Page 325)
9 When using axis torque-specific AMFs
Create an application for the axis torque referencing.
(>>> 13.13.2 "Axis torque referencing" Page 327)
10 Transfer the safety configuration to the robot controller by
means of project synchronization.
11 Activate the safety configuration on the robot controller
(>>> 13.10.1 "Activating the safety configuration" Page 284)
12 When using position-specific AMFs
Carry out position referencing.
13 When using axis torque-specific AMFs
Perform axis torque referencing.
14 Carry out safety acceptance.
(>>> 13.14 "Safety acceptance overview" Page 330)

13.9.2 Opening the safety configuration

Procedure

• In the Sunrise project, double-click on the file SafetyConfigura-

tion.sconf.

Description

The safety configuration contains several tables.

• KUKA PSM table
The table contains the safety functions prescribed by KUKA. These
cannot be deactivated or deleted. The reactions are permanently con-
figured. The parameters of the parameterizable AMFs used can be
changed.
The table documents the system behavior and, in conjunction with the
Customer PSM table, provides a full description of the permanently ac-
tive safety functions.
• Customer PSM table
The user-specific safety functions are configured in this table. It con-
tains the safety functions preconfigured by KUKA. These can be deac-
tivated, changed or deleted.

270/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
• Tables for ESM states (optional)
A table is created for each ESM state. It contains the safety functions
of the state. The standard configuration does not contain any precon-
figured ESM states.
• Tool selection table table
Safety-oriented tools can be mapped in this table. Each kinematic sys-
tem can be assigned a maximum of one fixed tool that is always ac-
tive and one or more tools that can be activated via an input.

13.9.2.1 Evaluating the safety configuration

When the safety configuration is evaluated, the Customer PSM and KUKA
PSM tables are always checked simultaneously. It is possible for the two
tables to contain identical safety functions with different reactions. If differ-
ent stop reactions are configured, a violation triggers the stronger stop re-
action. In other words, it triggers the stop reaction which causes an earlier
safety-oriented disconnection of the drives.
If the ESM mechanism is used, all safety functions of the currently active
ESM state are additionally monitored.

13.9.2.2 Overview of the graphical user interface for the safety configuration

Fig. 13-4: Graphical user interface for safety configuration

The description of the user interface elements refers to the configuration

of safety functions. The tool selection table is described separately.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 271/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Item Description
1 Table selected
Contains the configured safety functions of the selected PSM
table or of the selected ESM state.
2 Selection table
With respect to the cell selected in the highlighted table row,
the category, AMF or reaction of a safety function can be selec-
ted here.
3 Instance table
This area displays the instances of the AMF marked in the se-
lection table as well as the table rows in which they are used.
4 Parameter table
The parameter values of the AMF instance selected in the in-
stance table are displayed here. The values can be changed.
5 Information display
Information about the selected category, AMF or reaction
6 List of tables
In this area, the desired tables can be selected and new ESM
states can be added.
7 Computing time utilization of the safety controller
Indicates the percentage of the computing time used for the
open safety configuration, including all changes that have not
been saved.

List of tables

The list of tables in the lower area of the Editor is used to select the table
to be displayed and edited.

Fig. 13-5: List of tables

Item Description
1 “Tool selection table” tab
Opens the Tool selection table table. Safety-oriented tools can
be mapped.
2 “KUKA PSM” tab
Opens the KUKA PSM table. The parameters of the parameter-
izable AMFs used can be changed.
3 “Customer PSM” tab
Opens the Customer PSM table. Safety functions can be modi-
fied and created.
4 Tab for an ESM state
Opens the ESM state. The ESM state can be edited.

272/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Item Description
5 Add new ESM state button
Adds a new ESM state. The new state is automatically opened
and can be edited.

13.9.3 Configuring the safety functions of the PSM mechanism

The PSM mechanism defines safety monitoring functions which are per-
manently active.
The safety functions are displayed in tabular form. Each row in the table
contains a safety function.
In the PSM table Customer PSM, new safety functions are added and ex-
isting settings are adapted. This means that the category, the Atomic Mon-
itoring Functions (AMFs) used, the parameterization of the AMF instances
and the reaction can be changed. Individual safety functions can be acti-
vated or deactivated.

13.9.3.1 Opening the Customer PSM table

Procedure

1. Open the safety configuration.

2. Select the Customer PSM tab from the list of tables. The table is dis-
played and can be edited.

Fig. 13-6: PSM table Customer PSM

Item Description
1 Active column
Defines whether the safety function is active. Deactivated safety
functions are not monitored.

• Check box active: safety function is active.

• Check box not active: safety function is deactivated.
2 Category column
Defines the category of the safety function. In the event of an
error, the category is shown on the smartHMI as the cause of
error.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 273/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Item Description
3 Columns AMF 1, AMF 2, AMF 3
Define the individual AMFs of the safety function. Up to 3 AMFs
can be used. The safety function is violated if all of the AMFs
used are violated.
4 Reaction column
Defines the reaction of the safety function. It is triggered if the
safety function is violated.
5 Number of safety functions currently configured
A total of 100 rows are available for configuring the user-specif-
ic safety monitoring functions.
6 Buttons for editing the table
7 Selected row
The row containing the currently selected safety function is
highlighted in gray.
The following buttons are available:
Button Description
Add row
Adds a new row to the table (only possible when the
non-configured blank rows are hidden). The new row
has the standard configuration and is activated auto-
matically.
Reset row
Resets the configuration of the selected row to the
standard configuration. The safety function is deacti-
vated.
Show empty rows/Hide empty rows
All empty rows which are not configured are deactiva-
ted and preset with the standard configuration.

• Category: None
• AMF 1, AMF 2, AMF 3: None
• Reaction: Stop 1
The empty rows can be shown or hidden. The empty
rows are hidden by default.

13.9.3.2 Creating safety functions for the PSM mechanism

Precondition

• The Customer PSM table is open.

Procedure

Non-configured empty rows are displayed:

1. Select an empty row in the table.
2. Set the category, the AMFs used and the reaction of the safety func-
tion in the corresponding columns.
3. Set the check mark in the Active column if the row is to be activated.
Non-configured empty rows are not displayed:

274/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
1. Click on Add row. A preconfigured row is added to the table. The row
is automatically activated (check mark in the Active column).
2. Set the category, the AMFs used and the reaction of the safety func-
tion in the corresponding columns.

13.9.3.3 Deleting safety functions of the PSM mechanism

Precondition

• The Customer PSM table is open.

Procedure

1. In the table, select the row with the safety function to be deleted.
2. Click on Reset row. The safety function is deactivated and is given
the standard configuration (None, AMF, Reaction: Stop 1).

13.9.3.4 Editing existing safety functions of the PSM mechanism

Precondition

• The Customer PSM table is open.

Procedure

Changing the category:

1. Select the Category column in the desired row. The available catego-
ries are displayed in the Main Selection table.
2. Select the desired category from the Main selection table. The catego-
ry is applied to the safety function.
Changing the AMF used:
1. Select the AMF 1, AMF 2 or AMF 3 column in the desired row. The
available AMFs are displayed in the Main selection table.
2. Select the desired AMF from the Main selection table. The AMF is ap-
plied to the safety function.
3. For multiply instanced AMFs: select the desired instance from the
Main selection table. The instance is applied to the safety function.
4. For parameterizable AMFs: in the parameter table, set the parameter
of the AMF in the Value column and insert the settings with the Enter
key.
Changing a reaction:
1. Select the Reaction column in the desired row. The available reactions
are displayed in the Main selection table.
2. Select the desired reaction from the Main selection table. The reaction
is applied to the safety function.
3. If the Output reaction has been selected: in the Parameter table, se-
lect the output bit whose signal is to be set to LOW if a safety
function is violated. Accept the setting with the Enter key.
Activating/deactivating a safety function:
• Click on the Active column in the desired row. The check mark is set /
removed.

Once the safety configurations are transferred to the robot controller

and activated, only the activated safety functions are available.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 275/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

13.9.4 Configuring the safe states of the ESM mechanism

Using the ESM mechanism, various safety settings are defined by config-
urable safe states. Up to 10 safe states can be created. The states are
numbered sequentially from 1 to 10 and can therefore be identified unam-
biguously.
A safe state is defined in a table with up to 20 safety functions. These
safety functions define the safety settings which must be valid for the
state.
A safe state is represented in a table. Each row in the table contains a
safety function.
Use of the ESM mechanism is optional. The ESM mechanism is activated
if at least one ESM state is configured. If no ESM states are configured,
the mechanism is deactivated.
If the ESM mechanism is active, exactly one safe state is valid. The safe-
ty functions of this state are monitored in addition to the permanently ac-
tive safety functions. Depending on the situation, it is possible to switch
between the configured safe states. Switching can be carried out in the
robot application or in a background application.
(>>> 13.9.4.7 "Switching between ESM states" Page 281)
An ESM state is active until it is commanded to switch to another ESM
state.
The configured ESM state with the lowest number is automatically active
when the controller is booted.

13.9.4.1 Creating a new ESM state

Description

Up to 10 safe ESM states can be created for the ESM mechanism. If this
number is reached, the button for adding new states is hidden.
The ESM state is automatically opened when added and can be edited. It
has an active safety function with a standard configuration.

Precondition

• Safety configuration is open.

Procedure

1. Select the Add new ESM state button in the list of tables of the safe-
ty configuration.
A tab for the ESM state is added to the list of tables. The new ESM
state is given the lowest state number which has not yet been as-
signed.
2. Enter a name for the ESM state and configure the safety functions as
required for the ESM state.

276/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Overview of the ESM state with standard configuration

Fig. 13-7: ESM state with standard configuration

Item Description
1 Active column
Defines whether the safety function is active. Deactivated safety
functions are not monitored.

• Check box active: safety function is active.

• Check box not active: safety function is deactivated.
The safety function in the first row of the table is always active.
It cannot be deactivated (indicated by the lock icon).
2 AMF column
Defines the AMF of the safety function. Only one AMF is used
for safety functions of ESM states. If this AMF is violated, the
safety function and thus the entire state is violated.
3 Reaction column
Defines the reaction of the safety function. It is triggered if the
safety function is violated.
4 Number of safety functions currently configured
A total of 20 rows are available for configuring the safety moni-
toring functions of an ESM state.
5 Buttons for editing the table
(>>> "Buttons" Page 278)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 277/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Item Description
6 Add new ESM state button
Adds a new ESM state. The new state is automatically opened
and can be edited.
7 Tab for ESM state
Opens the ESM state. The ESM state can be edited.
8 List of tables
In this area, the desired tables can be selected and new ESM
states can be added.
9 Selected row
The row containing the currently selected safety function is
highlighted in gray.
10 Name of the ESM state (optional)
(>>> "Naming conventions" Page 278)
The name of the ESM state is shown in the safety configuration
report and, in the case of violation of the ESM state, in the cor-
responding message on the smartHMI.

Buttons

The following buttons are available:

Button Description
Delete state
Deletes the entire state The delete operation must be
confirmed via a dialog.
Add row
Adds a new row to the table (only possible when the
non-configured blank rows are hidden). The new row
has the standard configuration and is activated auto-
matically.
Reset row
Resets the configuration of the selected row to the
standard configuration. The safety function is deacti-
vated (exception: the first row of the table is always
active).
Show empty rows/Hide empty rows
All empty rows which are not configured are deactiva-
ted and preset with the standard configuration.

• AMF: None
• Reaction: Stop 1
The empty rows can be shown or hidden. The empty
rows are hidden by default.

Naming conventions

The following applies to names in the safety configuration:

• The name may have a maximum length of 64 characters.
• The name may contain the following letters, characters and digits:

278/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
‒ Letters A-Z and a-z as well as Ä, Ö, Ü and ä, ö, ü, ß
‒ Digits 0-9
‒ Space, hyphen, underscore
• The name must not start with a space.

13.9.4.2 Creating a safety function for the ESM state

Precondition

• Safety configuration is open.

• ESM state is open.

Procedure

Non-configured empty rows are displayed:

1. Select an empty row in the table of the ESM state.
2. Configure the AMF and the reaction of the safety function in the corre-
sponding columns as required.
3. If the row is to be activated, activate the check box in the Active col-
umn.
Non-configured empty rows are not displayed:
1. In the ESM state, click on the Add row button.
A preconfigured row is inserted into the table of the ESM state. The
row is automatically activated (check mark in the Active column).
2. Configure the AMF and the reaction of the safety function in the corre-
sponding columns as required.

Buttons

Button Description
Add row

Example of an ESM state

Fig. 13-8: ESM state for pick-and-place monitoring

13.9.4.3 Editing an existing safety function of an ESM state

Precondition

• Safety configuration is open.

• ESM state is open.

Procedure

Changing the AMF used:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 279/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

1. In the desired table row of the ESM state, select the AMF column.
The available AMFs are displayed in the selection table.
2. Select the desired AMF from the selection table. The AMF is applied
to the safety function.
3. For multiply instanced AMFs: select the desired instance from the in-
stance table. The instance is applied to the safety function.
4. For parameterizable AMFs: in the parameter table, set the parameters
of the AMF in the Value column and apply the settings with the Enter
key.
Changing a reaction:
1. In the desired table row of the ESM state, select the Reaction column.
The available reactions are displayed in the selection table.
2. Select the desired reaction from the selection table. The reaction is
applied to the safety function.
Activating/deactivating a safety function:
• In the desired table row of the ESM state, click on the Active column.
The check mark is set / removed.

13.9.4.4 Deleting a safety function of an ESM state

Precondition

• Safety configuration is open.

• ESM state is open.

Procedure

1. In the table of the ESM state, select the row with the safety function
that is to be deleted.
2. Click on the Reset row button.
The safety function is deactivated and is given the standard configura-
tion (None, AMF, Reaction: Stop 1).

Buttons

Button Description
Reset row

13.9.4.5 Deleting an ESM state

Description

Once the safety configuration is saved and closed, an ESM state is auto-
matically removed if it has the following settings:
• All rows have the standard configuration (AMF: None, Reaction:
Stop 1)
• The first row is activated and all other rows are deactivated.

Precondition

• Safety configuration is open.

280/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Procedure

1. In the list of tables of the safety configuration, select the tab of the
ESM state that is to be deleted.
2. In the ESM state, click on the Delete state button.
3. Answer the request for confirmation with Yes. The state is deleted.

Buttons

Button Description
Delete state

13.9.4.6 Deactivating the ESM mechanism

Description

Use of the ESM mechanism is optional. It can be deactivated.

Procedure

• Delete all ESM states.

13.9.4.7 Switching between ESM states

Description

The setESMState(…) method can be used to activate an ESM state and

switch between the different ESM states. The method belongs to the LBR
class and can be used in both a robot application and a background ap-
plication.

Syntax

robot.setESMState(state);

Explanation of the syntax

Element Description
robot Type: LBR
Name of the robot for which the ESM state is activated
state Type: String
Number of the ESM state which is activated

• 1 … 10
If a non-configured ESM state is specified, the robot
stops with a safety stop 1.

Example

In an application, the LBR is to be guided by hand. For this purpose, a

suitable start position is addressed. In order to address the start position,
ESM state 3 must be activated. ESM state 3 ensures sensitive collision
detection and monitors the Cartesian velocity.
Manual guidance is to begin once the start point has been reached. ESM
state 8 must be activated for manual guidance. ESM state 8 requires ena-
bling on the hand guiding device but permits a higher Cartesian velocity
than ESM state 3.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 281/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

@Inject
private LBR robot;
// ...

public void run() {

// ...
robot.setESMState("3");
robot.move(lin(getFrame("Start")).setCartVelocity(300));

robot.setESMState("8");
robot.move(handGuiding());
// ...
}

13.9.5 Mapping safety-oriented tools

Description

Each kinematic system can be assigned a maximum of one fixed safety-

oriented tool that is always active and one or more safety-oriented tools
that can be activated via an input.
• Assignment of a fixed tool (always active)
A fixed tool is coupled to the flange of the configured kinematic sys-
tem and cannot be uncoupled or changed. The fixed tool can be a
machining tool, a tool for picking up workpieces or a tool that can pick
up other tools, e.g. a tool changer.
The assignment of multiple fixed tools to a kinematic system is not al-
lowed. In this case, all tool-dependent monitoring functions of this kin-
ematic system enter the safe state.
• Assignment of tools that can be activated (via an input)
The tool is activated when the configured input signal is HIGH.
If a fixed tool is configured for this kinematic system, the activatable
tool is coupled to the pickup frame of the fixed tool (standard frame
for motions). If no fixed tool is configured for a kinematic system, it is
coupled to the flange of the kinematic system.
If an activatable tool is configured for a kinematic system, exactly one
activatable tool must always be active for this kinematic system. This
means that exactly one of the input signals configured for this kine-
matic system must be HIGH.
If multiple activatable tools are active simultaneously, or if none of the
activatable tools is active, all tool-dependent monitoring functions of
this kinematic system enter the safe state. For this reason, the tool No
tool must be activated if the activatable tool is uncoupled.

Procedure

1. Open the safety configuration.

2. Select the Tool selection table tab from the list of tables. Map the
tools as desired.
3. Save the safety configuration.

282/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Overview

Fig. 13-9: Tool selection table table

Item Description
1 State of the mapped tool

• Check box active: The tool is always active or activatable.

• Check box not active: The tool is deactivated.
2 Kinematic system to which the tool is assigned

• First kinematic system: Robot

• Second kinematic system: Mobile platform
• Third kinematic system: No function
• Fourth kinematic system: No function
3 Tool assigned to the kinematic system

• No tool: No tool is assigned to the kinematic system.

• All safety-oriented tools defined in the object templates are
available for selection.
4 Activation of the tool

• Always active: The tool is always active.

A maximum of 1 fixed tool can be assigned to each kine-
matic system.
• The tool can be activated via a safe input
The safe inputs of the Ethernet safety interface used are
available.
5 Number of tools currently mapped
A total of 50 rows are available for mapping.
6 Buttons for editing the table
7 Information display
Information about the selected parameter
8 Selection table
The table contains the values available for the parameter selec-
ted in the configuration line.
The following buttons are available:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 283/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Button Description
Add row
Adds a new row to the table (only possible when the
non-configured blank rows are hidden). The new row
has the standard configuration and is activated auto-
matically.
Reset row
Resets the configuration of the selected row to the
standard configuration. The mapped tool is activated.
Show empty rows/Hide empty rows
All empty rows which are not configured are deactiva-
ted and preset with the standard configuration.

• Assigned kinematic system: First kinematic sys-

tem
• Selected tool: No tool
• Activation signal: Always active
The empty rows can be shown or hidden. The empty
rows are hidden by default.

13.10 Activating the safety configuration

The safety configuration on the robot controller must be activated. If no

safety configuration is active, the robot cannot be moved.
When it is activated, the safety configuration is assigned a unique ID (=
checksum of the safety configuration) and displayed under Safety config
ID:. With this ID, the safety maintenance technician can clearly identify the
safety configuration activated on the robot controller.
If a new safety configuration has been transferred to the robot controller,
the previous safety configuration is no longer active and the new safety
configuration is not yet active:
• The new safety configuration must be activated.
• If the new safety configuration is not to be activated, the last active
safety configuration can be restored.

After activating the safety configuration, the safety maintenance techni-

cian must carry out a safety acceptance procedure in order to verify the
safety configuration. (>>> 13.14 "Safety acceptance overview"
Page 330)

If the activated safety configuration contains deactivated rows, i.e. if

safety functions in the PSM table or in an ESM state are deactivated, a
warning message is displayed on the Safety tile. Before using the safe-
ty configuration, it is advisable to check whether the deactivation of the
safety functions is desirable and permissible.

13.10.1 Activating the safety configuration

Precondition

• User group “Safety maintenance”

284/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Procedure

1. Select the Safety > Activation tile at the Station level. The Activation
view opens.
2. Press the Activate button.

13.10.2 Restoring the safety configuration

Description

If a new safety configuration is transferred to the robot controller, but is

not to be activated, the most recently active safety configuration can be
restored.

Precondition

• User group “Safety maintenance”

Procedure

1. Select the Safety > Activation tile at the Station level. The Activation
view opens.
2. Press the Reset button.

13.10.3 Deactivating the safety configuration

Description

An active safety configuration can be deactivated again. Following suc-

cessful deactivation, the robot can no longer be moved. A corresponding
message is displayed under the Safety tile.

Precondition

• User group “Safety maintenance”

Procedure

1. Select the Safety > Activation tile at the Station level. The Activation
view opens.
2. Press the Deactivate button.
3. Check whether the safety configuration has been deactivated success-
fully.

13.11 Using and parameterizing the AMFs

Instances

Up to 100 instances are available for each parameterizable AMF. As the

processing power of the safety controller is limited, this quantity cannot be
used to the full in practice.
• Each instance of the AMF used in the safety configuration requires
part of the available processing power. The processing time required
by an AMF instance depends, for example, on the number of parame-
ters and the complexity of the corresponding calculations.
• For the processing power, it is not relevant how often an AMF in-
stance is used in the safety configuration, how many rows are used in
the Customer PSM table or how many ESM states are used.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 285/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Response if the processing power of the safety controller is exceeded:

Safety configuration

• The required processing time of a safety configuration is calculated

automatically on saving the safety configuration. If it is too great, a
warning is displayed. It is nonetheless saved.
• The transfer of an excessively large safety configuration to the robot
controller is prevented. Project synchronization and installation of the
system software are canceled in this case with a corresponding error
message.

Names for AMF instances

A user-defined name can be assigned for each instance of an AMF.

The name of the AMF is shown in the safety configuration report and, if
the AMF is violated and a stop triggered, in messages on the smartHMI.
If no name is assigned, only the type and instance of the AMF are dis-
played in the corresponding message in the event of an error. A suitable
name, e.g. one that describes the function of the AMF, simplifies diagno-
sis.
Example:

Fig. 13-10: Examples of AMFs in error messages

1 Category of safety function

2 Table type, violated row
3 AMF type (AMF instance)
4 AMF name

Naming conventions

The following applies to names in the safety configuration:

• The name may have a maximum length of 64 characters.
• The name may contain the following letters, characters and digits:
‒ Letters A-Z and a-z as well as Ä, Ö, Ü and ä, ö, ü, ß
‒ Digits 0-9
‒ Space, hyphen, underscore
• The name must not start with a space.

13.11.1 Evaluating the safety equipment on the KUKA smartPAD

The smartPAD has an EMERGENCY STOP device and an enabling de-

vice. The corresponding safety-oriented functions are preconfigured in the
KUKA PSM table and cannot be changed.

286/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Further safety functions evaluated by the safety equipment on the smart-

Safety configuration
PAD can be configured. The following standard AMFs are available for
this purpose:
AMF Description
smartPAD Emergency Stop The AMF is violated if the EMERGENCY STOP device on the
smartPAD is pressed.
smartPAD enabling switch in- The AMF is violated if no enabling signal is issued on the
active smartPAD (no enabling switch is pressed on the smartPAD or
an enabling switch is fully pressed).
smartPAD enabling switch The AMF is violated if an enabling switch on the smartPAD is
panic active fully pressed (panic position).

13.11.2 Evaluating the operating mode

The set operating mode has a powerful effect on the behavior of the in-
dustrial robot and determines which safety precautions are required.
The following standard AMFs are available for configuring a safety func-
tion to evaluate the set operating mode:
AMF Description
Test mode The AMF is violated if a test operating mode is active (T1,
T2, CRR).
Automatic mode The AMF is violated if the active operating mode is an auto-
matic mode (AUT).
Reduced-velocity mode The AMF is violated if an operating mode is active whose ve-
locity is reduced to a maximum of 250 mm/s (T1, CRR).
Note: In the case of a mobile platform, the velocity is not re-
duced in T1 and CRR mode.
High-velocity mode The AMF is violated if an operating mode is active in which
the robot is moved with a programmed velocity (T2, AUT).

13.11.3 Evaluating the motion enable

Description

The robot cannot be moved without the motion enable. The motion enable
can be cancelled for various reasons, e.g. if enabling is not issued in Test
mode or if the EMERGENCY STOP is pressed on the smartPAD.
The AMF for motion enable functions like a group signal for all configured
stop conditions. In particular, it can be used for switching off peripheral
devices. For safety functions which receive the evaluation of the motion
enable, a safe output should therefore be configured as the reaction. If a
safety stop is set as the reaction, the robot cannot be moved.
AMF Description
Motion enable The AMF is violated if the motion enable is not issued due to
a stop request.
Note: This AMF is only suitable for use with an output as a
reaction.

Example

Switching off a tool (category: Output)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 287/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

A tool (e.g. a laser) which is connected to an output is to be switched off

Safety configuration

when the motion enable is cancelled. It is only to be switched off if the

operator safety is violated.
AMF1 AMF2 AMF3 Reaction
Input signal (operator - Motion enable Output (tool)
safety)

13.11.4 Monitoring of safety-oriented inputs

Description

Safety equipment, such as external EMERGENCY STOP devices, light

curtains and safety gates, can be connected to safety-oriented inputs. The
Input signal AMF is used to evaluate the associated input signal.
The inputs of the discrete safety interface or the inputs of the Ethernet
safety interface (if configured in WorkVisual) can be used as safety-orien-
ted inputs.
(>>> 13.3 "Safety interfaces" Page 254)
AMF Description
Input signal The AMF is violated if the monitored input is low (state “0”).

If a robot with a media flange Touch is used, the safety-oriented inputs

at which enabling and panic switches for the media flange are connec-
ted can be used in the AMFs.

Parameter Description
Name Name of the AMF (optional)
Input for safety signal Safety-oriented input to be monitored

Example 1

Operator safety (category: Operator safety)

A safety gate is connected to a safety-oriented input. If the safety gate is
opened in Automatic or T2 mode, a safety stop 1 (path-maintaining) is to
be triggered.
AMF1 AMF2 AMF3 Reaction
Input signal High-velocity mode - Stop 1 (path-main-
taining)

Example 2

External E-STOP (category: External EMERGENCY STOP)

An external EMERGENCY STOP device is connected to a safety-oriented
input. If the external EMERGENCY STOP device is pressed, a safety
stop 1 (path-maintaining) is triggered.
AMF1 AMF2 AMF3 Reaction
Input signal - - Stop 1 (path-main-
taining)

288/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
13.11.5 Manual guidance with enabling device and velocity monitoring

An application of human-robot collaboration involves manually guiding the

robot, e.g. to teach points on a path. This requires a hand guiding device
with a safety-oriented enabling device.
For manual guidance, safety-oriented velocity monitoring with a maximum
permissible velocity of 250 mm/s is preconfigured. The maximum permissi-
ble velocity can be adapted.
The maximum permissible velocity during manual guidance must be de-
fined in a risk assessment.
(>>> 13.11.5.3 "Velocity monitoring during manual guidance" Page 291)
CAUTION
If the robot is manually guided, an EMERGENCY STOP device must be
installed. It must always be within reach of the operator.

13.11.5.1 Monitoring of enabling switches on hand guiding devices

Description

The Hand guiding device enabling inactive AMF serves to evaluate 3‑step
enabling devices. Up to 3 enabling switches and 3 panic switches can be
configured. 3-step enabling devices with only one output which process
the panic signal internally can also be evaluated.
The AMF fulfils the following normative requirements and measures
against predictable misuse:
• If the enabling switch has been fully pressed down, the signal will not
be issued if the switch is released to the center position.
• The signal is cancelled in case of a stop request. To issue the signal
again, the enabling switch must be released and pressed again.
• The signal is only issued 100 ms after the enabling switch has been
pressed.
The following applies if multiple 3-position enabling switches are used:
• If all 3 enabling switches of an enabling device are held simultaneous-
ly in the center position, a safety stop 1 is triggered.
• It is possible to hold 2 enabling switches of an enabling device in the
center position simultaneously for up to 15 seconds. This makes it
possible to adjust grip from one enabling switch to another one. If the
enabling switches are held simultaneously in the center position for
longer than 15 seconds, this triggers a safety stop 1.
• If the enabling switches of different enabling devices are pressed si-
multaneously, e.g. an enabling switch on the smartPAD and an ena-
bling switch on the hand guiding device, a safety stop 1 (path-main-
taining) is triggered.

WARNING
If multiple enabling switches are used on the hand guiding device, each
of the enabling switches should be connected to a safety-oriented input
for the panic position. Only then is it assured that enabling will be with-
drawn if one enabling switch is pressed down fully, irrespective of the
position of the other enabling switches.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 289/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

AMF Description
Hand guiding device enabling The AMF is violated in the following cases:
inactive
• All safety-oriented inputs to which an enabling switch is
connected have the signal level LOW (state “0”)
• At least one of the safety-oriented inputs to which a panic
switch is connected has the signal level LOW (state “0”)

If a robot with a media flange Touch is used, the safety-oriented inputs

at which enabling and panic switches for the media flange are connec-
ted can be used in the AMFs.

Parameter Description
Name Name of the AMF (optional)
Enabling switch 1 used Indicates whether the enabling switch is connected to a safe-
Enabling switch 2 used ty-oriented input

Enabling switch 3 used • True: An input is connected.

• False: No input is connected.
Default: False
Enabling switch 1 input signal Safety-oriented input to which the enabling switch is connec-
Enabling switch 2 input signal ted

Enabling switch 3 input signal The inputs of the discrete safety interface or the inputs of the
Ethernet safety interface (if configured in WorkVisual) can be
used as safety-oriented inputs.
(>>> 13.3 "Safety interfaces" Page 254)
Panic switch 1 used Indicates whether the panic switch is connected to a safe in-
Panic switch 2 used put

Panic switch 3 used • True: An input is connected.

• False: No input is connected.
Default: False
Panic switch 1 input signal Safety-oriented input to which the panic switch is connected
Panic switch 2 input signal The inputs of the discrete safety interface or the inputs of the
Panic switch 3 input signal Ethernet safety interface (if configured in WorkVisual) can be
used as safety-oriented inputs.
(>>> 13.3 "Safety interfaces" Page 254)

Example

Manual guidance with signal (category: Enabling device)

A robot equipped with a hand guiding device is to be manually guided in
a defined area in order to teach the points on a path. The area for man-
ual guidance is defined by a Cartesian protected space. In this protected
space, a Cartesian velocity of 250 mm/s must only be exceeded if the en-
abling signal is issued via the hand guiding device. If no enabling signal is
issued, a safety stop 1 (path-maintaining) is triggered.
AMF1 AMF2 AMF3 Reaction
Hand guiding device Cartesian protected Cartesian velocity Stop 1 (path-main-
enabling inactive space monitoring monitoring taining)

290/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

13.11.5.2 Monitoring functions during manual guidance

Safety configuration
Description

The standard AMF Hand guiding device enabling active makes it possible
to implement safety functions that activate other monitoring functions dur-
ing manual guidance with the enabling device, e.g. Cartesian velocity
monitoring.
AMF Description
Hand guiding device enabling This AMF is violated if the enabling signal for manual guid-
active ance is issued.
The AMF Hand guiding device enabling active represents the
inverse state of the AMF Hand guiding device enabling inac-
tive:

• The AMF Hand guiding device enabling active is violated

if the AMF Hand guiding device enabling inactive is not
violated.
• The AMF Hand guiding device enabling active is not vio-
lated as long as the AMF Hand guiding device enabling
inactive is violated.
The AMF Hand guiding device enabling active takes into ac-
count the enabling device configured for the AMF Hand guid-
ing device enabling inactive.

Example

Space and velocity monitoring during manual guidance with enabling de-
vice (category: Workspace monitoring, Velocity monitoring)
During manual guidance of a robot with an enabling device, the robot
must not leave a defined workspace. Furthermore, the robot is to move
with a maximum velocity during manual guidance of 600 mm/s. If the
workspace is left while enabling is active, or if the velocity limit is excee-
ded, a safety stop 1 (path-maintaining) is to be executed.
AMF1 AMF2 AMF3 Reaction
Hand guiding device Cartesian workspace - Stop 1 (path-main-
enabling active monitoring taining)
Hand guiding device Cartesian velocity - Stop 1 (path-main-
enabling active monitoring taining)

13.11.5.3 Velocity monitoring during manual guidance

For manual guidance of the robot, a maximum permissible velocity must

be defined that may not be exceeded during manual guidance. The value
for this velocity must be defined in a risk assessment.
A safety function for safe velocity monitoring during manual guidance is
configured in row 3 of the KUKA PSM table. The safety function takes
into account the enabling device configured for the Hand guiding device
enabling inactive AMF. Once the enabling signal has been issued, a
safety stop 1 (path-maintaining) is carried out if the velocity limit is excee-
ded.
The instance of the Cartesian velocity monitoring AMF that is used has
the following preset parameter values:
• Monitored kinematic system: First kinematic system
• Monitored structure: Robot and tool

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 291/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

• Maximum velocity: 250 mm/s

The parameter values can be modified. (>>> 13.11.8.2 "Defining Cartesian
velocity monitoring" Page 294)

13.11.6 Evaluating the position referencing

Description

During position referencing, the mastering of the position sensors of a kin-

ematic system is checked. The system checks whether the measured po-
sition of an axis corresponds to the actual mechanical position of the axis.
The safety integrity of the safety functions based upon this is limited until
the position referencing test has been performed. This includes, for exam-
ple, safely monitored Cartesian and axis-specific robot positions, safely
monitored Cartesian velocities, TCP force monitoring and collision detec-
tion.
The Position referencing AMF can be used to check whether the position
values of all axes are referenced.
AMF Description
Position referencing The AMF is violated in the following cases:

• The position of at least one axis of the monitored kine-

matic system is not referenced.
• The position referencing of at least one axis has failed.

Parameter Description
Name Name of the AMF (optional)
Monitored kinematic system Kinematic system to be monitored

• First kinematic system: Robot

• Second kinematic system: No function
• Third kinematic system: No function
• Fourth kinematic system: No function

Example

Monitoring the position referencing status (category: Safety stop)

A robot with non-referenced axes may only be moved at a reduced veloc-
ity of maximum 250 mm/s. The reduced velocity is intended to prevent
hazards arising as a result of position referencing not having been per-
formed or having failed.
To ensure this, the referencing status of all axes is monitored in the oper-
ating modes with high velocity (T2 and AUT). As soon as the position of
at least one axis is not successfully referenced, a safety stop 1 (path-
maintaining) is triggered.
AMF1 AMF2 AMF3 Reaction
High-velocity mode - Position referencing Stop 1 (path-main-
taining)

292/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
13.11.7 Evaluation of axis torque referencing

Description

During axis torque referencing, the mastering of the axis torque sensors of
a kinematic system is checked.
Until the axis torque referencing has been performed successfully, the
safety integrity of the safety functions based on it is limited. This includes,
for example, axis torque and TCP force monitoring as well as collision de-
tection.
The Torque referencingAMF can be used to check whether all axis torque
sensors of a kinematic system are referenced.
AMF Description
Torque referencing The AMF is violated in the following cases:

• At least one axis torque sensor is not referenced.

• The referencing of at least one axis torque sensor has
failed.

Parameter Description
Name Name of the AMF (optional)
Monitored kinematic system Kinematic system to be monitored

• First kinematic system: Robot

• Second kinematic system: No function
• Third kinematic system: No function
• Fourth kinematic system: No function

Example

Monitoring the status of axis torque referencing (category: Safety stop)

A safe collision detection is configured for a station. If a torque of more
than 20 Nm is detected in at least one axis of the robot, a safety stop 0 is
triggered. Since the safety integrity of this function is only ensured for suc-
cessfully referenced axis torque sensors, the referencing status of the
sensors must be monitored simultaneously. As soon as at least one axis
torque sensor has not been referenced or referencing has failed, a safety
stop 1 (path-maintaining) is to be triggered in high-velocity operating
modes (T2 and AUT).
AMF1 AMF2 AMF3 Reaction
Collision detection - - Stop 0
High-velocity mode - Torque referencing Stop 1 (path-main-
taining)

13.11.8 Velocity monitoring functions

A moving kinematic system always presents a danger to persons in its vi-

cinity. In order to protect persons, it may be necessary to impose a de-
fined maximum velocity, for example to give persons time to move out of
the way of the robot. This means that the velocity must be monitored con-
tinuously.
Velocity monitoring functions are available for the robot and for mobile
platforms. The axis velocities and the Cartesian velocity of a kinematic
system can be monitored.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 293/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

13.11.8.1 Defining axis-specific velocity monitoring

Safety configuration

The AMF Axis velocity monitoring is used to define an axis-specific veloci-

ty monitoring function.
AMF Description
Axis velocity monitoring The AMF is violated if the absolute velocity of the monitored
axis of the monitored kinematic system exceeds the config-
ured limit.

Parameter Description
Name Name of the AMF (optional)
Monitored kinematic system Kinematic system to be monitored

• First kinematic system: robot

• Second kinematic system: mobile platform
• Third kinematic system: no function
• Fourth kinematic system: no function
Monitored axis Axis of the kinematic system to be monitored

• Axis1 … Axis16
In the case of a mobile platform, the axes are assigned as
follows:

• Achse1: front left drive

• Achse2: front right drive
• Achse3: rear left drive
• Achse4: rear right drive
Maximum velocity [°/s] Maximum permissible velocity at which the monitored axis
may move in the positive and negative direction of rotation

• 1 … 500 °/s

13.11.8.2 Defining Cartesian velocity monitoring

Description

The Cartesian velocity monitoring AMF is used to define a Cartesian ve-

locity monitoring function.
• In the case of a robot, the translational Cartesian velocity can be
monitored at all axis center points as well as at the robot flange.
If a safety-oriented tool is active on the robot controller, the system
can additionally or alternatively monitor the velocity at the center
points of the spheres which are used to configure the safety-oriented
tool.
(>>> 9.3.10 "Configuring a safety-oriented tool" Page 188)
The system does not monitor the entire structure of the robot and
tool against the violation of a velocity limit, but only defined points of
the robot structure and the center points of the monitoring spheres
of the tools. In particular with protruding tools and workpieces, the
monitoring spheres of the safety-oriented tool must be planned and
configured in such a way as to assure the safety integrity of the ve-
locity monitoring.

294/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
If the monitored kinematic system is fastened to a carrier kinematic
system (e.g. mobile platform, linear unit), it must be taken into con-
sideration that the Cartesian velocity of the monitoring spheres rela-
tive to the carrier kinematic system is monitored and not the abso-
lute velocity of the monitoring spheres in space.

• In the case of a mobile platform, the translational Cartesian velocity

can be monitored at 4 defined points near the corner points of the
platform.
If a safety-oriented tool is active on the robot controller, the system
can additionally or alternatively monitor the velocity at the center
points of the spheres which are used to configure the safety-oriented
tool.
Only velocity components within the plane of the platform are taken in-
to consideration.

Fig. 13-11: Velocity monitoring for platforms (monitored structure)

1 Monitored structure: Robot and tool

2 Monitored structure: Robot
3 Monitored structure: Tool
4 Monitored structure: Tool (no safety-oriented tool active)

AMF Description
Cartesian velocity monitoring The AMF is violated if the Cartesian translational velocity at
at least one point of the monitored kinematic system exceeds
the defined limit.
The AMF is additionally violated in the following cases:

• An axis is not mastered.

• The referencing of a mastered axis has failed.
Note: If an AMF is violated due to loss of mastering, the ro-
bot can only be moved and mastered again by switching to
CRR mode.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 295/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Parameter Description
Name Name of the AMF (optional)
Monitored kinematic system Kinematic system to be monitored

• First kinematic system: Robot

• Second kinematic system: Mobile platform
• Third kinematic system: No function
• Fourth kinematic system: No function
Monitored structure Structure to be monitored
Kinematic system to be monitored is a robot

• Robot and tool: The center points of the axes on the ro-
bot and the center points of the spheres used to configure
the active safety-oriented tool are monitored (default).
• Robot: The center points of the axes on the robot are
monitored.
• Tool: The center points of the spheres used to configure
the active safety-oriented tool are monitored.
Note: If no safety-oriented tool is active and the tool is selec-
ted as the structure to be monitored, the center point of the
robot flange is monitored.
(>>> "Spheres on the robot" Page 300)
Kinematic system to be monitored is a mobile platform

• Robot and tool: The 4 corner points of the platform and

the center points of the spheres used to configure the ac-
tive safety-oriented tool are monitored (default).
• Robot: The 4 corner points of the platform are monitored.
• Tool: The center points of the spheres used to configure
the active safety-oriented tool are monitored.
Note: If no safety-oriented tool is active and the tool is selec-
ted as the structure to be monitored, the frame at the center
point of the platform is monitored.
Maximum velocity [mm/s] Maximum permissible Cartesian velocity which must not be
exceeded at any monitored point

• 1 … 10000 mm/s

Example

Category: Velocity monitoring

If a Cartesian workspace is violated, the Cartesian velocity of the robot
must not exceed 300 mm/s. If this velocity is exceeded, a safety stop 1 is
triggered.
AMF1 AMF2 AMF3 Reaction
Cartesian workspace - Cartesian velocity Stop 1
monitoring monitoring

296/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

13.11.8.3 Direction-specific monitoring of Cartesian velocity

Safety configuration
Description

The Tool-related velocity component AMF is used to check whether the

Cartesian translational velocity in a specific direction is below the configu-
rable limit value.
The AMF can be used, for example, to ensure that the velocity in the
working direction of a sharp-pointed tool is not too high. The AMF can al-
so be used to monitor the motion direction.
The AMF monitors the translational Cartesian velocity at up to 6 points of
the last active safety-oriented tool of the kinematic chain. These monitor-
ing points are safety-oriented frames of the safety-oriented tool and can
be defined as such in the frame properties:
• Point for tool-related velocity
‒ If a safety-oriented frame is defined as a point for the tool-related
velocity, the origin of this frame is used as the monitored point.
‒ If no safety-oriented frame is defined as a point for the tool-related
velocity, the origin of the pickup frame of the active safety-oriented
tool is used as the monitored point:
‒ In the case of a fixed safety-oriented tool, the pickup frame is
the flange coordinate system. The velocity is monitored at the
origin of the flange coordinate system.
‒ In the case of a safety-oriented tool that is coupled to the fixed
tool, the pickup frame is the standard frame for motions of the
fixed tool. The velocity is monitored at the origin of the stand-
ard frame for motions.
Additionally, a safety-oriented frame defining the orientation for the tool-re-
lated velocity at the monitored points can be freely selected in the proper-
ties of the safety-oriented tool:
• Orientation for tool-related velocity
‒ If no safety-oriented frame is defined as an orientation frame for
the tool-related velocity, the pickup frame of the active safety-orien-
ted tool is used as the orientation for the tool-related velocity:
‒ In the case of a fixed safety-oriented tool, the pickup frame is
the flange coordinate system. The orientation of the flange co-
ordinate system determines the monitoring direction.
‒ In the case of a safety-oriented tool that is coupled to the fixed
tool, the pickup frame is the standard frame for motions of the
fixed tool. The orientation of the standard frame for motions
determines the monitoring direction.
(>>> 9.3.10 "Configuring a safety-oriented tool" Page 188)

Fig. 13-12: Orientation at the point for tool-related velocity

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 297/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

1 Point for the tool-related velocity

2 Orientation for the tool-related velocity
3 Orientation at the point for the tool-related velocity (combination of
1 and 2)
If the monitored kinematic system is a mobile platform, it is assumed that
the safety-oriented tool is fastened at the center point of the platform.

Fig. 13-13: Point for tool-related velocity

If no safety-oriented tool is active, the following frame is used as the point

and orientation for the tool-related velocity, depending on the monitored
kinematic system:
• For a robot: frame at the center point of the robot flange
• For a mobile platform: frame at the center point of the platform
The component of the velocity vectors of the configured points in a specif-
ic direction of the configured orientation frame is monitored. During config-
uration of the AMF, this direction is specified as a component of the veloc-
ity vectors in the coordinate system of the orientation frame. Any of the to-
tal of 6 components of the coordinate system, i.e. the X, Y and Z compo-
nents, each in the positive and negative direction, can be selected.
Furthermore, the maximum velocity that the selected component of the ve-
locity vector must not exceed is also defined.
If the monitored kinematic system is fastened to a carrier kinematic sys-
tem (e.g. mobile platform, linear unit), it must be taken into considera-
tion that the velocity of the monitored point relative to the carrier kine-
matic system is monitored and not the absolute velocity in space.

AMF Description
Tool-related velocity compo- The AMF is violated if the configured component of the veloc-
nent ity vector in the coordinate system of the orientation frame of
the monitored kinematic system exceeds the maximum de-
fined value at one or more of the monitored points.
In the case of an LBR, the AMF is additionally violated in the
following cases:

• An axis is not mastered.

• The referencing of a mastered axis has failed.

298/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Parameter Description
Name Name of the AMF (optional)
Monitored kinematic system Kinematic system to be monitored

• First kinematic system: Robot

• Second kinematic system: Mobile platform
• Third kinematic system: No function
• Fourth kinematic system: No function
Maximum velocity [mm/s] Maximum Cartesian velocity for the monitored component of
the velocity vector

• 1 … 10000 mm/s
Note: When selecting the maximum velocity, it must be noted
that, particularly in the case of highly dynamic motions, low
velocities against the commanded direction of motion may oc-
cur due to overshoot. For this reason, it is recommended that
the maximum velocity should not be set too low.
Component of the velocity Monitored component of the velocity vector (direction of moni-
vector toring)

• X positive or X negative
• Y positive or Y negative
• Z positive or Z negative

Example

A sharp-pointed tool may be moved in its working direction at a maximum

of 25 mm/s. In order to be able to monitor the velocity in the working di-
rection, a frame is created at the tool tip and the tool and the frame are
configured as safety-oriented. The safety-oriented frame at the tool tip is
defined in the frame properties as a point for the tool-related velocity and
in the tool properties as an orientation frame.
(>>> 9.3.10 "Configuring a safety-oriented tool" Page 188)
An instance of the Tool-related velocity component AMF is configured in
such a way that the positive Z component of the velocity vector in the co-
ordinate system of the tool tip may not exceed a value of 25 mm/s. For
this, the following parameters are set for the instance used:
• Monitored kinematic system: First kinematic system
• Maximum velocity [mm/s]: 25
• Component of the velocity vector: Z positive

Fig. 13-14: Velocity monitoring in the tool direction

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 299/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Item Description
1 Reference frame for the tool-related velocity component
2 Velocity vector of the translational Cartesian velocity
3 Maximum permissible velocity for the positive Z component of
the velocity vector
4 Positive Z component of the velocity vector
The velocity is below the maximum permissible velocity; the
AMF is not violated.
5 Positive Z component of the velocity vector
The velocity is above the maximum permissible velocity; the
AMF is violated.
The safety function configured with the AMF monitors the positive Z com-
ponent of the velocity vector. If the maximum velocity of 25 mm/s is ex-
ceeded by the monitored component in Automatic mode, a safety stop 1
(path-maintaining) is to be executed.
Category: Velocity monitoring
AMF1 AMF2 AMF3 Reaction
Automatic mode Tool-related velocity - Stop 1 (path-main-
component (1) taining)
First kinematic sys-
tem

13.11.9 Monitoring spaces

Description

The robot environment can be divided into areas in which it must remain
for execution of the application, and areas which it must not enter or may
only enter under certain conditions. The system must then continuously
monitor whether the robot is within or outside of such a monitoring space.
A monitoring space can be defined as a Cartesian cuboid or by means of
individual axis ranges.
A Cartesian monitoring space can be configured as a workspace in which
the robot must remain, or as a protected space which it must not enter.
Via the link to other safety monitoring functions, it is possible to define fur-
ther conditions which must be met when a monitoring space is violated.
For example, a monitoring space can be activated by a safe input or ap-
plicable in Automatic mode only.
If the robot has violated a monitoring space and been stopped by the
safety controller, the robot can be moved out of the violated area in
CRR mode.
(>>> 6.8 "CRR mode – controlled robot retraction" Page 91)

Spheres on the robot

Spheres are modeled around selected points on the robot, enclosing and
moving with the robot. These spheres are predefined and are monitored,
as standard, against the limits of activated Cartesian monitoring spaces.
The centers and radii of the monitored spheres are defined in the
machine data of the robot. A sphere is defined for each robot axis, for the
robot base and for the robot flange.
The dimensions of the monitored spheres vary according to robot type
and the media flange used:

300/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
• r = sphere radius
• z, y = sphere center point relative to the robot base coordinate system
Variant 1: LBR iiwa 7 R800 with media flange Touch
Base A1 A2 A3 A4 A5 A6 A7 Flange
r [mm] 135 90 125 90 125 90 80 85 65
z [mm] 50 90 340 538 740 935 1140 1130 1240
y [mm] -30
Variant 2: LBR iiwa 7 R800 with media flange (all variants except me-
dia flange Touch)
Base A1 A2 A3 A4 A5 A6 A7 Flange
r [mm] 135 90 125 90 125 90 80 85 65
z [mm] 50 90 340 538 740 935 1140 1130 1220
y [mm] -30

Fig. 13-15: Spheres on the LBR iiwa 7 R800 (variant 2)

Variant 3: LBR iiwa 14 R820 with media flange Touch

Base A1 A2 A3 A4 A5 A6 A7 Flange
r [mm] 150 100 140 90 131 90 80 85 65
z [mm] 50 160 360 580 780 980 1180 1170 1280
y [mm] -30
Variant 4: LBR iiwa 14 R820 with media flange (all variants except
media flange Touch)
Base A1 A2 A3 A4 A5 A6 A7 Flange
r [mm] 150 100 140 90 131 90 80 85 65
z [mm] 50 160 360 580 780 980 1180 1170 1260
y [mm] -30

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 301/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Spheres on tool

If a safety-oriented tool is active on the robot controller, the system not

only monitors the spheres on the robot as standard, but also the spheres
used to configure the safety-oriented tool.
(>>> 9.3.10 "Configuring a safety-oriented tool" Page 188)
The system does not monitor the entire structure of the robot and tool
against the violation of a space, but rather only the monitoring spheres.
In particular with protruding tools and workpieces, the monitoring
spheres of the safety-oriented tool must be planned and configured in
such a way as to assure the safety integrity of workspaces and protec-
ted spaces.

Selecting monitoring spheres

It is not necessary or appropriate to include all robot and tool spheres in

the Cartesian workspace monitoring of every application.
Example: If the entry of a tool into a protected space is programmed to
activate further monitoring functions, only the tool spheres must be moni-
tored.
The structure to be monitored can be selected when configuring Cartesian
monitoring spaces:
• Robot and tool (default)
• Only tool
• Only robot

Stopping distance

If the robot is stopped by a monitoring function, it requires a certain stop-

ping distance before coming to a standstill.
The stopping distance depends primarily on the following factors:
• Robot type
• Velocity of the robot
• Position of the robot axes
• Payload

Including stopping distances in the risk assessment

The stopping distance when a safety function is triggered varies accord-
ing to the specific robot type. Failure to take this into consideration
when parameterizing the safety functions may result in death, severe in-
juries or damage to property.
• The system integrator must include the stopping distances in the
risk assessment and parameterize the safety functions accordingly.

Further information about the stopping distances and stopping times can
be found in the assembly or operating instructions of the relevant robot.

13.11.9.1 Defining Cartesian workspaces

Description

A Cartesian workspace is defined as a cuboid whose position and orienta-

tion in space are defined relative to the world coordinate system.
The monitoring spheres are monitored against the limits of activated Car-
tesian workspaces and must move within these workspaces.

302/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The Cartesian workspace monitoring AMF is used to define a Cartesian

Safety configuration
workspace. The AMF is violated as soon as one of the monitored spheres
is no longer completely within the defined workspace.
The AMF is additionally violated in the following cases:
• An axis is not mastered.
• The referencing of a mastered axis has failed.

If the monitored kinematic system is mounted on a carrier kinematic

system (e.g. mobile platform, linear unit), it must be taken into consider-
ation that the position and orientation of the monitoring space are rela-
tive to the world coordinate system and are thus defined relative to the
alignment of the base of the monitored kinematic system. For this rea-
son, the monitoring space is also moved in the event of a change in po-
sition or inclination of the carrier kinematic system.

Parameter Description
Name Name of the AMF (optional)
Monitored kinematic system Kinematic system to be monitored

• First kinematic system: Robot

• Second kinematic system: No function
• Third kinematic system: No function
• Fourth kinematic system: No function
Monitored structure Structure to be monitored

• Robot and tool: The spheres on the robot and the

spheres used to configure the safety-oriented tool are
monitored. (Default)
• Robot: The spheres on the robot are monitored.
• Tool: The spheres used to configure the safety-oriented
tool are monitored.
Note: If no safety-oriented tool is configured and the tool is
selected as the structure to be monitored, the sphere on the
robot flange is monitored. (>>> "Spheres on the robot"
Page 300)
One corner of the cuboid is defined relative to the world coordinate sys-
tem. This is the origin of the workspace and is defined by the following
parameters:
Parameter Description
X, Y, Z [mm] Offset of the origin of the workspace along the X, Y and Z ax-
es of the world coordinate system

• -100,000 mm … +100,000 mm
A, B, C [°] Orientation of the origin of the workspace about the axes of
the world coordinate system, specified by the rotational an-
gles A, B, C

• 0° … 359°
Based on this defined origin, the size of the workspace is determined
along the coordinate axes:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 303/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Parameter Description
Length [mm] Length of the workspace (= distance along the positive X axis
of the origin)

• 0 mm … 100,000 mm
Width [mm] Width of the workspace (= distance along the positive Y axis
of the origin)

• 0 mm … 100,000 mm
Height [mm] Height of the workspace (= distance along the positive Z axis
of the origin)

• 0 mm … 100,000 mm

The violation of a Cartesian workspace is only rectified when all moni-

tored spheres have returned to within the workspace limits with a mini-
mum distance of 1 mm to these limits.

Example

The diagram shows an example of a Cartesian workspace. Its origin is off-

set in the negative X and Y directions with reference to the world coordi-
nate system.

Fig. 13-16: Example of a Cartesian workspace

1 Origin of the workspace

13.11.9.2 Defining Cartesian protected spaces

Description

A Cartesian protected space is defined as a cuboid whose position and

orientation in space are defined relative to the world coordinate system.
The monitoring spheres are monitored against the limits of activated pro-
tected spaces and must move outside of these protected spaces.
The Cartesian protected space monitoring AMF is used to define a Carte-
sian protected space. The AMF is violated as soon as one of the moni-

304/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

tored spheres is no longer completely outside of the defined protected

Safety configuration
space.
The AMF is additionally violated in the following cases:
• An axis is not mastered.
• The referencing of a mastered axis has failed.
If a very narrow protected space is configured, the robot may be able to
move into and out of the protected space without the space violation be-
ing detected. Possible cause: Due to a very high tool velocity, the protec-
ted space is only violated during a very short interval.
Assuming that the following minimum values are configured:
• Radius of tool sphere: 25 mm
• Thickness of protected space: 0 mm
In this case, tool velocities of over 4 m/s are required for the robot to
pass through the protected space without detection.
The following measures are recommended in order to prevent robots from
passing through protected spaces undetected:
• Configure Cartesian velocity monitoring (do not allow a value greater
than 4 m/s).
• OR: When configuring the protected space, select sufficient values for
the length, width and height of the protected space.
• OR: When configuring the tool spheres, select sufficient values for the
radius.

If the monitored kinematic system is mounted on a carrier kinematic

system (e.g. mobile platform, linear unit), it must be taken into consider-
ation that the position and orientation of the monitoring space are rela-
tive to the world coordinate system and are thus defined relative to the
alignment of the base of the monitored kinematic system. For this rea-
son, the monitoring space is also moved in the event of a change in po-
sition or inclination of the carrier kinematic system.

Parameter Description
Name Name of the AMF (optional)
Monitored kinematic system Kinematic system to be monitored

• First kinematic system: Robot

• Second kinematic system: No function
• Third kinematic system: No function
• Fourth kinematic system: No function
Monitored structure Structure to be monitored

• Robot and tool: The spheres on the robot and the

spheres used to configure the safety-oriented tool are
monitored. (Default)
• Robot: The spheres on the robot are monitored.
• Tool: The spheres used to configure the safety-oriented
tool are monitored.
Note: If no safety-oriented tool is configured and the tool is
selected as the structure to be monitored, the sphere on the
robot flange is monitored. (>>> "Spheres on the robot"
Page 300)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 305/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

One corner of the cuboid is defined relative to the world coordinate sys-
Safety configuration

tem. This is the origin of the protected space and is defined by the follow-
ing parameters:
Parameter Description
X, Y, Z [mm] Offset of the origin of the protected space along the X, Y and
Z axes of the world coordinate system

• -100,000 mm … +100,000 mm
A, B, C [°] Orientation of the origin of the protected space about the ax-
es of the world coordinate system, specified by the rotational
angles A, B, C

• 0° … 359°
Based on this defined origin, the size of the protected space is
determined along the coordinate axes:
Parameter Description
Length [mm] Length of the protected space (= distance along the positive
X axis of the origin)

• 0 mm … 100,000 mm
Width [mm] Width of the protected space (= distance along the positive Y
axis of the origin)

• 0 mm … 100,000 mm
Height [mm] Height of the protected space (= distance along the positive Z
axis of the origin)

• 0 mm … 100,000 mm

The violation of a Cartesian protected space is only rectified when all

monitored spheres have returned to outside the protected space limits
with a minimum distance of 1 mm to these limits.

Example

The diagram shows an example of a Cartesian protected space. Its origin

is offset in the negative X and positive Y directions with reference to the
world coordinate system.

Fig. 13-17: Example of a Cartesian protected space

306/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
1 Origin of the protected space

13.11.9.3 Defining axis-specific monitoring spaces

Description

The axis limits can be defined individually and safely monitored for each
axis. The axis angle must lie within the defined axis range.
The AMF Axis range monitoring is used to define an axis-specific monitor-
ing space. The AMF is violated if an axis is not inside the defined axis
range.
The AMF is additionally violated in the following cases:
• An axis is not mastered.
• The referencing of a mastered axis has failed.

Parameter Description
Name Name of the AMF (optional)
Monitored kinematic system Kinematic system to be monitored

• First kinematic system: Robot

• Second kinematic system: No function
• Third kinematic system: No function
• Fourth kinematic system: No function
Monitored axis Axis to be monitored

• Axis1 … Axis16
Note: Axis1 … Axis7 are used for an LBR.
Lower limit [°] Lower limit of the allowed axis range in which the monitored
axis may move

• -180° … +180°
Upper limit [°] Upper limit of the allowed axis range in which the monitored
axis may move

• -180° … +180°

The permissible axis range runs in the positive direction of rotation of

the axis from the lower to the upper limit.
If the axis position at ±180° lies within the permissible angle range, the
lower limit must be greater than the upper limit.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 307/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 13-18: Examples of axis-specific workspaces

1 Lower limit: -90°; upper limit: +90°

2 Lower limit: +90°; upper limit: -90°

For personnel protection, only the position of the axis is relevant. For
this reason, the positions are converted to the axis range -180° …
+180°, even for axes which can rotate more than 360°.

Example

Axes A1, A2 and A4 are to be monitored so that the robot may only be
moved in a limited space. The monitoring is activated by a safe input. The
permitted range of each axis is defined by an upper and lower limit, and
is shown in green in the corresponding chart in the PSM table.
As soon as one of the monitored axis ranges is violated, a safety stop 1
(path-maintaining) is triggered. For this purpose, an individual table row
must be used for each axis.

Fig. 13-19: PSM table – simultaneous monitoring of 3 axes

13.11.10 Monitoring the tool orientation

The Tool orientation AMF can be used to monitor the orientation of a safe-
ty-oriented tool. It checks whether a specific axis of the tool orientation
frame is within a permissible direction range.
This function can for example be used to prevent dangerous parts of the
mounted tool, e.g. sharp edges, from pointing towards humans in HRC
applications.
The following tool orientations are monitored, depending on the tool con-
figuration:

308/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
• As standard, the orientation of the Z axis of the tool orientation frame
of the last active safety-oriented tool of the kinematic chain is moni-
tored.
(>>> 9.3.10 "Configuring a safety-oriented tool" Page 188)
• If no tool orientation frame is defined, the Z axis of the pickup frame
of the last active safety-oriented tool of the kinematic chain is moni-
tored.
‒ If a fixed safety-oriented tool is active, this corresponds to the Z
axis of the flange coordinate system.
‒ If a safety-oriented tool is active and coupled to the fixed tool, this
corresponds to the Z axis of the pickup frame of the fixed tool.
• If no safety-oriented tool is active, the Z axis of the flange coordinate
system is monitored.
The permissible range for the orientation angle is defined by a reference
vector with a fixed orientation relative to the world coordinate system and
a permissible deviation angle from this reference vector.
The reference vector is defined by the rotation of the unit vector of the Z
axis of the world coordinate system about the 3 Euler angles A, B and C
relative to the world coordinate system. A monitoring cone is extended
around the reference vector. The opening of the cone is defined by a con-
figurable deviation angle. The deviation angle defines the permissible an-
gle between the tool orientation and reference vector. The values of the
angle of the reference vector and the deviation angle are defined in the
parameterization of the AMF.
The monitoring sphere defines the permissible range for the tool orienta-
tion.

Fig. 13-20: Monitoring cone for tool orientation

Item Description
1 Axes of the world coordinate system
2 Reference vector
The reference vector defines a fixed orientation relative to the
world coordinate system.
3 Monitoring cone
Defines the permissible range for the tool orientation.
4 Deviation angle
The deviation angle determines the opening of the monitoring
cone.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 309/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

If the monitored kinematic system is fastened to a carrier kinematic sys-

tem (e.g. mobile platform), it must be taken into consideration that the
orientation of the reference vector is relative to the world coordinate sys-
tem. This means that the reference orientation is defined relative to the
alignment of the base of the monitored kinematic system. For this rea-
son, the reference orientation is also moved in the event of a change in
inclination of the carrier kinematic system (e.g. due to driving up a
ramp).

AMF Description
Tool orientation The AMF is violated if the angle between the reference vector
and Z axis of the tool orientation frame is greater than the
configured deviation angle.
The AMF is additionally violated in the following cases:

• An axis is not mastered.

• The position referencing of a mastered axis has failed.

Parameter Description
Name Name of the AMF (optional)
Monitored kinematic system Kinematic system to be monitored

• First kinematic system: Robot

• Second kinematic system: No function
• Third kinematic system: No function
• Fourth kinematic system: No function
A [°] Rotation of the reference vector about the Z axis of the world
coordinate system

• 0° … 359°
B [°] Rotation of the reference vector about the Y axis of the world
coordinate system

• 0° … 359°
C [°] Rotation of the reference vector about the X axis of the world
coordinate system

• 0° … 359°
Operating angle [°] Workspace of the tool orientation
Defines the maximum permissible deviation angle between
the reference vector and the Z axis of the tool orientation
frame.

• 1° … 179°

310/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Fig. 13-21: Tool orientation (not violated and violated)

Item Description
1 Robot is not violating the Tool orientation AMF.
The Z axis of the tool orientation frame is within the range de-
fined by the monitoring cone.
2 Origin of the tool orientation frame
3 Monitoring cone
4 Z axis of the tool orientation frame
5 Robot is violating the Tool orientation AMF.
The Z axis of the tool orientation frame is outside of the range
defined by the monitoring cone.

13.11.11 Standstill monitoring (safe operational stop)

Description

If, under certain conditions, the robot must not move but must remain un-
der servo-control, the standstill of all axes must be safely monitored. The
AMF Standstill monitoring of all axes is used for this purpose.
This AMF is an extended AMF, meaning that the monitoring only begins
when all other AMFs of the safety function are violated.
Extended AMFs are not available for the safety functions of the ESM
mechanism.

Standstill is defined as retaining the axis positions. At the start of standstill

monitoring, the axis positions are saved and compared to the current joint
values for as long as the monitoring is active.
Since standstill monitoring is monitored in a narrow tolerance range, mon-
itoring can also be violated if the motion of the robot is caused by an out-
side force, e.g. if the robot is jolted.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 311/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

AMF Description
Standstill monitoring of all ax- The AMF is violated as soon as the joint value of an axis is
es outside of a tolerance range of +/- 0.1° of the value saved
when standstill monitoring was activated, or if one of the axes
moves at an absolute value of more than 1 °/s.

Parameter Description
Name Name of the AMF (optional)
Monitored kinematic system Kinematic system to be monitored

• First kinematic system: Robot

• Second kinematic system: No function
• Third kinematic system: No function
• Fourth kinematic system: No function

Example

Category: Safe operational stop

If the robot is situated outside of its workspace, it must be assured that
the robot is no longer moving as soon as persons are in its vicinity. The
workspace is configured by means of a Cartesian workspace. There is a
sensor connected to a safe input which detects persons at risk. If both the
workspace and the input signal are violated, the standstill monitoring is ac-
tivated.
AMF1 AMF2 AMF3 Reaction
Input signal Cartesian workspace Standstill monitoring Stop 1
monitoring of all axes

13.11.12 Activation delay for safety function

Description

The AMF Time delay can be used to delay the triggering of the reaction
of a safety function for a defined time.
This AMF is an extended AMF, meaning that the delay time only starts
running when all other AMFs of the safety function are violated.
Extended AMFs are not available for the safety functions of the ESM
mechanism.

AMF Description
Time delay This AMF is violated if the set time has expired.

If the same instance of the AMF is used for several safety functions, the
delay time begins running from the first activation.

312/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Parameter Description
Name Name of the AMF (optional)
Delay time Amount of time by which the triggering of the reaction of a
safety function is delayed.

• 12 ms … 24 h
The time can be entered in milliseconds (ms), seconds (s),
minutes (min) and hours (h). Each delay is a multiple of
12 ms, meaning that it is rounded up to the next multiple of
12.

Example

Category: Safety stop

A robot whose axes are not referenced is to be allowed to be moved in
Automatic mode for a limited time. Once this time has elapsed, e.g. after
2 hours, a safety stop 1 (path-maintaining) is triggered.
AMF1 AMF2 AMF3 Reaction
Automatic mode Position referencing Time delay Stop 1 (path-main-
taining)

13.11.13 Monitoring of forces and axis torques

Forces and axis torques can only be monitored on robots that are equip-
ped with position and axis torque sensors. These sensors can be used to
measure and monitor external forces acting on the robot and also axis tor-
ques.
If the permissible forces or torques are exceeded continuously due to
jamming, it is possible to move the robot free by changing to CRR
mode.

13.11.13.1 Axis torque monitoring

Axis torque monitoring can limit and monitor the torques of individual ax-
es.
The following points must be observed when using axis torque monitoring:
• Successful axis torque referencing is a precondition.

AMF Description
Axis torque monitoring The AMF is violated if the torque of the monitored axis ex-
ceeds or falls below the configured torque limit.

If the AMF is violated and a safety stop triggered, the interaction forces
may continue to increase due to the stopping distances of the robot. For
this reason, the AMF may only be used in collaborative operation at re-
duced velocity. For this, the AMF can be combined with the AMF Carte-
sian velocity monitoring, Axis velocity monitoring or Tool-related velocity
component.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 313/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Parameter Description
Name Name of the AMF (optional)
Monitored kinematic system Kinematic system to be monitored

• First kinematic system: robot

• Second kinematic system: no function
• Third kinematic system: no function
• Fourth kinematic system: no function
Monitored axis Axis to be monitored

• Axis1 … Axis16
Minimum torque [Nm] Minimum permissible torque for the given axis

• -500 … 500 Nm
Maximum torque [Nm] Maximum permissible torque for the given axis

• -500 … 500 Nm

13.11.13.2 Collision detection

Description

Collision detection monitors the external axis torques against a definable

limit value.
The external axis torque is that part of the torque of an axis which is gen-
erated from the forces and torques occurring as the robot interacts with its
environment. The external axis torque is not measured directly but is rath-
er calculated using the dynamic robot model. The accuracy of the calcula-
ted values depends on the dynamics of the robot motion and of the inter-
action forces of the robot with its environment.
The following points must be observed when using collision detection:
• Successful position and axis torque referencing are preconditions.
• The load data of safety-oriented tools are taken into consideration (if
active).
• If a safety-oriented fixed tool is configured, it must also be mounted
on the robot flange.
• The load data of workpieces that are picked up are only taken into
consideration if the current workpiece is communicated to the safety
controller.
(>>> 16.10.5 "Transferring workpiece load data to the safety controller"
Page 443)
• The weight of the heaviest workpiece whose mass is configured in the
safety-oriented project settings is taken into consideration.
(>>> 9.3.11.3 "Configuring the mass of the heaviest workpiece"
Page 196)

The AMF Collision detection does not automatically take into considera-
tion possible errors in the workpiece load data.
When configuring the collision detection, it is therefore necessary to set
the lowest possible values for the maximum permissible external torque.
In this way, significant deviations in the load data are interpreted as a
collision and cause a violation of the AMF.

314/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Workpieces that have been picked up must not come loose unintention-
ally and fall down while the monitoring is active. The user must ensure
this when using the AMF.

If the monitored kinematic system is fastened to a carrier kinematic sys-

tem (e.g. mobile platform, linear unit), it must be ensured that the carrier
kinematic system does not move while the AMF is being used. As long
as the robot base of the monitored kinematic system is being acceler-
ated, the safety integrity of the AMF is not assured.

If the monitored kinematic system is fastened to a carrier kinematic sys-

tem (e.g. mobile platform, linear unit), it must be ensured that the carrier
kinematic system does not move while the AMF is being used. As long
as the robot base of the monitored kinematic system is being acceler-
ated, the safety integrity of the AMF is not assured.

AMF Description
Collision detection This AMF is violated if the external torque of at least one axis
exceeds the configured limit value.

If the AMF is violated and a safety stop triggered, the interaction forces
may continue to increase due to the stopping distances of the robot. For
this reason, the AMF may only be used in collaborative operation at re-
duced velocity. For this, the AMF can be combined with the AMF Carte-
sian velocity monitoring, Axis velocity monitoring or Tool-related velocity
component.

External forces on the robot or tool with short distances to the robot ax-
es can only cause slight external torques in the robot axes under
certain circumstances. If the AMFs are used, this can pose a safety
risk, particularly in potential crushing situations during collaborative oper-
ation. Critical crushing situations can arise on the robot itself, between
the robot and the surroundings or between the tool and the surround-
ings.
It is therefore advisable to avoid potentially critical incidents of crushing
by using suitable equipment for the robot cell and/or by using one of the
following AMFs: Cartesian workspace monitoring, Cartesian protected
space monitoring, Axis range monitoring or Tool orientation.

Parameter Description
Name Name of the AMF (optional)
Monitored kinematic system Kinematic system to be monitored

• First kinematic system: Robot

• Second kinematic system: No function
• Third kinematic system: No function
• Fourth kinematic system: No function
Maximum external torque Maximum permissible external torque
[Nm]
• 0 … 30 Nm

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 315/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

13.11.13.3 TCP force monitoring

Safety configuration

Description

In TCP force monitoring, the external force acting on the tool or robot
flange is monitored against a definable limit value.
The external force on the TCP is not measured directly but is rather cal-
culated using the dynamic robot model. The accuracy of the calculated ex-
ternal force depends on the dynamics of the robot motion and of the ac-
tual force, among other things.
The following points must be observed when using TCP force monitoring:
• Successful position and axis torque referencing are preconditions.
• The load data of safety-oriented tools are taken into consideration (if
active).
• If a safety-oriented fixed tool is configured, it must also be mounted
on the robot flange.
• The load data of workpieces that are picked up are only taken into
consideration if the current workpiece is communicated to the safety
controller.
(>>> 16.10.5 "Transferring workpiece load data to the safety controller"
Page 443)
• The weight of the heaviest workpiece whose mass is configured in the
safety-oriented project settings is taken into consideration.
(>>> 9.3.11.3 "Configuring the mass of the heaviest workpiece"
Page 196)

The AMF TCP force monitoring automatically takes into consideration

possible errors in the workpiece load data. For this reason, when config-
uring the monitoring, it is necessary to set a value for the maximum per-
missible external force at the TCP which is greater than the weight of
the heaviest workpiece configured in the safety-oriented project settings.

Workpieces that have been picked up must not come loose unintention-
ally and fall down while the monitoring is active. The user must ensure
this when using the AMF.

If the monitored kinematic system is fastened to a carrier kinematic sys-

tem (e.g. mobile platform, linear unit), it must be ensured that the carrier
kinematic system does not move while the AMF is being used. As long
as the robot base of the monitored kinematic system is being acceler-
ated, the safety integrity of the AMF is not assured.

If the monitored kinematic system is fastened to a carrier kinematic sys-

tem (e.g. mobile platform, linear unit), it must be ensured, during use of
the AMF, that the mounting direction of the monitored kinematic system
does not differ from the configured mounting direction (e.g. due to tilting
of the mobile platform). Otherwise, the safety integrity of the AMF is not
assured.

AMF Description
TCP force monitoring This AMF is violated if the external force acting on the tool or
robot flange exceeds the configured limit value.

316/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
If the AMF is violated and a safety stop triggered, the interaction forces
may continue to increase due to the stopping distances of the robot. For
this reason, the AMF may only be used in collaborative operation at re-
duced velocity. For this, the AMF can be combined with the AMF Carte-
sian velocity monitoring, Axis velocity monitoring or Tool-related velocity
component.

External forces on the robot with short distances to the robot axes can
only cause slight external torques in the robot axes under certain cir-
cumstances. If the AMFs are used, this can pose a safety risk, particu-
larly in potential crushing situations during collaborative operation. Criti-
cal crushing situations can arise on the robot itself or between the robot
and the surroundings.
It is therefore advisable to avoid potentially critical incidents of crushing
by using suitable equipment for the robot cell and/or by using one of the
following AMFs: Cartesian workspace monitoring, Cartesian protected
space monitoring, Axis range monitoring or Tool orientation.

Parameter Description
Name Name of the AMF (optional)
Monitored kinematic system Kinematic system to be monitored

• First kinematic system: Robot

• Second kinematic system: No function
• Third kinematic system: No function
• Fourth kinematic system: No function
Maximum TCP force [N] Maximum permissible external force on the TCP

• 50 … 1,000 N

Accuracy of force detection

• The accuracy of TCP force detection is dependent on the robot pose.

The safety controller recognizes non-permissible poses and sets the
AMF TCP force monitoring to “violated” with a corresponding error
message.
Non-permissible poses are those in which it is possible for TCP forces
to have a short distance to all robot axes. This applies to singularity
poses and poses near singularities.
(>>> 15.11 "Singularities" Page 392)
• External forces on the robot reduce the accuracy of TCP force detec-
tion. In many cases, the safety controller can automatically detect the
external forces acting on the robot. The AMF TCP force monitoring is
violated in this case.

It is not possible to guarantee that the safety controller will always auto-
matically detect external forces acting on the robot. The user must en-
sure that the external forces act exclusively on the TCP in order to as-
sure the safety integrity of the AMF TCP force monitoring.

13.11.13.4 Direction-specific monitoring of the external force on the TCP

Description

The Base-related TCP force component AMF is used to monitor the exter-
nal force acting in a specific direction on the tool or on the robot flange
relative to a base coordinate system against a definable limit value.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 317/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

As standard, the world coordinate system is used as the base coordinate

Safety configuration

system. No other base coordinate system can currently be defined for this
monitoring function.
The AMF monitors the force along the component of a reference coordi-
nate system. The orientation of the reference coordinate system corre-
sponds as standard to the orientation of the base coordinate system. The
orientation of the reference coordinate system relative to the base coordi-
nate system can be modified in the AMF.

Fig. 13-22: Base-related TCP force monitoring

1 World coordinate system (= base coordinate system for the moni-

toring function)
2 World coordinate system is located as standard in the base of the
robot.
3 Negative X component of the TCP force vector
4 Negative Y component of the TCP force vector
5 Positive Z component of the TCP force vector
6 TCP force vector
The external force on the TCP is not measured directly but is rather cal-
culated using the dynamic robot model. The accuracy of the calculated ex-
ternal force depends on the dynamics of the robot motion and of the ac-
tual force, among other things.
The following points must be observed when monitoring base-related TCP
force components:
• Successful position and axis torque referencing are preconditions.
• The load data of safety-oriented tools are taken into consideration (if
active).
• If a safety-oriented fixed tool is configured, it must also be mounted
on the robot flange.
• The load data of workpieces that are picked up are only taken into
consideration if the current workpiece is communicated to the safety
controller.
(>>> 16.10.5 "Transferring workpiece load data to the safety controller"
Page 443)

318/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
• The weight of the heaviest workpiece whose mass is configured in the
safety-oriented project settings is taken into consideration.
(>>> 9.3.11.3 "Configuring the mass of the heaviest workpiece"
Page 196)

The Base-related TCP force component AMF automatically takes into

consideration possible errors in the workpiece load data.
For this reason, when configuring the monitoring, it is necessary to set
a value for the maximum permissible external force at the TCP which is
greater than the weight component of the mass of the heaviest work-
piece in the monitored direction.

The monitoring of individual force components has advantages over TCP

force monitoring:
• The monitoring function can be used in a larger workspace.
• Workpieces have no influence on horizontal monitoring functions.
Possible errors in the workpiece load data are not automatically taken
into consideration. This results in additional external forces in the verti-
cal direction. In the case of a monitoring function in the horizontal di-
rection, these errors have no effect.

The AMF Base-related TCP force component may only be used if the
direction in which hazardous forces can arise is known. At the same
time, it must be ensured that no hazardous forces can arise in the non-
monitored directions. If this is not the case, either the AMF TCP force
monitoring must be used, or the other directions must also be monitored
using the AMF Base-related TCP force component.

Workpieces that have been picked up must not come loose unintention-
ally and fall down while the monitoring is active. The user must ensure
this when using the AMF.

If the monitored kinematic system is fastened to a carrier kinematic sys-

tem (e.g. mobile platform, linear unit), it must be ensured that the carrier
kinematic system does not move while the AMF is being used. As long
as the robot base of the monitored kinematic system is being acceler-
ated, the safety integrity of the AMF is not assured.

If the monitored kinematic system is fastened to a carrier kinematic sys-

tem (e.g. mobile platform, linear unit), it must be ensured, during use of
the AMF, that the mounting direction of the monitored kinematic system
does not differ from the configured mounting direction (e.g. due to tilting
of the mobile platform). Otherwise, the safety integrity of the AMF is not
assured.

If the monitored kinematic system is fastened to a carrier kinematic sys-

tem (e.g. mobile platform, linear unit), it must be taken into considera-
tion that the reference coordinate system for the configured force com-
ponent is defined relative to the robot base. The monitored direction of
the force component moves with the carrier kinematic system.

AMF Description
Base-related TCP force com- The AMF is violated if the external force acting along the
ponent monitored component of the TCP force vector exceeds the
configured limit value.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 319/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

If the AMF is violated and a safety stop triggered, the interaction forces
may continue to increase due to the stopping distances of the robot. For
this reason, the AMF may only be used in collaborative operation at re-
duced velocity. For this, the AMF can be combined with the AMF Carte-
sian velocity monitoring, Axis velocity monitoring or Tool-related velocity
component.

External forces on the robot with short distances to the robot axes can
only cause slight external torques in the robot axes under certain cir-
cumstances. If the AMFs are used, this can pose a safety risk, particu-
larly in potential crushing situations during collaborative operation. Criti-
cal crushing situations can arise on the robot itself or between the robot
and the surroundings.
It is therefore advisable to avoid potentially critical incidents of crushing
by using suitable equipment for the robot cell and/or by using one of the
following AMFs: Cartesian workspace monitoring, Cartesian protected
space monitoring, Axis range monitoring or Tool orientation.

Parameter Description
Name Name of the AMF (optional)
Monitored kinematic system Kinematic system to be monitored

• First kinematic system: Robot

• Second kinematic system: No function
• Third kinematic system: No function
• Fourth kinematic system: No function
Maximum TCP force [N] Maximum external force acting along the monitored compo-
nent of the TCP force vector

• 50 … 1,000 N
A [°] Rotation of the TCP force vector about the Z axis of the base
coordinate system

• 0° … 359°
B [°] Rotation of the TCP force vector about the Y axis of the base
coordinate system

• 0° … 359°
C [°] Rotation of the TCP force vector about the X axis of the base
coordinate system

• 0° … 359°
Component of the TCP force Component of the TCP force vector that is monitored (direc-
vector tion of monitoring)

• X positive or X negative
• Y positive or Y negative
• Z positive or Z negative

Accuracy of force detection

• The accuracy of TCP force detection is also dependent on the robot

pose. The safety controller recognizes non-permissible poses and sets

320/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

the AMF Base-related TCP force component to “violated” with a corre-

Safety configuration
sponding error message.
Non-permissible poses are those in which it is possible for TCP forces
to have a short distance to all robot axes. This applies to singularity
poses and poses near singularities.
(>>> 15.11 "Singularities" Page 392)
Depending on the direction of the monitored force component, the
AMF Base-related TCP force component can be used closer to singu-
larities than the AMF TCP force monitoring. This can result in a larger
workspace.
• External forces on the robot reduce the accuracy of TCP force detec-
tion. In many cases, the safety controller can automatically detect the
external forces acting on the robot. The AMF Base-related TCP force
component is violated in this case.

It is not possible to guarantee that the safety controller will always auto-
matically detect external forces acting on the robot. The user must en-
sure that the external forces act exclusively on the TCP in order to as-
sure the safety integrity of the AMF Base-related TCP force component.

Example

A workpiece is to be set down on a table. In order to be able to detect

possible high crushing forces between the workpiece and the setdown
surface, the force acting on the workpiece in the positive Z direction must
be monitored. If the force in this direction exceeds a value of 50 N, a
safety stop 1 (path-maintaining) is to be triggered.

Fig. 13-23: Base-related TCP force monitoring in Z positive

Category: Collision detection

AMF1 AMF2 AMF3 Reaction
Base-related TCP - - Stop 1 (path-main-
force component taining)
The AMF Base-related TCP force component has the following parame-
ters:
• Monitored kinematic system: First kinematic system
• Maximum TCP force: 50 N
• Component of the TCP force vector: Z positive
• A = B = C: 0°

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 321/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

13.12 Example of a safety configuration

The sole purpose of this example is to illustrate the safety configuration

with KUKA Sunrise.Workbench.

The basis for a system’s safety configuration is always a risk assess-

ment carried out by the user. The safety configuration displayed below
serves only as an example and does not claim to be comprehensive.

13.12.1 Task

An LBR is used in an application in which it collaborates with a human.

The tool installed on the robot is set as safety-oriented.
The operator places a workpiece in a workpiece pick-up position at
regular intervals. One task of the robot is to check that the workpiece is
present. It proceeds as follows: from a start position, it moves through the
area accessible to humans (collaboration space) with a transfer motion.
The purpose of this transfer motion is to achieve a pre-position of 20 cm
above the waiting workpiece. It then moves toward the workpiece.
This lowering motion is parametrized with a force break condition (process
limit value: 20 N). After reaching the process limit value, the robot uses its
current position to determine whether the workpiece is present or not. The
workpiece is not present if the robot can move all the way to the work-
piece pick-up position. After it has finished checking, the robot moves
back to the pre-position and out of the collaboration space.

13.12.2 Requirements

The following safety functions are required as part of the risk assessment
for the above-described process:
1. It must be possible to stop the robot by pressing an external EMER-
GENCY STOP switch within reach of the operator.
2. The robot must not leave a defined workspace. The collaboration
space is part of the workspace.
3. A transfer motion between the start position and pre-position can
cause unintentional collisions with the operator. However, the space is
designed in such a way that humans cannot be crushed. To reduce
the risk of a collision, the maximum robot velocity for this space must
be limited to 500 mm/s.
4. Collisions must be safely detected during the transfer motion and must
cause the robot to come to a standstill. This is the case if, due to the
collision, a torque of 15 Nm is exceeded in at least one axis.
5. During the motion between the pre-position and the workpiece pick-up
position, there is a risk of the hand and arm of the operator being
crushed. In order to ensure that the operator can respond appropriate-
ly and that the braking distances are sufficiently short, the robot veloc-
ity must not exceed 100 mm/s for this motion.
6. Furthermore, the robot must be brought to a standstill during the mo-
tion between the pre-position and the workpiece pick-up position if
forces of more than 50 N arise. Force values of 20 N or more cause
the lowering motion in the process to be aborted and are thus suffi-
ciently below the latter limit.

322/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
13.12.3 Suggested solution for the task

Description

In order for the requirements to be implemented, permanent and switcha-

ble safety monitoring functions must be configured:
• Permanent monitoring of the external EMERGENCY STOP device and
workspace
• ESM state for the transfer motion between the start position and the
pre-position
• ESM state for the motion between the pre-position and the workpiece
pick-up position
To ensure a stable and smooth process sequence, the application must
be designed in such a way that the defined limit values for the safety
functions (velocity and workspace) are maintained.
The robot application implemented in the process described is not descri-
bed here.

Permanent safety monitoring

The EMERGENCY STOP function must be active throughout operation

and the robot must not leave the workspace. Corresponding safety func-
tions are configured in the Customer PSM table.

Fig. 13-24: Permanent safety monitoring (external E-STOP, Cartesian workspace)

Row Description
1 External EMERGENCY STOP
Implements requirement 1
An external EMERGENCY STOP is connected to a safe in-
put. If the operator actuates the EMERGENCY STOP, a
safety stop 1 (path-maintaining ) is executed.
2 Cartesian workspace monitoring
Implements requirement 2
The workspace is represented by a safely monitored Carte-
sian workspace. If the robot leaves the configured space, a
safety stop 1 (path-maintaining) is executed.

ESM state for transfer motion

An ESM state is defined for the transfer motion through the collaboration
space between the start and pre-position. This is activated in the applica-
tion before the transfer motion begins.
Velocity monitoring and collision detection must be active during the trans-
fer motion in order to sufficiently reduce the hazard in the event of a colli-
sion between human and robot.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 323/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

A protected space is additionally defined to rule out the possibility of the

Safety configuration

hand or arm of the operator being crushed. This brings the robot to a
standstill as soon as the distance between the robot or tool and the work-
piece pick-up position becomes less than 15 cm.

Fig. 13-25: ESM state for transfer motion

Row Description
1 Cartesian velocity monitoring
Implements requirement 3
If a Cartesian velocity exceeds 500 mm/s, a safety stop 1
(path-maintaining) is executed.
2 Collision detection
Implements requirement 4
If a collision causes an external torque of more than 15 Nm
in at least one robot axis, a safety stop 1 (path-maintaining)
is executed.
3 Protected space monitoring
Implements the safety of the state regardless of the time
and place of activation
The safely monitored protected space encompasses the
space above the workpiece pick-up position. As soon as
the robot or the safely monitored tool enters this space, a
safety stop 1 (path-maintaining) is executed.

ESM state for workpiece pick-up position

A specific ESM state is defined for the motions between the pre-position
and the workpiece pick-up position. This is activated in the application be-
fore the lowering motion begins.
Velocity monitoring and force monitoring must be active during the motion
in order to sufficiently reduce the hazard to the operator due to crushing
of the operator’s hand or lower arm.
The state must ensure a sufficient degree of safety, regardless of the time
or place of activation. The low permissible velocity and the active force
monitoring mean that no further measures are necessary.

324/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Fig. 13-26: ESM state for workpiece pick-up position

Row Description
1 Cartesian velocity monitoring
Implements requirement 5
If a Cartesian velocity exceeds 100 mm/s, a safety stop 1
(path-maintaining) is executed.
2 Force monitoring
Implements requirement 6
If a contact situation causes a force of more than 50 N to
be exerted at the TCP, a stop 0 is executed.

13.13 Position and axis torque referencing

Overview

During position and axis torque referencing, the mastering of the corre-
sponding sensors is checked. The safety integrity of the following AMFs is
only guaranteed if position and/or axis torque referencing has been carried
out successfully:
Position refer- Axis torque ref-
AMF
encing erencing
Standstill monitoring of all axes

Axis torque monitoring

Axis range monitoring

Cartesian velocity monitoring

Tool-related velocity component

Cartesian workspace monitoring

Cartesian protected space monitoring

Tool orientation

Collision detection

TCP force monitoring

Base-related TCP force component

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 325/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Request

After the following events, the referencing and thus the safety integrity of
the aforementioned AMFs is no longer given and the position and/or axis
torque referencing must be carried out again:
• Robot controller is rebooted.
• Safety configuration is modified.
• Position referencing of an axis fails.
• Axis torque referencing of an axis fails.
• Maximum torque of an axis torque sensor is exceeded.
• Only position referencing: Axis is remastered.
These events lead to cancellation of the referencing but not to a violation
of the AMFs. The kinematic system can be moved, but the safety integrity
of the AMFs is no longer given. The AMFs are only violated after these
events if the referencing of an axis fails.
The Position referencing AMF and the Torque referencing AMF can be
used to evaluate the referencing status and to initiate the safe state in the
absence of position and/or axis torque referencing.
(>>> 13.11.6 "Evaluating the position referencing" Page 292)
(>>> 13.11.7 "Evaluation of axis torque referencing" Page 293)

Methods for position referencing

During position referencing, the mastering of the position sensors of a kin-

ematic system is checked. The system checks whether the measured po-
sition of an axis corresponds to the actual mechanical position of the axis.
Position referencing can be carried out using different methods.
• Referencing with internal mastering sensors in the kinematic system
(>>> 13.13.1 "Position referencing with internal mastering sensors in
kinematic systems" Page 326)
• External confirmation of position mastering
(>>> 13.13.4 "External position referencing" Page 329)

Methods for axis torque referencing

During axis torque referencing, the mastering of the axis torque sensors of
a kinematic system is checked. The system checks whether the expected
torque of an axis corresponds to the actual torque of the axis.

13.13.1 Position referencing with internal mastering sensors in kinematic sys-

tems

Description

This procedure can only be used for kinematic systems with internal axis
mastering sensors, e.g. for robots of type LBR. It does not require an ex-
ternal device for verifying the mastering.
The mastering is automatically checked when an axis passes over the in-
ternal axis mastering mark at a low enough velocity. Referencing is suc-
cessful when the mastering sensor detects the mastering mark in a nar-
row range around the saved mastering position of the motor.
Referencing fails in the following cases:
• The mastering sensor does not detect a mastering mark in the range
around the saved mastering position of the motor.

326/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
• The mastering sensor detects the mastering mark of the axis at an un-
expected motor position.

Precondition

The position of an axis is referenced when the axis is moved over the
mastering position and the detected position of the mastering mark devi-
ates by no more than +/- 0.5° from the expected position.
Preconditions for this:
• The velocity at which the axis is moved over the mastering position
must be < 30 °/s.
• At the very least, a defined axis-specific range before and after the
mastering position must be passed through. The motion direction is
not relevant.
The axis-specific range of motion is robot-specific:
Robot A1 A2 A3 A4 A5 A6 A7
LBR iiwa 7 R800 ±10.5° ±10.5° ±10.5° ±10.5° ±10.5° ±14° ±14°
LBR iiwa 14 R820 ±9.5° ±9.5° ±10.5° ±10.5° ±10.5° ±14° ±14°

Execution

If the specified preconditions have been met, the position referencing is

performed continuously by the system for all axes. It can be performed in
a targeted manner in the following ways:
• Automatically while the program is running, when an axis moves over
the mastering position at less than 30 °/s
• By jogging, with the user moving each axis individually over the mas-
tering position
• By executing a referencing application

Template

KUKA Sunrise.Workbench provides a referencing application in which the

axes are moved over the mastering position, starting from the HOME po-
sition of the robot.
(>>> 13.13.3 "Creating a referencing application" Page 329)
If it is not possible to reference from the HOME position, a user-specific
application for position referencing must be created and executed.

13.13.2 Axis torque referencing

Description

During axis torque referencing, the mastering of the axis torque sensors is
checked. For this, the external axis torque is determined at a number of
different measurement poses. The external axis torque is the difference
between the expected and measured torque of an axis. It is calculated for
each axis using the robot model and the specified load data.

Referencing application

For axis torque referencing, a total of 10 measured axis torque values per
axis must be available. These are acquired at 5 different measurement
poses, which are each addressed with positive and negative directions of
axis rotation.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 327/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The safety controller evaluates the external torque for all 10 measured
Safety configuration

values and determines the mean value of the external torque for each ax-
is. Referencing is successful if this mean value lies within a defined toler-
ance.
The following must be taken into consideration when providing a referenc-
ing application:
• The robot must be at standstill during the measurement.
• A wait time of at least 2.5 seconds in which the robot does not move
is required between the moment the measurement pose is reached
and the measurement itself. Wait times which are too short can
reduce the referencing accuracy due to oscillations on the robot.
• The measurement is started with the sendSafetyCommand() method.
• There may be a maximum of 15 seconds between 2 consecutive
measurements.
• Each of the measurement poses must be addressed in sequence with
positive and negative directions of axis rotation before the next meas-
urement pose is addressed in order to check the hysteresis in the axis
torque detection. The safety integrity of the referencing of the axis tor-
que sensors is otherwise not given.

Template

KUKA Sunrise.Workbench provides an application that can be used to

perform axis torque referencing.
• If a load is mounted on the robot flange, it must be integrated into the
application.
• If the measurement poses cannot be addressed, they can be adapted
in the application.
(>>> 13.13.3 "Creating a referencing application" Page 329)

Execution

Before performing the axis torque referencing, the user must ensure the
following points:
• The load data of the fixed tool mounted on the robot flange must
match the load data with which the fixed safety-oriented tool is con-
figured.
• The load data of the tool that is coupled to the fixed tool (if present)
must match the load data of the activated safety-oriented tool.
• The load data of the workpiece that is picked up (if present) must
match the load data of the activated workpiece.
• There must be no supplementary loads mounted on the robot, e.g.
dress packages.
If one of these points is not met, the safety integrity of the referencing
of the axis torque sensors is not given.

328/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
If the monitored kinematic system is fastened to a carrier kinematic sys-
tem (e.g. mobile platform, linear unit), the user must ensure the follow-
ing points:
• The carrier kinematic system may not be moved during axis torque
referencing.
• The mounting direction of the kinematic system to be referenced
may not differ from the configured mounting direction (e.g. due to
tilting of the mobile platform).
If one of these points is not met, the safety integrity of the referencing
of the axis torque sensors is not given.

13.13.3 Creating a referencing application

Description

KUKA Sunrise.Workbench provides a referencing application that can be

used to perform position referencing and axis torque referencing.

Precondition

• Robot with internal axis mastering sensors and axis torque sensors

Procedure

1. In the Package Explorer view, select the desired project or package

in which the application is to be created.
2. Select the menu sequence File > New > Sunrise application. The
wizard for creating a new Sunrise application is opened.
3. In the folder Application examples > LBR iiwa, select the application
Position and GMS referencing.
4. Click on Finish. The application PositionAndGMSReferencing.java is
created in the source folder of the project and opened in the editor
area of Sunrise.Workbench.
5. Adapt the application as required.
(>>> 13.13.2 "Axis torque referencing" Page 327)
(>>> 13.13.1 "Position referencing with internal mastering sensors in
kinematic systems" Page 326)
6. Perform project synchronization in order to transfer the application to
the robot controller.

13.13.4 External position referencing

Description

The user has the possibility of implementing his own test method or an
external system for position referencing, e.g. a tracker, a navigation sys-
tem or an absolute encoder. Confirmation that the external position refer-
encing has been successfully carried out must be communicated to the ro-
bot controller via a safety-oriented input.
The input for external position referencing can be configured in the safety-
oriented project settings. If the external signal at this input changes from
LOW to HIGH and back to LOW within 2 seconds, the position
referencing has been successfully confirmed.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 329/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

External position referencing is merely an interface for setting the posi-

tion referencing. The safety maintenance personnel is responsible for
the correct use of the referencing input, i.e.:
• They must provide a suitable test method for position mastering.
• The test method for position mastering must be sufficiently accurate.
The accuracy of the position-based AMFs depends on the accuracy
of the test method.
• They must ensure that the input is only set after the position master-
ing has been successfully tested.

13.13.4.1 Configuring the input for external position referencing

Description

The safety-oriented input that allows external position referencing is con-

figured in the safety-oriented project settings.

Procedure

1. Right-click on the desired project in the Package Explorer view and

select Sunrise > Change project settings from the context menu.
The Properties for [Sunrise Project] window opens.
2. Select Sunrise > Safety in the directory in the left area of the window.
3. Make the following settings in the right-hand part of the window:
• Set the check mark at Allow external position referencing.
• Select the input that is to be used for external position referencing.
The inputs of the discrete safety interface and of the Ethernet
safety interface can be used as long as they are configured in
WorkVisual.
(>>> 13.3 "Safety interfaces" Page 254)
The enabling device of the hand guiding device can also be used
as an input.
4. Click on OK to save the settings and close the window.

13.14 Safety acceptance overview

The system must not be put into operation until the safety acceptance
procedure has been completed successfully. For successful safety accept-
ance, the points in the checklists must be completed fully and confirmed
in writing by the safety maintenance technician.
The completed checklists, confirmed in writing, must be kept as docu-
mentary evidence.

Safety acceptance must be carried out in the following cases:

• Following initial start-up or recommissioning of the industrial robot
• After a change to the industrial robot
• After a change to the safety configuration
• After a software update, e.g. of the System Software
Safety acceptance after a software update is only necessary if the ID
of the safety configuration (= checksum) has changed as a result of
the update.
The system integrator determines the required safety functions using the
risk assessment as a basis. Once the safety configuration is activated on

330/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

the robot controller, the safety functions must be tested for correct func-

Safety configuration
tioning.
If a test requires persons to be present in the danger zone, the test
must be conducted in T1 mode.

The following checklists must be used to verify whether the configured

safety parameters have been correctly transferred.
The checklists must be processed in the following order:
1. Basic properties of the safety configuration
(>>> 13.14.1 "Basic properties of the safety configuration" Page 331)
2. Configuration of the tool selection table
(>>> 13.14.2 "Tool selection table" Page 334)
3. Configuration of safety-oriented tools
(>>> 13.14.3 "Safety-oriented tools" Page 336)
4. Rows used in the Customer PSM table
(>>> 13.14.4 "Rows used in Customer PSM table" Page 341)
5. Rows used in the ESM states
(>>> 13.14.5 "Rows used in the ESM states" Page 342)
6. AMFs used in the PSM tables and ESM states
(>>> 13.14.6 "AMFs used in PSM tables and ESM states" Page 343)
7. Non-used ESM states
(>>> 13.14.5.1 "Non-used ESM states" Page 343)
8. General safety settings
(>>> 13.14.7 "General safety settings" Page 355)
It is possible to create a report of the current safety configuration.
(>>> 13.14.8 "Creating a safety configuration report" Page 357)

13.14.1 Basic properties of the safety configuration

Checklist

• Serial number of the robot: ____________________

• ID of the safety configuration: ____________________
• Name of safety maintenance technician: ____________________

No. Activity Yes Not relevant

1 Operator safety: is all operator safety equipment configured,
properly connected and tested for correct function?
2 Operator safety: a stop is triggered if AUT or T2 mode is ac-
tive with the operator safety open.
3 Operator safety: a manual reset function is present and acti-
vated.
4 Brake test: is a brake test planned and has an application
been created for this purpose?
5 Enabling on hand guiding device: is the enabling device of
the hand guiding device configured, properly connected and
tested for correct function?
6 Local EMERGENCY STOP: are all local EMERGENCY
STOP devices configured, properly connected and tested for
correct function?

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 331/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

No. Activity Yes Not relevant

7 External EMERGENCY STOP: are all external
EMERGENCY STOP devices configured, properly connected
and tested for correct function?
8 Local and external EMERGENCY STOP: are the local and
external EMERGENCY STOPs each configured as an indi-
vidual AMF in a row of the PSM table?
9 If unplugging of the smartPAD is allowed in the station con-
figuration: is at least one external EMERGENCY STOP de-
vice installed?
10 Safety stop: is all safety stop equipment configured, properly
connected and tested for correct function?
11 Safe operational stop: is all equipment for the safe opera-
tional stop configured, properly connected and tested for cor-
rect function?
12 When using position-specific AMFs: is the limited safety in-
tegrity of the position-specific AMFs taken into consideration
in the absence of position referencing?
(>>> 13.13 "Position and axis torque referencing" Page 325)
Note: Initiation of the safe state in the absence of position
referencing can be configured by using the Position referenc-
ing AMF.
13 When using position-specific AMFs: has position referencing
been carried out successfully?
14 If external position referencing is used: has a suitable test
method for position mastering been provided?
15 If external position referencing is used: has it been ensured
that the input is only set after successful testing?
16 Velocity monitoring: have all necessary velocity monitoring
tests been configured and tested?
17 Manual guidance: has it been configured in such a way that
appropriate velocity monitoring is active in every operating
mode for manual guidance?
18 If using the enabling device of the hand guiding device as
an input for deactivating safety functions:
Has it been taken into consideration that using the enabling
device as an input may result in safety functions being deac-
tivated during manual guidance?
19 Workspace monitoring: have all necessary workspace moni-
toring tests been configured and tested?
20 Cartesian workspace monitoring functions: has it been taken
into consideration that the system does not monitor the en-
tire structure of the robot, tool and workpiece against the
space violation, but only the monitoring spheres on the robot
and tool?
21 Collision detection: have all necessary HRC functionalities
been configured?
22 Collision detection: has it been configured in such a way
that velocity monitoring is also always active when collision
detection is active?

332/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
No. Activity Yes Not relevant
23 Collision detection: has it been configured in such a way
that velocity monitoring is also always active when TCP
force monitoring or monitoring of a base-related TCP force
component is active?
24 Collision detection: when using the Base-related TCP force
component AMF:
Has it been ensured that no hazardous forces can arise in
the non-monitored directions?
25 Collision detection: is a safety stop 0 configured for all
safety monitoring functions in order to detect crushing situa-
tions?
26 When using axis torque-specific AMFs: is the limited safety
integrity of the axis torque-specific AMFs taken into consider-
ation in the absence of position referencing and/or axis tor-
que referencing?
(>>> 13.13 "Position and axis torque referencing" Page 325)
Note: Initiation of the safe state in the absence of position
and/or axis torque referencing can be configured by using
the Position referencing AMF and/or the Torque referencing
AMF.
27 In the configuration of all rows in the PSM table and all
ESM states, has it been taken into account that the safe
state of the AMFs is the “violated” state (state “0”)?
Note: In the event of an error, an AMF goes into the safe
state.
28 PSM configuration: in the configuration of output signals, has
it been taken into account for the safety reaction that an out-
put is LOW (state “0”) in the safe state?
29 PSM configuration: Was a check carried out during configu-
ration of the “Brake” safety reaction to see whether there
could be an increased risk due to rapid switching to and
from the violation state of the AMFs with which the Cartesi-
an velocity monitoring is linked?
Note: In the case of rapid switching between the states, it is
possible that the “Brake” safety reaction could lead to no re-
duction in velocity.
30 ESM configuration: are all ESM states consistent, i.e. does
each individual ESM state sufficiently reduce all dangers?
31 Have axis torque referencing and position referencing been
carried out successfully?
32 If the monitored kinematic system is fastened to a carrier
kinematic system (e.g. mobile platform, linear unit):
Has the fact been taken into consideration that, with the
AMF Cartesian workspace monitoring / Cartesian protected
space monitoring, the monitoring space is defined relative to
the base of the monitored kinematic system and moves with
the carrier kinematic system?

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 333/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

No. Activity Yes Not relevant

33 If the monitored kinematic system is fastened to a carrier
kinematic system (e.g. mobile platform, linear unit):
Has the fact been taken into consideration that, with the
Cartesian velocity monitoring AMF, it is not the absolute ve-
locity, but the velocity of the monitored kinematic system rel-
ative to the carrier kinematic system that is monitored?
34 If the monitored kinematic system is fastened to a carrier
kinematic system (e.g. mobile platform, linear unit):
Has the fact been taken into consideration that, with the
Tool-related velocity component AMF, it is not the absolute
velocity, but the velocity of the monitored kinematic system
relative to the carrier kinematic system that is monitored?
35 If the monitored kinematic system is fastened to a carrier
kinematic system (e.g. mobile platform):
Has the fact been taken into consideration that, with the Tool
orientation AMF, the reference orientation is defined relative
to the carrier kinematic system and moves with the carrier
kinematic system?
36 If the monitored kinematic system is fastened to a carrier
kinematic system (e.g. mobile platform):
Has the fact been taken into consideration that, with the
Base-related TCP force component AMF, the reference coor-
dinate system is defined relative to the robot base and the
monitored direction of the force component moves with the
carrier kinematic system?
37 If the monitored kinematic system is fastened to a carrier
kinematic system (e.g. mobile platform, linear unit):
Has the fact been taken into consideration that the safety in-
tegrity of the Collision detection, TCP force monitoring and
Base-related TCP force component AMFs is only assured as
long as the carrier kinematic system is at a standstill?

By signing, the signatory confirms the correct and complete performance of the safety accept-
ance test.

___________________________________________ ___________________________________________

Place, date Signature

___________________________________________ ___________________________________________

Place, date Signature

___________________________________________ ___________________________________________

Place, date Signature

13.14.2 Tool selection table

Description

If one of the following AMFs is used in the safety configuration, the map-
ped safety-oriented tools must be checked:
• Cartesian velocity monitoring
Only if the monitoring spheres on the tool are configured as a struc-
ture to be monitored.

334/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
• Tool-related velocity component
• Cartesian workspace monitoring / Cartesian protected space monitor-
ing
Only if the monitoring spheres on the tool are configured as a struc-
ture to be monitored.
• Tool orientation
• Collision detection
• TCP force monitoring
• Base-related TCP force component
• Torque referencing
For each activated row of the tool selection table, it is necessary to check
whether the selected tool has been correctly assigned to the kinematic
system. This can be done, for example, using a suitable test for verifica-
tion of the tool parameters. A test is suitable if it checks a tool parameter,
the value of which differs considerably from that of the other safety-orien-
ted tools:
• In the case of considerably different geometric dimensions, it is advis-
able to check whether the geometric tool data have been specified
correctly.
(>>> 13.14.3.5 "Geometry data of the tool" Page 339)
• In the case of considerably different load data, it is advisable to check
whether the load data of the tool have been specified correctly.
(>>> 13.14.3.6 "Load data of the tool" Page 340)
• In the case of considerably different parameters when using the Tool
orientation AMF, it is advisable to check whether the tool orientation
that is to be monitored has been configured correctly.
(>>> 13.14.3.3 "Tool orientation" Page 338)
• In the case of considerably different parameters when using the Tool-
related velocity component AMF, it is advisable to check whether the
velocity component that is to be monitored has been configured cor-
rectly.
(>>> 13.14.3.4 "Points and orientation for tool-related velocity compo-
nent" Page 339)

For each row in the tool selection table, the points in the checklist must
be executed and separately documented.

Precondition

• If the tool is activated via an input: the configured input is HIGH.

• If the tool is always active: only the fixed tool is mounted on the kine-
matic system.

Checklist

• Row no.: ____________________

• Assigned kinematic system: ____________________
• Selected tool: ____________________
• Activation signal (always active / name of input):
____________________

No. Activity Yes

1 The row has been checked successfully: the correct tool has been as-
signed to the kinematic system.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 335/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

13.14.3 Safety-oriented tools

13.14.3.1 Pickup frame of fixed tools

Description

If the fixed tool of a kinematic system can pick up activatable tools, and if
one of the following AMFs is used simultaneously in the safety configura-
tion, the position and orientation of the pickup frame of the fixed tool (=
default frame for motions of the fixed tool) must be checked:
• Cartesian velocity monitoring
Only if the monitoring spheres on the tool are configured as a struc-
ture to be monitored.
• Tool-related velocity component
• Cartesian workspace monitoring / Cartesian protected space monitor-
ing
Only if the monitoring spheres on the tool are configured as a struc-
ture to be monitored.
• Tool orientation
• Collision detection
• TCP force monitoring
• Base-related TCP force component
• Torque referencing
If the fixed tool of a kinematic system can pick up workpieces, and if one
of the following AMFs is used simultaneously in the safety configuration,
the position and orientation of the pickup frame of the fixed tool must
again be checked:
• Collision detection
• TCP force monitoring
• Base-related TCP force component
• Torque referencing
If the fixed tool is used for picking up workpieces (no activatable tool can
be coupled), the pickup frame of the fixed tool must be verified. For this
purpose, check whether the load data of the tool have been specified cor-
rectly. The test must be carried out with as heavy a workpiece as possi-
ble.
(>>> 13.14.3.6 "Load data of the tool" Page 340)
If the fixed tool is used for picking up an activatable tool (e.g. in the case
of a tool changer), the pickup frame of the fixed tool must be verified by
means of a suitable test with the activatable tool coupled to the fixed tool.
A test is suitable if the parameters of the pickup frame have a major influ-
ence on the test result:
• In the case of large values for the position of the pickup frame and/or
a protruding coupled tool, it is advisable to check whether the geomet-
ric tool data have been specified correctly.
(>>> 13.14.3.5 "Geometry data of the tool" Page 339)
If the tool is relevant for the monitoring of a tool-related velocity com-
ponent, it is advisable to check whether the velocity component to be
monitored has been configured correctly.
(>>> 13.14.3.4 "Points and orientation for tool-related velocity compo-
nent" Page 339)

336/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
• In the case of large values for the position of the pickup frame and a
heavy coupled tool, it is advisable to check whether the load data of
the tool have been specified correctly.
(>>> 13.14.3.6 "Load data of the tool" Page 340)
• If only the tool orientation is monitored for a kinematic system, the ori-
entation of the pickup frame can be verified. The test is only suitable if
none of the other AMFs mentioned above is used in the safety config-
uration for this kinematic system.
(>>> 13.14.3.3 "Tool orientation" Page 338)

For each configured fixed tool in the tool selection table, the points in
the checklist must be executed and separately documented if the follow-
ing preconditions are met:
• The tool can pick up workpieces or activatable tools.
• AND: One of the AMFs listed here is used in the safety configura-
tion for the kinematic system to which the tool is assigned.

Precondition

• If the fixed tool picks up workpieces:

‒ The tool has picked up the heaviest possible workpiece.
‒ In the application, the correct workpiece has been transferred to
the safety controller.
• If the fixed tool picks up activatable tools:
‒ An activatable tool is coupled to the fixed tool.
‒ The input used to activate the coupled tool is HIGH.

Checklist

• Name of the fixed tool: ____________________

No. Activity Yes

1 Position and orientation of the pickup frame have been checked suc-
cessfully.

13.14.3.2 Pickup frames of activatable tools

Description

If an activatable tool of a kinematic system can pick up a workpiece and,

at the same time, one of the following AMFs is used in the safety config-
uration, the position and orientation of the pickup frame of the activatable
tool must be checked:
• Collision detection
• TCP force monitoring
• Base-related TCP force component
• Torque referencing
The pickup frame of the tool can be verified by checking whether the load
data of the tool have been specified correctly. The test must be carried
out with as heavy a workpiece as possible.
(>>> 13.14.3.6 "Load data of the tool" Page 340)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 337/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

For each configured activatable tool in the tool selection table, the
points in the checklist must be executed and separately documented if
the following preconditions are met:
• The tool can pick up workpieces.
• AND: One of the AMFs listed here is used in the safety configura-
tion for the kinematic system to which the tool is assigned.

Precondition

• The input used to activate the tool is HIGH.

• The tool has picked up the heaviest possible workpiece.
• In the application, the correct workpiece has been transferred to the
safety controller.

Checklist

• Name of the activatable tool: ____________________

No. Activity Yes

1 Position and orientation of the pickup frame have been checked suc-
cessfully.

13.14.3.3 Tool orientation

Description

If one of the following AMFs is used in the safety configuration, it is nec-

essary to check whether the tool orientation that is to be monitored has
been configured correctly:
• Tool orientation
For verification, the Tool orientation AMF must be verified successfully.
(>>> 13.14.6.24 "Tool orientation AMF" Page 352)
The checklist must be completed for every safety-oriented tool that is
mapped in the tool selection table to a kinematic system for which the
Tool orientation AMF is configured.

Precondition

• Position referencing has been carried out successfully (not necessary

in the case of a mobile platform).
• The correct safety-oriented tool is active.
• If a fixed tool is checked, no activatable tool is coupled.

Checklist

• Name of the tool: ____________________

No. Activity Yes

1 The correct configuration of the tool orientation to be monitored has
been successfully checked.

338/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

13.14.3.4 Points and orientation for tool-related velocity component

Safety configuration
Description

If one of the following AMFs is used in the safety configuration, it is nec-

essary to check whether the points and orientation of the tool-related ve-
locity component have been configured correctly:
• Tool-related velocity component
For verification, the Tool-related velocity component AMF must be verified
successfully.
(>>> 13.14.6.25 "Tool-related velocity component AMF" Page 354)
The checklist must be completed for every safety-oriented tool that
could be taken into consideration in the Tool-related velocity component
AMF according to the tool selection table.

Precondition

• Position referencing has been carried out successfully (not necessary

in the case of a mobile platform).
• The correct safety-oriented tool is active.
• If a fixed tool is checked, no activatable tool is coupled.

Checklist

• Name of the tool: ____________________

No. Activity Yes

1 The correct configuration of the points and orientation of the tool-related
velocity component to be monitored has been successfully checked.

13.14.3.5 Geometry data of the tool

Description

If one of the following AMFs is used in the safety configuration, it is nec-

essary to check that the geometric tool data have been entered correctly:
• Cartesian velocity monitoring
Only if the monitoring spheres on the tool are configured as a struc-
ture to be monitored.
• Cartesian workspace monitoring / Cartesian protected space monitor-
ing
Only if the monitoring spheres on the tool are configured as a struc-
ture to be monitored.
The geometric tool data can be tested by intentionally violating one of the
configured monitoring spaces with each tool sphere and checking the re-
action.
If no space monitoring functions are used, only the position of the sphere
center points is relevant. The configured Cartesian velocity limit can be
tested by intentionally exceeding this velocity for each tool sphere and
checking the reaction.
The checklist must be completed for every safety-oriented tool that is
mapped in the tool selection table to a kinematic system for which one
of the AMFs referred to above is configured.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 339/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Precondition

• Position referencing has been carried out successfully (not necessary

in the case of a mobile platform).
• The correct safety-oriented tool is active.
• If a fixed tool is checked, no activatable tool is coupled.

Checklist

• Name of the safety-oriented tool: ____________________

No. Activity Yes Not relevant

1 Tool sphere (frame name) _____________
Have the radius and position of the tool sphere been cor-
rectly entered and checked?
2 Tool sphere (frame name) _____________
Have the radius and position of the tool sphere been cor-
rectly entered and checked?
3 Tool sphere (frame name) _____________
Have the radius and position of the tool sphere been cor-
rectly entered and checked?
4 Tool sphere (frame name) _____________
Have the radius and position of the tool sphere been cor-
rectly entered and checked?
5 Tool sphere (frame name) _____________
Have the radius and position of the tool sphere been cor-
rectly entered and checked?
6 Tool sphere (frame name) _____________
Have the radius and position of the tool sphere been cor-
rectly entered and checked?

13.14.3.6 Load data of the tool

Description

If any of the following AMFs is used in the safety configuration, it is nec-

essary to check that the load data of the safety-oriented tool have been
entered correctly:
• Collision detection
• TCP force monitoring
• Base-related TCP force component
• Torque referencing
It is advisable to check the load data by performing axis torque referenc-
ing in several suitable poses. Suitable poses include those with similar ax-
is angles in the horizontal extended position and the following properties:
• Axes A2, A4 and A6 are loaded.
• The poses differ in their axis value of A7 by 90°.
If the load data are correct, axis torque referencing must be successful.
The checklist must be completed for every safety-oriented tool that is
mapped in the tool selection table to a kinematic system for which one
of the AMFs referred to above is configured.

340/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Precondition

• Position and axis torque referencing have been carried out successful-
ly.
• The correct safety-oriented tool is active.
• If the load data of a fixed tool are being checked: No activatable tool
is coupled.
• If a workpiece is picked up by the tool to check the load data: In the
application, the correct workpiece has been transferred to the safety
controller.

Checklist

• Name of the tool: ____________________

• Mass: ____________________
• Center of mass:
‒ MS X: ____________________
‒ MS Y: ____________________
‒ MS Z: ____________________

No. Activity Yes

1 Have the load data of the tool been correctly entered and checked?

13.14.4 Rows used in Customer PSM table

Description

Each row in the Customer PSM table must be tested to verify that the ex-
pected reaction is triggered. If the reaction is to switch off an output, the
test must also ensure that the output is correctly connected.
The “Brake” reaction can be checked by moving the robot at a velocity
that exceeds the limit value of the Cartesian velocity monitoring. As soon
as all other AMFs of the PSM row are violated, the velocity must be re-
duced to a value below the limit value. There must be no stop to a com-
plete standstill.
A PSM row in the table can be tested by violating 2 of its AMFs at a time.
It is then possible to test the remaining AMF separately in a targeted
manner. If fewer than 3 AMFs are used in a row, the unassigned columns
are regarded as violated AMFs.
(>>> 13.14.6 "AMFs used in PSM tables and ESM states" Page 343)
For each row in the table Customer PSM, the points in the checklist
must be executed and separately documented.

Checklist

• Row no.: ____________________

No. Activity Yes Not relevant

1 AMF 1 was tested successfully. Precondition: AMF 2 and
AMF 3 are violated.
AMF 1: ______________________________________
2 AMF 2 was tested successfully. Precondition: AMF 1 and
AMF 3 are violated.
AMF 2: ______________________________________

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 341/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

No. Activity Yes Not relevant

3 AMF 3 was tested successfully. Precondition: AMF 1 and
AMF 2 are violated.
AMF 3: ______________________________________

13.14.5 Rows used in the ESM states

Description

Each row in the ESM state must be tested to verify that the expected re-
action is triggered when the configured AMF is violated.
(>>> 13.14.6 "AMFs used in PSM tables and ESM states" Page 343)
For each ESM state, the points in the checklist must be executed and
separately documented.

Checklist

• Number of the ESM state: ____________________

• Name of the ESM state: ____________________

No. Activity Yes Not relevant

1 AMF row 1 was tested successfully.
AMF row 1: _________________________________
2 AMF row 2 was tested successfully.
AMF row 2: _________________________________
3 AMF row 3 was tested successfully.
AMF row 3: _________________________________
4 AMF row 4 was tested successfully.
AMF row 4: _________________________________
5 AMF row 5 was tested successfully.
AMF row 5: _________________________________
6 AMF row 6 was tested successfully.
AMF row 6: _________________________________
7 AMF row 7 was tested successfully.
AMF row 7: _________________________________
8 AMF row 8 was tested successfully.
AMF row 8: _________________________________
9 AMF row 9 was tested successfully.
AMF row 9: _________________________________
10 AMF row 10 was tested successfully.
AMF row 10: _________________________________
11 AMF row 11 was tested successfully.
AMF row 11: _________________________________
12 AMF row 12 was tested successfully.
AMF row 12: _________________________________

342/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
No. Activity Yes Not relevant
13 AMF row 13 was tested successfully.
AMF row 13: _________________________________
14 AMF row 14 was tested successfully.
AMF row 14: _________________________________
15 AMF row 15 was tested successfully.
AMF row 15: _________________________________
16 AMF row 16 was tested successfully.
AMF row 16: _________________________________
17 AMF row 17 was tested successfully.
AMF row 17: _________________________________
18 AMF row 18 was tested successfully.
AMF row 18: _________________________________
19 AMF row 19 was tested successfully.
AMF row 19: _________________________________
20 AMF row 20 was tested successfully.
AMF row 20: _________________________________

13.14.5.1 Non-used ESM states

Description

All ESM states which are not used must be tested as to whether a safety
stop is triggered when the ESM state is selected.

Checklist

No. Activity Yes Not relevant

1 Selection of non-used ESM state 1 was tested successfully.
2 Selection of non-used ESM state 2 was tested successfully.
3 Selection of non-used ESM state 3 was tested successfully.
4 Selection of non-used ESM state 4 was tested successfully.
5 Selection of non-used ESM state 5 was tested successfully.
6 Selection of non-used ESM state 6 was tested successfully.
7 Selection of non-used ESM state 7 was tested successfully.
8 Selection of non-used ESM state 8 was tested successfully.
9 Selection of non-used ESM state 9 was tested successfully.
10 Selection of non-used ESM state 10 was tested successfully.

13.14.6 AMFs used in PSM tables and ESM states

An AMF which is used in more than one row in the PSM table must be
separately tested in each row.
(>>> 13.14.4 "Rows used in Customer PSM table" Page 341)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 343/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

13.14.6.1 AMF smartPAD Emergency Stop

Safety configuration

Checklist

• Name of the AMF: ____________________

No. Activity Yes

1 The configured reaction is triggered by pressing the E-STOP on the
smartPAD.

13.14.6.2 AMF smartPAD enabling switch inactive

Checklist

• Name of the AMF: ____________________

No. Activity Yes

1 The configured reaction is triggered by releasing all enabling switches
on the smartPAD.

13.14.6.3 AMF smartPAD enabling switch panic active

Checklist

• Name of the AMF: ____________________

No. Activity Yes

1 The configured reaction is triggered by pressing an enabling switch
down fully on the smartPAD.

13.14.6.4 AMF Hand guiding device enabling inactive

Description

All enabling and panic switches configured for the hand guiding device
must be tested.

Checklist

• Name of the AMF: ____________________

• Input used, enabling switch 1: ____________________
• Input used, enabling switch 2: ____________________
• Input used, enabling switch 3: ____________________
• Input used, panic switch 1: ____________________
• Input used, panic switch 2: ____________________
• Input used, panic switch 2: ____________________

No. Activity Yes Not relevant

1 The configured reaction is triggered by releasing enabling
switch 1.
2 The configured reaction is triggered by pressing fully down
on enabling switch 1 (panic position).
3 The configured reaction is triggered by releasing enabling
switch 2.

344/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
No. Activity Yes Not relevant
4 The configured reaction is triggered by pressing fully down
on enabling switch 2 (panic position).
5 The configured reaction is triggered by releasing enabling
switch 3.
6 The configured reaction is triggered by pressing fully down
on enabling switch 3 (panic position).

13.14.6.5 AMF Hand guiding device enabling active

Description

All enabling switches configured for the hand guiding device must be tes-
ted.

Checklist

• Name of the AMF: ____________________

• Input used, enabling switch 1: ____________________
• Input used, enabling switch 2: ____________________
• Input used, enabling switch 3: ____________________

No. Activity Yes Not relevant

1 The configured reaction is triggered by pressing enabling
switch 1.
2 The configured reaction is triggered by pressing enabling
switch 2.
3 The configured reaction is triggered by pressing enabling
switch 3.

13.14.6.6 AMF Test mode

Checklist

• Name of the AMF: ____________________

No. Activity Yes

1 The configured reaction is triggered in T1.
2 The configured reaction is triggered in T2.
3 The configured reaction is triggered in CRR.

13.14.6.7 AMF Automatic mode

Checklist

• Name of the AMF: ____________________

No. Activity Yes

1 The configured reaction is triggered in AUT.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 345/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

13.14.6.8 AMF Reduced-velocity mode

Safety configuration

Checklist

• Name of the AMF: ____________________

No. Activity Yes

1 The configured reaction is triggered in T1.
2 The configured reaction is triggered in CRR.

13.14.6.9 AMF High-velocity mode

Checklist

• Name of the AMF: ____________________

No. Activity Yes

1 The configured reaction is triggered in T2.
2 The configured reaction is triggered in AUT.

13.14.6.10 AMF Motion enable

Checklist

• Name of the AMF: ____________________

No. Activity Yes

1 The configured reaction is triggered if, for example, the E-STOP is
pressed on the smartPAD.

13.14.6.11 AMF Input signal

Checklist

• Instance of the AMF: ____________________

• Name of the AMF: ____________________
• Input for safety signal: ____________________

No. Activity Yes

1 The configured reaction is triggered if the input is LOW (state “0”).

13.14.6.12 Standstill monitoring of all axes AMF

Precondition

• Position referencing has been carried out successfully.

Checklist

• Instance of the AMF: ____________________

• Name of the AMF: ____________________
• Monitored kinematic system: ____________________

346/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
No. Activity Yes
1 The configured reaction is triggered if one axis of the monitored kinemat-
ic system is moved.

13.14.6.13 Axis torque monitoring AMF

Description

The AMF can be tested by displaying the current measured axis torques
on the smartPAD and then subjecting the monitored axis to gravitational
force or manual loading.

Precondition

• Axis torque referencing has been carried out successfully.

Checklist

• Instance of the AMF: ____________________

• Name of the AMF: ____________________
• Monitored kinematic system: ____________________
• Monitored axis: ____________________
• Maximum permissible axis torque: ____________________
• Minimum permissible axis torque: ____________________

No. Activity Yes

1 The configured reaction is triggered if the axis torque exceeds the maxi-
mum permissible value.
2 The configured reaction is triggered if the axis torque falls below the
minimum permissible value.

13.14.6.14 AMF Axis velocity monitoring

Description

The AMF can be tested by moving the monitored axis at a velocity of ap-
prox. 10% over the configured velocity limit.

Checklist

• Instance of the AMF: ____________________

• Name of the AMF: ____________________
• Monitored kinematic system: ____________________
• Monitored axis: ____________________
• Maximum permissible axis velocity: ____________________

No. Activity Yes

1 The configured reaction is triggered if the maximum permissible axis ve-
locity is exceeded.

13.14.6.15 AMF Position referencing

This AMF is violated after the robot controller is rebooted.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 347/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Checklist

• Instance of the AMF: ____________________

• Name of the AMF: ____________________
• Monitored kinematic system: ____________________

No. Activity Yes

1 The configured reaction is triggered if one or more axes of the moni-
tored kinematic system are not referenced.

13.14.6.16 AMF Torque referencing

This AMF is violated after the robot controller is rebooted.

Checklist

• Instance of the AMF: ____________________

• Name of the AMF: ____________________
• Monitored kinematic system: ____________________

No. Activity Yes

1 The configured reaction is triggered if one or more axes of the moni-
tored kinematic system are not referenced.

13.14.6.17 Axis range monitoring AMF

Precondition

• Position referencing has been carried out successfully.

Checklist

• Instance of the AMF: ____________________

• Name of the AMF: ____________________
• Monitored kinematic system: ____________________
• Monitored axis: ____________________
• Lower limit of the permissible axis range: ____________________
• Upper limit of the permissible axis range: ____________________

No. Activity Yes

1 The configured reaction is triggered if the lower limit of the permissible
axis range is exceeded.
2 The configured reaction is triggered if the upper limit of the permissible
axis range is exceeded.

13.14.6.18 Cartesian velocity monitoring AMF

Description

In order to test the configured velocity limit of the AMF, the monitored kin-
ematic system must be moved in such a way that the monitored point that
moves fastest is moved at a velocity of approx. 10% above the configured
limit value.
It is also necessary to check whether the structure to be monitored (robot
and/or tool) is correctly configured:

348/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
• If both structures are monitored, the velocity monitoring must be viola-
ted both by the monitoring points on the robot and by the monitoring
points on the tool.
• If only one of the two structures is monitored, the velocity monitoring
must be violated by either the monitoring points on the robot or the
monitoring points on the tool.

Precondition

• Position referencing has been carried out successfully.

Checklist

• Instance of the AMF: ____________________

• Name of the AMF: ____________________
• Monitored kinematic system: ____________________
• Monitored structure: ____________________
• Maximum permissible Cartesian velocity: ____________________

No. Activity Yes Not relevant

1 The configured reaction is triggered if the maximum permis-
sible Cartesian velocity is exceeded at the fastest moving
monitored point.
2 The configured reaction is triggered if the velocity monitoring
is violated exclusively by the monitoring points on the robot.
3 The configured reaction is triggered if the velocity monitoring
is violated exclusively by the monitoring points on the tool.

13.14.6.19 AMF Cartesian workspace monitoring / Cartesian protected space mon-

itoring

Description

The first step is to test whether the orientation of the monitoring space is
correctly configured. This involves violating 2 adjoining space surfaces at
a minimum of 3 different points in each case.
The second step is to test whether the size of the monitoring space is
correctly configured. This involves violating the other space surfaces at
1 point in each case. In total, at least 10 points must be addressed.
The third step is to test whether the structure to be monitored is correctly
configured. This involves violating the space monitoring, both with the
monitoring spheres on the robot and on the tool (if both structures are to
be monitored), or just with the monitoring spheres on the robot or on the
tool.

Precondition

• Position referencing has been carried out successfully.

Checklist

• Instance of the AMF: ____________________

• Name of the AMF: ____________________
• Type of monitoring space: ____________________
• Monitored kinematic system: ____________________
• Monitored structure: ____________________
• Offset of the origin of the monitoring space:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 349/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

‒ X: ____________________ mm
‒ Y: ____________________ mm
‒ Z: ____________________ mm
• Orientation of the origin of the monitoring space:
‒ A: ____________________ °
‒ B: ____________________ °
‒ C: ____________________ °
• Length of the monitoring space: ____________________ mm
• Width of the monitoring space: ____________________ mm

No. Activity Yes Not relevant

1 The correct configuration of the orientation of the monitoring
space has been tested as described above. The configured
reaction is triggered every time the monitoring space is vio-
lated.
2 The correct configuration of the size of the monitoring space
has been tested as described above. The configured reac-
tion is triggered every time the monitoring space is violated.
3 The configured reaction is triggered if the space monitoring
is violated on the monitoring spheres on the robot.
4 The configured reaction is triggered if the space monitoring
is violated on the monitoring spheres on the tool.

13.14.6.20 Collision detection AMF

Description

The AMF can be tested by displaying the current measured external axis
torques on the smartPAD and then loading the individual axes.

Precondition

• Axis torque referencing has been carried out successfully.

• Position referencing has been carried out successfully.

Checklist

• Instance of the AMF: ____________________

• Name of the AMF: ____________________
• Monitored kinematic system: ____________________
• Maximum permissible external axis torque: ____________________

No. Activity Yes

1 The configured reaction is triggered if the external torque of one or more
axes of the monitored kinematic system exceeds the maximum permissi-
ble external torque.

13.14.6.21 TCP force monitoring AMF

Description

In order to test the AMF, suitable measuring equipment is required, e.g. a

spring balance.
During the test, it must be noted that the monitoring function automatically
takes into consideration possible errors in the workpiece load data. This

350/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

means that the response may be triggered before the permissible external

Safety configuration
TCP force has been reached.
Premature triggering of the response can be prevented by performing the
test as follows:
• Tool has picked up no workpiece.
• In the application, transfer no workpiece to the safety controller.
• Apply the TCP force in the direction of gravitational acceleration (verti-
cally downwards) or perpendicular to gravitational acceleration.

Precondition

• Axis torque referencing has been carried out successfully.

• Position referencing has been carried out successfully.

Checklist

• Instance of the AMF: ____________________

• Name of the AMF: ____________________
• Monitored kinematic system: ____________________
• Maximum permissible external TCP force: ____________________

No. Activity Yes

1 The configured reaction is triggered if the external force acting on the
TCP exceeds the maximum permissible force.

13.14.6.22 Base-related TCP force component AMF

Description

In order to test the AMF, suitable measuring equipment is required, e.g. a

spring balance.
For the test, a force that is just above the configured maximum permissi-
ble TCP force must be exerted on the tool or robot flange in 2 different di-
rections:
• Along the direction of the configured force component
• In a direction perpendicular to the direction of the configured force
component
This is to ensure that the AMF is only violated if an excessive force is ap-
plied along the direction of the configured force component.
During the test, it must be noted that the monitoring function automatically
takes into consideration possible errors in the workpiece load data. This
means that the response may be triggered before the permissible external
TCP force has been reached.
If, for example, no workpiece is picked up during the test, and if no work-
piece has been transferred to the safety controller in the application, this
force that is additionally taken into consideration corresponds to the
weight of the heaviest workpiece configured in the safety-oriented project
settings. The force that is taken into consideration counteracts gravitation-
al acceleration (it is applied vertically upwards).

Precondition

• Axis torque referencing has been carried out successfully.

• Position referencing has been carried out successfully.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 351/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Checklist

• Instance of the AMF: ____________________

• Name of the AMF: ____________________
• Monitored kinematic system: ____________________
• Maximum permissible external TCP force: ____________________
• Monitored component of the force vector: ____________________
• Base-related orientation:
‒ A: _____________ °
‒ B: _____________ °
‒ C: _____________ °

No. Activity Yes

1 The configured reaction is triggered if the external force acting along the
direction of the monitored component of the force vector exceeds the
maximum permissible force.
2 The configured reaction is not triggered if the force is applied in a direc-
tion perpendicular to the direction of the monitored force component.

13.14.6.23 AMF Time delay

Checklist

• Instance of the AMF: ____________________

• Name of the AMF: ____________________
• Delay time: ____________________

No. Activity Yes

1 The configured reaction is triggered after the configured time.

13.14.6.24 Tool orientation AMF

Description

In order to test the AMF, the permissible orientation cone must be violated
at 3 straight lines offset by approx. 120° to one another. This ensures that
the permissible orientation angle, the orientation of the reference vector
and the tool orientation are correctly configured.

352/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Fig. 13-27: Position of the straight lines on the monitoring cone

The orientation angles of the Z axis of the tool orientation frame are de-
fined using 3 straight lines situated on the edge of the monitoring cone
and offset at 120° to one another. These orientation angles must be set in
order to test the AMF Tool orientation. The AMF must be violated when all
3 orientation angles are exceeded.

Precondition

• Position referencing has been carried out successfully.

Procedure

The procedure describes an example of how the correct configuration of

the monitoring cone can be tested.
1. Orient the Z axis of the tool orientation frame according to the refer-
ence vector relative to the world coordinate system.
2. Exceed the permissible deviation angle by tilting the tool orientation
frame in B or C.
The configured reaction must be triggered.
3. Orient the Z axis of the tool orientation frame according to the refer-
ence vector relative to the world coordinate system.
If a stop reaction has been configured, the robot must be switched to
CRR mode in order for it to be moved.
4. Rotate the tool orientation frame by 120° in A.
5. Exceed the permissible deviation angle by tilting the tool orientation
frame in B or C.
The configured reaction must be triggered.
6. Orient the Z axis of the tool orientation frame according to the refer-
ence vector relative to the world coordinate system.
If a stop reaction has been configured, the robot must be switched to
CRR mode in order for it to be moved.
7. Rotate the tool orientation frame by 120° in A.
8. Exceed the permissible deviation angle by tilting the tool orientation
frame in B or C.
The configured reaction must be triggered.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 353/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The test must be carried out for every instance of the AMF and for ev-
ery tool that is mapped in the tool selection table to a kinematic system
for which the Tool orientation AMF is configured.
(>>> 13.14.3.3 "Tool orientation" Page 338)

If a fixed tool is configured that can pick up activatable tools, the fixed
tool must be checked in addition to the activatable tools without an acti-
vatable tool being coupled.
Example: 4 instances of the AMF are configured, with 5 different tools
that can be selected for fastening to the fixed tool. At least 6 tests are
necessary to verify all AMF instances and tool orientations. If, on the
other hand, only 2 different tools are available for selection for fastening
to the fixed tool, 4 tests are sufficient.

Checklist

• Instance of the AMF: ____________________

• Name of the AMF: ____________________
• Monitored kinematic system: ____________________
• Safety-oriented tool used: ____________________
• Orientation of the reference vector relative to the world coordinate sys-
tem:
‒ A: _____________ °
‒ B: _____________ °
‒ C: _____________ °
• Permissible workspace (deviation angle): _____________ °

No. Activity Yes

1 The correct configuration of the monitoring cone has been checked and
the configured reaction is triggered when the permissible angle for all 3
straight lines has been exceeded.

13.14.6.25 Tool-related velocity component AMF

Description

A motion must be programmed for every point that has been defined as a
point for the tool-related velocity component in the configuration parame-
ters of the currently mounted tool.
During this test motion, it must be ensured that the tested tool point has a
higher velocity along the monitored direction than the other tool point for
the tool-related velocity component. This can be achieved by including a
suitable reorientation of the tool in the test motion.
The test motion must be performed twice:
• Once at a velocity slightly above the maximum permissible velocity
• Once at a velocity slightly below the maximum permissible velocity
This is to ensure that the velocity limit is violated only by the tested point.
The test must be repeated for every tool point that has been defined as a
point for the tool-related velocity component.

Precondition

• Position referencing has been carried out successfully.

354/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Checklist

• Instance of the AMF: ____________________

• Name of the AMF: ____________________
• Monitored kinematic system: ____________________
• Tool used: ____________________
• Tested tool point: ____________________
• Monitored component of the velocity vector: ____________________
• Maximum permissible Cartesian velocity of the monitored component:
____________________

No. Activity Yes

1 The configured reaction is triggered if the motion is executed with a ve-
locity that exceeds the maximum permissible velocity.
2 The configured reaction is not triggered if the motion is executed with a
velocity that is below the maximum permissible velocity.

The test must be performed for all instances of the AMF and for all pos-
sible safety-oriented tools.
(>>> 13.14.3.4 "Points and orientation for tool-related velocity compo-
nent" Page 339)

If a fixed tool is configured that can pick up activatable tools, the fixed
tool must be checked in addition to the activatable tools. When checking
the fixed tool, no activatable tool may be coupled.
Example: 4 instances of the AMF are configured. At the same time, 5
different tools are available for selection for mounting on the fixed tool.
At least 6 tests are necessary to verify all AMF instances and tool-rela-
ted velocity components. If, on the other hand, only 2 different tools are
available for selection for fastening to the fixed tool, 4 tests are suffi-
cient.

13.14.7 General safety settings

13.14.7.1 smartPAD unplugging allowed

Description

The safety parameter smartPAD unplugging allowed in the station con-

figuration determines whether it is possible to move the robot with the
smartPAD unplugged. The configured response must be tested while the
robot is moving in Automatic mode.
• Disconnection not allowed:
If the smartPAD is disconnected, the robot is stopped with a safety
stop.
• Disconnection allowed:
If the smartPAD is disconnected, the robot continues moving.

Checklist

• smartPAD unplugging allowed (true/false): ____________________

No. Activity Yes

1 The expected response occurs if the smartPAD is unplugged while the
robot is moving in Automatic mode.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 355/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

13.14.7.2 Allow muting via input

Safety configuration

Description

If an input that allows the deactivation of safety functions is configured in

the safety-oriented project settings, a safety stop triggered by one of the
following AMFs can be briefly cancelled:
• Axis range monitoring
• Cartesian workspace monitoring
• Cartesian protected space monitoring
• Tool orientation
• Tool-related velocity component
• Standstill monitoring of all axes
• Position referencing
• Torque referencing
• Axis torque monitoring
• Collision detection
• TCP force monitoring
• Base-related TCP force component
The configured input must be tested. For this, a safety stop must be trig-
gered using at least one of the above AMFs, e.g. by violating a work-
space or activating a standstill monitoring function.
• Deactivation of safety functions via an input not allowed:
If the configured input is set to HIGH and retains this value, the robot
cannot be moved when the corresponding AMF is violated.
• Deactivation of safety functions via an input allowed:
If the configured input is set to HIGH and retains this value, the robot
can be moved for 5 seconds even though the corresponding AMF is
violated.

Checklist

• Allow muting via input (true/false): ____________________

• Configured input: ____________________

No. Activity Yes

1 The expected response occurs when the configured input is set to HIGH
and an attempt is made to move the robot.

13.14.7.3 Allow external position referencing

Description

The safety-oriented input configured for external position referencing must

be tested.
The axis positions are not referenced after a reboot of the robot controller.
If the safety configuration contains a position-dependent AMF, the warning
“Axis not referenced” is displayed.
• External position referencing not allowed:
If the configured input is set to HIGH for less than 2 seconds, the
warning will still be displayed.
• External position referencing allowed:
If the configured input is set to HIGH for less than 2 seconds, the
warning will no longer be displayed.

356/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety configuration
Checklist

• Allow external position referencing (true/false):

____________________
• Configured input: ____________________

No. Activity Yes

1 If the configured input is set to HIGH for less than 2 seconds, the warn-
ing “Axis not referenced” will no longer be displayed.

13.14.7.4 Mass of the heaviest workpiece

Description

If workpieces are picked up in an application of a kinematic system and,

at the same time, one of the following AMFs is used in the safety config-
uration, it is necessary to check whether the mass of the heaviest work-
piece has been configured correctly in the safety-oriented project settings:
• TCP force monitoring
• Base-related TCP force component
To check the configuration, 2 workpieces of different masses must be
transferred in the application with setSafetyWorkpiece(…):
• The mass of the workpiece is 1 g greater than the configured mass of
the heaviest workpiece (invalid workpiece mass):
If the invalid workpiece mass is transferred, a message must be dis-
played, indicating that the workpiece load data are invalid.
• The mass of the workpiece is the same as the configured mass of the
heaviest workpiece (valid workpiece mass):
When the valid workpiece mass is transferred, no such message may
be displayed.
On transferring the workpieces, one of the specified AMFs must also be
active.

Checklist

• Monitored kinematic system: ____________________

• Configured mass of the heaviest workpiece: ____________________

No. Activity Yes

1 If setSafetyWorkpiece(…) is used to transfer a workpiece whose mass is
1 g greater than the configured mass of the heaviest workpiece, a mes-
sage stating that the workpiece load data used are invalid is displayed.
2 If setSafetyWorkpiece(…) is used to transfer a workpiece whose mass is
the same as the configured mass of the heaviest workpiece, no mes-
sage stating that the workpiece load data used are invalid is displayed.

13.14.8 Creating a safety configuration report

Description

A report of the current safety configuration can be created and displayed

in the Editor. The report can be edited and printed for documentation pur-
poses.
The safety configuration report contains the following information for the
unambiguous assignment of the safety configuration:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 357/667

Safety configuration KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

• Name of the Sunrise project to which the safety configuration belongs

• Safety version used
• Safety ID (checksum of the safety configuration)
The safety ID must match the ID of the safety configuration which is
activated on the robot controller and is to be tested.
• Date and time of the last modification to the safety configuration

Checklists

The report provides the following checklists matching the safety configura-
tion:
• Checklist for checking the rows used in the Customer PSM table
• Checklists for checking the ESM states which have been used and not
used
• Checklists for checking the AMFs used
• Checklists for checking the safety-oriented project settings

The checklists provided by the safety configuration report are not suffi-
cient for a complete safety acceptance procedure. The following addi-
tional checklists must be used for complete safety acceptance:
• Checklist for basic test of the safety configuration
• Checklists for checking the safety-oriented tool
• Checklist for checking the tool selection table

Warnings

The safety configuration is checked. There are warnings for the following
situations:
• One row in the Customer PSM table is deactivated.
• One row in an ESM state is deactivated.
• Unplugging of the smartPAD is allowed, but no external EMERGENCY
STOP is used.
• The input for deactivating safety functions is used in the tool selection
table.
• Warning of the possible need to perform the brake test if a position-
based or axis torque-based monitoring function is configured.
• The “Brake” safety reaction is configured.
A check must be carried out to ensure that there is no increased risk
due to rapid switching to and from the violation state of the AMFs with
which the Cartesian velocity monitoring is linked.
The safety maintenance technician must give reasons why a warning may
be ignored.

Procedure

• Right-click on the desired project in the Package Explorer view and

select Sunrise > Create safety configuration report from the context
menu.
The report of the current safety configuration is created and opened in
the editor area.

358/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

KUKA Sunrise.SafetyVisualization
14 KUKA Sunrise.SafetyVisualization

14.1 Overview of KUKA Sunrise.SafetyVisualization 1.0

Description

KUKA Sunrise.SafetyVisualization 1.0 is an add-on option for the 3D visu-

alization of Cartesian monitoring spaces. The Cartesian monitoring spaces
are defined in the safety configuration and have been transferred to the
robot controller.

Connection via a web browser

If the option is enabled in the station configuration of the project that is

active on the robot controller, the user can connect to the robot controller
via a web browser.
• For this purpose, enter the IP address of the robot controller and port
8080 in the browser.
‒ e.g. 172.31.1.147:8080
The web browser then shows the current 3D visualization of the robot cell.
(>>> 14.1.1 "3D visualization" Page 359)

Supported web browsers

• Google Chrome version 69 or higher

• Mozilla Firefox version 60.3 or higher

Required browser settings

• JavaScript support is active.

• Hardware acceleration is active.
• Popups are allowed.

Supported robots

• LBR iiwa 7 R800

• LBR iiwa 14 R820

No robot model is visualized for other robot types.

14.1.1 3D visualization

Description

All active monitoring spaces are shown in the 3D visualization by default.

Active means: at least one PSM or ESM row in which a monitoring space
is used is activated in the safety configuration.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 359/667

KUKA Sunrise.SafetyVisualization KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 14-1: Overview of 3D visualization

1 Menu
2 GENERAL submenu
3 SAFETY SPHERE FILTER submenu
4 SAFETY SPACE FILTER submenu
5 PROTECTED SPACES submenu
6 WORKSPACES submenu
7 Orientation of the world coordinate system

360/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

KUKA Sunrise.SafetyVisualization
Item Description
1 Menu
The menu contains various displays and submenus.

• The menu and all submenus can be collapsed and expan-

ded.
• The menu language is English.
2 GENERAL submenu
General information (display only)

• Current connection status

• Name of the active project
• Current operating mode
• Active safety-oriented tool
• Active ESM state
The displays are refreshed automatically.
GENERAL submenu
Monitoring Space Visualization menu item

• Configurable visualization of the monitoring spaces

(>>> 14.1.1.1 "Visualizing the monitoring spaces" Page 362)
3 SAFETY SPHERE FILTER submenu
Filter for visualizing the safety spheres
(>>> 14.1.1.2 "Filter settings" Page 364)
4 SAFETY SPACE FILTER submenu
Filter for selecting and visualizing the monitoring spaces
(>>> 14.1.1.2 "Filter settings" Page 364)
5 PROTECTED SPACES submenu
Display of the protected spaces (name); according to filter se-
lection
6 WORKSPACES submenu
Display of the workspaces (name); according to filter selection
7 Orientation of the world coordinate system

• Red = +XWORLD
• Green = +YWORLD
• Blue = +ZWORLD

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 361/667

KUKA Sunrise.SafetyVisualization KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Buttons

Fig. 14-2: Standard view of menu

1 Closes the menu. 3 Expands the submenu.

2 Collapses the submenu.

Button Description
Close Controls Closes the menu.
Open Controls Opens the menu.
Expands a submenu.
Collapses a submenu.

14.1.1.1 Visualizing the monitoring spaces

Description

In the GENERAL submenu, it is possible to set how the monitoring

spaces are to be visualized. The following options are available for selec-
tion in the Monitoring Space Visualization menu item:

Wireframe

Visualization as a wireframe model

362/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

KUKA Sunrise.SafetyVisualization
Fig. 14-3: Visualization as a wireframe model

Transparent

Transparent visualization

Fig. 14-4: Transparent visualization

Solid

Non-transparent visualization

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 363/667

KUKA Sunrise.SafetyVisualization KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 14-5: Non-transparent visualization

14.1.1.2 Filter settings

Description

The safety spheres and monitoring spaces of the safety configuration that
are to be shown in 3D visualization can be set using various filters.

364/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

KUKA Sunrise.SafetyVisualization
Fig. 14-6: Filter settings

1 Filter for visualizing the safety spheres

2 Filter for selecting and visualizing the monitoring spaces
3 Display of the protected spaces (name); according to filter selec-
tion
4 Display of the workspaces (name); according to filter selection

SAFETY SPHERE FILTER

Filter for visualizing the safety spheres

The safety spheres on the robot and tool can be hidden and unhidden.
Only the safety spheres on the tool are visualized as standard.

SAFETY SPACE FILTER

Filter for selecting and visualizing the monitoring spaces

Filter criteria:

• Monitoring Type
Monitoring spaces of the Customer PSM table and/or ESM table(s) of
the safety configuration
‒ All: all tables
‒ Customer PSM: only Customer PSM table
‒ Or only a specific ESM table (selection by name of the ESM table)
• Row
Row(s) within the selected Customer PSM table and/or ESM table(s)
Only those rows are displayed in which at least one monitoring space
is configured.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 365/667

KUKA Sunrise.SafetyVisualization KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

‒ All: all relevant rows of the table(s)

‒ Active: only the relevant activated rows of the table(s)
‒ Or only a specific table row
• Only Stopping
Only monitoring spaces for which a stop reaction is configured in at
least one table row
• Space Type
Protected spaces and/or workspaces

PROTECTED SPACES

Display of the protected spaces (name); according to filter selection

It is possible to select and deselect individual protected spaces or all pro-
tected spaces at once (SELECT ALL). Only the selected spaces are
shown in the 3D visualization; deselected spaces are hidden.

WORKSPACES

Display of the workspaces (name); according to filter selection

It is possible to select and deselect individual workspaces or all workspa-
ces at once (SELECT ALL). Only the selected spaces are shown in the
3D visualization; deselected spaces are hidden.

Visualization of additional information

Certain AMFs that are configured in a row with a monitoring space, and
also the configured reaction, are indicated by icons. All table rows in
which the monitoring space is used are taken into account.
Icons for configured AMFs:
Icon Description
Monitoring of a safety-oriented input

• AMF Input signal

Velocity monitoring

• AMF Axis velocity monitoring

• AMF Cartesian velocity monitoring
• AMF Tool-related velocity component
Force monitoring

• AMF TCP force monitoring

• AMF Base-related TCP force component
Torque monitoring

• AMF Axis torque monitoring

• AMF Collision detection
Icons for configured reaction:
Icon Description
Stop configured as the reaction

Output signal configured as the reaction

366/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

KUKA Sunrise.SafetyVisualization
Example

The following monitoring functions are active in a Cartesian protected

space:
• Monitoring of the velocity of axis A1; stop as the reaction to the veloc-
ity limit being exceeded
• TCP force monitoring; output signal as the reaction to the maximum
permissible force being exceeded

Fig. 14-7: Visualization of additional information using the example of a protected space

14.1.2 Color coding

Description

The configured safety spheres and Cartesian monitoring spaces are

marked in color. The monitoring spaces differ according to space type,
configured reaction and violation state.

Surfaces and edges

The surfaces and edges of the non-violated monitoring spaces are dis-
played in the following colors depending on the type of space and the
configured reaction:
Surfaces:

• Workspace: green
• Protected space: blue
Edges:

• Stop configured as the reaction: black

• No stop configured as the reaction: green/blue
(color according to type of space)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 367/667

KUKA Sunrise.SafetyVisualization KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 14-8: Surfaces and edges

1 Workspace without stop as reaction

2 Protected space without stop as reaction
3 Workspace with stop as reaction
4 Protected space with stop as reaction

Safety spheres and surfaces in the event of a space violation

The safety spheres and the surfaces of violated monitoring spaces are
displayed in the following colors:
Safety spheres:

• Safety spheres on the robot: yellow

• Safety spheres on the tool: yellow
Surfaces in the event of a space violation:

• There has been a space violation but this has not caused a stop: yel-
low
This applies in the following cases, for example:
‒ An output is configured as the reaction.
‒ A stop is configured as the reaction but the table row in which the
space is configured has not yet been violated. For example, be-
cause the space monitoring is combined with an input signal and
this input has not been switched.
• Space violation has caused a stop: red

368/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

KUKA Sunrise.SafetyVisualization
A “stop at boundaries” will only be correctly visualized if the stop reac-
tion is defined in a table row with the monitoring space in the safety
configuration.
If the stop reaction is cascaded, in other words if an output is switched
in the event of a space violation and this output triggers a stop reaction
in another table row, this will not be detected. The surface of the moni-
toring space remains yellow although the space violation caused a stop.

Fig. 14-9: Safety spheres and surfaces in the event of a space viola-
tion

1 Non-violated protected space

2 Safety sphere on the robot
3 Violated workspace; no stop due to space violation
4 Safety spheres on the tool
5 Violated protected space; space violation has caused a stop

14.1.3 Highlighting monitoring spaces

Description

In the 3D visualization, individual monitoring spaces can be highlighted by

means of the mouse pointer:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 369/667

KUKA Sunrise.SafetyVisualization KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

• The line thickness of the space edges is increased.

• A deselected space is temporarily displayed again.

Procedure

• In the menu, position the mouse pointer on the name of the monitor-
ing space to be highlighted.

Example

Fig. 14-10: Right-hand workspace highlighted

14.1.4 Orbiting, zooming, panning the 3D visualization

Description

The 3D visualization can be orbited, zoomed and panned using the

mouse:
• Left mouse button: orbit
• Mouse wheel: zoom
• Right mouse button: pan

Procedure

To orbit:
1. Click into the 3D visualization and hold down the left mouse button.
2. Move the mouse in the desired direction. The 3D visualization and the
world coordinate system are orbited as the mouse moves.
To zoom:
• Click into the 3D visualization and scroll with the mouse wheel.
‒ Scroll up: zoom is increased.
‒ Scroll down: zoom is decreased.

370/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

To pan:

KUKA Sunrise.SafetyVisualization
1. Click into the 3D visualization and hold down the right mouse button.
2. Move the mouse in the desired direction. The 3D visualization moves
with the mouse.

Alternatively, the arrow keys can be used for panning.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 371/667

KUKA Sunrise.SafetyVisualization KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

372/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Basic principles of motion programming

15 Basic principles of motion programming
This chapter describes the theoretical principles of motion programming.
The programming of motions in KUKA Sunrise.Workbench is described in
the following chapter: (>>> 16 "Programming" Page 397)

15.1 Overview of motion types

The start point of a motion is always the end point of the previous mo-
tion.

The following motion types can be programmed as an individual motion:

• Point-to-point motion (PTP)
(>>> 15.2 "PTP motion type" Page 373)
• Linear motion (LIN)
(>>> 15.3 "LIN motion type " Page 374)
• Circular motion (CIRC)
(>>> 15.4 "CIRC motion type" Page 374)
• Manual guidance motion with hand guiding device
(>>> 15.7 "Manual guidance motion type" Page 381)
The following types of motion can be programmed as segments of a CP
spline block:
• Linear motion (LIN)
• Circular motion (CIRC)
• Polynomial motion (SPL)
The following types of motion can be programmed as segments of a JP
spline block:
• Point-to-point motion (PTP)
(>>> 15.6 "Spline motion type" Page 375)
The following motions are known as CP (“Continuous Path”) motions:
• LIN, CIRC, SPL, CP spline blocks
The following motions are known as JP (“Joint Path”) motions:
• PTP, JP spline blocks

15.2 PTP motion type

The robot guides the TCP along the fastest path to the end point. The
fastest path is generally not the shortest path in space and is thus not a
straight line. As the motions of the robot axes are simultaneous and rota-
tional, curved paths can be executed faster than straight paths.
PTP is a fast positioning motion. The exact path of the motion is not pre-
dictable, but is always the same, as long as the general conditions are
not changed.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 373/667

Basic principles of motion programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 15-1: PTP motion

15.3 LIN motion type

The robot guides the TCP at the defined velocity along a straight path in
space to the end point.
In a LIN motion, the robot configuration of the end pose is not taken into
account.

Fig. 15-2: LIN motion

15.4 CIRC motion type

The robot guides the TCP at the defined velocity along a circular path to
the end point. The circular path is defined by a start point, auxiliary point
and end point.
In a CIRC motion, the robot configuration of the end pose is not taken in-
to account.

374/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Basic principles of motion programming

Fig. 15-3: CIRC motion

15.5 SPL motion type

The motion type SPL enables the generation of curved paths. SPL mo-
tions are always grouped together in spline blocks. The resulting paths
run smoothly through the end points of the SPL motion.
In an SPL motion, the robot configuration of the end pose is not taken in-
to account.
Curved lines are achieved by grouping together 2 or more SPL seg-
ments. If a single SPL segment is executed, the result is the same as
for a LIN command.

15.6 Spline motion type

Spline is a motion type that is particularly suitable for complex, curved

paths. With a spline motion, the robot can execute these complex paths in
a continuous motion. Such paths can also be generated using approxima-
ted LIN and CIRC motions, but splines have advantages, however.
Splines are programmed in spline blocks. A spline block is used to group
together several individual motions as an overall motion. The spline block
is planned and executed by the robot controller as a single motion block.
The motions contained in a spline block are called spline segments.
• A CP spline block can contain SPL, LIN and CIRC segments.
• A JP spline block can contain PTP segments.
In a Cartesian spline motion, the robot configuration of the end pose is
not taken into account.
The configuration of the end pose of a spline segment depends on the ro-
bot configuration at the start of the spline segment.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 375/667

Basic principles of motion programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Path of a spline block

Fig. 15-4: Curved path with spline block

• The path is defined by means of points that are located on the path.
These points are the end points of the individual spline segments.
‒ All points are passed through without exact positioning.
Exception: The velocity is reduced to 0.
(>>> 15.6.1 "Velocity profile for spline motions" Page 376)
‒ If all points are situated in a plane, then the path is also situated
in this plane.
‒ If all points are situated on a straight line, then the path is also a
straight line.
• There are a few cases in which the velocity is reduced.
(>>> 15.6.1 "Velocity profile for spline motions" Page 376)
• The path always remains the same, irrespective of the override set-
ting, velocity or acceleration.
• Circles and tight radii are executed with great precision.

15.6.1 Velocity profile for spline motions

The robot controller already takes the physical limits of the robot into con-
sideration during planning. The robot moves as fast as possible within the
constraints of the programmed velocity, i.e. as fast as its physical limits
will allow.
The path always remains the same, irrespective of the override setting,
velocity or acceleration.
Only dynamic effects, such as those caused by high tool loads or the in-
stallation angle of the robot, may result in slight path deviations.
Reduction of the velocity
With spline motions, the velocity falls below the programmed velocity in
the following cases:

• Tight corners, e.g. due to abrupt change in direction

• Major reorientation
• Motion in the vicinity of singularities

376/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Reduction of the velocity due to major reorientation can be avoided with

Basic principles of motion programming

spline segments by programming the orientation control SplineOrienta-
tionType.Ignore.
(>>> 15.9 "Orientation control with LIN, CIRC, SPL" Page 384)
Reduction of the velocity to 0
With spline motions, exact positioning is carried out in the following cases:

• Successive spline segments with the same end points

• Successive LIN and/or CIRC segments. Cause: inconstant velocity di-
rection.

Fig. 15-5: Exact positioning at P2

In the case of LIN-CIRC transitions, the velocity also drops to 0 if the

straight line is a tangent of the circle. This is caused by the fact that
at the transition point between the straight line (curvature equals 0)
and the circle (curvature is not equal to 0) the curvature characteristic
is not constant.

Fig. 15-6: Exact positioning at P2

Exceptions:

• In the case of successive LIN segments that result in a straight line

and in which the orientations change uniformly, the velocity is not re-
duced.

Fig. 15-7: P2 is executed without exact positioning.

• In the case of a CIRC-CIRC transition, the velocity is not reduced if

both circles have the same center point and the same radius and if
the orientations change uniformly. Since the required accuracy is diffi-
cult to achieve by teaching the end point and auxiliary point, calcula-
tion of the points on the circle is recommended.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 377/667

Basic principles of motion programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

15.6.2 Modifications to spline blocks

Description

• Modification of the position of the point:

If a point within a spline block is offset, the path is modified, at most,
in the 2 segments before this point and the 2 segments after it.
Small point offsets generally result in small modifications to the path.
If, however, very long segments are followed by very short segments
or vice versa, small modifications can have a very great effect.
• Modification of the segment type:
If an SPL segment is changed into an LIN segment or vice versa, the
path changes in the previous segment and the next segment.

Example 1

Original path:

Spline mySpline = new Spline(

spl(getApplicationData().getFrame("/P1")),
spl(getApplicationData().getFrame("/P2")),
spl(getApplicationData().getFrame("/P3")),
spl(getApplicationData().getFrame("/P4")),
circ(getApplicationData().getFrame("/P5"),
getApplicationData().getFrame("/P6")),
spl(getApplicationData().getFrame("/P7")),
lin(getApplicationData().getFrame("/P8"))
);
// ...
robot.move(ptp(getApplicationData().getFrame("/P0")));
robot.move(mySpline);

Fig. 15-8: Original path

A point is offset relative to the original path:

P3 is offset. This causes the path to change in segments P1 - P2, P2 -
P3 and P3 - P4. Segment P4 - P5 is not changed in this case, as it be-
longs to a CIRC segment and a circular path is thus defined.

378/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Basic principles of motion programming

Fig. 15-9: Point has been offset

The type of a segment is changed relative to the original path:

In the original path, the segment type of P2 - P3 is changed from SPL to
LIN. The path changes in segments P1 - P2, P2 - P3 and P3 - P4.

Spline mySpline = new Spline(

spl(getApplicationData().getFrame("/P1")),
spl(getApplicationData().getFrame("/P2")),
lin(getApplicationData().getFrame("/P3")),
spl(getApplicationData().getFrame("/P4")),
circ(getApplicationData().getFrame("/P5"),
getApplicationData().getFrame("/P6")),
spl(getApplicationData().getFrame("/P7")),
lin(getApplicationData().getFrame("/P8"))
);
// ...
robot.move(ptp(getApplicationData().getFrame("/P0")));
robot.move(mySpline);

Fig. 15-10: Segment type has been changed

Example 2

Original path:

Spline mySpline = new Spline(

spl(getApplicationData().getFrame("/P2")),
spl(getApplicationData().getFrame("/P3")),

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 379/667

Basic principles of motion programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

spl(getApplicationData().getFrame("/P4")),
spl(getApplicationData().getFrame("/P5")),
);
// ...
robot.move(mySpline);

Fig. 15-11: Original path

The following frame coordinates were taught:

Frame X Y Z
P2 100.0 0.0 0.0
P3 102.0 0.0 0.0
P4 104.0 0.0 0.0
P5 204.0 0.0 0.0
A point is offset relative to the original path:
P3 is moved slightly in the Y direction. This causes the path to change in
all the segments illustrated.
Frame X Y Z
P3 102.0 1.0 0.0
Since P2 - P3 and P3 - P4 are very short segments and P1 - P2 and P4
- P5 are long segments, the slight offset causes the path to change great-
ly.

Fig. 15-12: Point has been offset

Remedy:

• Distribute the points more evenly.

• Program straight lines (except very short ones) as LIN segments

15.6.3 LIN-SPL-LIN transition

In the case of a LIN-SPL-LIN segment sequence, it is usually desirable for

the SPL segment to be located within the smaller angle between the two
straight lines. Depending on the start and end point of the SPL segment,
the path may also move outside this area.

380/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Basic principles of motion programming

Fig. 15-13: LIN-SPL-LIN

The path remains inside the smaller angle if the following conditions are
met:

• The extensions of the two LIN segments intersect.

• 2/3 ≤ a/b ≤ 3/2
a = distance from start point of the SPL segment to intersection of the
LIN segments
b = distance from intersection of the LIN segments to end point of the
SPL segment

15.7 Manual guidance motion type

Description

The robot can be guided using a hand guiding device. The hand guiding
device is a device equipped with an enabling device and which is required
for the manual guidance of the robot.
Manual guidance mode can be switched on in the application using the
motion command handGuiding(). Manual guidance begins at the actual
position which was reached before the mode was switched on.
(>>> 16.9 "Programming manual guidance" Page 427)
In manual guidance mode, the robot reacts compliantly to external forces
and can be manually guided to any point in the Cartesian space. The im-
pedance parameters are automatically set when the robot is switched to
Manual guidance mode. The impedance parameters for manual guidance
cannot be modified.
A manual guidance motion command can only be executed by an applica-
tion in Automatic mode. If the application is paused in Manual guidance
mode, e.g. because of a safety stop triggered by an EMERGENCY STOP,
the manual guidance motion is terminated. When the application is re-
sumed, the next motion command is executed directly.

Precondition

• Hand guiding device with enabling device

• Manual guidance in Automatic mode is configured as not allowed (pa-
rameter Enable manual guidance in Automatic mode = false)
(>>> 10.4.3 "Handguiding Support" Page 209)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 381/667

Basic principles of motion programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

• ESM state for manual guidance motion has been configured.

The ESM state contains the AMF Hand guiding device enabling inac-
tive, which monitors the enabling switch on the hand guiding device.
(>>> 13.11.5.1 "Monitoring of enabling switches on hand guiding devi-
ces" Page 289)
The robot can be guided manually when the enabling switch on the
hand guiding device is pressed and held in the center position. If the
enabling switch is pressed down fully or released, the signal for man-
ual guidance is cancelled and the robot remains in its current position.
• ESM state for all motions except manual guidance motion has been
configured.
The ESM state does not contain the Hand guiding device enabling in-
active AMF. The signal at the hand guiding device is not evaluated.
• Automatic mode
• The safety equipment must be HRC-compliant.

In Manual guidance mode, incorrectly selected parameters (e.g. incor-

rect load data, incorrect tool), incorrect information (e.g. from defective
torque sensors) or additional overlaid forces can be interpreted as exter-
nal forces. This can result in unpredictable robot motions.

If the signal for manual guidance is issued before manual guidance

mode is switched on in the application, manual guidance mode will be
active as soon as it is switched on. This means that motion execution is
not paused when the mode is switched on, making for a smooth transi-
tion between application mode and manual guidance mode.
Precondition for this response: the application velocity is less than the
maximum permissible velocity configured for manual guidance.
(>>> 13.11.5.3 "Velocity monitoring during manual guidance" Page 291)
If the application is executed at a higher velocity, the application is
paused before switching to manual guidance mode. (Then release the
enabling switch, press the Start key and wait until the application is
paused again.)

15.8 Approximate positioning

Approximate positioning means that the motion does not stop exactly at
the end point of the programmed motion, allowing continuous robot mo-
tion. During motion programming, different parameters can influence the
approximate positioning.
The point at which the original path is left and the approximate positioning
arc begins is referred to as the approximate positioning point.
To approximate motions without exact positioning, they must be execu-
ted asynchronously or grouped in a MotionBatch.
(>>> 16.6.1 "Synchronous and asynchronous motion execution"
Page 416)
(>>> 16.6.6 "MotionBatch" Page 420)

In the case of approximate positioning of motions executed synchro-

nously, an exact positioning point is executed at the start of the approx-
imate positioning arc. This also applies, in the case of synchronous ex-
ecution, to the last motion within a MotionBatch.

PTP motion
The TCP leaves the path that would lead directly to the end point and
moves, instead, along a path that allows it to pass the end point without

382/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

exact positioning. The path thus goes past the point and no longer passes

Basic principles of motion programming

through it.
During programming, the relative maximum distance from the end point at
which the TCP may deviate from its original path in axis space is defined.
A relative distance of 100% corresponds to the entire path from the start
point to the end point of the motion.
The approximation contour executed by the TCP is not necessarily the
shorter path in Cartesian space. The approximated point can thus also be
located within the approximate positioning arc.

Fig. 15-14: PTP motion, P2 is approximated

LIN motion
The TCP leaves the path that would lead directly to the end point and
moves along a shorter path. During programming of the motion, the maxi-
mum distance from the end point at which the TCP may deviate from its
original path is defined.

Fig. 15-15: LIN motion, P2 is approximated

CIRC motion
The TCP leaves the path that would lead directly to the end point and
moves along a shorter path. During programming of the motion, the maxi-
mum distance from the end point at which the TCP may deviate from its
original path is defined.
The auxiliary point may fall within the approximate positioning range and
not be passed through exactly. This is dependent on the position of the
auxiliary point and the programmed approximation parameters.

Fig. 15-16: CIRC motion, PEND is approximated

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 383/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

All spline blocks and all individual motions can be approximated with one
Basic principles of motion programming

another. It makes no difference whether they are CP or JP spline blocks,

nor is the motion type of the individual motion relevant.
The motion type of the approximate positioning arc always corresponds to
the second motion. In the case of PTP-LIN approximation, for example,
the approximate positioning arc is of type CP.
If a spline block is approximated, the entire last segment is approximated.
If the spline block only consists of one segment, a maximum of half the
segment is approximated (this also applies for PTP, LIN and CIRC).
Approximate positioning not possible due to time:
If approximation is not possible due to delayed motion commanding, the
robot waits at the start of the approximate positioning arc. The robot
moves again as soon as it has been possible to plan the next block. The
robot then executes the approximate positioning arc. Approximate position-
ing is thus technically possible; it is merely delayed.
No approximate positioning in Step mode:
In Step mode, the robot stops exactly at the end point, even in the case
of approximated motions.
In the case of approximate positioning from one spline block to another
spline block, the result of this exact positioning is that the path is different
in the last segment of the first block and in the first segment of the sec-
ond block in relation to the path in standard mode.
In all other segments of both spline blocks, the path is identical in both
program run modes.
Approximated motions which were sent to the robot controller asynchro-
nously before Step mode was activated and which are waiting there to be
executed will stop at the approximate positioning point. For these motions,
the approximate positioning arc will be executed when the program is re-
sumed.

15.9 Orientation control with LIN, CIRC, SPL

Description

The orientation of the TCP can be different at the start point and end
point of a motion. During motion programming, it is possible to define how
to deal with the different orientations.
Orientation control is set as a motion parameter by the setOrientation-
Type(…) method. Orientation control is a value of type Enum SplineOrien-
tationType.

384/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Basic principles of motion programming

Orientation control Description
Constant The orientation of the TCP remains constant during the motion.
The orientation of the start point is retained. The orientation of the
end point is not taken into consideration.
Ignore The orientation of the TCP changes during the motion.
This option is only available for individual spline segments, not for
the entire spline block or individual motions. The controller calcu-
lates the orientation control on the basis of the orientation of the
surrounding control points, unless their orientation is also ignored.
Ignore is used if no specific orientation is required for a spline seg-
ment.
(>>> "Ignore" Page 386)
Note: In the case of Ignore, the orientation of the end point is not
taken into consideration. If it is important for the taught orientation
to be maintained at the end point, e.g. to avoid collisions, Ignore
must not be used.
OriJoint The orientation of the TCP changes continuously during the mo-
tion. This is done by linear transformation (axis-specific motion) of
the wrist axis angles.
Note: Use OriJoint if, with VariableOrientation, the robot passes
through a wrist axis singularity. The orientation of the TCP
changes continuously during the motion, but not uniformly. OriJoint
is thus not suitable if a specific orientation must be maintained ex-
actly, e.g. in the case of laser welding.
VariableOrientation During the motion, a continuous transition of the orientation of the
TCP occurs from the orientation of the start point to the orientation
of the end point.
If the orientation control is not set, this orientation control is
applied as standard.

Fig. 15-17: Constant orientation (constant)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 385/667

Basic principles of motion programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 15-18: Variable orientation (VariableOrientation or OriJoint)

CIRC motion

It is possible to define for CIRC motions whether the orientation control is

to be space-related or path-related.
(>>> 15.9.1 "Orientation control reference system for CIRC" Page 387)
During CIRC motions, the robot controller only takes the orientation of the
end point into consideration. It is possible to define whether, and to what
extent, the orientation of the auxiliary point is to be taken into considera-
tion. The orientation behavior at the end point can also be defined.

Ignore

The orientation type SplineOrientationType.Ignore is used if no specific ori-

entation is required at a point. The robot controller ignores the taught or
programmed orientation of the point. Instead, it calculates the optimal ori-
entation for this point on the basis of the orientations of the surrounding
points. This reduces the cycle time.
Example:

robot.move(P0);
Spline path6 = new Spline(
spl(P1),
spl(P2),
spl(P3).setOrientationType(SplineOrientationType.Ignore),
spl(P4).setOrientationType(SplineOrientationType.Ignore),
spl(P5),
spl(P6)
);
// ...
robot.move(path6);

The taught or programmed orientation of P3 and P4 is ignored.

SplineOrientationType.Ignore is not allowed for the following spline seg-
ments:

• The first and last segment in a spline block

• CIRC segments with OrientationReferenceSystem.Path
• Segments followed by a CIRC segment with OrientationReferenceSys-
tem.Path
• Segments followed by a segment with SplineOrientationType.Constant
• Successive segments in a spline block with the same end point

386/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Basic principles of motion programming

15.9.1 Orientation control reference system for CIRC

Description

It is possible to define for CIRC motions whether the orientation control is

to be space-related or path-related.
The reference system of the orientation control is set as a motion param-
eter by the setOrientationReferenceSystem(…) method. Orientation control
is a value of type Enum OrientationReferenceSystem.
The reference system of the orientation control can only be specified be-
fore the orientation type.
Reference sys-
Description
tem
Base Base-related orientation control during the circular
motion
Path Path-related orientation control during the circular mo-
tion

Example

Path-related circular motion with constant orientation:

robot.move(circ(P6, P7)
.setOrientationReferenceSystem(
OrientationReferenceSystem.Path)
.setOrientationType(SplineOrientationType.Constant));

Limitation

OrientationReferenceSystem.Path is not allowed for the following spline

segments:

• CIRC segments with SplineOrientationType.Ignore

• CIRC segments preceded by a segment with SplineOrientationType.Ig-
nore

15.9.2 Combination of reference system and orientation type for CIRC

If the reference system of the orientation control is combined with Spli-

neOrientationType.OriJoint, the reference system has no influence on
the orientation control.

Path-related circular motion with constant orientation:

• OrientationReferenceSystem.Path
• SplineOrientationType.Constant

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 387/667

Basic principles of motion programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 15-19: Constant orientation, path-related

Path-related circular motion with variable orientation:

• OrientationReferenceSystem.Path
• SplineOrientationType.VariableOrientation

Fig. 15-20: Variable orientation, path-related

Base-related circular motion with constant orientation:

• OrientationReferenceSystem.Base
• SplineOrientationType.Constant

388/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Basic principles of motion programming

Fig. 15-21: Constant orientation, base-related

Base-related circular motion with variable orientation:

• OrientationReferenceSystem.Base
• SplineOrientationType.VariableOrientation

Fig. 15-22: Variable orientation, base-related

15.10 Redundancy information

For a given axis position of a robot, the resulting point in Cartesian space
at which the TCP is located is unambiguously defined. Conversely, howev-
er, the axis position of the robot cannot be unambiguously determined
from the Cartesian position X, Y, Z and orientation A, B, C of the TCP. A
Cartesian point can be reached with multiple axis configurations. In order
to determine an unambiguous configuration, the Status parameter must be
specified.
Robots with 6 axes already have ambiguous axis positions for a given
Cartesian point. With its additional 7th axis, an LBR is able to reach a giv-
en position and orientation with a theoretically unlimited number of axis
poses. To unambiguously determine the axis pose for an LBR, the redun-
dancy angle must be specified in addition to the Status.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 389/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The Turn parameter is required for axes which can exceed the angle
Basic principles of motion programming

±180°. In PTP motions, this helps to unambiguously define the direction of

rotation of the axes. Turn has no influence on CP motions.
Status, Turn and the redundancy angle are saved during the teaching of a
frame. They are managed as arrays of the data type AbstractFrame.

Programming

The Status of a frame is only taken into account in PTP motions to this
frame. With CP motions, the Status given by the axis configuration at the
start of the motion is used.
In order to avoid an unpredictable motion at the start of an application
and to define an unambiguous axis configuration, it is advisable to pro-
gram the first motion in an application with one of the following instruc-
tions: The axis configuration should not be in the vicinity of a singular axis
position.
• PTP motion to a specified axis configuration with specification of all
axis values:
ptp(double a1, double a2, double a3, double a4, dou-
ble a5, double a6, double a7)
• PTP motion to a specified axis configuration:
ptp(JointPosition joints)
• PTP motion to a taught frame (AbstractFrame type):
ptp(getApplicationData().getFrame(String frameName));

15.10.1 Redundancy angle

With its 7th axis, an LBR is able to reach a point in space with a theoret-
ically unlimited number of different axis configurations. An unambiguous
pose is defined via the redundancy angle.
In an LBR, the redundancy angle has the value of the 3rd axis.
The following applies for all motions:
• The redundancy angle of the end frame is taken into account when
the robot that was used when teaching the frame also executes the
motion command. In particular, the robot name defined in the station
configuration must match the device specified in the frame properties.
• If the robots do not match or if calculated frames are used, the redun-
dancy angle given at the start of motion by the axis configuration is
retained.

15.10.2 Status

The Status specification prevents ambiguous axis positions. The Status is

described by a binary number with 3 bits.

Bit 0

Specifies the position of the wrist root point (intersection of axes A5, A6,
A7) with reference to the X axis of the coordinate system of axis A1. The
alignment of the A1 coordinate system is identical to the robot base coor-
dinate system if axis A1 is at 0°. It moves with axis A1.

390/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Basic principles of motion programming

Position Value
Overhead area Bit 0 = 1
The robot is in the overhead area if the X value of
the position of the wrist root point, relative to the A1
coordinate system, is negative.
Basic area Bit 0 = 0
The robot is in the basic area if the X value of the
position of the wrist root point, relative to the A1 co-
ordinate system, is positive.

Bit 1

Specifies the position of axis A4.

Position Value
A4 < 0° Bit 1 = 1
A4 ≥ 0° Bit 1 = 0

Bit 2

Specifies the position of axis A6.

Position Value
A6 < 0° Bit 2 = 1
A6 ≥ 0° Bit 2 = 0
The following applies for PTP motions:
• The Status of the end frame is taken into account when the robot
which was used when teaching the frame also executes the motion
command. In particular, the robot name defined in the station configu-
ration must match the device specified in the frame properties.
• If the robots do not match or if calculated frames are used, the Status
given by the axis configuration at the start of the motion is retained.
The following applies for CP motions:
• The Status of the end frame is not taken into account. The Status giv-
en by the axis configuration at the start of the motion is retained.
• Exception: A change of Status is possible if the end frame is ad-
dressed with the SplineOrientationType.ORI_JOINT orientation
control. The Status of the end frame is not taken into consideration in
this case either. The Status at the end of the motion is determined by
the path planning, which selects the shortest route to the end frame.

15.10.3 Turn

The Turn specification makes it possible to move axes through angles

greater than +180° or less than -180° without the need for special motion
strategies (e.g. auxiliary points). The Turn is specified by a binary number
with 7 bits.
With rotational axes, the individual bits determine the sign before the axis
value in the following way:
Bit = 0: Angle ≥ 0°
Bit = 1: Angle < 0°

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 391/667

Basic principles of motion programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Value Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0

0 A7 ≥ 0° A6 ≥ 0° A5 ≥ 0° A4 ≥ 0° A3 ≥ 0° A2 ≥ 0° A1 ≥ 0°
1 A7 < 0° A6 < 0° A5 < 0° A4 < 0° A3 < 0° A2 < 0° A1 < 0°
The Turn is not taken into account in an LBR because none of its axes
can rotate over ±180°.

15.11 Singularities

Due to the axis position, Cartesian motions of the robot may be limited.
Due to the combination of axis positions of the entire robot, no motions
can be transferred from the drives to the flange (or to an object on the
flange, e.g. a tool) in at least one Cartesian direction. In this case, or if
very slight Cartesian changes require very large changes to the axis an-
gles, one speaks of singularity positions.
It is advisable to move the robot as slowly as possible near singularities.

15.11.1 Kinematic singularities

The flexibility due to the redundancy of a 7-axis robot, in contrast to the 6-

axis robot, requires 2 or more kinematic conditions (e.g. extended posi-
tion, 2 rotational axes coincide) to be active at the same time in order
reach a singularity position. There are 4 different robot positions in which
flange motion in one Cartesian direction is no longer possible. Here only
the position of 1 or 2 axes is important in each case. The other axes can
take any position.

A4 singularity

This kinematic singularity is given when A4 = 0°. It is called the extended

position.

Fig. 15-23: Extended position A4 = 0°

Motion is blocked in the direction of the robot base or parallel to axis A3

or A5. An additional kinematic condition for this singularity is reaching the
workspace limit. It is automatically met through A4 = 0°.
An extended robot arm causes a degree of freedom for the motion of the
wrist root point to be lost (it can no longer be moved along the axis of the
robot arm). The position of axes A3 and A5 can no longer be resolved.

A4/A6 singularity

This kinematic singularity is given when A4 = 90° and A6 = 0°.

392/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Basic principles of motion programming

Fig. 15-24: A4 = 90° and A6 = 0°

Motion parallel to axis A6 or A2 is blocked.

A2/A3 singularity

This kinematic singularity is given when A2 = 0° and A3 = ±90° (π/2).

Fig. 15-25: A2 = 0° and A3 = ±90° (π/2)

Motion is blocked in the direction of the robot or parallel to axis A2 or A5.

A5/A6 singularity

This kinematic singularity is given when A5 = ±90° (π/2) and A6 = 0°.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 393/667

Basic principles of motion programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 15-26: A5 = ±90° (π/2) and A6 = 0°

Motion parallel to axis A6 is blocked.

15.11.2 System-dependent singularities

Description

The redundant configuration of the LBR with its 7th axis allows the robot
arm to move without the flange moving. In this null space motion, all axes
move except A4, the “elbow axis”. In addition to the normal redundancy, it
is possible, under certain circumstances, that only subchains of the robot
can move and not all axes.
All of the robot positions in this category have in common that slight Car-
tesian changes result in very large changes to the axis angles. They are
very similar to the singularities in 6-axis robots since, in the LBR too, a di-
vision is made into the position part and orientation part of the wrist root
point.

Wrist axis singularity

Wrist axis singularity means the axis position A6 = 0°. The position of ax-
es A5 and A7 can thus no longer be resolved. There are an infinite num-
ber of ways to position these two axes to generate the same position on
the flange.

A1 singularity

If the wrist root point is directly over A1, no reference value can be speci-
fied for the redundancy circle according to the definition above. The rea-
son for this is that any A1 value is permissible here for A3 = 0°.
Every axis position of A1 can be compensated for with a combination of
A5, A6 and A7 so that the flange position remains unchanged.

A2 singularity

With an extended “shoulder”, the position of axes A1 and A3 can no lon-

ger be resolved according to the pattern above.

394/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Basic principles of motion programming

A2/A4 singularity

If A1 and A7 coincide, the position of axes A1 and A7 can no longer be

resolved according to the pattern above.
System-dependent singularities can be avoided in most cases by a suit-
able elbow position.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 395/667

Basic principles of motion programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

396/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
16 Programming

16.1 Java Editor

16.1.1 Opening a robot application in the Java Editor

Description

The Java Editor allows more than one file to be open simultaneously. If
required, they can be displayed side by side or one above the other. This
provides a convenient way of comparing contents, for example.

Precondition

• Robot application has been created.

Procedure

• Double-click on a Java file in the Package Explorer view.

Alternative procedure

• Right-click on the Java file and select Open or Open With > Java Ed-
itor from the context menu.

16.1.2 Structure of a robot application

Fig. 16-1: Structure of a robot application

Item Description
1 This line contains the name of the package in which the robot
application is located.
2 The import section contains the imported classes which are re-
quired for programming the robot application.
Note: Clicking on the “+” icon opens the section, displaying the
imported classes.
3 Header of the robot application (contains the class name of the
robot application)
(>>> "Header" Page 398)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 397/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Item Description
4 Declaration section
The data arrays of the classes required in the robot application
are declared here.
When the robot application is created, instances of the necessa-
ry classes are automatically integrated by means of dependency
injection. As standard, this is the instance of the robot used,
here an LBR.
(>>> 16.3.3 "Dependency injection" Page 409)
5 initialize() method
In this method, initial values are assigned to data arrays that
have been created in the declaration section and are not inte-
grated using dependency injection.
6 run() method
The programming of the robot application begins in this method.
When the robot application is created, a motion instruction
which moves the robot to the HOME position is automatically in-
serted.
(>>> 16.15 "HOME position" Page 459)

Header

In a robot application, this is the special form of Java class:

public class RobotApplication extends RoboticsAPIApplication

Element Description
public The keyword public designates a class which is publicly
visible. Public classes can be used across all packages.
class The keyword class designates a Java class. The name
of the class is derived from the name of the application.
extends The application is subordinate to the RoboticsAPIAppli-
cation class.

16.1.3 Edit functions

16.1.3.1 Renaming variables

Description

A variable name can be changed in a single action at all points where it

occurs.

Procedure

1. Select the desired variable at any point.

2. Right-click and select Refactor > Rename… from the context menu.
OR: Press the keyboard shortcut ALT + SHIFT +R.
3. The variable is framed in blue and can now be edited. Change the
name and confirm with the Enter key.

398/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.1.3.2 Auto-complete

Programming
Description

An auto-complete function is available in the Java Editor.

When entering code, it is possible to display an “Auto-complete” list con-
taining entries that are compatible with characters which have already
been entered. These entries are prioritized according to their frequency of
use, i.e. the selection is dynamically adapted to the user’s actions.
An entry from the “Auto-complete” list can be inserted into the program
code as needed. This makes it unnecessary to retype the complex syntax
of methods, for example. All that is then required is to enter the variable
elements in the syntax manually.

Procedure

1. Begin typing the code.

When entering a dot operator for a data array or enum, the “Auto-
complete” list is automatically displayed. The list contains the follow-
ing entries:
‒ Available methods of the corresponding class (only for data ar-
rays)
‒ Available constants of the corresponding class

2. Press CTRL + space bar. The “Auto-complete” list containing the avail-
able entries is displayed.
If the list contains only one matching entry, this can automatically be
inserted into the program code by pressing CTRL + space bar.

3. Select the appropriate entry from the list and press the Enter key. The
entry is inserted in the program code.
If an entry is selected, the Javadoc information on this entry is dis-
played automatically.
(>>> 16.1.4 "Displaying Javadoc information" Page 401)
4. Complete the syntax if necessary.

Navigating and filtering

There are various ways to navigate to the “Auto-complete” list and to filter
the available entries:
• Use the arrow keys on the keyboard to move from one entry to the
next (up or down)
• Scrolling
• Complete the entered code with additional characters. The list is fil-
tered and only the entries which correspond to the characters are dis-
played.
• Press CTRL + space bar. Only the available template suggestions are
displayed.

16.1.3.3 Templates – Fast entry of Java statements

Description

Templates for fast entry are available for common Java statements, e.g.
FOR loops.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 399/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Procedure

1. Begin typing the code.

2. Press CTRL + space bar (twice). A list of the template suggestions
that are compatible with the characters already entered is displayed.
3. Accept the instruction with the Enter key. Or double-click on a different
instruction.
4. Complete the syntax.

Alternative procedure

Selecting templates in the Templates view:

1. Select the menu sequence Window > Show View > Other.... The
Show View window opens.
2. In the General folder, select Templates. Confirm with OK. The Tem-
plates view opens.
3. Position the cursor in the line in which the code template is to be in-
serted.
4. Double-click on the desired Java instruction in the Templates view.
The code is inserted in the editor.
5. Complete the syntax.

16.1.3.4 Creating user-specific templates

Description

User-specific templates can be created, e.g. templates for motion blocks

with specific motion parameters which are used frequently during program-
ming.

Procedure

1. In the Templates view, select the context in which the template is to

be inserted.
2. Right-click on the context and select New... from the context menu.
or: Click on the Create a New Template icon.
The New Template window opens.
3. Enter a name for the template in the Name box.
4. Enter a description in the Description box (optional).
5. In the Pattern box, enter the desired code.
6. Confirm the template properties with OK. The template is created and
inserted into the Templates view.

16.1.3.5 Extracting methods

Description

Parts of the program code can be extracted from the robot application and
made available as a separate method. This makes particular sense for fre-
quently recurring tasks, as it increases clarity within the robot application.

Procedure

1. Select the desired program code.

2. Right-click in the editor area.
3. Select Refactor > Extract Method… from the context menu.

400/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

OR: Press the keyboard shortcut ALT + SHIFT +M.

Programming
The Extract method window opens.
4. Enter a unique method name and select the desired Access modifier.
Confirm with OK.
The method is generated and the selected program code is inserted
into this method. At all other points within the class where the extrac-
ted code excerpt additionally occurs, it is likewise replaced with the
method call.

Access modifier

This option defines which classes can call the extracted method.
Option Description
private This method can only be called by the corre-
sponding class itself.
default The following classes can call the method:

• The corresponding class

• The inner classes of the corresponding
class
• All classes of the package in which the cor-
responding class is located
protected The following classes can call the method:

• The corresponding class

• The subclasses of the corresponding class
(inheritance)
• The inner classes of the corresponding
class
• All classes of the package in which the cor-
responding class is located
public All classes can call the method, regardless of
the relationship to the corresponding class and
of the package assignment.

16.1.4 Displaying Javadoc information

Description

Javadoc is a documentation generated from specific Java comments. The

functionalities and use of classes, methods and libraries are described in
Javadoc.
The Javadoc information can be displayed during programming. The infor-
mation is only available in English.
The various display functions are described using the example of the LBR
class.

Procedure

Displaying Javadoc information in auto-complete:

1. In auto-complete (CTRL + space bar), select an entry in the “Auto-
complete” list. The associated Javadoc information is displayed in a
separate window in the editor area.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 401/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 16-2: Javadoc information in auto-complete

1 “Auto-complete” list 2 Javadoc information

2. In order to pin the window in the editor area, press the tab key or
click inside the window.
Pinning the window makes it possible to navigate to the Javadoc de-
scription, e.g. by scrolling.
Displaying Javadoc information using the mouse pointer:
• Move the mouse pointer to the desired element name in the program
code. The associated Javadoc information is automatically displayed in
a window in the editor area.
The following elements react to the mouse pointer:

‒ Methods
‒ Classes (data types, not user-defined data arrays)
‒ Interfaces
‒ ENUM arrays

Fig. 16-3: Javadoc information using the mouse pointer

• Further display options are available from here:

‒ In order to be able to navigate to the Javadoc description, e.g. by
scrolling, move the mouse pointer in the window.
The window is not pinned. If the mouse pointer is moved out of
the window, the window closes.
‒ In order to pin the window in the editor area, press the F2 key or
click inside the window.
It is also possible to navigate to the Javadoc description in the pin-
ned window.
‒ To additionally display the Javadoc information in the Javadoc
view, left-click on the selected element.
If the window is not pinned in the editor area, it is closed.

402/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Navigation

Fig. 16-4: Navigating to the Javadoc description

Item Description
1 Linked class
Left-clicking on the linked class displays the complete Javadoc
information relating to this class in the Javadoc browser.
Note: If the corresponding link in the Javadoc view is selected,
the complete Javadoc information is displayed in the view itself.
2 Show in Javadoc View button
The window in the editor section closes and the Javadoc infor-
mation is displayed in the Javadoc view.
3 Open Attached Javadoc Browser button
The window in the editor section closes and the complete Java-
doc information relating to the corresponding class is displayed
in the Javadoc browser.

There is a further option for displaying the complete Javadoc

information on a specific element in the Javadoc browser: Select the de-
sired element in the program code and press SHIFT + F2.

16.1.4.1 Configuration of the Javadoc browser

The configuration of the Javadoc browser is described briefly using the ex-
ample of the LBR class.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 403/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 16-5: Configuration of the Javadoc browser

404/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Item Description
1 Navigation
2 Class hierarchy
(>>> Fig. 16-6)
The inheritance relationships of the class are displayed here.
3 Description of the class
The task of the class and its functionality is described here.
Special aspects of using the class are normally indicated in this
area. It may also contain short examples for using the class.
The earliest library version in which the class is available is nor-
mally specified at the end of the description. The description
may additionally contain a list of references to further classes or
methods which may be of interest.
4 Overviews

• Field Summary
Overview of the data fields which belong to the class
The data fields inherited from a parent class are listed here.
• Constructor Summary
Overview of the constructors which belong to the class
• Method Summary
Overview of the methods which belong to the class
The methods inherited from a parent class are listed here.
The overviews contain short descriptions of the data fields, con-
structors and methods of the class, provided that these were
specified during the creation of Javadoc. Inherited data fields
and methods are only listed.
Detailed descriptions on the data fields, constructors and meth-
ods can be found in the Details area. Click on the respective
name to directly access the detailed description.
5 Details

• Field Detail
Detailed description of the data fields which belong to the
class
• Constructor Detail
Detailed description of the constructors which belong to the
class
• Method Detail
Detailed description of the methods which belong to the
class
The detailed description may, for example, contain a list and de-
scription of the transferred parameters and return value. Provi-
ded there are any, the exceptions which may occur when exe-
cuting a method or constructor are also named here.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 405/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 16-6: Class hierarchy

Item Description
1 Name of the package to which the class belongs
2 Name of the class
3 Class hierarchy (parentage of the class)
4 List of interfaces implemented by the class
5 List of subclasses derived from the class

16.2 Symbols and fonts

The following symbols and fonts are used in the syntax descriptions:
Syntax element Appearance
Java code • Courier font
• Upper/lower-case letters
Examples: private; new; linRel; Tool
Elements that must be re- • Italics
placed by program-specific
• Upper/lower-case letters
entries
Examples: endpoint; name; mode
Optional elements • In angle brackets
Example: <.setVelocity(value)>
Elements that are mutually • Separated by the “|” symbol
exclusive
Example: ++ |--

16.3 Data types

There are 2 kinds of data type in Java:

• Primitive data types

406/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
• Complex data types
Complex data types are defined in Java by classes.
Data types that are frequently required for robot programming are pre-
defined in the KUKA RoboticsAPI.
Overview of important data types:
Data type Description
int Integer

• -2³¹ … +2³¹-1
Examples: -1; 32; 8000
double Double-precision floating-point number

• -1.7E+308 … +1.7E+308
Examples: 1.25; -98.76; 123.456
boolean Logic state

• true
• false
char Character (1 character)

• ASCII character
Examples: ‘A’; ‘1’; ‘q’
String Character string

• ASCII character
Examples: “KUKA”; “tool”

The names of the primitive data types are displayed in violet in the Java
Editor.

16.3.1 Declaration

Description

To allow programming in Java, the necessary objects must first be created

(declared), i.e. the data type and identifier must be defined.

Syntax

Data type Name;

Explanation of the syntax

Element Description
Data type Data type of the variable
Name Name of the variable

Examples

int counter;
double value;
Controller kuka_Sunrise_Cabinet;
ForceCondition contactForceReached;

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 407/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.3.2 Initialization

Before an object can be used in the program, it must be assigned an ini-

tial value.
Primitive data types are automatically assigned a default value when
they are created. The initial value depends on the data type.

16.3.2.1 Primitive data types

Description

In the case of primitive data types, the assignment is done by the opera-
tor “=” followed by the desired value.
Primitive data types can be created and used in the run() method of an
application, for example.

Example

The variables a and b are created in an application and assigned an ini-

tial value. Subsequently, the variable c is created and assigned the sum
of the variables a and b.

@Override
public void run() {
// ...
int a = 3;
int b = 5;
// ...
int c = a + b;
// ...
}

16.3.2.2 Complex data types

Description

Complex data types are always instanced by the call of a constructor in

conjunction with the keyword new. The instancing can take place either di-
rectly or within a method that supplies an object of the data type as the
return value.
Depending on the specific implementation of the associated class, param-
eters for the first instancing can be transferred to the constructor if re-
quired.
Further values are assigned to the properties by the methods provided by
the class.
In robot applications, complex data types are usually created after the
header and initialized in the initialize() method.

Example

In an application, data arrays for a Cartesian impedance mode and a

force break condition are created and initialized.

public class ExampleApplication extends

RoboticsAPIApplication {
// ...
private CartesianImpedanceControlMode softInToolX;
private ForceCondition contactForceReached;

408/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
@Override
public void initialize() {
softInToolX = new CartesianImpedanceControlMode();
softInToolX.setDampingToDefaultValue();
// ...
contactForceReached =
ForceCondition.createSpatialForceCondition(…);
}

@Override
public void run() {
// ...
robot.move(ptp(getFrame("/P20"))
.breakWhen(contactForceReached));
}
}

16.3.3 Dependency injection

Description

With the aid of dependency injection, it is no longer necessary to actually

generate instances of certain object types. It is sufficient to provide the
points where the objects are to be used with an appropriate annotation so
that the runtime system performs the generation. This allows an applica-
tion that is based on multiple Java classes to access common objects
without having to transfer the objects to the classes in each case.
Dependency injection can only be used in classes that are themselves
generated by dependency injection. If such a class is instanced with new,
the corresponding points remain non-initialized (“null”). As the runtime sys-
tem generates robot and background applications with dependency injec-
tion, the function can be used there.

Syntax

@Inject
<Modifier> Data type Name;

Explanation of the syntax

Element Description
@Inject Annotation for initializing the array of type Data type with
dependency injection.
Modifier If required, valid modifiers can be used here for the array
declaration, e.g.:

• public, private, protected, etc.

The modifier static cannot be used for arrays with
@Inject and final should also be avoided.
Data type Data type of the array
Name Name of the array

Example

Injection and use of an array

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 409/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

@Inject
private InjectableClass myField;

public void myMethod() {

myField.doSomething();
}

Constructor and method injection are also possible in addition to array

injection. These are described in greater detail in the documentation of
the Guice injection library, for example.

16.3.3.1 Dependency injection for Sunrise types

Description

The most important types in Sunrise can be integrated using dependency

injection. This applies to the following types, among others:
• Controller
• Robot
• LBR
• Tool
• Workpiece
• ITaskLogger
• IStatusController
• IApplicationData
• All generated I/O groups
• All classes created in Sunrise.Workbench which are derived from Tool
or Workpiece and have been configured as Class of Template in the
properties of an object template.

Other classes and interfaces in addition to those described here can al-
so be integrated using dependency injection. A list of these objects can
be found in the Javadoc of UseRoboticsAPIContext.

Procedure

To call Javadoc of UseRoboticsAPIContext:

1. Move the mouse pointer over RoboticsAPIApplication in the header of
an application.
2. A window opens. In it, click on the link Available type for Dependen-
cy Injection.
3. The Javadoc file is displayed in the editor area.

If object templates are to be integrated using dependency injection, the

annotation @Named("TemplateName") must additionally be used. The
name of the object template as configured in the Object templates
view must be entered as the TemplateName.

Examples

An LBR iiwa and a gripper are integrated in a robot application by means

of dependency injection. An object template with the name “Gripper” has
been created for the gripper. The gripper is attached to the robot during
initialization. Motions with both devices are executed in the application.
In addition, a logger object is integrated which is used to display LOG in-
formation of the smartHMI.

410/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
public class ExampleApplication extends
RoboticsAPIApplication {
@Inject
private ITaskLogger logger;
@Inject
private IApplicationData data;
@Inject
private LBR robot;
@Inject
@Named("Gripper")
private Tool gripper;

@Override
public void initialize() {
// initialize your application here
gripper.attachTo(robot.getFlange());
logger.info("Application initialized!");
}

@Override
public void run() {
// your application execution starts here
robot.move(ptpHome());
robot.move(ptp(data.getFrame("/Start")));
// ...
logger.info("Move gripper");
gripper.move(linRel().setXOffset(25.0));
// ...
}
}

The signals of an I/O group are to be used in both the robot application
and a background application.
Use in robot application:

public class ExampleApplication extends

RoboticsAPIApplication {
@Inject
private LBR robot;
@Inject
private LEDsIOGroup appLEDs;

@Override
public void initialize() {
// initialize your application here
}

@Override
public void run() {
// your application execution starts here
// ...
appLEDs.setBlueLight(true);
robot.move(handGuiding());
appLEDs.setBlueLight(false);
// ...
}
}

Use in background application:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 411/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

public class MonitoringTask extends

RoboticsAPICyclicBackgroundTask {
// ...
private boolean appRunning;
@Inject
private LEDsIOGroup bgtLEDs;

@Override
public void initialize() {
// initialize your task here
initializeCyclic(0, 500, TimeUnit.MILLISECONDS,
CycleBehavior.BestEffort);
}

@Override
public void runCyclic() {
// ...
if (appRunning) {
// If application is running,
// LED changes its state continuously
bgtLEDs.setYellowLight(!bgtLEDs.getYellowLight());
}
else {
// If application is not running, LED remains off
bgtLEDs.setYellowLight(false);
}
// ...
}
}

16.3.3.2 Dependency injection for dedicated types

Description

A class can be used via dependency injection if it meets one of the fol-
lowing conditions:
• The class has a public constructor without parameters. An @Inject an-
notation on the constructor is not absolutely essential in this case.
• The class has a public constructor with an @Inject annotation which
either contains no parameters or for which all parameters can be ob-
tained via dependency injection.
All classes that are present in an application and meet the specified con-
ditions can be integrated in all constituent parts of the application using
@Inject. A new instance of the class is generated as standard for each in-
tegration using @Inject.

Singletons

If a dedicated class is provided with the annotation @Singleton in addition

to dependency injection, this results in only one instance of this class be-
ing used in the application. This means that all objects of this class gen-
erated via dependency injection refer to the same instance.
Use of the annotation @Singleton enables an application to be subdivi-
ded into multiple classes which can be called from the main application.

State variables, e.g. of tool and workpiece classes, can be used by vari-
ous program sections through this mechanism.
(>>> 16.10.4 "Integrating dedicated object classes with dependency injec-
tion" Page 440)

412/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
This procedure represents an alternative to the process data, though
the state variables are not automatically saved.

Example

The classes Vehicle, Motor and Wheel are used in a project. The
classes Motor and Wheel are to be available in the Vehicle class via
dependency injection. As a vehicle usually only has one motor (or
engine), the Motor class is to be defined as a singleton.
2 objects of each of the classes Motor and Wheel are integrated in the
Vehicle class. Comparison of the objects is then intended to show that
the objects of the Motor class refer to the same instance whereas the
objects of the Wheel class refer to different instances.
The Vehicle class is likewise integrated in a robot application using de-
pendency injection. An object of the ITaskLogger class is integrated in
both the robot application and the Vehicle class by means of dependen-
cy injection. Integrating the ITaskLogger interface via dependency injection
also enables information from the Vehicle class to be displayed on the
smartHMI.
Wheel class:

public class Wheel

{
@Inject
public Wheel() {}
// ...
}

Motor class:

@Singleton
public class Motor
{
@Inject
public Motor() {}
// ...
}

Vehicle class:

public class Vehicle {

@Inject
private ITaskLogger logger;
@Inject
private Wheel frontWheel;
@Inject
private Wheel rearWheel;
@Inject
private Motor motor;
@Inject
private Motor additionalMotor;
// ...
@Inject
private Vehicle() {
}

public void setCarStatus() {

frontWheel.setName("FrontWheel");
rearWheel.setName("RearWheel");
motor.setName("Motor");

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 413/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

additionalMotor.setName("AdditionalMotor");
// ...
}

public void printCarStatus() {

logger.info("**************************");
logger.info("Comparing the instances of Wheel:");
if (frontWheel == rearWheel {
logger.info(frontWheel + " and " +
rearWheel + " are equal.");
}
else {
logger.info(frontWheel + " and " +
rearWheel + " are NOT equal.");
}

logger.info("Comparing the instances of Motor:");

if (motor == additionalMotor {
logger.info(motor + " and " + additionalMotor +
" are equal.");
}
else {
logger.info(motor + " and " + additionalMotor +
" are NOT equal.");
}
logger.info("**************************");
}
// ...
}

Robot application (CarApplication class):

public class CarApplication extends RoboticsAPIApplication {

@Inject
private ITaskLogger logger;
@Inject
private Vehicle myNewCar;

@Override
public void initialize() {
myNewCar.setName("Isolde")
// ...
}

@Override
public void run() {
logger.info("Name of vehicle:" + myNewCar.getName());
myNewCar.setCarStatus();
myNewCar.printCarStatus();
}
}

The screenshot (>>> Fig. 16-7) shows the information displayed on the
smartHMI when the robot application is executed. Besides the displays re-
lating to the robot application it also contains information from the Vehi-
cle class. This was made possible through integration of the ITaskLogger
interface by means of dependency injection.

414/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Fig. 16-7: CarApplication – Display on smartHMI

• Instances of Wheel
The compared objects are not identical. The result of the ELSE
branch was displayed on the smartHMI and the names of the 2 ob-
jects are different.
• Instances of Motor
The result of the IF branch was displayed on the smartHMI. As both
objects refer to the same instance due to the @Singleton annotation,
the name is changed twice and corresponds to the one last set (here
“AdditionalMotor”).

16.4 Requesting individual values of a vector

Methods which request data from a frame generally return an object of

the Vector class (package: com.kuka.roboticsAPI.geometricModel.math).
The components of the vector can be requested individually.

Overview

The following methods of the Vector class are available:

Method Description
getX() Return value type: double
Requests the X component of the vector
getY() Return value type: double
Requests the Y component of the vector
getZ() Return value type: double
Requests the Z component of the vector
get(index) Return value type: double
Requests the components determined by the index pa-
rameter
Values of index (type: int):

• 0: X component of the vector

• 1: Y component of the vector
• 2: Z component of the vector

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 415/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.5 Network communication via UDP and TCP/IP

Certain ports are enabled on the robot controller for communication with
external devices via UDP or TCP/IP.
The following port numbers (client or server socket) can be used in a ro-
bot application:
• 30,000 to 30,010

16.6 Motion programming: PTP, LIN, CIRC

16.6.1 Synchronous and asynchronous motion execution

Description

In Sunrise, motion commands can be used for all movable objects of a

station. A movable object can be a robot, for example, but also a tool
which is attached to the robot flange or a workpiece held by a tool (e.g. a
gripper).
Motion commands can be executed synchronously and asynchronously.
The following methods are available for this:
• move(…) for synchronous execution
Synchronous means that the motion commands are sent in steps to
the real-time controller and executed. The further execution of the pro-
gram is interrupted until the motion has been executed. Only then is
the next command sent.
• moveAsync(…) for asynchronous execution
Asynchronous means that the next program line is executed directly
after the motion command is sent. The asynchronous execution of mo-
tions is required for approximating motions, for example.

CAUTION
If asynchronous motions are approximated, the robot may perform an
approximate positioning motion at an unexpected point.
Such unexpected approximate positioning motions can be avoided by
grouping together approximated individual motions in a MotionBatch.
(>>> 16.6.6 "MotionBatch" Page 420)

The way in which the different motion types are programmed is shown by
way of example for the object “robot”.
Motion programming for tools and workpieces is described here:
(>>> 16.10.3 "Moving tools and workpieces" Page 439)
During programming, it is possible to specify values with a higher accu-
racy than the robot can achieve. For example, it is possible to specify
position data in the nanometer range, but it is not possible to achieve
this accuracy.

Syntax

Executing a motion synchronously:

Object.move(Motion);
Executing a motion asynchronously:
Object.moveAsync(Motion);

416/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Explanation of the syntax

Element Description
Object Object of the station which is being moved
The variable name of the object declared and initialized
in the application is specified here.
Motion Motion which is being executed
The motion to be executed is defined by the following el-
ements:

• Motion type or block: ptp, lin, circ, spl or spline,

splineJP, batch
• Target position
• Further optional motion parameters

16.6.2 PTP

Description

Executes a point-to-point motion to the end point. The coordinates of the

end point are absolute.
The end point can be programmed in the following ways:
• Insert a frame from the application data in a motion instruction.
• Create a frame in the program and use it in the motion instruction.
The redundancy information for the end point – Status, Turn and re-
dundancy angle – must be correctly specified. Otherwise, the end
point cannot be correctly addressed.

• Specify the angles of axes A1 … A7. All axis values must always be
specified.

Syntax

PTP motion with a specified frame:

ptp(getApplicationData().getFrame("/End point"))<.Motion pa-
rameters>
PTP motion with specified axis angles:
ptp(A1, A2, … A7)<.Motion parameters>

Explanation of the syntax

Element Description
End point Path of the frame in the frame tree or variable name of
the frame (if created in the program)
A1 … A7 Axis angles of axes A1 … A7 (type: double; unit: rad)
Motion pa- Further motion parameters, e.g. velocity or acceleration
rameters

Examples

PTP motion to the “StartPos” frame:

robot.move(ptp(getApplicationData().getFrame("/StartPos")));

PTP motion into the vertical stretch position:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 417/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

robot.move(ptp(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0));

PTP motion to the “StartPos” frame with a specified relative velocity:

robot.move(ptp(getApplicationData().getFrame("/StartPos"))
.setJointVelocityRel(0.25));

16.6.3 LIN

Description

Executes a linear motion to the end point. The coordinates of the end
point are Cartesian and absolute.
The end point can be programmed in the following ways:
• Insert a frame from the application data in a motion instruction.
• Create a frame in the program and use it in the motion instruction.

Syntax

lin(getApplicationData().getFrame("/End point"))<.Motion pa-

rameters>

Explanation of the syntax

Element Description
End point Path of the frame in the frame tree or variable name of
the frame (if created in the program)
The redundancy information for the end point – Status
and Turn – are ignored in the case of LIN (and CIRC)
motions. Only the redundancy angle is taken into ac-
count.
Motion pa- Further motion parameters, e.g. velocity or acceleration
rameters

Examples

LIN motion to the “/Table/P1” frame:

robot.move(lin(getApplicationData().getFrame("/Table/P1")));

LIN motion with the Cartesian velocity specified:

robot.move(lin(getApplicationData().getFrame("/Table/P1"))
.setCartVelocity(150.0));

16.6.4 CIRC

Description

Executes a circular motion. An auxiliary point and an end point must be

specified in order for the controller to be able to calculate the circular mo-
tion. The coordinates of the auxiliary point and end point are Cartesian
and absolute.
The auxiliary point and end point can be programmed in the following
ways:
• Insert a frame from the application data in a motion instruction.
• Create a frame in the program and use it in the motion instruction.

418/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Syntax

circ(getApplicationData().getFrame("/Auxiliary point"), ge-

tApplicationData().getFrame("/End point"))
<.Motion parameters>

Explanation of the syntax

Element Description
Auxiliary Path of the frame in the frame tree or variable name of
point the frame (if created in the program)
The redundancy information for the end point – Status,
Turn and redundancy angle – are ignored.
End point Path of the frame in the frame tree or variable name of
the frame (if created in the program)
The redundancy information for the end point – Status
and Turn – are ignored in the case of CIRC (and LIN)
motions. Only the redundancy angle is taken into ac-
count.
Motion pa- Further motion parameters, e.g. velocity or acceleration
rameters

Examples

CIRC motion to the end frame “/Table/P4” via the auxiliary frame “/Table/
P3”:

robot.move(circ(getApplicationData().getFrame("/Table/P3"),
getApplicationData().getFrame("/Table/P4")));

CIRC motion with the absolute acceleration specified:

robot.move(circ(getApplicationData().getFrame("/Table/P3"),
getApplicationData().getFrame("/Table/
P4")).setCartAcceleration(25));

16.6.5 LIN REL

Description

Executes a linear motion to the end point. The coordinates of the end
point are relative to the end position of the previous motion, unless this
previous motion is terminated by a break condition. In this case, the coor-
dinates of the end point are relative to the position at which the motion
was interrupted.
In a relative motion, the end point is offset as standard in the coordinate
system of the moved frame. Another reference coordinate system in which
to execute the relative motion can optionally be specified. The coordinates
of the end point then refer to this reference coordinate system. This can
for example be a frame created in the application data or a calibrated
base.
The end point can be programmed in the following ways:
• Enter the Cartesian offset values individually.
• Use a frame transformation of type Transformation. The frame trans-
formation has the advantage that the rotation can also be specified in
degrees.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 419/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Syntax

LinRel motion with offset values:

linRel(x, y, z<, a, b, c>
<, Reference system>)
LinRel motion with frame transformation:
linRel(Transformation.ofDeg|ofRad(x, y, z, a, b, c)
<, Reference system>)

Explanation of the syntax

Element Description
x, y, z Offset in the X, Y and Z directions (type: double, unit:
mm)
a, b, c Rotation about the Z, Y and X axes (type: double)
The unit depends on the method used:

• Offset values and Transformation.ofRad: rad

• Transformation.ofDeg: degrees
Reference Type: AbstractFrame
system
Reference coordinate system in which the motion is exe-
cuted

Examples

The moving frame is the TCP of a gripper. This TCP moves 100 mm in
the X direction and 200 mm in the negative Z direction in the tool coordi-
nate system from the current position. The orientation of the TCP does
not change.

gripper.getFrame("/TCP2").move(linRel(100, 0, -200));

The robot moves 10 mm from the current position in the coordinate sys-
tem of the P1 frame. The robot additionally rotates 30° about the Z and Y
axes of the coordinate system of the P1 frame.

robot.move(linRel(Transformation.ofDeg(10, 10, 10, 30, 30,

0), getApplicationData().getFrame("/P1")));

16.6.6 MotionBatch

Description

Several individual motions can be grouped in a MotionBatch and thus

transmitted to the robot controller at the same time. As a result, motions
can be approximated within the MotionBatch.
The motion parameters, e.g. velocity, acceleration, orientation control, etc.
can be programmed for the entire batch or per motion.
Only axis-specific motion parameters, e.g. setJoint…Rel(…), can be
specified for the entire batch. Cartesian motion parameters, e.g. set-
Cart…(…), must be specified in the individual block.

Both variants can appear together, e.g. to assign another parameter value
to an individual motion than to the batch.

420/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
The motion parameter specified for a single block overwrites the motion
parameter specified for the entire batch. This also applies if a lower pa-
rameter value is specified for the batch than for the individual block.

Syntax

Object.move(batch(
Motion,
Motion,
…
Motion,
Motion
)<.Motion parameter>);

Explanation of the syntax

Element Description
Object Object of the station which is being moved
The variable name of the object declared and initialized
in the application is specified here.
Motion Motion with or without motion parameters

• ptp, lin, circ or spline

Motion pa- Motion parameters which are programmed at the end of
rameters the batch apply to the entire batch.
Only axis-specific motion parameters can be program-
med!

16.7 Motion programming: spline

16.7.1 Programming tips for spline motions

• The number of spline segments in a spline block is only limited by the

available memory.
• The planning of a spline motion with many small segments and small
distances between points can take a very long time. To avoid exces-
sively long planning times:
‒ Program a maximum of 500 segments per spline block.
‒ If possible, program distances between points > 5 mm.
• Spline motions (with many segments) can be programmed using an
array of spline segments.
• A spline block should cover only one process (e.g. an adhesive
seam). More than one process in a spline block leads to a loss of
structural clarity within the program and makes changes more difficult.
• Use LIN and CIRC segments in cases where the workpiece necessi-
tates straight lines and arcs. (Exception: use SPL segments for very
short straight lines.) Otherwise, use SPL segments, particularly if the
points are close together.
• Procedure for defining the path:
1. First teach or calculate a few characteristic points. Example: points
at which the curve changes direction.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 421/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

2. Test the path. At points where the accuracy is still insufficient, add
more SPL points.
• Avoid successive LIN and/or CIRC segments, as this often reduces
the velocity to 0. To avoid this:
‒ Program SPL segments between LIN and CIRC segments. The
length of the SPL segments must be at least > 0.5 mm. Depend-
ing on the actual path, significantly larger SPL segments may be
required.
‒ Replace a LIN segment with several SPL segments in a straight
line. In this way, the path becomes a straight line.
• Avoid successive points with identical Cartesian coordinates, as this
reduces the velocity to 0.
• If the robot executes points which lie on a work surface, a collision
with the work surface is possible when approaching the first point.

Fig. 16-8: Collision with work surface

A collision can be avoided by inserting a LIN segment before the work

surface. Observe the recommendations for the LIN-SPL-LIN transition.
(>>> 15.6.3 "LIN-SPL-LIN transition" Page 380)

Fig. 16-9: Avoiding a collision with the work surface

• Avoid using SPL segments if the robot moves near the workspace lim-
it. It is possible to exceed the workspace limit with SPL, even though
the robot can reach the end frame in another motion type or by
means of jogging.

16.7.2 Creating a CP spline block

Description

A CP spline block can be used to group together several SPL, LIN and/or
CIRC segments to an overall motion.
A spline block must not include any other instructions, e.g. variable as-
signments or logic statements.
The motion parameters, e.g. velocity, acceleration, orientation control, etc.
can be programmed for the entire spline block or per segment. Both var-
iants can appear together, e.g. to assign a different parameter value to an
individual segment than to the block.

422/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
The motion parameter specified for a single spline segment overwrites
the motion parameter specified for the entire spline block. This also ap-
plies if a lower parameter value is specified for the spline block than for
the spline segment.

Syntax

Spline Name = new Spline(

Segment,
Segment,
…
Segment,
Segment
)<.Motion parameter>;

Explanation of the syntax

Element Description
Name Name of the spline block
Segment Motion with or without motion parameters

• spl, lin or circ

Motion pa- Motion parameters which are programmed at the end of
rameters the spline block apply to the entire spline block.

Example

Spline mySpline = new Spline(

spl(getApplicationData().getFrame("/P1")),
circ(getApplicationData().getFrame("/P2"),
getApplicationData().getFrame("/P3")),
spl(getApplicationData().getFrame("/P4"))
.setCartVelocity(150),
lin(getApplicationData().getFrame("/P5"))
).setCartVelocity(250);

16.7.3 Creating a JP spline block

Description

A JP spline block can be used to group together several PTP segments

as an overall motion.
A spline block must not include any other instructions, e.g. variable as-
signments or logic statements.
The motion parameters, e.g. velocity, acceleration, etc. can be program-
med for the entire spline block or per segment. Both variants can appear
together, e.g. to assign a different parameter value to an individual seg-
ment than to the block.
The motion parameter specified for a single spline segment overwrites
the motion parameter specified for the entire spline block. This also ap-
plies if a lower parameter value is specified for the spline block than for
the spline segment.

Syntax

SplineJP Name = new SplineJP(

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 423/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Segment,
Programming

Segment,
…
Segment,
Segment
)<.Motion parameter>;

Explanation of the syntax

Element Description
Name Name of the spline block
Segment PTP motion with or without motion parameters
Motion pa- Motion parameters which are programmed at the end of
rameters the spline block apply to the entire spline block.

Example

SplineJP mySpline = new SplineJP(

ptp(getApplicationData().getFrame("/P1")),
ptp(getApplicationData().getFrame("/P2"))
).setJointVelocityRel(0.75);

16.7.4 Using spline in a motion instruction

Description

The spline motion programmed in a spline block is used as the motion

type in the motion instruction.

Syntax

Object.move(spline block);

Explanation of the syntax

Element Description
Object Object of the station which is being moved
The variable name of the object declared and initialized
in the application is specified here.
Spline block Name of the spline block

Example

robot.move(mySpline);

16.8 Overview of motion parameters (PTP, LIN, CIRC, SPL, Spline)

The required motion parameters can be added in any order to the motion
instruction. Dot operators and “set” methods are used for this purpose.

424/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Method Description
setCartVelocity(…) Absolute Cartesian velocity (type: double, unit: mm/s)

• > 0.0
This value specifies the maximum Cartesian velocity at which the ro-
bot may move during the motion. Due to limitations in path planning,
the maximum velocity may not be reached and the actual velocity
may be lower.
If no velocity is specified, the motion is executed with the fastest pos-
sible velocity.
Note: This parameter cannot be set for PTP motions.
setJointVelocity Axis-specific relative velocity (type: double, unit: %)
Rel(…)
• 0.0 … 1.0
Refers to the maximum value of the axis velocity in the machine data.
(>>> 16.8.1 "Programming axis-specific motion parameters"
Page 426)
setCart Absolute Cartesian velocity (type: double, unit: mm/s2)
Acceleration(…)
• > 0.0
If no acceleration is specified, the motion is executed with the fastest
possible acceleration.
Note: This parameter cannot be set for PTP motions.
setJointAcceleration Axis-specific relative acceleration (type: double, unit: %)
Rel(…)
• 0.0 … 1.0
Refers to the maximum value of the axis acceleration in the machine
data.
(>>> 16.8.1 "Programming axis-specific motion parameters"
Page 426)
setCartJerk(…) Absolute Cartesian jerk (type: double, unit: mm/s3)

• > 0.0
If no jerk is specified, the motion is executed with the fastest possible
change in acceleration.
Note: This parameter cannot be set for PTP motions.
setJointJerkRel(…) Axis-specific relative jerk (type: double, unit: %)

• 0.0 … 1.0
Refers to the maximum value of the axis-specific change in accelera-
tion in the machine data.
(>>> 16.8.1 "Programming axis-specific motion parameters"
Page 426)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 425/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Method Description
setBlendingRel(…) Relative approximation distance (type: double)

• 0.0 … 1.0
The relative approximation distance is the furthest distance before the
end point at which approximate positioning can begin. If “0.0” is set,
the approximation parameter does not have any effect.
The maximum distance (= 1.0) is always the length of the individual
motion or the length of the last segment in the case of splines. For
motions which are not commanded within a spline, only the range be-
tween 0% and 50% is available for approximate positioning. In this
case, if a value greater than 50% is parameterized, approximate posi-
tioning nevertheless begins at 50% of the block length.
setBlendingCart(…) Absolute approximation distance (type: double, unit: mm)

• ≥ 0.0
The absolute approximation distance is the furthest distance before
the end point at which approximate positioning can begin. If “0.0” is
set, the approximation parameter does not have any effect.
setBlendingOri(…) Orientation parameter for approximate positioning (type: double, unit:
rad)

• ≥ 0.0
Approximation starts, at the earliest, when the absolute difference of
the dominant orientation angle for the end orientation falls below the
value set here. If “0.0” is set, the approximation parameter does not
have any effect.
setOrientation Orientation control (type: Enum)
Type(…)
• Constant
• Ignore
• OriJoint
• VariableOrientation (default)
(>>> 15.9 "Orientation control with LIN, CIRC, SPL" Page 384)
setOrientation Only relevant for CIRC motions: Reference system of orientation con-
ReferenceSystem(…) trol (type: Enum)

• Base
• Path
(>>> 15.9.1 "Orientation control reference system for CIRC"
Page 387)

16.8.1 Programming axis-specific motion parameters

Description

The following axis-specific motion parameters can be programmed:

• Relative velocity setJointVelocityRel(…)
• Relative acceleration setJointAccelerationRel(…)
• Relative jerk setJointJerkRel(…)
There are various ways of specifying these axis-specific relative values. A
valid value for all axes, different values for each individual axis or a value
for an individual axis.

426/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

By way of example, these possibilities are described using the relative ve-

Programming
locity:
• setJointVelocityRel(Value)
If a value of type double is transferred, the relative velocity applies to
all axes.
• setJointVelocityRel(Array_variable)
In order to assign each axis its own relative velocity, a double array is
transferred with the corresponding axis values. In an array, the axis
values of up to 12 axes can be defined, beginning with axis A1.
• setJointVelocityRel(Axis, Value)
To specify the relative velocity of an individual axis, this axis is trans-
ferred as JointEnum.

Examples

All axes move at 50% of maximum velocity:

robot.move(ptp(getApplicationData().getFrame("/P1"))
.setJointVelocityRel(0.5));

Axis A5 moves at 50%, all other axes move at 20% of maximum velocity:

double[] velRelJoints = {0.2, 0.2, 0.2, 0.2, 0.5, 0.2, 0.2};

robot.move(ptp(getApplicationData().getFrame("/P1"))
.setJointVelocityRel(velRelJoints));

Axis A4 moves at 50% of maximum velocity, all other axes move at maxi-
mum velocity:

robot.move(ptp(getApplicationData().getFrame("/P1"))
.setJointVelocityRel(JointEnum.J4, 0.5));

16.9 Programming manual guidance

Description

The robot can be guided using a hand guiding device. Manual guidance
mode can be switched on in the application using the motion command
handGuiding(). Manual guidance begins at the actual position which was
reached before the mode was switched on.
If Manual guidance mode is used in the application, at least 2 ESM states
must be configured:
• ESM state for manual guidance motion
The ESM state contains the AMF Hand guiding device enabling inac-
tive, which checks whether the enabling signal has not been issued on
the hand guiding device.
(>>> 13.11.5 "Manual guidance with enabling device and velocity mon-
itoring" Page 289)
It is advisable to configure a safety stop 1 (path-maintaining) as the
stop reaction for the AMF Hand guiding device enabling inactive. Fol-
lowing a path-maintaining stop, the application can be resumed
directly by pressing the Start key.
If a non-path-maintaining stop reaction is configured for the AMF Hand
guiding device enabling inactive, the robot must first be repositioned
following manual guidance before the application can be resumed.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 427/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

A risk assessment must determine whether it is permissible to con-

figure a path-maintaining stop reaction for the EMS state which
monitors the enabling switch on the hand guiding device.

• ESM state for all motions except manual guidance motion

The ESM state does not contain the AMF Hand guiding device ena-
bling inactive. The signal at the hand guiding device is not evaluated.
In the application, motions before and after manual guidance are generally
required. It is advisable to monitor each of these motions using an ESM
state which does not evaluate the signal on the hand guiding device, and
to only switch to the ESM state for the manual guidance motion directly
before switching to Manual guidance mode. If this is carried out in the ap-
plication in this manner, the response is as follows:
• If the signal for manual guidance is issued before Manual guidance
mode is switched on in the application, Manual guidance mode will be
active as soon as it is switched on. This means that the application is
not paused when the mode is switched on, making for a smooth tran-
sition between Application mode and Manual guidance mode.
Precondition for this response: the application velocity is less than the
maximum permissible velocity configured for manual guidance.
(>>> 13.11.5.3 "Velocity monitoring during manual guidance"
Page 291)
If the application is executed at a higher velocity, the application is
paused before switching to manual guidance mode. (Then release the
enabling switch, press the Start key and wait until the application is
paused again.)
• If the signal for manual guidance is first issued when Manual guidance
mode is already switched on in the application, the Start key must be
pressed in order to manually guide the robot. The pause in the appli-
cation allows the operator to move his hand to the hand guiding de-
vice.
• Manual guidance mode has ended when the signal for manual guid-
ance has been cancelled, e.g. by releasing the enabling switch. The
application is paused and can only be resumed by pressing the Start
key. The pause in the application allows the operator to remove his
hand from the hand guiding device.

CAUTION
If, when switching to Manual guidance mode, the application is in an
ESM state which does not contain a Hand guiding device enabling inac-
tive AMF, the robot can nevertheless be manually guided in one situa-
tion: the enabling switch on the hand guiding device is pressed and a
Hand guiding device enabling inactive AMF is configured in any other
ESM state or in the PSM table.
This combination must be avoided under all circumstances: in a situa-
tion like this, the application is not paused when manual guidance is ter-
minated and the enabling switch on the hand guiding device is released.
Instead, the application is resumed without any further operator actions.
If further motions follow manual guidance, these are executed directly
while the operator’s hand is still on the hand guiding device and thus
within the robot’s motion range.

Switching between ESM states is effected via non-safety-oriented sig-

nals. For this reason, it must be ensured that the defined ESM state al-
ways assures a sufficient degree of safety, regardless of the time or
place of activation. (>>> 13.1 "Safety concept" Page 251)

428/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Preparation

The handGuiding() motion command belongs to the HRCMotions class.

The class must be manually inserted into the import section of the robot
application. The following line must be programmed:

import static com.kuka.roboticsAPI.motionModel.HRCMotions.*;

To enable the HRCMotions class to be integrated, the catalog element

Handguiding Support must be selected in the station configuration
(Software tab).

Syntax

Object.move(handGuiding());

Explanation of the syntax

Element Description
Object Object of the station which is being moved
The variable name of the object declared and initialized
in the application is specified here.

Example

1 robot.setESMState("1");
2 robot.move(ptp(getApplicationData().getFrame("/P1")));
3 robot.setESMState("2");
4 robot.move(handGuiding());
5 robot.setESMState("1");
6 robot.move(ptp(getApplicationData().getFrame("/P2")));

Line Description
1 ESM state 1 is activated for the robot. In this example,
ESM state 1 monitors the operator safety.
2 Frame "/P1" is addressed with a PTP motion.
3 ESM state 2 is activated for the robot. ESM state 2 moni-
tors the enabling switch on the hand guiding device.
If a signal has not yet been issued via the switch, the con-
figured stop reaction is triggered and the application is
paused.
4 Manual guidance mode is activated.
The robot can be guided manually as soon as the enabling
switch on the hand guiding device is pressed and held in
the center position.
When the signal for manual guidance has been cancelled,
e.g. by releasing the enabling switch, Manual guidance
mode has ended. The stop reaction configured for ESM
state 2 is triggered and motion execution is paused.
5 ESM state 1 is activated for the robot. In this example,
ESM state 1 monitors the operator safety.
Motion execution remains paused. The Start key must be
pressed in order to resume the application.
6 Frame "/P2" is addressed with a PTP motion.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 429/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.9.1 Overview of motion parameters (manual guidance)

For manual guidance, axis limits and velocity limits can be programmed.
The required motion parameters can be added in any order to the motion
command handGuiding(). Dot operators and “set” methods are used for
this purpose.
Axis limits:
Method Description
setJointLimits Activation of the axis limits for manual guidance (type: boolean[])
Enabled(…)
• true: Axis limit active
• false: Axis limit not active
Note: This method refers to the limits that the user can set using the
methods setJointLimitsMax(…) and setJointLimitsMin(…). The outer-
most axis limits of the robot (software limit switches) are always moni-
tored.
setJointLimitsMax(…) Upper axis limits (type: double[]; unit: rad)
setJointLimitsMin(…) Lower axis limits (type: double[]; unit: rad)
Note: The lower axis limit must always be lower than the correspond-
ing upper axis limit.
setJointLimitViolation Response if an axis limit is reached (type: boolean)
FreezesAll(…)
• true: If an axis limit is reached, all axes involved in the motion
work against a further motion towards the limit switch.
• false: If an axis limit is reached, only the affected axis works
against a further motion towards the limit switch.
Default: true
If this value is not set, the default value is automatically applied.
setPermanentPullOn Response if an axis limit is already exceeded at the start of manual
ViolationAtStart(…) guidance (type: boolean)

• true: When the enabling signal for manual guidance is issued, the
axis is moved automatically out of the non-permissible range.
When the permissible range is reached, the motion is stopped au-
tomatically.
• false: When the enabling signal for manual guidance is issued,
the axis does not move. It must be moved out of the non-permis-
sible range manually.
Default: false
If this value is not set, the default value is automatically applied.
Velocity limits:

430/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Method Description
setCartVelocity Cartesian velocity limit (type: double, unit: mm/s)
Limit(…)
• > 0.0
Default: 500.0
If the velocity limit is exceeded, increasing torques act against the
motion and cushion it.
setJointVelocity Velocity limitation for all axes (type: double; unit: rad/s)
Limit(…)
• > 0.0
Default: 1.0
If the velocity limit is exceeded, increasing torques act against the
motion and cushion it.

16.9.2 Axis limitation for manual guidance

Description

The motion range of each axis is limited by means of software limit

switches. For manual guidance, additional axis limitations can be program-
med, thereby further restricting the motion range:
• setJointLimitsMin(…), setJointLimitsMax(…)
Define a lower and upper axis limit that must be specified individually
for each axis.
Defining a lower and an upper axis limit results in a permissible axis
range, in which manual guidance is freely possible, and 2 non-permis-
sible axis ranges between the upper/lower axis limit and the respective
software limit switch.
• setJointLimitsEnabled(…)
The defined axis limitation must be activated or deactivated
individually for each axis.

Fig. 16-10: Axis limits for manual guidance (examples)

1 Position of software limit switch

2 Lower limit of the permissible axis range
3 Upper limit of the permissible axis range
If one of the axis limits is reached during manual guidance, a virtual
spring damper system is tensioned. This generates a resistance against

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 431/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

any further motion towards the limit switch, with the resistance becoming
Programming

greater the nearer an axis comes to the limit switch.

The following applies as standard:

• If an axis limit is reached, all axes involved in the motion work against
a further motion towards the limit switch.
With setJointLimitViolationFreezesAll(false), it is possible
to define that only the axis that has reached the limit works against a
further motion towards the limit switch.
• If an axis limit is already exceeded at the start of manual guidance,
the affected axis must be moved manually out of the non-permissible
range.
With setPermanentPullOnViolationAtStart(true), it is possi-
ble to define that the axis is to move automatically out of the non-per-
missible range.

Example

@Inject
private LBR robot;
private HandGuidingMotion motion;
// ...

motion = handGuiding()
.setJointLimitsMax(+1.407, +0.872, +0.087, -0.785, +0.087,
+1.571, +0.087)
.setJointLimitsMin(-1.407, +0.175, -0.087, -1.571, -0.087,
-1.571, -0.087)
.setJointLimitsEnabled(false, true, false, true, false,
true, false)
.setJointLimitViolationFreezesAll(false)
.setPermanentPullOnViolationAtStart(true);

robot.move(motion);

16.9.3 Velocity limitation for manual guidance

Description

In addition to the axis limitation, velocity limits that may not be exceeded
can be programmed for manual guidance:
• setCartVelocityLimit(…)
Defines the maximum permissible Cartesian velocity. It is monitored
both at the robot flange and at the TCP.
• setJointVelocityLimit(…)
Defines the maximum permissible axis velocity for all axes.
As soon as the operator exceeds one of these maximum velocity limits
axis in manual guidance, increasing torques act against the motion and
cushion it.
Axis velocity reduction before axis limitation:
If the programmed maximum permissible axis velocity is exceeded near
the axis limits during manual guidance, the axis velocity is continuously re-
duced to a minimum axis velocity specified by KUKA. This ensures that
the manual guidance motion is automatically decelerated before the axis
limits and the operator can only approach the axis limits at reduced veloc-
ity.

432/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The method setJointLimitViolationFreezesAll(…) determines whether only

Programming
the velocity of the affected axis is reduced, or the velocity of all axes in-
volved in the motion.

Fig. 16-11: Axis velocity reduction before axis limitation

1 Programmed maximum axis velocity for manual guidance

2 Programmed axis limit for manual guidance
3 Specified minimum axis velocity
4 Axis limitation by means of software limit switches

Example

@Inject
private LBR robot;
private HandGuidingMotion motion;
// ...

motion = handGuiding()
.setJointLimitsMax(+1.407, +0.872, +0.087, -0.785, +0.087,
+1.571, +0.087)
.setJointLimitsMin(-1.407, +0.175, -0.087, -1.571, -0.087,
-1.571, -0.087)
.setJointLimitsEnabled(false, true, false, true, false,
true, false)
.setJointVelocityLimit(0.5)
.setCartVelocityLimit(500.0)
.setJointLimitViolationFreezesAll(false)
.setPermanentPullOnViolationAtStart(true);

robot.move(motion);

16.10 Using tools and workpieces in the program

An application constitutes a programmed model of a real station and must

therefore contain all movable objects and fixed geometric objects in the
station. Examples of movable objects for a station are robots, tools and
workpieces. Examples of fixed objects are support tables or conveyors.
Robots are automatically declared and initialized when the robot applica-
tion is created. Tools and workpieces used in the robot application must
be integrated using dependency injection.
Tools and workpieces can be created and managed as object templates in
the Object templates view.
(>>> 9.3 "Object management" Page 180)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 433/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Data types

The data types for the objects in a station are predefined in the Robotic-
sAPI, e.g.:
Data type Object
Controller Robot controller
LBR Lightweight robot
Tool Tool
Workpiece Workpiece

16.10.1 Integrating tools and workpieces

Description

Tools and workpieces created in the object templates can be integrated in-
to robot and background applications using dependency injection. The
name of the template is specified by means of an additional annotation.

Syntax

@Inject
@Named("Template name")
private Data type Object name;

Explanation of the syntax

Element Description
@Inject Annotation for integrating resources by means of depend-
ency injection
@Named Annotation for specifying the object template to be used
Template Name of the object template as specified in the Object
name templates view
private The keyword designates locally valid variables. Locally
valid means that the data array can only be used by the
corresponding class.
Data type Class of the resource (Tool or Workpiece) that is to be
integrated
Object name Name of the identifier, as it is to be used in the applica-
tion

The annotation @Named may be omitted for tools if there is only one
single object template for a tool. The annotation is always required for
other objects.

Example

Tools and workpieces in the object templates:

434/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Fig. 16-12: Object templates

Declaration of the objects in the robot application:

public class ExampleApplication extends

RoboticsAPIApplication {
@Inject
@Named("Gripper")
private Tool gripper;

@Inject
@Named("GuidingTool")
private Tool guidingTool;

@Inject
@Named("Pen")
private Workpiece pen;

@Override
public void initialize() {
// initialize your application here
}

@Override
public void run() {
// your application execution starts here
}
}

16.10.2 Attaching tools and workpieces to the robot

In order to be able to use tools and workpieces as movable objects in

motion instructions, they must be attached to the robot in the application
via the method attachTo(…).
• Tools are directly or indirectly attached to the robot flange.
• Workpieces are indirectly attached to the robot via a tool or another
workpiece.
As soon as a tool or workpiece is attached to the robot via the method at-
tachTo(…), the load data from the robot controller are taken into account.
In addition, all frames of the attached object can be used for the motion
programming.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 435/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.10.2.1 Attaching a tool to the robot flange

Programming

Description

Via the method attachTo(…), the origin frame of a tool is attached to the
flange of a robot used in the application. The robot flange is accessed via
the method getFlange().

Syntax

Tool.attachTo(Robot.getFlange());

Explanation of the syntax

Element Description
Tool Name of the tool variable
Robot Name of the robot variable

Example

A guiding tool is attached to the robot flange.

Fig. 16-13: Attaching the guiding tool to the flange.

@Inject
private LBR robot;
@Inject
private Tool guidingTool;
// ...

@Override
public void initialize() {
// ...
guidingTool.attachTo(robot.getFlange());
// ...
}

16.10.2.2 Attaching a workpiece to other objects

Description

As standard, the origin frame of the workpiece is used to attach it to the

frame of another object.
However, every other frame created for a workpiece can also be used as
a reference point for attaching to another object.
Frames for tools and workpieces can be created in the Object templates
view.

436/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

(>>> 9.3.6 "Creating a frame for a tool or workpiece" Page 184)

Programming
In order to use a frame in the program, the object frame is requested with
the method getFrame(…). As an input parameter, this contains the path of
the frame as a string.

Syntax

To use the origin frame for the attachment:

Workpiece.attachTo(Object.getFrame("End frame"));
To use another reference frame for the attachment:
Workpiece.getFrame("Reference frame").attachTo(Object.get-
Frame("End frame"));

Explanation of the syntax

Element Description
Workpiece Name of the workpiece variable
Reference Reference frame of the workpiece which is used for the
frame attachment to the other object
End frame Frame of the object to which the reference frame of the
workpiece is attached

After the attach, the reference frame of the workpiece and the end
frame of the object attached to it match.

Example 1

A pen is attached to the gripper frame via its origin frame.

Fig. 16-14: Pen in gripper (attachment via origin frame)

@Inject
private LBR robot;
@Inject
private Tool gripper;

@Inject
@Named("Pen")
private Workpiece pen;
// ...

@Override
public void run() {
// ...
pen.attachTo(gripper.getFrame("/TCP1"));
// ...

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 437/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Example 2

A 2nd frame is defined at the tip of the gripper. If this is to be used to

grip the pen, attachment via the origin frame of the pen is not possible.
For this purpose, a grip point was created on the pen. This is used as the
reference frame for the attachment to the gripper.

Fig. 16-15: Pen in gripper (connection via grip frame)

@Inject
private LBR robot;
@Inject
private Tool gripper;

@Inject
@Named("Pen")
private Workpiece pen;
// ...

@Override
public void run() {
// ...
pen.getFrame("/Grip").attachTo(gripper.getFrame("/TCP2"));
// ...
}

16.10.2.3 Detaching objects

Description

If a tool is removed or a workpiece is set down, the object must also be

detached in the application. The method detach() is used for this purpose.

Syntax

Object.detach();

Explanation of the syntax

Element Description
Object Name of the object variable

438/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Example

The guidance tool is detached.

guidingTool.detach();

16.10.3 Moving tools and workpieces

Description

Every movable object in a station can be moved with move(…) and move-
Async(…). The reference point of the motion is dependent on the object
type:
• If a robot is moved, the reference point is always the robot flange cen-
ter point.
• If a tool or workpiece is moved, the standard reference point is the de-
fault motion frame which was defined for this object in the Object
templates view.
(>>> 9.3.8 "Defining a default motion frame" Page 187)
In this case, the tool or workpiece is linked directly to the motion com-
mand via the variable name declared in the application.
• However, any other frame created for a tool or workpiece can also be
programmed as a reference point of the motion.
In this case, using the method getFrame(…), the path to the frame of
the object used for the motion must be specified (on the basis of the
origin frame of the object).

Syntax

To use the default frame of the object for the motion:

Object.move(Motion);
To use a different frame of the object for the motion:
Object.getFrame("Moved frame").move(Motion));

Explanation of the syntax

Element Description
Object Object of the station which is being moved
The variable name of the object declared and initialized
in the application is specified here.
Moved Path to the frame of the object which is used for the mo-
frame tion
Motion Motion which is being executed

Examples

The PTP motion to point P1 is executed with the default frame of the grip-
per.

gripper.attachTo(robot.getFlange());
gripper.move(ptp(getApplicationData().getFrame("/P1")));

The PTP motion to point P1 is executed with a different frame than the
default frame of the gripper, here TCP1:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 439/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

gripper.attachTo(robot.getFlange());
gripper.getFrame("/
TCP1").move(ptp(getApplicationData().getFrame("/P1")));

A pen is gripped. The next motion is a PTP motion to point P20. This
point is executed with the default frame of the workpiece “pen”.

gripper.attachTo(robot.getFlange());
// ...
pen.attachTo(gripper.getFrame("/TCP1"));
pen.move(ptp(getApplicationData().getFrame("/P20"));

16.10.4 Integrating dedicated object classes with dependency injection

Description

Tools and workpieces created in the object templates are based on the
classes Tool and Workpiece. Specific properties or functions that tools and
workpieces generally have are not considered by these basic classes. For
a gripper, examples might include functions for opening and closing.
Such specific object properties and functions can be defined in separate
object classes. The following steps are required in order to be able to use
the user-defined object classes in the same way as the basic classes in
applications:
Step Description
1 Derive a new object class from a suitable basic class:

• Basic class for tools:

com.kuka.roboticsAPI.geometricModel.Tool
• Basic class for workpieces:
com.kuka.roboticsAPI.geometricModel.Workpiece
The constructor of the created object class must have the
following properties:

• Visibility level public

• Transfer parameter of type String (name of the object
template is transferred)
• Must not be annotated with @Inject
2 Define object properties and functions in the new object
class.
3 In the object templates, assign the new object class to the
desired objects. For this, enter the full identifier (Package
name.Class name) of the object class under Template
class in the Properties view.
Note: Object templates that use an object class derived
from a basic class are integrated into an application such
as this by means of dependency injection.

Entering the object class as a template in the properties is especially

important because the load data of the templates are then automatically
assigned to the integrated object. If this is not done, the object class be-
haves like a specially created class without dependencies.
(>>> 16.3.3.2 "Dependency injection for dedicated types" Page 412)
If the load data are required for motions (e.g. for a robot under impe-
dance control), this can result in unexpected motions of the robot.

440/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Dependency injection can also be used in dedicated classes. For exam-
ple, the ITaskLogger can be integrated in order to display output infor-
mation on the smartHMI.

Singletons

Object classes that are derived from Tool and used in a Sunrise project
as described here are always integrated as singletons. This means that
each object annotated with the type of the object class refers to the same
instance.
As standard, object classes that are derived from Workpiece are not sin-
gletons. When annotating, a new instance is therefore created every time.
Workpieces can be made singletons by placing the annotation @Singleton
before the header of the class.

Procedure

Derive a new object class from a basic class:

1. Select the desired Sunrise project in the Package Explorer.
2. Select the menu sequence File > New > Class. The New Java class
window opens.
3. In the Package: box, enter a name for the Java package in which the
new class is to be created.
4. Enter a name for the new class in the Name box.
5. To the right of the Superclass: box, click on Browse.... The Super-
class selection window is opened.
6. Enter the name of the basic class in the Select type box (Tool or
Workpiece).
7. Confirm the selection with OK. The name of the basic class is now
displayed in the Superclass: box.
8. Click on Finish. The Java package with the newly created class is in-
serted into the source folder of the Sunrise project and opened in the
editor area.
9. Create a constructor with the desired properties.
10. The required arrays and methods can now be defined.

Example

Step 1:
For a gripper, the object class Gripper is created using the procedure de-
scribed above. The class Gripper is derived from the basic class Tool and
expands the basic class to include the functions for opening and closing
the gripper.

1 package tools;
2 import com.kuka.roboticsAPI.geometricModel.Tool;
3 public class Gripper extends Tool {
4 @Inject
5 private ITaskLogger logger;
6
7 public Gripper(String name) {
8 super(name);
9 }
10
11 /**
12 * Opens the gripper
13 */
14 public void openGripper(){

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 441/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

15 // ...
16 logger.info("Gripper is open.");
17 }
18
19 /**
20 * Closes the gripper
21 */
22 public void closeGripper(){
23 // ...
24 logger.info("Gripper is closed.");
25 }
26 }

Line Description
1 Name of the Java package that contains the class Gripper
4 … 5 Integration of the ITaskLogger interface by means of de-
pendency injection
7 … 9 Standard constructor of the class Gripper (adopted from
Tool)
14 … 17 Method openGripper() for opening the gripper
22 … 25 Method closeGripper() for closing the gripper
16, 24 Information displayed on smartHMI with the aid of the ITas-
kLogger interface
Step 2:
An object template with the name “ExampleGripper” is created for the
gripper. The object class Gripper is assigned to the object template:
• Entry under Template class in the Properties view: tools.Gripper
The name of the Java package (here “tools”) that contains the class
Gripper must be specified.
Step 3:
The object class Gripper and the corresponding functions can be used in
the robot application.

1 public class ExampleApplication extends

RoboticsAPIApplication {
2 @Inject
3 private LBR robot;
4 @Inject
5 private Gripper gripper;
6
7 @Override
8 public void initialize() {
9 // initialize your application here
10 // ...
11 gripper.attachTo(robot.getFlange());
12 // ...
13 }
14
15 @Override
16 public void run() {
17 // your application execution starts here
18 // ...
19 gripper.openGripper();
20 gripper.move(lin(getFrame("/GripPos")));
21 gripper.closeGripper();
22 // ...

442/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
23 }
24 }

Line Description
4 … 5 A tool of type Gripper is integrated.
The tool has the functions defined in the object class Grip-
per.
11 The tool is attached to the robot flange.
19 … 21 The functions defined in the object class Gripper are used
to program a gripping process:

• Open gripper, move to grip position, close gripper.

16.10.5 Transferring workpiece load data to the safety controller

Description

If a workpiece load-specific AMF is used in the safety configuration and,

at the same time, workpieces are picked up, the user must use the setSa-
fetyWorkpiece(…) method to communicate to the safety controller which
workpiece is currently being used. Workpiece load-specific AMFs include:
• TCP force monitoring
• Base-related TCP force component
• Collision detection
(>>> 9.3.11 "Safety-oriented use of workpieces" Page 193)
The setSafetyWorkpiece(…) method belongs to the LBR class and can be
used in both robot applications and background applications.
setSafetyWorkpiece(…) is used to transfer the workpiece load data to the
safety controller. If a workpiece is set down again and there are no longer
any workpiece load data to be taken into consideration, the value null
must be transferred.
The workpiece load data transferred to the safety controller using setSa-
fetyWorkpiece(…) are not safety-oriented. For this reason, in the event
of an error, the AMF Collision detection may use load data which devi-
ate from the actual workpiece load. These deviations are misinterpreted
as external axis torques.

The workpiece load data transferred with setSafetyWorkpiece(…) are tak-

en into consideration exclusively by the safety controller. If the workpiece
load data are also to be taken into consideration in the
non-safety-oriented part of the robot controller, the workpieces must also
be integrated by means of the corresponding commands.
(>>> 16.10.1 "Integrating tools and workpieces" Page 434)
(>>> 16.10.2.2 "Attaching a workpiece to other objects" Page 436)

Syntax

robot.setSafetyWorkpiece(Workpiece);

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 443/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Explanation of the syntax

Element Description
robot Type: LBR
Name of the robot
Workpiece Type: PhysicalObject
Workpiece whose load data are to be transferred to the
safety controller
If no workpiece is to be taken into consideration any lon-
ger, null must be transferred.

Example

A safety-oriented tool and 2 workpieces are created in the object tem-

plates.

Fig. 16-16: Object templates: workpieces and tool

The tool contains the frame “GrippingPoint”, which serves as a gripping

point for workpieces and which is selected as the standard frame for mo-
tions.
In the application, the workpiece “ComponentA” is picked up and set
down. The workpiece “ComponentB” is then picked up. All load changes
are to be taken into consideration in both the safety-oriented and non-
safety-oriented part of the robot controller.

public class ChangeOfLoadExample extends

RoboticsAPIApplication {
@Inject
private LBR robot;
@Inject
private Tool gripper;

@Inject
@Named("ComponentA")
private Workpiece componentA;

@Inject
@Named("ComponentB")
private Workpiece componentB;

@Override
public void initialize() {
// ...
// attach gripper to robot flange
gripper.attachTo(robot.getFlange());
}

444/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
@Override
public void run() {
// ...
// after pick-up, attach workpiece to set load data for
// motion control
componentA.attachTo(gripper.getDefaultMotionFrame());
// set load data for safety controller
robot.setSafetyWorkpiece(componentA);
// ...
// after putting it down, detach workpiece to no longer
// consider its load for motion control
componentA.detach();

// workpiece is no longer considered for safety

// controller
robot.setSafetyWorkpiece(null);
// ...
// pick-up of second workpiece
componentB.attachTo(gripper.getDefaultMotionFrame());
robot.setSafetyWorkpiece(componentB);
// ...
}
}

16.11 Using inputs/outputs in the program

When exporting an I/O configuration from WorkVisual, a separate Java

class is created for each I/O group in the corresponding Sunrise project.
Each of these Java classes contains the methods required for program-
ming, in order to be able to read the inputs/outputs of an I/O group and
write to the outputs of an I/O group.
The source code of the Java classes of the package com.kuka.gener-
ated.ioAccess must not be changed manually. To expand the function-
ality of an I/O group, it is possible to derive further classes from the
classes created or to continue to use objects from these classes, e.g.
as arrays of their own classes (aggregating).

To use the inputs/outputs of an I/O group in the application, the user must
integrate the I/O group by means of dependency injection.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 445/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 16-17: Project structure after exporting the I/O configuration

Item Description
1 com.kuka.generated.ioAccess Java package
The class created for an I/O group and the methods of this
class are saved in the package.
The Java class NameIOGroup.java (here: LampSwitch-
IOGroup.java) contains the following elements:

• Class name of the I/O group: NameIOGroup

• Constructor for assigning the robot controller to the I/O
group: NameIOGroup(Controller)
• get and set methods for every configured output: getOut-
put(), setOutput(Value)
• “Get” method for every configured input: getInput()
2 generatedFiles folder

• IODescriptions folder
The data in an I/O group are saved in an XML file. The
XML file can be displayed but not edited.
3 IOTemplates folder
The data of an I/O group saved as a template are saved in an
XML file. The XML file can be displayed but not edited.
A template can be copied into another Sunrise project in order
to be used there. The template can then be imported into Work-
Visual, edited there and re-exported.
(>>> 11.5.8 "Importing an I/O group from a template" Page 230)
(>>> 11.5.7 "Exporting an I/O group as a template" Page 230)

The generatedFiles folder is used by the system and must not be used
for saving files created by the user.

446/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
16.11.1 Integrating an I/O group

Description

I/O groups can be integrated into robot and background applications by

means of dependency injection. As a result, the Java package com.ku-
ka.generated.ioAccess is automatically imported with the classes and
methods of the I/O group.

Syntax

@Inject
private Data type Group name;

Explanation of the syntax

Element Description
@Inject Annotation for integrating resources by means of depend-
ency injection
private The keyword designates locally valid variables. Locally
valid means that the data array can only be used by the
corresponding class.
Data type Class of the resource (I/O group) that is to be integrated
Class name of the I/O group:

• NameIOGroup
Name = Name of the I/O group, as defined in WorkVisual
Group name Name of the identifier, as it is to be used in the applica-
tion

Example

Integrating the I/O group “LampSwitch”:

public class ExampleApplication extends

RoboticsAPIApplication {
// ...
@Inject
private LampSwitchIOGroup lampSwitch;
// ...

@Override
public void initialize() {
// ...
}

@Override
public void run() {
// ...
}
}

16.11.2 Reading inputs/outputs

Description

The “get” method of an input/output is used to request the state of the in-
put/output.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 447/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Syntax

Group name.getInput|Output();

Explanation of the syntax

Element Description
Group name Name of the identifier of the I/O group
Input Name of the input (as defined in WorkVisual)
Output Name of the output (as defined in WorkVisual)

Example

The state of the switch at input “Switch1” and of the lamp at output
“Lamp1” is requested.

public void run() {

// ...
lampSwitch.getLamp1();
lampSwitch.getSwitch1();
// ...
}

16.11.3 Setting outputs

WARNING
Outputs are switched in certain situations although a safety-oriented
stop request is present (e.g. in the case of a pressed EMERGENCY
STOP or violated space monitoring). This can cause unexpected mo-
tions of the connected periphery (e.g opening of a gripper).
The following situations can now occur:
• Background application switches output.
• Function called via user key switches output.
• Robot applications continue running to the next synchronous motion
command after a stop request. The code executed up to that point
switches the output.
The behavior described can also be desirable; however, there must nev-
er be any danger to human and machine. This must be ensured by the
system integrator, e.g. by means of de-energizing outputs with hazard
potential.

NOTICE
It is not permissible to set outputs in a robot application that signal sys-
tem states to the external controller. Failure to observe this precaution
may result in malfunctioning of the external controller and damage to
property.

Description

The “set” method of an output is used to change the value of the output.
No “set” methods are available for inputs. They can only be read.

Syntax

Group name.setOutput(Value);

448/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Explanation of the syntax

Element Description
Group name Name of the identifier of the I/O group
Output Name of the output (as defined in WorkVisual)
Value Value of the output
The data type of the value to be transferred depends on
the output type.

Example

The lamp at output “Lamp1” is switched on and then switched off after
2000 ms.

public void run() {

// ...
lampSwitch.setLamp(true);
ThreadUtil.milliSleep(2000);
lampSwitch.setLamp(false);
// ...
}

16.12 Requesting axis torques

Description

Measuring the torques acting on an axis of sensitive robots that have axis
torque sensors.
The ITorqueSensitiveRobot interface provides the methods required for re-
questing the sensor data:
• getMeasuredTorque()
The measured torque values can be requested and evaluated in the
application via the method getMeasuredTorque().
• getExternalTorque()
Frequently, it is not the pure measured values which are of interest
but rather only the externally acting torques, without the component re-
sulting from the weight of the robot and mass inertias during motion.
These values are referred to as external torques. These external tor-
ques be accessed via the getExternalTorque() method.
In order to be able to display external torques correctly, the load
mounted on the robot must be configured correctly and communica-
ted to the system.

• getSingleTorqueValue(…), getTorqueValues()
The methods getMeasuredTorque() and getTorqueValues() return an
object of the type TorqueSensorData containing the torque sensor data
of all axes. From this object, it is then possible to request either all
values as an array with getTorqueValues(…) or a single axis value
with getSingleTorqueValue(…).

The data requested from the axis torque sensors via Java are not avail-
able in real time. This means that the data supplied by the system in
the program were already created several milliseconds earlier.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 449/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Syntax

To request the measured torques:

TorqueSensorData measuredData = robot.getMeasuredTorque();
Requesting external torques:
TorqueSensorData externalData = robot.getExternalTorque();
Requesting all axis values:
double[] allValues = measuredData|externalData.getTorqueVal-
ues();
Requesting an individual axis value:
double singleValue =
measuredData|externalData.getSingleTorqueValues(joint);

Explanation of the syntax

Element Description
measured Type: TorqueSensorData
Data
Variable for the return value of getMeasuredTorque(). The
return value contains all measured torques requested
from the robot.
externalData Type: TorqueSensorData
Variable for the return value of getExternalTorque(). The
return value contains all external torques requested from
the robot.
robot Type: LBR
Name of the robot from which the torques are requested
allValues Type: double[]; unit: Nm
Array variable for the return value of getTorqueValues().
The return value contains all torque values of all axes.
singleValue Type: double; unit: Nm
Variable for the return value of getSingleTorqueVal-
ue(joint). The return value contains the torque value of a
single axis.
joint Type: JointEnum
Axis whose torque value is requested

Example

For a specific process step, the measured and externally acting torques
are requested in all axes and saved in an array to be evaluated later. The
measured torque in axis A2 is read and displayed on the smartHMI. For
output purposes, a logger object has been integrated with dependency in-
jection.

TorqueSensorData measuredData = robot.getMeasuredTorque();

TorqueSensorData externalData = robot.getExternalTorque();

double[] measuredTorques = measuredData.getTorqueValues();

double[] externalTorques = externalData.getTorqueValues();

double torqueA2 =
measuredData.getSingleTorqueValue(JointEnum.J2);
logger.info("Currently measured torque for joint 2 [Nm]:" +
torqueA2);

450/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
16.13 Reading Cartesian forces and torques

Sensitive robots that have axis torque sensors measure the torques acting
on the axes. The robot controller calculates the Cartesian forces and tor-
ques on the basis of these measured values.
The external Cartesian forces and torques acting on the robot flange, the
TCP of a tool or any point of a gripped object can be requested from the
robot. The IForceSensitiveRobot interface provides the methods for this.
The following points must be taken into consideration:
• The Cartesian forces and torques are estimated based on the meas-
ured values of the axis torque sensors.
A force application point must be specified for the calculation. The ex-
ternal Cartesian forces and torques calculated for the force application
point are only meaningful in terms of the physics involved if there are
no external forces acting on any other points on the robot.
• The reliability of the calculated values can decrease considerably in
extreme poses, e.g. extended positions or singularities.
• The quality and validity of the calculated values can be checked.
• When changing the load data, e.g. with the attachTo command, the re-
quest can only be executed after the motion command has been sent
to the robot controller. For this purpose, a null space motion or the
motion command positionHold(…) is sufficient.

16.13.1 Requesting external Cartesian forces and torques

Description

The method getExternalForceTorque(…) is used by the robot to read the

external Cartesian forces and torques currently acting on the robot flange,
the TCP of a tool or any point of a gripped workpiece.
The method receives a frame as the transfer parameter. The transferred
frame is the reference frame for calculating the forces and torques, e.g.
the tip of a probe. The method calculates the externally applied forces
and torques for the position described by the frame.
For a meaningful calculation in terms of the physics involved, the transfer-
red frame must describe a point which is mechanically fixed to the flange.
The given frame must also be statically connected to the robot flange
frame in the frame structure.
Optionally, a second frame can be transferred to the method as a param-
eter. This frame specifies the orientation of a coordinate system in which
the forces and torques are represented.

Syntax

ForceSensorData data = robot.getExternalForceTorque(

measureFrame<, orientationFrame>);

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 451/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Explanation of the syntax

Element Description
data Type: ForceSensorData
Variable for the return value of getExternalForceTor-
que(…). The return value contains the calculated Cartesi-
an forces and torques.
robot Type: LBR
Name of the robot
measure Type: AbstractFrame
Frame
Reference frame for calculation of the Cartesian forces
and torques.
orientation Type: AbstractFrame
Frame
Optional: Orientation of the frame in which the forces and
torques are represented.

Examples

Requesting the external forces and torques acting on the robot flange:

ForceSensorData data =
robot.getExternalForceTorque(robot.getFlange());

Requesting the external forces and torques acting on the robot flange with
the orientation of the world coordinate system:

ForceSensorData data =
robot.getExternalForceTorque(robot.getFlange(),
World.Current.getRootFrame());

16.13.2 Requesting forces and torques individually

Description

The external Cartesian forces and torques requested with getExternalFor-

ceTorque() can be requested separately from one another. The class
ForceSensorData provides the following methods for this:
• getForce()
• getTorque()
The result of these requests is a vector in each case. The values for each
degree of freedom can be requested individually with the methods of the
Vector class.
(>>> 16.4 "Requesting individual values of a vector" Page 415)

Syntax

To request a force vector:

Vector force = data.getForce();
To request a torque vector:
Vector torque = data.getTorque();

452/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Explanation of the syntax

Element Description
force Type: vector (com.kuka.roboticsAPI.geometricModel.math)
Vector with the Cartesian forces which act in the X, Y
and Z directions (unit: N)
torque Type: vector (com.kuka.roboticsAPI.geometricModel.math)
Vector with the Cartesian torques which act about the X,
Y and Z axes (unit: Nm)
data Type: ForceSensorData
Variable for the return value of getExternalForceTor-
que(…). The return value contains the calculated Cartesi-
an forces and torques.

Example

Requesting the Cartesian force which is currently acting on the robot

flange in the X direction:

ForceSensorData data =
robot.getExternalForceTorque(robot.getFlange());

Vector force = data.getForce();

double forceInX = force.getX();

16.13.3 Checking the reliability of the calculated values

Description

In unfavorable robot positions, the calculated Cartesian forces and torques

can deviate from the actual forces and torques applied. In particular near
singularities, several of the calculated values are highly unreliable and can
be invalid. Depending on the axis position, this only applies to some of
the calculated values.
The quality and validity of the calculated values can be evaluated and re-
quested in the program. The class ForceSensorData provides the follow-
ing methods for this:
• getForceInaccuracy(), getTorqueInaccuracy()
The inaccuracy of the calculated force and torque values can be re-
quested.
The result of these requests is a vector in each case. The values for
each degree of freedom can be requested individually with the meth-
ods of the Vector class.
(>>> 16.4 "Requesting individual values of a vector" Page 415)
Depending on the axis position, the quality of the calculated values for
the individual degrees of freedom may be different. By requesting the
individual values, it is possible to determine the degrees of freedom
for which the calculation of forces and torques in the current pose
supplies valid values.
• isForceValid(…), isTorqueValid(…)
The validity of the calculated force and torque values can be reques-
ted.
A limit value for the maximum permissible inaccuracy up to which the
calculated values are still valid is transferred as a parameter for each
method.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 453/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Syntax

Requesting the inaccuracy of the calculated values:

Vector force = data.getForceInaccuracy();
Vector torque = data.getTorqueInaccuracy();
Requesting the validity of the calculated values:
boolean valid = data.isForceValid(tolerance);
boolean valid =data.isTorqueValid(tolerance);

Explanation of the syntax

Element Description
force Type: vector (com.kuka.roboticsAPI.geometricModel.math)
Vector with the values for the inaccuracy with which the
Cartesian forces acting in the X, Y and Z directions are
calculated (unit: N)
torque Type: vector (com.kuka.roboticsAPI.geometricModel.math)
Vector with the values for the inaccuracy with which the
Cartesian torques acting about the X, Y and Z axes are
calculated (unit: Nm)
data Type: ForceSensorData
Variable for the return value of getExternalForceTor-
que(…). The return value contains the calculated Cartesi-
an forces and torques.
tolerance Type: double; unit: N or Nm
Limit value for the maximum permissible inaccuracy up to
which the calculated Cartesian forces and torques are
still valid
valid Type: boolean
Variable for the return value of isForceValid(…) or isTor-
queValid(…)

• true: The inaccuracy value in all Cartesian directions

is less than or equal to the limit value defined with
tolerance.
• false: The inaccuracy value in one or more Cartesian
directions exceeds the tolerance value

Example

A certain statement block should only be executed if the external Cartesi-

an forces acting along the axes of the flange coordinate system have
been calculated with an accuracy of 20 N or better.

ForceSensorData data =
robot.getExternalForceTorque(robot.getFlange());

if (data.isForceValid(20)){
//do something
}

454/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
16.14 Requesting the robot position

The axis-specific and Cartesian robot position can be requested in the ap-
plication. It is possible to request the actual and the setpoint position for
each.

Overview

The following methods of the Robot class are available:

Method Description
getCommandedCartesianPosi- Return value type: Frame
tion(…)
Requests the Cartesian setpoint position
getCommandedJointPosition() Return value type: JointPosition
Requests the axis-specific setpoint position
getCurrentCartesianPosi- Return value type: Frame
tion(…)
Requests the Cartesian actual position
getCurrentJointPosition() Return value type: JointPosition
Requests the axis-specific actual position
getPositionInformation(…) Return value type: PositionInformation
Requests the Cartesian position information
The return value contains the following information:

• Axis-specific actual position

• Axis-specific setpoint position
• Cartesian actual position
• Cartesian setpoint position
• Cartesian setpoint/actual value difference (rotational)
• Cartesian setpoint/actual value difference (translational)

16.14.1 Requesting the axis-specific robot position

Description

For requesting the axis-specific actual or setpoint position of the robot, the
position of the robot axes is first saved in a variable of type JointPosition.
From this variable, the positions of individual axes can then be requested.
The axis whose position is to be requested can be specified using either
its index or the Enum JointEnum.

Syntax

To request the axis-specific actual position:

JointPosition position = robot.getCurrentJointPosition();
To request the axis-specific setpoint position:
JointPosition position = robot.getCommandedJointPosition();
Requesting the position of an individual axis:
double value = position.get(axis);

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 455/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Explanation of the syntax

Element Description
position Type: JointPosition
Variable for the return value. The return value contains
the requested axis positions.
robot Type: Robot
Name of the robot from which the axis positions are re-
quested
value Type: double; unit: rad
Position of the requested axis
axis Type: int or JointEnum
Index or JointEnum of the axis whose position is reques-
ted

• 0 … 11: Axis A1 … Axis A12

• JointEnum.J1 … JointEnum.J12: Axis A1 … Axis
A12

Example

First the axis-specific actual position of the robot and then the position of
axis A3 are requested via the index of the axis. The angle for axis A3 is
displayed in degrees on the smartHMI. For output purposes, a logger ob-
ject has been integrated with dependency injection.

JointPosition actPos = robot.getCurrentJointPosition();

double a3 = actPos.get(2);
logger.info("Position A3: " + Math.toDegrees(a3) + "°");

16.14.2 Requesting the Cartesian actual or setpoint position

Description

It is possible to request the Cartesian actual or setpoint position of the ro-

bot flange as well as any other frame below it. This means every frame of
an object which is attached to the robot flange via the attachTo command,
e.g. the TCP of a tool or the frame of a gripped workpiece.
As standard, the result of the request, i.e. the Cartesian position, refers to
the world coordinate system. Optionally, it is possible to specify another
reference coordinate system relative to which the Cartesian position is re-
quested. This can for example be a frame created in the application data
or a calibrated base.
The result of the request is saved in a variable of type Frame and con-
tains all the necessary redundancy information (redundancy angle, Status
and Turn). From this variable, the position (X, Y, Z) and orientation (A, B,
C) of the frame can be requested via the type-specific get methods.

Syntax

To request the Cartesian actual position:

Frame position = robot.getCurrentCartesianPosition(
frameOnFlange<, referenceFrame>);
To request the Cartesian setpoint position:

456/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Frame position = robot.getCommandedCartesianPosition(

Programming
frameOnFlange<, referenceFrame>);

Explanation of the syntax

Element Description
position Type: Frame
Variable for the return value. The return value contains
the requested Cartesian position.
robot Type: Robot
Name of the robot from which the Cartesian position is
requested
frameOn Type: ObjectFrame
Flange
Robot flange or a frame subordinated to the flange
whose Cartesian position is requested
reference Type: AbstractFrame
Frame
Reference coordinate system relative to which the Carte-
sian position is requested. If no reference coordinate sys-
tem is specified, the Cartesian position refers to the
world coordinate system.

Examples

Cartesian actual position of the robot flange with reference to the world
coordinate system:

Frame cmdPos =
robot.getCurrentCartesianPosition(robot.getFlange());

Cartesian actual position of the TCP of a tool with reference to a base:

tool.attachTo(robot.getFlange());
// ...
Frame cmdPos =
robot.getCurrentCartesianPosition(tool.getFrame("/TCP"),
getApplicationData().getFrame("/Base"));

16.14.3 Requesting the Cartesian setpoint/actual value difference

Description

The Cartesian setpoint/actual value difference (= difference between the

programmed and measured position) can be requested with the getPosi-
tionInformation(…) method.
The result of the request is saved in a variable of type PositionInforma-
tion. From this variable, the translational and rotational setpoint/actual val-
ue differences can be requested separately from each other.

Syntax

To request position information:

PositionInformation info = robot.getPositionInformation(
frameOnFlange<, referenceFrame>);
To request the translational setpoint/actual value difference:
Vector translatoryDiff = info.getTranslationOffset();
To request the rotational setpoint/actual value difference:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 457/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Rotation rotatoryDiff = info.getRotationOffset();

Programming

The Cartesian actual/setpoint value position saved in the PositionInfo-

mation object can be read with the methods getCurrentCartesianPosi-
tion(…) and getCommandedCartesianPosition(…) that have already
been described.

Explanation of the syntax

Element Description
info Type: PositionInformation
Variable for the return value. The return value contains
the requested position information.
robot Type: Robot
Name of the robot from which the position information is
requested
frameOn Type: ObjectFrame
Flange
Robot flange or a frame subordinated to the flange
whose position information is being requested
reference Type: AbstractFrame
Frame
Reference coordinate system relative to which the posi-
tion information is requested. If no reference coordinate
system is specified, the position information refers to the
world coordinate system.
translatory- Type: vector (com.kuka.roboticsAPI.geometricModel.math)
Diff
Translational setpoint/actual value difference in the X, Y,
Z directions (type: double, unit: mm)
The offset values for each degree of freedom can be re-
quested individually with the “get” methods of the Vector
class.
(>>> 16.4 "Requesting individual values of a vector"
Page 415)
rotatoryDiff Type: rotation (com.kuka.roboticsAPI.geometricMo-
del.math)
Setpoint/actual value difference of the axis angles A, B,
C (type: double, unit: rad)
The offset values for each degree of freedom can be re-
quested individually with the “get” methods of the Rota-
tion class - getAlphaRad(), getBetaRad, getGammaRad().

Example

Reading of the translational setpoint/actual value difference in the X direc-

tion and the setpoint/actual value difference of the axis angle C.

tool.attachTo(robot.getFlange());
// ...
PositionInformation posInf =
robot.getPositionInformation(tool.getFrame("/TCP"),
getApplicationData().getFrame("/Base"));

Vector transDiff = posInf.getTranslationOffset();

Rotation rotDiff = posInf.getRotationOffset();

double transOffsetInX = transDiff.getX();

458/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
double rotOffsetofC = rotDiff.getGammaRad();

16.15 HOME position

The HOME position is an application-specific position of the robot. It can

be reset for an application during initialization.
As standard, the HOME position has the following values:
Axis A1 A2 A3 A4 A5 A6 A7
Pos. 0° 0° 0° 0° 0° 0° 0°

16.15.1 Changing the HOME position

Description

The HOME position in an application can be changed with setHomePosi-

tion(…). The method belongs to the Robot class.
A HOME position must meet the following conditions:
• Good starting position for program execution
• Good standstill position. For example, the stationary robot must not be
an obstacle.
The new HOME position can be transferred as an axis-specific or Cartesi-
an position (frame). It is only applicable in the application in which it was
changed. Other applications continue to use the HOME position with the
default values.

Syntax

robot.setHomePosition(home);

Explanation of the syntax

Element Description
robot Type: Robot
Name of the robot to which the new HOME position re-
fers
home Type: JointPosition; unit: rad
1st option: transfer the axis position of the robot in the
new HOME position.
Type: AbstractFrame
2nd option: transfer a frame as the new HOME position.
Note: The frame must contain all redundancy information
so that the axis positions of the robot in the HOME posi-
tion are unambiguous. This is the case with a taught
frame, for example.

Examples

To transfer an axis-specific position as the HOME position:

@Inject
private LBR robot;
// ...
JointPosition newHome = new JointPosition(0.0, 0.0, 0.0,
Math.toRadians(90), 0.0, 0.0, 0.0);

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 459/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

robot.setHomePosition(newHome);

To transfer the taught frame as the HOME position and move to it with
ptpHome():

@Inject
private LBR robot;
// ...
ObjectFrame newHome = getApplicationData().getFrame("/
Homepos");
robot.setHomePosition(newHome);
robot.moveAsync(ptpHome());

16.16 Requesting system states

Different system states can be requested from the robot and processed in
the application. The requesting of system states is primarily required when
using a higher-level controller so that the controller can react to changes
in state.

16.16.1 Requesting the HOME position

Description

The following methods of the Robot class are available for requesting the
HOME position:
• getHomePosition()
Requests the HOME position currently defined for the robot
• isInHome()
Checks whether the robot is currently in the HOME position

Syntax

To request the HOME position:

JointPosition homePos = robot.getHomePosition();
To check whether the robot is currently in the HOME position:
boolean result = robot.isInHome();

Explanation of the syntax

Element Description
homePos Type: JointPosition
Variable for the return value of getHomePosition(). The
return value contains axis angles of the requested HOME
position.
robot Type: robot
Name of the robot from which the HOME position is re-
quested
result Type: boolean
Variable for the return value of isInHome(). The return
value is true when the robot is in the HOME position.

460/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Example

As long as the robot is not yet in the HOME position, a certain statement
block is to be executed.

@Inject
private LBR robot;
// ...
while (! robot.isInHome()) {
//do something
}

16.16.2 Requesting the mastering state

Description

The method isMastered() is available for requesting the mastering state.

The method belongs to the Robot class.

Syntax

boolean result = robot.isMastered();

Explanation of the syntax

Element Description
robot Type: Robot
Name of the robot whose mastering state is requested
result Type: Boolean
Variable for the return value

• true: All axes are mastered.

• false: One or more axes are unmastered.

16.16.3 Checking “ready for motion”

Description

The method isReadyToMove() is available for checking whether the robot

is ready for motion. The method belongs to the Robot class. It returns the
value “true” if the robot is ready to move.
The robot is ready to move if the following conditions are met:
• No safety stop is active.
• The drives are in an error-free state.
• Automatic mode is set.
OR:
In mode T1 or T2, the enabling signal is issued via the smartPAD (en-
abling switch in center position).

When the enabling signal for manual guidance is issued (enabling

switch on the hand guiding device in the center position), the isReady-
ToMove() method returns the value “false”. The robot is not ready to
move because it can be guided manually and is already being moved.

If the check returns the value “true”, this does not necessarily mean that
the brakes are open and that the robot is under active servo control.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 461/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Syntax

boolean result = robot.isReadyToMove();

Explanation of the syntax

Element Description
robot Type: Robot
Name of the robot which is checked as to whether it is
ready for motion
result Type: boolean
Variable for the return value

• true: Robot is ready for motion.

• false: Robot is not ready for motion.

16.16.3.1 Reacting to changes in the “ready for motion” signal

Description

There is a notification service of the Controller class in RoboticsAPI which

reports changes in the “ready for motion” signal. To register for the serv-
ice, transfer an IControllerStateListener object to the Controller attribute in
the robot application. The method addControllerListener(…) is used for
this purpose.
The method onIsReadyToMoveChanged(…) is called every time the
“ready to move” signal changes. The reaction to the change can be pro-
grammed in the body of the method onIsReadyToMoveChanged(…).

Syntax

kuka_Sunrise_Cabinet.addControllerListener(new
IControllerStateListener() {
...
@Override
public void onIsReadyToMoveChanged(Device device,
boolean isReadyToMove) {
// Reaction to change
}
...
});

Explanation of the syntax

Element Description
kuka_Sun- Type: Controller
rise_Cabinet
Controller attribute of the robot application (= name of
the robot controller in the application)

16.16.4 Checking the robot activity

Description

A robot is active if a motion command is active. This affects both motion

commands from the application and jogging commands.

462/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The hasActiveMotionCommand() method is available for checking whether

Programming
the robot is active. The method belongs to the Robot class.
The request does not provide any information as to whether the robot is
currently in motion:
• If the request returns the value “false” (no motion command active),
this does not necessarily mean that the robot is stationary. For exam-
ple, robot activity may be checked directly after a synchronous motion
command with a break condition. If the break condition occurs, the
check supplies the value “false” if the robot is braked and moving.
• If the request returns the value “true” (motion command active), this
does not necessarily mean that the robot is moving. For example, the
request returns the value “true” if a robot executes the motion com-
mand positionHold(…) and is stationary.

Syntax

boolean result = robot.hasActiveMotionCommand();

Explanation of the syntax

Element Description
robot Type: Robot
Identifier for the robot whose activity is checked
result Type: boolean
Variable for the return value

• true: A motion command is active.

• false: No motion command is active.

16.16.5 Requesting the state of safety signals

Description

The state of the following safety signals can be requested and evaluated
in an application:
• Active operating mode
• Enabling
• Local EMERGENCY STOP
• External EMERGENCY STOP
• “Operator safety” signal
• Stop request (safety stop)
• Referencing state of position and axis torque sensors
The state of the different safety signals is first requested via the method
getSafetyState() and grouped in an object of type ISafetyState.
From this object, the states of individual safety signals can then be re-
quested. The interface ISafetyState contains the methods required for this.

Syntax

ISafetyState currentState = kinematics.getSafetyState();

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 463/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Explanation of the syntax

Element Description
currentState Type: ISafetyState
Variable for the return value. The return value contains
the state of the safety signals at the time of requesting
with getSafetyState().
Note: This does not apply to the referencing states. Ref-
erencing states are not requested until the corresponding
methods of the ISafetyState object are called.
kinematics Type: MovableDevice
Kinematic system for which the state of the safety
signals is requested

Precondition

The EMERGENCY STOP signal and the “Operator Safety” signal can only
be evaluated if the following conditions are met in the safety configuration:
• The selected category matches the safety function:
‒ Category Local EMERGENCY STOP for local EMERGENCY
STOP
‒ Category External EMERGENCY STOP for external EMERGENCY
STOP
‒ Category Operator safety for operator safety
• The configured reaction is a safety stop (no output).

Overview

Methods of the ISafetyState interface

The implementing class of the interface is SunriseSafetyState (package:
com.kuka.roboticsAPI.controllerModel.sunrise).
Method Description
getEmergencyStopInt() Return value type: Enum of type EmergencyStop
Checks whether a local E-STOP is activated.

• ACTIVE: local E-STOP is activated.

• INACTIVE: local E-STOP is not activated.
• NOT_CONFIGURED: not relevant, as a local E-STOP is
always configured.
getEmergencyStopEx() Return value type: Enum of type EmergencyStop
Checks whether an external E-STOP is activated.

• ACTIVE: external E-STOP is activated.

• INACTIVE: external E-STOP is not activated.
• NOT_CONFIGURED: no external EMERGENCY STOP is
configured.

464/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Method Description
getEnablingDeviceState() Return value type: Enum of type EnablingDeviceState
Checks whether an enabling switch is pressed.

• HANDGUIDING: enabling switch on the hand guiding de-

vice is pressed.
• NORMAL: enabling switch on the smartPAD is pressed.
• NONE: no enabling switch is pressed or a safety function
has been violated and is blocking motion enable.
getOperationMode() Return value type: Enum of type OperationMode (package:
com.kuka.roboticsAPI.deviceModel)
Checks which operating mode is active.

• T1, T2, AUT, CRR

getOperatorSafetyState() Return value type: Enum of type OperatorSafety
Checks the “Operator safety” signal.

• OPERATOR_SAFETY_OPEN: operator safety is violated

(e.g. safety gate is open).
• OPERATOR_SAFETY_CLOSED: operator safety is not
violated.
• NOT_CONFIGURED: no operator safety is configured.
getSafetyStopSignal() Return value type: Enum of type SafetyStopType
Checks whether a safety stop is activated.

• NOSTOP: no safety stop is activated.

• STOP0: a safety stop 0 or a safety stop 1 is activated.
• STOP1: a safety stop 1 (path-maintaining) is activated.
• STOP2: this value is currently not returned.
The methods for requesting the referencing state are described here:
(>>> 16.16.5.1 "Requesting the referencing state" Page 466)

Example

The system checks whether a safety stop is activated. If this is the case,
the operator safety is then checked. If this is violated, a message is dis-
played on the smartHMI. For output purposes, a logger object has been
integrated with dependency injection.

ISafetyState safetyState = robot.getSafetyState();

SafetyStopType safetyStop = safetyState.getSafetyStopSignal();

if (safetyStop != SafetyStopType.NOSTOP) {
OperatorSafety operatorSafety = safetyState.getOperatorSafetyState();
if (operatorSafety == OperatorSafety.OPERATOR_SAFETY_OPEN) {
logger.warn("The safety gate is open!");
}
}

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 465/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.16.5.1 Requesting the referencing state

Programming

Description

Sensitive robots have referenceable position and axis torque sensors. The
referencing state of these sensors can be requested, e.g. to check wheth-
er referencing needs to be carried out again. If a robot has no reference-
able sensors, the request returns the value “false”.
Method Description
isAxisGMSReferenced(…) Return value type: boolean
Checks whether the axis torque sensor of a specific robot ax-
is is referenced. The axis to be checked is transferred as a
parameter (type: JointEnum).

• true: Axis torque sensor of the axis is referenced.

• false: Axis torque sensor of the axis is not referenced or
the robot has no axis torque sensors that can be refer-
enced.
If an invalid axis is transferred, i.e. an axis that is not present
on the robot, an Illegal Argument Exception is triggered.
areAllAxesGMSReferenced() Return value type: boolean
Checks whether all axis torque sensors of the robot are refer-
enced.

• true: All axis torque sensors are referenced.

• false: At least 1 axis torque sensor is not referenced or
the robot has no axis torque sensors that can be refer-
enced.
isAxisPositionReferenced(…) Return value type: boolean
Checks whether the position sensor of a specific robot axis is
referenced. The axis to be checked is transferred as a param-
eter (type: JointEnum).

• true: Position sensor of the axis is referenced.

• false: Position sensor of the axis is not referenced or the
robot has no position sensors that can be referenced.
If an invalid axis is transferred, i.e. an axis that is not present
on the robot, an Illegal Argument Exception is triggered.
areAllAxesPosition Return value type: boolean
Referenced()
Checks whether all position sensors of the robot are refer-
enced.

• true: All position sensors are referenced.

• false: At least 1 position sensor is not referenced or the
robot has no position sensors that can be referenced.

Example

Checking whether the position sensor of axis A1 is referenced

boolean isReferencedJ1 =
robot.getSafetyState().isAxisPositionReferenced(JointEnum.J1)
;

466/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.16.5.2 Reacting to a change in state of safety signals

Programming
Description

There is a notification service of the Controller class in RoboticsAPI which

reports changes in the state of safety signals. This service enables a di-
rect reaction to the change in a signal state.
To register for the service, transfer an ISunriseControllerStateListener ob-
ject to the Controller attribute in the robot application. The method add-
ControllerListener(…) is used for this purpose.
The method onSafetyStateChanged(…) is called every time the state of a
safety signal changes. The reaction to the change can be programmed in
the body of the method onSafetyStateChanged(…).

Syntax

kuka_Sunrise_Cabinet.addControllerListener(new
ISunriseControllerStateListener() {
// ...
@Override
public void onSafetyStateChanged(Device device,
SunriseSafetyState safetyState) {
// Reaction to change in state
}
});

Explanation of the syntax

Element Description
kuka_Sun- Type: Controller
rise_Cabinet
Controller attribute of the robot application (= name of
the robot controller in the application)

Example

If the state of a safety signal changes, the operator safety is checked via
the method onSafetyStateChanged()(…). If this is violated, a message is
displayed on the smartHMI. For output purposes, a logger object has
been integrated with dependency injection.

kuka_Sunrise_Cabinet.addControllerListener(new
ISunriseControllerStateListener() {

// ...

@Override
public void onSafetyStateChanged(Device device, SunriseSafetyState
safetyState) {
OperatorSafety operatorSafety = safetyState.getOperatorSafetyState();
if (operatorSafety == OperatorSafety.OPERATOR_SAFETY_OPEN) {
logger.warn("The saftey gate is open!");
}
}
});

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 467/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.17 Changing and requesting the program run mode

Description

The program run mode can be changed and requested via the methods
setExecutionMode(…) and getExecutionMode() of the SunriseExecution-
Service. The SunriseExecutionService itself is requested by the Controller.

Preparation

1. Variable of type SunriseExecutionService.

2. Request the SunriseExecutionService via the method getExecutionSer-
vice() and save in the variable.

Syntax

To change the program run mode:

service.setExecutionMode(ExecutionMode.newMode);
To request the current program run mode:
currentMode = service.getExecutionMode();

Explanation of the syntax

Element Description
service: Type: SunriseExecutionService
Variable for the return value (contains the SunriseExecu-
tionService reequested by the Controller)
newMode Type: Enum of type ExecutionMode
New program run mode

• ExecutionMode.Step: Step mode (program

sequence with a stop after each motion command)
• ExecutionMode.Continuous: Standard mode (contin-
uous program sequence without stops)
currentMode Type: ExecutionMode
Variable for the return value (contains the program run
mode requested by the SunriseExecutionService)

Example

The SunriseExecutionService is requested by the Controller and saved in

the variable “serv”.

@Inject
private Controller controller;
private SunriseExecutionService serv;
// ...

@Override
public void initialize() {
// ...
serv = (SunriseExecutionService)controller
.getExecutionService();
// ...
}

The system first switches to Step mode and then back to standard mode.

468/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
@Override
public void run() {
// ...
serv.setExecutionMode(ExecutionMode.Step);
// ...
serv.setExecutionMode(ExecutionMode.Continuous);
// ...
}

The current program run mode is requested.

@Override
public void run() {
// ...
ExecutionMode currentMode;
currentMode = serv.getExecutionMode();
// ...
}

16.18 Changing and requesting the override

The interface IApplicationOverrideControl provides methods with which the

current override can be requested or changed in the application. For this,
the interface IApplicationControl must be accessed in the first step using
the method getApplicationControl().
The following override types are distinguished:

• Manual override: Override which can be adjusted manually by the user

via the smartPAD
(>>> 6.18.3 "Setting the manual override" Page 114)
• Application override: Programmed override set by the application
• Effective program override: Product of the manual override and appli-
cation override

Overview

Methods used for requesting the current override:

Method Description
getApplicationOverride() Return value type: double
Requests the application override
getManualOverride() Return value type: double
Requests the manual override
getEffectiveOverride() Return value type: double
Requests the effective program override
Methods used for changing the override:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 469/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Method Description
setApplicationOverride(…) Sets the application override to the specified value (type: dou-
ble)

• 0 … 1
clipApplicationOverride(…) Reduces the application override to the specified value (type:
double)

• 0 … 1
If a value is specified that is higher than the value currently
programmed for the application override, the statement cli-
pApplicationOverride(…) is ignored.
clipManualOverride(…) Reduces the manual override to the specified value (type:
double)

• 0 … 1
If a value is specified that is higher than the currently pro-
grammed manual override, the statement clipManualOverr-
ide(…) is ignored.

Example

getApplicationControl().setApplicationOverride(0.5);
// ...
double actualOverride =
getApplicationControl().getEffectiveOverride();

16.18.1 Reacting to an override change

Description

It is possible for an application to inform itself when an override changes.

A listener of type IApplicationOverrideListener must be defined and regis-
tered for this purpose.
When changing an override, the method onOverrideChanged(…) is called.
The reaction to the change can be programmed in the body of the
method onOverrideChanged(…).

Syntax

Defining a listener:
IApplicationOverrideListener overrideListener =
new IApplicationOverrideListener(){
@Override
public void onOverrideChanged(double effectiveOverride,
double manualOverride, double applicationOverride) {
// Reaction to override change
};
};
Registering a listener:
getApplicationControl().
addOverrideListener(overrideListener);
Removing a listener:
getApplicationControl().
removeOverrideListener(overrideListener);

470/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Explanation of the syntax

Element Description
override Type: IApplicationOverrideListener
Listener
Name of the listener

16.19 Overview of conditions

Often, values are to be monitored in applications and if definable limits

are exceeded or not reached, specific reactions are to be triggered. Possi-
ble sources for these values include the sensors of the robot or
configured inputs. The progress of a motion can also be monitored. Possi-
ble reactions are the termination of a motion being executed or the execu-
tion of a handling routine.
A condition can have 2 states: it is met (state = TRUE) or not met (state
= FALSE). To define a condition, an expression is formulated. In this ex-
pression, data, such as measurements provided by the system, are com-
pared with a permissible limit value. The result of the evaluation of the ex-
pression defines the state of the condition.
Since different system data can be used for formulating conditions, there
are different kinds of conditions. Each condition type is made available as
its own class in the RoboticsAPI. They belong to the com.kuka.roboticsA-
PI.conditionModel package and implement the ICondition interface.
Some system data, e.g. axis torques or Cartesian forces and torques on
the robot flange, are only available for sensitive robot types equipped with
corresponding sensor systems. These sensitive robot types include, for
example, the LBR. Condition types using forces or torques are only sup-
ported by these sensitive robot types. If these condition types are applied
to robots that do not provide information about forces or torques, this re-
sults in a runtime error (Exception).

Categories

The various condition types can be subdivided into the following catego-
ries:
• Sensor-related conditions
• Path-related conditions
• Distance-related conditions
• I/O-related conditions
Sensor-related conditions:
Data type Description
JointTorqueCondition The axis torque condition is met if the torque measured in an
axis lies outside of a defined range of values.
(>>> 16.19.2 "Axis torque condition" Page 474)
ForceCondition The force condition is met if the Cartesian force exerted on a
frame below the robot flange (e.g. at the TCP) exceeds a de-
fined magnitude.
(>>> 16.19.3 "Force condition" Page 475)
ForceComponentCondition The force component condition is met if the Cartesian force
exerted along an axis of a frame below the robot flange (e.g.
along an axis of the TCP) exceeds a defined range.
(>>> 16.19.4 "Force component condition" Page 481)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 471/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Data type Description

CartesianTorqueCondition The conditions for the Cartesian torque is met if the Cartesian
torque acting about the axis of a frame below the robot flange
(e.g. about the axis of the TCP) exceeds a defined value.
(>>> 16.19.5 "Condition for Cartesian torque" Page 483)
TorqueComponentCondition The torque component condition is met if the Cartesian torque
exerted about an axis of a frame below the robot flange (e.g.
about an axis of the TCP) is outside a defined range.
(>>> 16.19.6 "Torque component condition" Page 487)
Path-related conditions:
Data type Description
MotionPathCondition The path-related condition is met if a defined distance on the
planned path, from the start or end point of the motion, is
reached. In addition, it is possible to define a time delay
which must be met.
(>>> 16.19.7 "Path-related condition" Page 489)
Distance-related conditions:
Data type Description
FrameDistanceCondition The distance condition is met if the Cartesian distance be-
tween 2 frames is less than a defined distance, e.g. the dis-
tance between a TCP or gripped workpiece and a defined,
fixed reference point.
(>>> 16.19.8 "Distance condition" Page 491)
FrameDistanceComponent The distance component condition is met if the Cartesian dis-
Condition tance between 2 frames relative to the specified axes of an
orientation frame is less than a defined distance.
(>>> 16.19.8.1 "Distance component condition" Page 492)
I/O-related conditions:
Data type Description
BooleanIOCondition The condition for Boolean signals is met if a Boolean digital
input or output has a specific state.
(>>> 16.19.9 "Condition for Boolean signals" Page 493)
IORangeCondition The condition for the value range of a signal is met if the val-
ue of an analog or digital input or output lies within a defined
range.
(>>> 16.19.10 "Condition for the range of values of a signal"
Page 494)

Areas of application

• Abortion of motions
A motion is terminated as soon as a specific event occurs. The event
occurs if the condition already has the state TRUE before the start of
the motion or if it switches to the state TRUE during the motion.
(>>> 16.20 "Break conditions for motion commands" Page 495)

472/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
• Path-related switching actions (trigger)
An action is triggered as soon as a specific event occurs. The event
occurs if the condition already has the state TRUE before the start of
the motion or if it switches to the state TRUE during the motion.
(>>> 16.21 "Path-related switching actions (trigger)" Page 499)
• Monitoring of processes
The state of a condition is checked cyclically using a listener. If the
state of the condition changes, it is possible to react.
(>>> 16.22 "Monitoring of processes" Page 503)
• Blocking wait for condition
An application is stopped until a certain condition is met or a certain
wait time has expired.
(>>> 16.23 "Blocking wait for condition" Page 508)

16.19.1 Complex conditions

Conditions can be logically linked to one another so that it is possible to

define complex conditions. The logic operators required for this are availa-
ble as ICondition methods. The calling ICondition object is linked to one
or more conditions, which are transferred as parameters.
The operators can be called several times in a row and in this way, paren-
theses and nesting of operations can be realized. The evaluation is thus
dependent on the order of calling.

Operators

Operator Description/syntax
NOT Inversion of the calling ICondition object
ICondition invert();
XOR EITHER/OR operation linking the calling ICondition object
with a further condition
ICondition xor(ICondition other);
other: further condition
AND AND operation linking the calling ICondition object with
one or more additional conditions
ICondition and(ICondition other1, ICondition
other2, …);
other1, other2, …: further conditions
OR OR operation linking the calling ICondition object with
one or more additional conditions
ICondition or(ICondition other1, ICondition
other2, …);
other1, other2, …: further conditions

Example

JointTorqueCondition condA = …;
JointTorqueCondition condB = …;
JointTorqueCondition condC = …;
JointTorqueCondition condD = …;

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 473/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

ICondition combi1, combi2, combi3, combi4;

// NOT A
combi1 = condA.invert();

// A AND B AND C
combi2 = condA.and(condB, condC);

// (A OR B) AND C
combi3 = condA.or(condB).and(condC);

// (A OR B) AND (C OR D)
combi4 = condA.or(condB).and(condC.or(condD));

16.19.2 Axis torque condition

Description

The axis torque condition is used to check whether the external torque de-
termined in an axis lies outside of a defined range of values.
(>>> 16.12 "Requesting axis torques" Page 449)
The load data must be specified correctly during programming. Only
then is the condition usefully applicable.

This condition is only supported by sensitive robots, e.g. a robot of type

LBR. If the condition is applied to a different robot that does not provide
the required sensor information, this results in a runtime error (Excep-
tion).

Constructor syntax

JointTorqueCondition(JointEnum joint, double minTorque,

double maxTorque)

Explanation of the syntax

Element Description
joint Axis whose torque value is to be checked
minTorque Lower limit value for the axis torque (unit: Nm)
The condition is met if the torque is less than or equal to
minTorque.
maxTorque Upper limit value for the axis torque (unit: Nm)
The condition is met if the torque is greater than or equal
to minTorque.
The following must apply when determining the upper and lower limit val-
ues for the torque: minTorque ≤ maxTorque.

Example

The condition is met if a torque value of ≤ -2.5 Nm or ≥ 4.0 Nm is meas-

ured in axis J3.

JointTorqueCondition torqueCondJ3 =
new JointTorqueCondition(JointEnum.J3, -2.5, 4.0);

474/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
16.19.3 Force condition

Description

The force condition can be used to check whether a Cartesian force exer-
ted on a frame below the robot flange exceeds a defined limit value.
For example, it is possible to react to the force generated when the robot
presses on a surface using a tool mounted on the flange. For the force
condition, the projections of the force vector exerted on a frame below the
flange are considered. The position of this frame is defined by the point of
application of the force (here the tool tip). The orientation of the frame
should correspond to the orientation of the surface.

Fig. 16-18: Force vectors

1 Frame which specifies the orientation of the reference frame (here:

orientation of the surface)
2 Point of application of the force, here the tip of the tool
3 Reference frame below the flange onto which the force vector is
projected. The position of the frame corresponds to the point of ap-
plication of the force. The orientation corresponds to the orientation
of the surface.

The following force vectors are relevant:

• Normal force N:
The normal force is the projection of the force exerted on the surface
normal (= vector which is perpendicular to the surface). This results in
the part of the force exerted vertically on the surface. For example,
pressure is exerted via the normal force in order to fit a component.
• Shear force S:
The shear force is the projection of the force exerted on the surface.
This results in the part of the force exerted parallel to the surface. The
shear force is generated by friction.

The load data must be specified correctly during programming. Only

then is the condition usefully applicable.

The force estimation cannot return meaningful values near singularity

positions. It is advisable not to use the force component condition for
this type of axis configuration. Alternatively, the axis torque condition
can be used or the axis position can be adapted using the redundancy
so as to ensure that there is no singularity.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 475/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

This condition is only supported by sensitive robots, e.g. a robot of type

LBR. If the condition is applied to a different robot that does not provide
the required sensor information, this results in a runtime error (Excep-
tion).

Methods

Force conditions are of the data type ForceCondition. ForceCondition con-

tains the following static methods for programming conditions:
• createSpatialForceCondition(…): Condition for Cartesian force from all
directions
• createNormalForceCondition(…): Condition for normal force
• createShearForceCondition(…): Condition for shear force
To formulate the condition, a frame below the flange coordinate system
(e.g. the tip of a tool) is defined as a reference system. The forces which
are exerted relative to this frame are determined. The orientation of the
reference system can be optionally defined via an orientation frame. This
can be used, for example, to define the position of the surface on which
the force is exerted.
A limit value is defined to determine the minimum force magnitude which
meets the condition.
The Cartesian force is calculated from the measured values of the axis
torque sensors. The reliability of the calculated force values varies de-
pending on the axis configuration. If the quality of the force calculation is
also to be taken into account, it is possible to specify a value for the max-
imum permissible inaccuracy. If the system calculates an inaccuracy ex-
ceeding this value, the force condition is also met.

16.19.3.1 Condition for Cartesian force from all directions

Description

The static method createSpatialForceCondition(…) is used to define a

condition which is valid regardless of the direction from which the Cartesi-
an force is exerted on a frame below the flange.

Syntax

ForceCondition.createSpatialForceCondition(
AbstractFrame measureFrame<, AbstractFrame
orientationFrame>, double threshold<, double tolerance>)

Explanation of the syntax

Element Description
measure Frame below the robot flange relative to which the exer-
Frame ted force is determined.
The position of the point of application of the force is de-
fined using this parameter.
orientation Optional. The orientation of the reference system is de-
Frame fined using this parameter.
If the orientationFrame parameter is not specified, meas-
ureFrame defines the orientation of the reference system.

476/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Element Description
threshold Maximum magnitude of force which may act on the refer-
ence system (unit: N).

• ≥ 0.0
The condition is met if the magnitude of force exerted on
the reference system from any direction exceeds the val-
ue specified here.
tolerance Optional. Maximum permissible inaccuracy of the calcula-
ted values (unit: N).

• > 0.0
Default: 10.0
The condition is met if the inaccuracy of the force calcu-
lation is greater than or equal to the value specified here.
If the parameter is not specified, the default value is au-
tomatically used.

Example

The condition is met as soon as the magnitude of the force acting from
any direction on the TCP of a tool exceeds 30 N.

public class ExampleApplication extends

RoboticsAPIApplication {
@Inject
private LBR robot;
@Inject
private Tool gripper;
// ...

@Override
public void initialize() {
// ...
gripper.attachTo(robot.getFlange());
// ...
}

@Override
public void run() {
// ...
ForceCondition spatialForce_tcp = ForceCondition
.createSpatialForceCondition(
gripper.getFrame("/TCP"),
30.0);
// ...
}
}

16.19.3.2 Condition for normal force

Description

A condition for the normal force can be defined via the static method cre-
ateNormalForceCondition(…). The component of the force exerted along a
definable axis of a frame below the flange (e.g. along an axis of the TCP)
is considered here. This axis is generally defined so that it is perpendicu-
lar to the surface on which the force is exerted (surface normal).

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 477/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Syntax

ForceCondition.createNormalForceCondition(AbstractFrame
measureFrame<, AbstractFrame orientationFrame>,
CoordinateAxis direction, double threshold<,
double tolerance>)

Explanation of the syntax

Element Description
measure Frame below the robot flange relative to which the exer-
Frame ted force is determined.
The position of the point of application of the force is de-
fined using this parameter.
orientation Optional. The orientation of the reference system is de-
Frame fined using this parameter.
If the orientationFrame parameter is not specified, meas-
ureFrame defines the orientation of the reference system.
direction Coordinate axis of the reference system.
The force component acting on the axis specified here is
checked with the condition.

• CoordinateAxis.X
• CoordinateAxis.Y
• CoordinateAxis.Z
threshold Maximum magnitude of force which may act along the
axis of the reference system (unit: N).

• ≥ 0.0
The condition is met if the magnitude of force exceeds
the value specified here.
tolerance Optional. Maximum permissible inaccuracy of the calcula-
ted values (unit: N).

• > 0.0
Default: 10.0
The condition is met if the inaccuracy of the force calcu-
lation is greater than or equal to the value specified here.
If the parameter is not specified, the default value is au-
tomatically used.

Example

A gripper mounted on the flange presses on a table plate. The robot is to

react to that part of the force exerted at the TCP of the gripper which acts
vertically on the table plate. The reference system is therefore defined
such that its Z axis runs along the surface normal of the table plate.
The condition is met as soon as the normal force exceeds a magnitude of
45 N. The condition is also to be considered met if the inaccuracy value
of the calculated data exceeds 8.

public class ExampleApplication extends

RoboticsAPIApplication {
@Inject
private LBR robot;
@Inject

478/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
private Tool gripper;
// ...

@Override
public void initialize() {
// ...
gripper.attachTo(robot.getFlange());
// ...
}

@Override
public void run() {
// ...
ForceCondition normalForce_z = ForceCondition
.createNormalForceCondition(
gripper.getFrame("/TCP"),
getFrame("/Table/Edge/Tabletop"),
CoordinateAxis.Z,
45.0,
8.0);
// ...
}
}

16.19.3.3 Condition for shear force

Description

A condition for the shear force can be defined via the static method crea-
teShearForceCondition(…). The component of the force acting parallel to
a plane is considered here. The position of the plane is determined by
specifying the axis which is vertical to the plane.

Syntax

ForceCondition.createShearForceCondition(AbstractFrame
measureFrame<, AbstractFrame orientationFrame>,
CoordinateAxis normalDirection, double threshold<,
double tolerance>)

Explanation of the syntax

Element Description
measure Frame below the robot flange relative to which the exer-
Frame ted force is determined.
The position of the point of application of the force is de-
fined using this parameter.
orientation Optional. The orientation of the reference system is de-
Frame fined using this parameter.
If the orientationFrame parameter is not specified, meas-
ureFrame defines the orientation of the reference system.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 479/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Element Description
normal Coordinate axis of the reference system.
Direction
The axis specified here defines the surface normal of a
plane. The force component acting parallel to this plane
is checked.

• CoordinateAxis.X
• CoordinateAxis.Y
• CoordinateAxis.Z
threshold Maximum magnitude of force which may be exerted par-
allel to the reference system plane defined by its surface
normal (unit: N).

• ≥ 0.0
The condition is met if the magnitude of force exceeds
the value specified here.
tolerance Optional. Maximum permissible inaccuracy of the calcula-
ted values (unit: N).

• > 0.0
Default: 10.0
The condition is met if the inaccuracy of the force calcu-
lation is greater than or equal to the value specified here.
If the parameter is not specified, the default value is au-
tomatically used.

Example

A gripper mounted on the flange presses on a table plate. The force at

the TCP of the gripper is to be determined using the orientation of the ta-
ble plate. This process considers the shear force which acts parallel to the
XY plane of the measurement point, defined by the TCP and the position
of the table.
To define the XY plane, the axis perpendicular to this plane must be
specified as a parameter. This is the Z axis.
The condition is met as soon as the shear force exceeds a magnitude of
25 N. The condition is also to be considered met if the inaccuracy value
of the calculated data exceeds 5.

public class ExampleApplication extends

RoboticsAPIApplication {
@Inject
private LBR robot;
@Inject
private Tool gripper;
// ...

@Override
public void initialize() {
// ...
gripper.attachTo(robot.getFlange());
// ...
}

@Override
public void run() {
// ...

480/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
ForceCondition shearForce_xyPlane = ForceCondition
.createShearForceCondition(
gripper.getFrame("/TCP"),
getFrame("/Table/Edge/Tabletop"),
CoordinateAxis.Z,
25.0,
5.0);
// ...
}
}

16.19.4 Force component condition

Description

The force component condition can be used to check whether the Cartesi-
an force exerted on a frame below the robot flange (e.g. at the TCP) in
the X, Y or Z direction exceeds a defined range.
The load data must be specified correctly during programming. Only
then is the condition usefully applicable.

The force estimation cannot return meaningful values near singularity

positions. It is advisable not to use the force component condition for
this type of axis configuration. Alternatively, the axis torque condition
can be used or the axis position can be adapted using the redundancy
so as to ensure that there is no singularity.

This condition is only supported by sensitive robots, e.g. a robot of type

LBR. If the condition is applied to a different robot that does not provide
the required sensor information, this results in a runtime error (Excep-
tion).

The force component condition belongs to the ForceComponentCondition

class. For the force component condition, a frame below the flange coor-
dinate system is defined as a reference system. The force is determined
at this frame, e.g. at the tip of a tool. The orientation of the reference sys-
tem can be optionally defined via an orientation frame.
The direction from which the force is checked is defined with one of the
coordinate axes of the reference system. The force component condition
is met if the Cartesian force along the defined coordinate axis of the refer-
ence system lies outside of a definable range of values.
The Cartesian force is calculated from the measured values of the axis
torque sensors. The reliability of the calculated force values varies de-
pending on the axis configuration. If the quality of the force calculation is
also to be taken into account, it is possible to specify a value for the max-
imum permissible inaccuracy. If the system calculates an inaccuracy ex-
ceeding this value, the force component condition is also met.

Constructor syntax

The ForceComponentCondition class has several constructors which differ

in their number of input parameters:
ForceComponentCondition(AbstractFrame measureFrame
<, AbstractFrame orientationFrame>, CoordinateAxis
coordinateAxis, double min, double max<, double tolerance>)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 481/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Explanation of the syntax

Element Description
measure Frame below the robot flange relative to which the exer-
Frame ted force is determined.
The position of the point of application of the force is de-
fined using this parameter.
orientation Optional: The orientation of the reference system is de-
Frame fined using this parameter.
If the orientationFrame parameter is not specified, meas-
ureFrame defines the orientation of the reference system.
coordinate Coordinate axis of the frame relative to which the exerted
Axis force is determined. Defines the direction from which the
acting force is checked.

• CoordinateAxis.X
• CoordinateAxis.Y
• CoordinateAxis.Z
min Lower limit of the range of values for the force exerted
along the coordinate axis of the reference system (unit:
N).
The force component condition is met if the force falls
below the value specified here.
max Upper limit of the range of values for the force exerted
along the coordinate axis of the reference system (unit:
N).
The force component condition is met if the force ex-
ceeds the value specified here.
Note: The upper limit value must be greater than the
lower limit value: max > min.
tolerance Optional: Maximum permissible inaccuracy of the calcula-
ted values.

• > 0.0
Default: 10.0
The force component condition is met if the inaccuracy of
the force calculation is greater than or equal to the value
specified here.
If the parameter is not specified, the default value is au-
tomatically used.

Example

A joining process is ideally executed with a force of between 20 N and

25 N. A force component condition is to be defined, and is met if the
force acting in the Z direction at the free end of a gripped workpiece is
between 20 N and 25 N.
To this end, a force component condition is first defined which has the
status FALSE in this range of values. The desired result is then realized
by inversion.

public class ExampleApplication extends

RoboticsAPIApplication {
@Inject
private LBR robot;

482/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
@Inject
private Tool gripper;
@Inject
@Named("Bolt")
private Workpiece bolt;
// ...

@Override
public void run() {
// ...
bolt.attachTo(gripper.getFrame("/Root"));

ForceComponentCondition assemblyForce_inverted =
new ForceComponentCondition(
bolt.getFrame("/Assembly"),
CoordinateAxis.Z,
20.0,
25.0);

ICondition assemblyForce =
assemblyForce_inverted.invert();
// ...
}
}

16.19.5 Condition for Cartesian torque

Description

The condition can be used to check whether a Cartesian torque exerted

on a frame below the robot flange exceeds a defined limit value. The
point of application of the torque is specified by means of a frame below
the robot flange coordinate system.
One application for this condition is the monitoring of torques that occur in
a screw fastening process.

Fig. 16-19: Torque vectors in the screw fastening process

1 Power wrench
2 Screw
3 Reference frame, here the tip of the power wrench
The condition for the Cartesian torque can be used to check different pro-
jections of the torque vector acting on the axes of the reference frame:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 483/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

• Torque MTurn
The torque exerted about an axis arises from the projection of the tor-
que vector on this axis.
• Tilting torque MTilt
The tilting torque arises from the projection of the torque vector on a
plane.
The torque is applied about the longitudinal axis of the power wrench dur-
ing a screw fastening process in order to screw in the screw. If the condi-
tion for the torque is used, it is possible to ensure that the maximum per-
missible values are not exceeded when fastening screws.
The tilting torque arises during a screw fastening process as a result of
undesired tilting of the power wrench about the longitudinal axis, forwards
or to the side. If the condition for the tilting torque is configured, it is pos-
sible to check whether the tilting torque is within an acceptable range of
values.
The load data must be specified correctly during programming. Only
then is the condition usefully applicable.

The force estimation cannot return meaningful values near singularity

positions. It is advisable not to use the force component condition for
this type of axis configuration. Alternatively, the axis torque condition
can be used or the axis position can be adapted using the redundancy
so as to ensure that there is no singularity.

This condition is only supported by sensitive robots, e.g. a robot of type

LBR. If the condition is applied to a different robot that does not provide
the required sensor information, this results in a runtime error (Excep-
tion).

Methods

Conditions for the Cartesian torque are of data type CartesianTorqueCon-

dition. CartesianTorqueCondition contains the following static methods for
programming conditions:
• createSpatialTorqueCondition(…): Condition for Cartesian torque from
all directions
• createTurningTorqueCondition(…): Condition for torque
• createTiltingTorqueCondition(…): Condition for tilting torque
To formulate the condition, a frame is defined as a reference system be-
low the flange coordinate system. The torque is determined at this frame,
e.g. at the tip of a power wrench. The orientation of the reference system
can be optionally defined via an orientation frame. In this way, the desired
orientation of the screw can be specified, for example.
A limit value is defined to determine the minimum Cartesian torque magni-
tude which meets the condition.
The Cartesian torque is calculated from the measured values of the axis
torque sensors. The reliability of the calculated Cartesian torques varies
depending on the axis configuration. If the quality of the calculation is also
to be taken into account, it is possible to specify a value for the maximum
permissible inaccuracy. If the system calculates an inaccuracy exceeding
this value, the condition for the Cartesian torque is also met.

484/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.19.5.1 Condition for Cartesian torque from all directions

Programming
Description

The static method createSpatialTorqueCondition(…) is used to define a

condition which is valid regardless of the direction from which the Cartesi-
an torque is exerted on a frame below the flange.

Syntax

CartesianTorqueCondition.createSpatialTorqueCondition(
AbstractFrame measureFrame<, AbstractFrame
orientationFrame>, double threshold<, double tolerance>)

Explanation of the syntax

Element Description
measure Frame below the robot flange at which the exerted
Frame torque is determined.
The position of the point of application of the torque is
defined using this parameter.
orientation Optional: The orientation of the reference system is de-
Frame fined using this parameter.
If the orientationFrame parameter is not specified, meas-
ureFrame defines the orientation of the reference system.
threshold Maximum magnitude of the torque which may act on the
reference system (unit: Nm).

• ≥ 0.0
The condition is met if the magnitude of the torque exer-
ted on the reference system from any direction exceeds
the value specified here.
tolerance Optional: Maximum permissible inaccuracy of the calcula-
ted values (unit: Nm).

• > 0.0
Default: 10.0
The condition is met if the inaccuracy of the torque cal-
culation is greater than or equal to the value specified
here.
If the parameter is not specified, the default value is au-
tomatically used.

16.19.5.2 Condition for torque

Description

A condition for the torque can be defined via the static method createTur-
ningTorqueCondition(…). The component of the overall torque applied
about a definable axis of a frame below the flange (e.g. about an axis of
the TCP) is considered here.

Syntax

CartesianTorqueCondition.createTurningTorqueCondition(
AbstractFrame measureFrame<, AbstractFrame

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 485/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

orientationFrame>, CoordinateAxis direction,

Programming

double threshold<, double tolerance>)

Explanation of the syntax

Element Description
measure Frame below the robot flange at which the exerted
Frame torque is determined.
The position of the point of application of the torque is
defined using this parameter.
orientation Optional: This parameter defines the orientation of the
Frame frame relative to which the torque is determined.
If the orientationFrame parameter is not specified, meas-
ureFrame defines the orientation of the reference system.
direction Coordinate axis of the reference system
The component of the overall torque acting on the axis
specified here of the reference system is checked using
this condition.

• CoordinateAxis.X
• CoordinateAxis.Y
• CoordinateAxis.Z
threshold Maximum magnitude of the torque that may be applied to
the axis of the reference system (unit: Nm).

• ≥ 0.0
The condition is met if the magnitude of the torque ex-
ceeds the value specified here.
tolerance Optional: Maximum permissible inaccuracy of the calcula-
ted values (unit: Nm).

• > 0.0
Default: 10.0
The condition is met if the inaccuracy of the torque cal-
culation is greater than or equal to the value specified
here.
If the parameter is not specified, the default value is au-
tomatically used.

16.19.5.3 Condition for tilting torque

Description

A condition for the tilting torque can be defined via the static method cre-
ateTiltingTorqueCondition(…). The component of the overall torque applied
to a plane of the reference system is considered here. The position of the
plane is determined by specifying the axis which is vertical to the plane
(surface normal).

Syntax

CartesianTorqueCondition.createTiltingTorqueCondition(
AbstractFrame measureFrame<, AbstractFrame
orientationFrame>, CoordinateAxis normalDirection,
double threshold<, double tolerance>)

486/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Explanation of the syntax

Element Description
measure Frame below the robot flange at which the exerted
Frame torque is determined.
The position of the point of application of the torque is
defined using this parameter.
orientation Optional: This parameter defines the orientation of the
Frame frame relative to which the torque is determined.
If the orientationFrame parameter is not specified, meas-
ureFrame defines the orientation of the reference system.
normal Coordinate axis of the reference system
Direction
The axis specified here defines the surface normal of a
plane. The component of the overall torque applied to
the plane is checked.

• CoordinateAxis.X
• CoordinateAxis.Y
• CoordinateAxis.Z
threshold Maximum magnitude of the tilting torque that may be ap-
plied to the plane of the reference system defined by its
surface normal (unit: Nm).

• ≥ 0.0
The condition is met if the magnitude of the torque ex-
ceeds the value specified here.
tolerance Optional: Maximum permissible inaccuracy of the calcula-
ted values (unit: Nm).

• > 0.0
Default: 10.0
The condition is met if the inaccuracy of the torque cal-
culation is greater than or equal to the value specified
here.
If the parameter is not specified, the default value is au-
tomatically used.

16.19.6 Torque component condition

Description

The torque component condition can be used to check whether the Carte-
sian torque exerted about the X, Y or Z axis of a frame below the robot
flange (e.g. about an axis of the TCP) is outside a defined range. It is
used for monitoring the Cartesian torque in a specific direction, e.g. for
monitoring screw fastening processes.
The load data must be specified correctly during programming. Only
then is the condition usefully applicable.

The force estimation cannot return meaningful values near singularity

positions. It is advisable not to use the force component condition for
this type of axis configuration. Alternatively, the axis torque condition
can be used or the axis position can be adapted using the redundancy
so as to ensure that there is no singularity.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 487/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

This condition is only supported by sensitive robots, e.g. a robot of type

LBR. If the condition is applied to a different robot that does not provide
the required sensor information, this results in a runtime error (Excep-
tion).

The torque component condition is represented by the TorqueComponent-

Condition class. For the torque component condition, a frame below the
flange coordinate system is defined as a reference system. The torque is
determined at this frame, e.g. at the tip of a power wrench. The orienta-
tion of the reference system can be optionally defined via an orientation
frame.
The direction in which the torque is checked is defined with one of the co-
ordinate axes of the reference system. The torque component condition is
met if the Cartesian torque about the defined coordinate axis of the refer-
ence system lies outside a definable range of values.
The Cartesian torque is calculated from the measured values of the axis
torque sensors. The reliability of the calculated Cartesian torques varies
depending on the axis configuration. If the quality of the calculation is also
to be taken into account, it is possible to specify a value for the maximum
permissible inaccuracy. If the system calculates an inaccuracy exceeding
this value, the torque component condition is also met.

Constructor syntax

The TorqueComponentCondition class has several constructors which dif-

fer in their number of input parameters:
TorqueComponentCondition(AbstractFrame measureFrame
<, AbstractFrame orientationFrame>, CoordinateAxis
component, double min, double max<, double tolerance>)

Explanation of the syntax

Element Description
measure Frame below the robot flange relative to which the exer-
Frame ted torque is determined.
The position of the point of application of the torque is
defined using this parameter.
orientation Optional: This parameter defines the orientation of the
Frame frame relative to which the torque is determined.
If the orientationFrame parameter is not specified, meas-
ureFrame defines the orientation of the reference system.
coordinate Coordinate axis of the frame relative to which the exerted
Axis torque is determined. Defines the direction in which the
acting torque is checked.

• CoordinateAxis.X
• CoordinateAxis.Y
• CoordinateAxis.Z
min Lower limit of the range of values for the torque exerted
about the coordinate axis of the reference system (unit:
Nm).
The torque component condition is met if the torque falls
below the value specified here.

488/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Element Description
max Upper limit of the range of values for the torque exerted
about the coordinate axis of the reference system (unit:
Nm).
The torque component condition is met if the torque ex-
ceeds the value specified here.
Note: The upper limit value must be greater than the
lower limit value: max > min.
tolerance Optional: Maximum permissible inaccuracy of the calcula-
ted values (unit: Nm).

• > 0.0
Default: 10.0
The condition is met if the inaccuracy of the torque cal-
culation is greater than or equal to the value specified
here.
If the parameter is not specified, the default value is au-
tomatically used.

16.19.7 Path-related condition

Description

Path-related conditions are always used in conjunction with a motion com-

mand. They serve as break conditions or triggers for path-related switch-
ing actions.
The condition defines a point on the planned path (switching point) on
which a motion is to be terminated or a desired action is to be triggered.
If the switching point is reached, the condition is met.
The braking process or the defined action is only triggered when the
switching point is reached. When using a path-related condition as a
break condition, this results in the robot coming to a standstill after the
switching point rather than directly at it.

The switching point can be defined by a shift in space and/or time. The
shift can optionally refer to the start or end point of a motion.
If a time offset is defined, a change to the override influences the
switching point. The action linked to a path-related condition is therefore
only triggered with an effective program override of 100% and at the de-
fined switching point in T2 or Automatic modes.

Path-related conditions are of data type MotionPathCondition.

Constructor syntax

The MotionPathCondition class has the following constructor:

MotionPathCondition(ReferenceType reference,
double distance, long delay)

Static methods

A MotionPathCondition object can also be created via one of the following

static methods:
MotionPathCondition.createFromDelay(
ReferenceType reference, long delay)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 489/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

MotionPathCondition.createFromDistance(
ReferenceType reference, double distance)

Explanation of the syntax

Element Description
reference Reference point of the condition (type: Enum Reference-
Type)

• ReferenceType.START: Start point

• ReferenceType.DEST: End point
distance Offset in space relative to the reference point of the con-
dition.
For CP motions, distance specifies the Cartesian dis-
tance between the switching point and the reference
point, i.e. the distance along the path which connects the
switching point and the reference point, and not the
shortest distance between these points. (Unit: mm)
For PTP motions, distance does not specify a Cartesian
distance but rather a path parameter without a unit.

• Negative value: Offset contrary to the direction of mo-

tion
• Positive value: Offset in the direction of motion
(>>> "Maximum offset" Page 490)
delay Offset in time relative to the path point defined by dis-
tance. Or if distance is not defined, to the reference point
of the condition. (Unit: ms)

• Negative value: Offset contrary to the direction of mo-

tion
• Positive value: Offset in the direction of motion
Phases in which the application is paused are not inclu-
ded in the time measurement.
(>>> "Maximum offset" Page 490)

Maximum offset

The switching point can only be offset within certain limits. The limits ap-
ply to the entire offset, comprising the shift in space and time.
• Negative offset, at most to the start point of the motion
• Positive offset, at most to the end point of the motion
The following parameterizations may not be used, as they will inevitably
lead to an offset beyond the permissible limits and thus to a runtime error:
Value combination Effect
reference = ReferenceType.START The switching point is before the
start of the motion.
distance < 0
reference = ReferenceType.START
distance = 0
delay < 0

490/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Value combination Effect
reference = ReferenceType.DEST The switching point is after the
end of the motion.
distance > 0
reference = ReferenceType.DEST
distance = 0
delay > 0
Even if a valid value combination has been used, the switching point can
nevertheless be offset beyond the permissible limits. In these cases, the
response is as follows:
• A condition which is met before the start of the motion triggers the
motion at the start point.
• A condition which is met after the end of the motion is never a trigger.

Example

A path-related condition is to be formulated for an adhesive bonding appli-

cation. The adhesive bead is to end 5 cm before the end point of the mo-
tion. In order for the flow of adhesive to end in time, the condition must
be met 700 ms before this distance to the end is reached.

MotionPathCondition glueStop = new

MotionPathCondition(ReferenceType.DEST, -50.0, -700);

16.19.8 Distance condition

Description

The distance condition can be used to check whether the Cartesian dis-
tance between 2 frames is less than a defined distance.
• One of the frames must be a movable frame that is located beneath
the robot flange, e.g. a TCP on the tool or the frame of a gripped
workpiece.
• The other frame must be a static frame.
• The movable frame must be linked to the robot flange if the condition
is to be used in a motion command or monitored with a listener.

Fig. 16-20: Distance condition

1 Movable frame
2 Static frame

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 491/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

3 Minimum distance between the 2 frames

Constructor syntax

FrameDistanceCondition(AbstractFrame frameA,
AbstractFrame frameB, double distanceThreshold)

Explanation of the syntax

Element Description
frameA One of the frames whose distance from another frame is
being checked
frameB One of the frames whose distance from another frame is
being checked
distance Minimum distance between the 2 frames (unit: mm)
Threshold
• > 0.0
The distance condition is met if the distance between the
2 frames is less than the specified minimum distance.

16.19.8.1 Distance component condition

Description

The distance component condition, like the distance condition, can be

used to check the Cartesian distance between 2 frames. Additionally, dif-
ferent projections of the distance vector in the coordinate system of an ori-
entation frame can be considered:
• If only one coordinate axis of the orientation frame is specified, the
distance vector is projected onto this coordinate axis and the distance
in the direction of this axis is measured.
• If 2 coordinate axes of the orientation frame are specified, the
distance vector is projected onto the surface formed by these 2 coor-
dinate axes and the distance is measured on this surface. This condi-
tion can be pictured as a virtual cylinder about the static frame with
the movable frame being checked for entry into the cylinder radius (=
minimum distance).

Constructor syntax

FrameDistanceComponentCondition(AbstractFrame frameA,
AbstractFrame frameB, double distanceThreshold,
AbstractFrame orientationFrame,
EnumSet<CoordinateAxis> coordinateAxes)

Explanation of the syntax

Element Description
frameA One of the frames whose distance from another frame is
being checked
frameB One of the frames whose distance from another frame is
being checked

492/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Element Description
distance Minimum distance between the 2 frames (unit: mm)

• > 0.0
The distance component condition is met if the distance
between the 2 frames is less than the specified minimum
distance.
orientation- Frame which specifies the orientation of the distance vec-
Frame tor
Note: The frame must be a static frame and must not be
connected to the robot flange.
coordinate Coordinate axes of the orientation frame to be consid-
Axes ered

• CoordinateAxis.X
• CoordinateAxis.Y
• CoordinateAxis.Z
At least one coordinate axis must be specified.

16.19.9 Condition for Boolean signals

Description

The Boolean signal condition can be used to check Boolean digital inputs
or outputs. The condition is met if a Boolean input or output has a specific
state.
Boolean signal conditions are of data type BooleanIOCondition.

Constructor syntax

BooleanIOCondition(AbstractIO booleanSignal,
boolean booleanIOValue)

Explanation of the syntax

Element Description
boolean Boolean input/output signal that is checked
Signal
boolean State of the input/output signal with which the condition
IOValue is met

• true, false

Example

A boolean digital input signal is returned via a switch. In order to react to

the signal in an application, a boolean signal condition is to be formulated.
The condition must be fulfilled as soon as a high level (state TRUE) is
present when the switch is activated.

public class ExampleApplication extends

RoboticsAPIApplication {
// ...
@Inject
private SwitchesIOGroup switches;
// ...

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 493/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

@Override
public void run() {
// ...
AbstractIO switch1 = switches.getInput("Switch1");
BooleanIOCondition switch1_active =
new BooleanIOCondition(switch1, true);
}
}

16.19.10 Condition for the range of values of a signal

Description

The value of a digital or analog input or output can be checked with the
condition for the range of values of a signal. The condition is met if the
value of the signal lies within a defined range.
Conditions for ranges of values are of data type ForceComponentCondi-
tion.

Constructor syntax

IORangeCondition(AbstractIO signal, Number minValue, Num-

ber maxValue)

Explanation of the syntax

Element Description
signal Analog or digital input/output signal that is checked
minValue Lower limit of the range of values in which the condition
is met
The value returned by the signal must be greater than or
equal to minValue.
maxValue Upper limit of the range of values in which the condition
is met
The value returned by the signal must be less than or
equal to maxValue.

Example

A temperature sensor returns an analog input signal whose value can lie
in the range between 0 °C and 2000 °C. As soon as a threshold of 35 °C
is exceeded, a condition for monitoring the sensor signal should be met.

public class ExampleApplication extends

RoboticsAPIApplication {
// ...
@Inject
private SensorIOGroup sensors;
// ...

@Override
public void run() {
// ...
AbstractIO temperatureSensor =
sensors.getInput("TemperatureSensor2");
IORangeCondition tempHigher35 =
new IORangeCondition(temperatureSensor, 35.0, 2000.0);
}

494/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
}

16.20 Break conditions for motion commands

For certain processes a planned motion must not be fully executed but
rather terminated when definable events occur. For example, in joining
processes, the robot must stop if a force threshold is reached.

16.20.1 Defining break conditions

Description

Break conditions are conditions which cause a motion to be terminated. A

break condition is met if it already has the state TRUE before the start of
the motion or if it switches to the state TRUE during the motion.
Conditions are defined as objects of type ICondition. The available condi-
tion types belong to the package com.kuka.roboticsAPI.conditionModel.
An overview of the available condition types can be found here:
(>>> 16.19 "Overview of conditions" Page 471)
To define a break condition for a motion, an object of the desired condi-
tion type is transferred to the motion command via the method break-
When().
breakWhen(…) can be called several times when programming a motion
command to define different break conditions for a motion. The individual
break conditions are then linked by a logic OR operation.
The following points must be taken into consideration when programming
break conditions:
• For a spline block, break conditions can only be programmed for the
entire spline block. Break conditions for individual splines segments
are not permissible.
• If a break condition defined for a motion within a MotionBatch is trig-
gered, this is terminated, and then the next motion command in the
batch is executed. If a break condition defined for the entire Motion-
Batch occurs, the entire MotionBatch is terminated.
• A break condition causes the motion currently being executed to be
terminated. If no appropriate reaction strategy is programmed in the
application, subsequent motions are carried out immediately after the
terminated motion.
• In the case of approximated motions, the approximate positioning arc
is part of the path of the subsequent motion. For this reason, only the
break conditions for the subsequent motion affect the approximate po-
sitioning arc.
• If the break condition in an approximated motion occurs just before
the approximate positioning point is reached, and if this does not
cause the robot to come to a standstill until it is on the approximate
positioning arc, the robot is accelerated again when the approximate
positioning arc is reached in order to execute the subsequent motion.

Syntax

motion.breakWhen(condition_1<, condition_2, … >);

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 495/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Explanation of the syntax

Element Description
motion Type: Motion
Motion for which a break condition is to be defined
Example:

• ptp(getApplicationData().getFrame("/P1"))
condition Type: ICondition
Parameterized ICondition object which describes a break
condition

Example

A LIN motion is terminated if the torque in axis A3 is less than or equal to

-12 Nm or greater than or equal to 0 Nm.

JointTorqueCondition cond_1 =
new JointTorqueCondition(JointEnum.J3, -12.0, 0.0);
robot.move(lin(getApplicationData().getFrame("/P10"))
.breakWhen(cond_1));

16.20.2 Evaluating the break conditions

Description

If break conditions have been defined for a motion command, it is possi-

ble to view different information on the termination of a motion; for this
purpose, the motion command is temporarily stored in an IMotionContain-
er variable. Via the method getFiredBreakConditionInfo(), this variable can
be requested for an object of type IFiredConditionInfo, which contains the
information about termination of the motion. If no break condition occurs
during the motion, getFiredBreakConditionInfo() returns zero.

Syntax

IMotionContainer motionCmd = motion.breakWhen(...);

IFiredConditionInfo firedCondInfo =
motionCmd.getFiredBreakConditionInfo();

Explanation of the syntax

Element Description
motion Motion instruction
Example:

• lbr.move(ptp(getApplicationData().getFrame("/P1"))
motionCmd Type: IMotionContainer
Temporary memory for the motion command
firedCondIn- Type: IFiredConditionInfo
fo
Information about termination of the motion

Overview

The following methods are available in the IFiredConditionInfo interface:

496/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Method Description
getFiredCondition() Return value type: ICondition
Requests the condition which caused a motion to be termina-
ted
getPositionInfo() Return value type: PositionInformation
Requests for robot position valid at the time when the break
condition was triggered.
getStoppedMotion() Return value type: IMotion
Requests the segment of a spline block or the motion of a
MotionBatch which was terminated

16.20.2.1 Requesting a break condition

Description

The condition which caused the termination of a motion can be requested

via the method getFiredCondition(). The return value is of type ICondition
and can be compared to the transferred break conditions via the
equals(…) method.
The request is particularly useful if several break conditions for a motion
have been defined by repeatedly calling the breakWhen(…) method.

Syntax

ICondition firedCondition = firedCondInfo.getFiredCondition();

Explanation of the syntax

Element Description
firedCondition Type: ICondition
Variable for the return value. The variable contains
the condition which caused the motion to be termina-
ted.
firedCondInfo Type: IFiredConditionInfo
Information about termination of the motion

Example

The break conditions “cond1” and “cond2” are generated.

ICondition cond1;
ICondition cond2;
cond1 = new ...;
cond2 = new ...;

The break conditions “cond1” and “cond2” are transferred to a LIN motion
with breakWhen(…). The “motionCmd” variable of type IMotionContainer
can be used to evaluate the motion command.

IMotionContainer motionCmd =
robot.move(lin(getApplicationData().getFrame("P10"))
.breakWhen(cond1)
.breakWhen(cond2));

The information about the termination of the motion is requested by "mo-

tionCmd". If the requested information is not equal to null, the motion

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 497/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

has been terminated. The system only requests the triggered break condi-
Programming

tion in this case.

IFiredConditionInfo firedInfo =
motionCmd.getFiredConditionInfo();

if (firedInfo != null) {
ICondition firedCond = firedInfo.getFiredCondition();
if (firedCond.equals(cond1)) {
// ...
}
// ...
}

16.20.2.2 Requesting the robot position at the time of termination

Description

The robot position at the time when the break condition was triggered can
be requested via the method getPositionInfo().
The following position information can be accessed via the return value of
type PositionInformation.
• Axis-specific actual position
• Cartesian actual position
• Axis-specific setpoint position
• Cartesian setpoint position
• Setpoint/actual value difference (translational)
• Setpoint/actual value difference (rotational)

Syntax

PositionInformation firedPosInfo =
firedCondInfo.getPositionInfo();

Explanation of the syntax

Element Description
firedPosInfo Type: PositionInformation
Variable for the return value. The return value contains
the position information at the time when the break con-
dition was triggered.
firedCondIn- Type: IFiredConditionInfo
fo
Information about termination of the motion

Example

The Cartesian actual position of the robot at the time when the break con-
dition was triggered is requested via the method getCurrentCartesianPosi-
tion().

PositionInformation firedPosInfo =
firedInfo.getPositionInfo();
Frame firedCurrPos =
firedPosInfo.getCurrentCartesianPosition();

498/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.20.2.3 Requesting a terminated motion (spline block, MotionBatch)

Programming
Description

Break conditions can be defined for an entire spline block or MotionBatch.

If a break condition occurs, the entire spline block or MotionBatch is termi-
nated.
The method getStoppedMotion() can be used to check which spline seg-
ment or which motion of a MotionBatch has been terminated. The return
value is of type IMotion.

Syntax

IMotion stoppedMotion = firedCondInfo.getStoppedMotion();

Explanation of the syntax

Element Description
stoppedMotion Type: IMotion
Variable for the return value. The variable contains
the terminated motion.
firedCondInfo Type: IFiredConditionInfo
Information about termination of the motion

Example

Request using the example of a spline block:

ICondition stopCondition = new ...;

// ...
Spline splineMotion = new Spline(
spl(getApplicationData().getFrame("/P1")),
circ(getApplicationData().getFrame("/P2"),
getApplicationData().getFrame("/P3")),
spl(getApplicationData().getFrame("/P4"))
.setCartVelocity(150),
lin(getApplicationData().getFrame("/P5"))
).setCartVelocity(250).breakWhen(stopCondition);

IMotionContainer splineCont = robot.move(splineMotion);

IFiredConditionInfo firedInfoSpline =
splineCont.getFiredConditionInfo();

if (firedInfoSpline != null) {
IMotion stoppedMotion = firedInfoSpline.getStoppedMotion();
// ...
}

16.21 Path-related switching actions (trigger)

A trigger is an event which is used to activate user-defined, path-related

actions. If a specific event occurs while a motion is being executed, the
action is triggered. The action is performed in parallel with the robot mo-
tion. For example, during a positioning motion, the gripper must be
opened at the right time in order to be open when the pickup position for
the workpiece to be transported is reached.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 499/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.21.1 Programming triggers

Description

Events which activate path-related switching actions are called triggers.

Events are defined using conditions. An event occurs if the defined condi-
tion already has the state TRUE before the start of the motion or if it
switches to the state TRUE during the motion.
Conditions are defined as objects of type ICondition. The available condi-
tion types belong to the package com.kuka.roboticsAPI.conditionModel.
An overview of the available condition types can be found here:
(>>> 16.19 "Overview of conditions" Page 471)
To program a trigger, an object of the desired condition type and an ITrig-
gerAction object which describes the action to be executed are transferred
to the motion command via the method triggerWhen(…).
triggerWhen(…) can be called several times when programming a motion
command to define different triggers for a motion. The execution of the
corresponding switching actions is only dependent on whether the trigger-
ing event occurs, and is not influenced by the order of calling via trigger-
When(…).
The triggering event cannot re-trigger an action while it is being execu-
ted. The trigger is not effective again until the method triggerWhen(…)
has ended. It is possible to request the number of events missed while
the method was being executed.
(>>> 16.21.3 "Evaluating trigger information" Page 502)

Syntax

motion.triggerWhen(condition, action);

Explanation of the syntax

Element Description
motion Type: Motion
Motion for which a trigger must be defined
Example:

• ptp(getApplicationData().getFrame("/P1"))
condition Type: ICondition
Parameterized ICondition object which describes the con-
dition for the trigger
action Type: ITriggerAction
ITriggerAction object which describes the action to be
executed
(>>> 16.21.2 "Programming a path-related switching ac-
tion" Page 500)

16.21.2 Programming a path-related switching action

Description

The path-related action to be executed when an event occurs is defined

via an ITriggerAction object. ITriggerAction is an interface from the
com.kuka.roboticsAPI.conditionModel package. This interface currently
does not provide any methods.

500/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The ICallbackAction interface, which is derived from ITriggerAction, can be

Programming
used for programming actions. The interface has the method onTrigger-
Fired(…). The action to be carried out when the trigger is activated can
be programmed in the body of the method onTriggerFired(…).
An ICallbackAction object can be used in any number of triggers.
The onTriggerFired(…) method is not called in real time. It is therefore
not possible to guarantee specific time behavior. This can lead to de-
layed execution of the action.

Syntax

ICallbackAction action = new ICallbackAction() {

@Override
public void onTriggerFired(IFiredTriggerInfo triggerIn-
formation) {
//Action to be executed
}
};

Explanation of the syntax

Element Description
action Type: ICallbackAction
ICallbackAction object which describes the action trans-
ferred with triggerWhen(…)
onTrigger Method whose execution is fired by the trigger
Fired(…)
trigger Type: IFiredTriggerInfo
Informa-
Contains information about the firing trigger
tion
(>>> 16.21.3 "Evaluating trigger information" Page 502)

Example

During motion to point “P1”, output “DO1” is always switched at the mo-
ment when input “DI1” is TRUE.

//set trigger action

ICallbackAction toggleOut_1 = new ICallbackAction() {
@Override
public void onTriggerFired(IFiredTriggerInfo
triggerInformation) {
//toggle output state when trigger fired
if (IOs.getDO1())
{
IOs.setDO1(false);
}
else
{
IOs.setDO1(true);
}
}
};

//set trigger condition

BooleanIOCondition buttonPressed = new BooleanIOCondition(
IOs.getInput("DI1"), true);

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 501/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

//motion with trigger

robot.move(ptp(P1)).triggerWhen(buttonPressed, toggleOut_1));
robot.move(ptp(P2));

16.21.3 Evaluating trigger information

The onTriggerFired(…) method is called when a trigger is activated. The

object triggerInformation of type IFiredTriggerInfo, which contains
various information about the activating trigger, is transferred to the on-
TriggerFired(…) method. This trigger information can be requested.

Overview

The following methods of the IFiredTriggerInfo class are available:

Method Description
getFiredCondition() Return value type: ICondition
Requests the condition which fired the trigger
getMissedEvents() Return value type: int
Checks how many times the event which fired the trigger still occur-
red while the triggered action was being executed
Note: The triggering event cannot re-trigger an action while it is being
executed.
getMotionContainer() Return value type: IMotionContainer
Requests the motion command, during the execution of which the trig-
ger was fired
getPosition Return value type: PositionInformation
Information()
Requests the position information valid at the time when the trigger
was fired.
The return value contains the following position information:

• Axis-specific actual position

• Cartesian actual position
• Axis-specific setpoint position
• Cartesian setpoint position
• Setpoint/actual value difference (translational)
• Setpoint/actual value difference (rotational)
getTriggerTime() Return value type: java.util.Date
Requests the time at which the trigger was fired
To request the position information obtained with getPositionInformation(),
the following methods of the PositionInformation class are available:
Method Description
getCommandedCartesian Return value type: Frame
Position()
Requests the Cartesian setpoint position at triggering time
getCommandedJointPosition() Return value type: JointPosition
Requests the axis-specific setpoint position at triggering time
getCurrentCartesianPosition() Return value type: Frame
Requests the Cartesian actual position at triggering time

502/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Method Description
getCurrentJointPosition() Return value type: JointPosition
Requests the axis-specific actual position at triggering time

Example 1

When the trigger is fired, the triggering time and condition are displayed
on the smartHMI. For output purposes, a logger object has been integra-
ted with dependency injection.

BooleanIOCondition in1 = new BooleanIOCondition(_input_1,

true);

ICallbackAction ica = new ICallbackAction() {

@Override
public void onTriggerFired(IFiredTriggerInfo
triggerInformation) {
logger.info("TriggerTime: "+ triggerInformation
.getTriggerTime().toString());
logger.info("TriggerCondition: "+ triggerInformation
.getFiredCondition().toString());
}
};

robot.move(ptp(getApplicationData().getFrame("/P1"))
.triggerWhen(in1, ica));

Example 2

The axis-specific and Cartesian robot position at triggering time are re-
quested.

BooleanIOCondition in1 = new BooleanIOCondition(_input_1,

true);

ICallbackAction ica = new ICallbackAction() {

@Override
public void onTriggerFired(IFiredTriggerInfo
triggerInformation) {
PositionInformation posInfo = triggerInformation
.getPositionInformation();
posInfo.getCommandedCartesianPosition();
posInfo.getCommandedJointPosition();
posInfo.getCurrentCartesianPosition();
posInfo.getCommandedJointPosition();
};
};

robot.move(ptp(getApplicationData().getFrame("/P1"))
.triggerWhen(in1, ica));

16.22 Monitoring of processes

Processes can be monitored using a listener so that it is possible to react

to certain events while an application is running.
These events are changes in state of defined conditions. The listener
monitors the state of the condition. If the state of the condition changes,
the listener is notified and the predetermined handling routine is triggered
as a reaction.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 503/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

During execution of a handling routine, the listener is not informed if fur-

Programming

ther events occur. Once the handling routine has been completed, these
events are only transferred to the listener and handled if the appropriate
notification type has been defined.

16.22.1 Listener for monitoring conditions

Various listener interfaces are available from the package com.kuka.robot-

icsAPI.conditionModel for monitoring a condition. The listeners differ in
type in that they are each notified of a certain change in state of the
monitored condition.
Each listener type declares a method which is executed when the listener
is notified. The desired handling routine is programmed in the body of this
method.
Data type Description
IRisingEdgeListener Notification when the monitored condition is met (rising edge):

• Rising edge: change in state from FALSE to TRUE

Method for the handling routine:

• onRisingEdge(…)
IFallingEdgeListener Notification when the monitored condition is no longer met (falling
edge):

• Falling edge: change in state from TRUE to FALSE

Method for the handling routine:

• onFallingEdge(…)
IAnyEdgeListener Notification for every change in state of the condition (rising or falling
edge):

• Rising edge: change in state from FALSE to TRUE

• Falling edge: change in state from TRUE to FALSE
Method for the handling routine:

• onAnyEdge(…)

Overview

The following programming steps are required in order to be able to react

to the change in state of a condition:
Step Description
1 Create a listener object to monitor the condition.
(>>> 16.22.2 "Creating a listener object to monitor the con-
dition" Page 505)
2 Program the desired handling routine in the listener method.
3 Register the listener for notification in case of a change in
state of the condition.
(>>> 16.22.3 "Registering a listener for notification of
change in state" Page 506)
4 Activate the notification service for the listener.
(>>> 16.22.4 "Activating or deactivating the notification serv-
ice for listeners" Page 507)

504/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
16.22.2 Creating a listener object to monitor the condition

Description

The syntax of a listener object is described here using the listener IA-
nyEdgeListener as an example. The listener method onAnyEdge(…) is au-
tomatically declared when the object is created. The method has input pa-
rameters containing information about the event that triggered execution of
the method. This information can be requested and evaluated.
The listener objects of the other listener types are created in the same
way and are structured analogously.

Syntax

IAnyEdgeListener condListener = new IAnyEdgeListener() {

@Override
public void onAnyEdge(ConditionObserver conditionObserv-
er, Date time, int missedEvents, boolean conditionVal-
ue) {
// Reaction to change in state
}
};

Explanation of the syntax

Element Description
condListener Type: IAnyEdgeListener
Name of the listener object
condition Type: ConditionObserver
Observer
Object notified by the listener
time Type: Date
Date and time the listener was notified
missed Type: int
Events
Number of changes in state which have occurred but not
been handled.
Possible causes of non-handled events:

• The notification service was deactivated when the

triggering event occurred.
• The handling routine was being executed when the
triggering event occurred again.
These events can be handled using the notification type
NotificationType.MissedEvents. (>>> "NotificationType"
Page 506)
condition Type: Boolean
Value
Only present with the listener method onAnyEdge(…).
Specifies the edge via which the method was called.

• true = rising edge: change in state from FALSE to

TRUE
• false = falling edge: change in state from TRUE to
FALSE

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 505/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.22.3 Registering a listener for notification of change in state

Description

An object of type ConditionObserver is required to register a listener for

notification in case of a change in state.
To create an object of type ConditionObserver, the ObserverManager of
the application must first be requested via the method getObserverManag-
er(). The ObserverManager class provides various methods for creating
the required object.
• createAndEnableConditionObserver(…)
The notification service for the listener is active immediately.
• createConditionObserver(…)
The notification service for the listener is not active immediately, but
rather must be explicitly activated.
(>>> 16.22.4 "Activating or deactivating the notification service for lis-
teners" Page 507)
The transferred parameters in each case are identical for both methods.

Syntax

ConditionObserver myObserver =
getObserverManager().createAndEnableConditionObserver
(condition, notificationType, listener)

Explanation of the syntax

Element Description
myObserver Type: ConditionObserver
Object which monitors the defined condition
condition Type: ICondition
Condition which is monitored
notification Type: Enum of type NotificationType
Type
Notification type
Defines the events at which the listener is to be notified
in order to execute the desired handling routine.
(>>> "NotificationType" Page 506)
listener Type: IRisingEdgeListener, IFallingEdgeListener or IA-
nyEdgeListener
Listener object which is registered

NotificationType

The Enum of type NotificationType has the following values:

506/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Value Description
EdgesOnly The listener is only notified in the event of an edge
change (according to the listener type used).
OnEnable The listener is notified in the event of an edge
change (according to the listener type used).
In addition, the state of the monitored condition is
checked upon activation of the listener. Depending on
the listener type, the listener is notified when the fol-
lowing events occur:

• IRisingEdgeListener: only if the condition is met

upon activation
• IFallingEdgeListener: only if the condition is not
met upon activation
• IAnyEdgeListener: if the condition is met or not
met upon activation
MissedEvents The listener is notified in the event of an edge
change (according to the listener type used).
In addition, following the execution of the handling
routine, the listener is notified if triggering events
were missed. This means that if the triggering edge
change again occurs during execution of the handling
routine, the listener is also notified again, and the
handling routine is executed a second time.
All Combination of OnEnable and MissedEvents
The listener is notified in the case of all events de-
scribed under OnEnable and MissedEvents.

16.22.4 Activating or deactivating the notification service for listeners

Description

The methods for activating or deactivating the notification service belong

to the ConditionObserver class.
The notification service must only be activated if the method createCondi-
tionObserver(…) was used to register the listener.

Syntax

To activate the notification service:

myObserver.enable()
To deactivate the notification service:
myObserver.disable()

Explanation of the syntax

Element Description
myObserver Type: ConditionObserver
Object which monitors the defined condition

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 507/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.22.5 Programming example for monitoring

A listener of type IRisingEdgeListener is defined for monitoring a force

condition. As soon as a force of 35 N on the TCP is exceeded, this is
considered a collision. The listener is notified and a warning lamp lights
up.
NotificationType.MissedEvents is defined as the notification type. If the
permissible force at the TCP is repeatedly exceeded while the warning
lamp is switched on, the listener will be informed promptly.

ForceCondition collision = ForceCondition

.createSpatialForceCondition(tool.getDefaultMotionFrame(), 35);

IRisingEdgeListener collisionListener = new IRisingEdgeListener() {

@Override
public void onRisingEdge(ConditionObserver conditionObserver,
Date time, int missedEvents) {
signals.setWarningLED(true);
}
});

ConditionObserver collisionObserver = getObserverManager()

.createConditionObserver(collision, NotificationType.MissedEvents,
collisionListener);

collisionObserver.enable();

16.23 Blocking wait for condition

Description

With waitFor(…), an application is stopped until a certain condition is met

or a certain wait time has expired. The application is then resumed.
Latency times may occur while the wait command is being processed. It
is not possible to guarantee that the programmed wait time will be main-
tained exactly.

waitFor(…) must access the ObserverManager of the application. This is

called with getObserverManager().
All condition types are supported with the exception of MotionPathCondi-
tion.
An overview of the available condition types can be found here:
(>>> 16.19 "Overview of conditions" Page 471)

Syntax

Blocking wait with no time limit:

getObserverManager().waitFor(condition)
Blocking wait with a time limit:
boolean result = getObserverManager().waitFor(condition,
timeout, timeUnit)

508/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Explanation of the syntax

Element Description
condition Type: ICondition
Condition which is waited for
If the condition is already met when waitFor(…) is called,
the application is immediately resumed.
timeout Type: long
Maximum wait time
If the condition of the defined wait time does not occur,
the application is also resumed without the occurrence of
the condition.
timeUnit Type: Enum of type TimeUnit
Unit of the specified wait time
The Enum TimeUnit is an integral part of the standard
Java library.
result Type: boolean
Variable for the return value of waitFor(…). The return
value is true if the condition occurs within the specified
wait time.
Note: If no wait time is defined, waitFor(…) does not
supply a return value.

Example

A wait for a boolean input signal is required in the application. The appli-
cation is to be blocked for a maximum of 30 seconds. If the input signal is
not supplied within this time, a defined handling routine is then to be exe-
cuted.

public class ExampleApplication extends

RoboticsAPIApplication {
// ...
@Inject
private SwitchIOGroup inputs;
// ...

@Override
public void run() {
// ...
Input input = inputs.getInput ("Input");

BooleanIOCondition inputCondition =
new BooleanIOCondition(input, true);

boolean result = getObserverManager()

.waitFor(inputCondition, 30, TimeUnit.SECONDS);

if (!result) {
//do something
}
else {
//continue program
}
}

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 509/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.24 Recording and evaluating data

While an application is being executed, specific data, for example external

forces and torques, can be recorded for later evaluation. The DataRecor-
der class (package: com.kuka.roboticsAPI.sensorModel) is available for
programming the data recording.
The recorded data are saved in a file and stored on the robot controller in
the directory C:\KRC\Roboter\Log\DataRecorder.
The file name is defined with the DataRecorder object to be created. If an
error has occurred during recording, the file name begins with “FaultyDa-
taRecorder…”.
The file can be opened with a text editor or read into an Excel table.

16.24.1 Creating an object for data recording

Description

For data recording, an object of type DataRecorder must first be created

and parameterized. The following default parameters are set if the stand-
ard constructor is used for this purpose:
• The file name under which the recorded data are saved is created au-
tomatically. The name also contains an ID which is internally assigned
by the system: DataRecorderID.log
• No recording duration is defined. Data are recorded until the buffer
(currently 16 MB) is full or the maximum number of data sets (current-
ly 30,000) is reached.
• The recording rate, i.e. the minimum time between 2 recordings, is
1 ms.

Constructor syntax

The DataRecorder class has the following constructors:

DataRecorder() (standard constructor)
DataRecorder(String fileName, long timeout, TimeUnit timeU-
nit, int sampleRate)

Explanation of the syntax

Element Description
fileName File name (with extension) under which the recorded
data are saved
Example: "Recording_1.log"
timeout Recording duration

• -1: No recording duration is defined.

• ≥ 1
Default: -1
The time unit is defined with timeUnit.

510/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Element Description
timeUnit Time unit for the recording duration
Example: TimeUnit.SECONDS
The Enum TimeUnit is an integral part of the standard
Java library.
sampleRate Recording rate (unit: ms)

• ≥ 1
Default: 1

The DataRecorder class offers “set” methods which can be used to

adapt the parameter values, in particular when using the standard con-
structor.
• setFileName(…), setSampleRate(…), setTimeout(…, …)
In setTimeout(…, …), the first parameter defines the recording duration
and the second parameter defines the corresponding time unit.

Example 1

Data are to be recorded every 100 ms for a duration of 5 s and written to

the file Recording_1.log.

DataRecorder rec_1 = new DataRecorder("Recording_1.log", 5,

TimeUnit.SECONDS, 100);

Example 2

The DataRecorder object is generated using the standard constructor.

This only specifies that data are recorded every 1 ms for an indefinite du-
ration. The recorded data are to be written to the file Recording_2.log.
The file name is defined with the corresponding “set” method.

DataRecorder rec_2 = new DataRecorder();

rec_2.setFileName("Recording_2.log");

16.24.2 Specifying data to be recorded

Using dot operators and the corresponding “add” method, the data to be
recorded are added to the DataRecorder object created for this purpose.
The simultaneous recording of various data is possible.

Overview

The following “add” methods of the DataRecorder class are available:

Method Description
addInternalJointTorque(…) Return value type: DataRecorder
Recording of the measured axis torques of the robot which is
transferred as a parameter (type: Robot)
addExternalJointTorque(…) Return value type: DataRecorder
Recording of the external axis torques (adjusted to the model)
of the robot which is transferred as a parameter (type: robot)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 511/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Method Description
addCartesianForce(…) Return value type: DataRecorder
Recording of the Cartesian forces along the X, Y and Z axes
of the frame which is transferred as a parameter (unit: N).
A second frame can be transferred as a parameter in order to
define the orientation for the force measurement. If no sepa-
rate frame is specified for the orientation, null must be
transferred.
addCartesianTorque(…) Return value type: DataRecorder
Recording of the Cartesian torques along the X, Y and Z ax-
es of the frame transferred as a parameter (unit: Nm).
A second frame can be transferred as a parameter in order to
define the orientation for the torque measurement. If no sepa-
rate frame is specified for the orientation, null must be
transferred.
Parameters:

• AbstractFrame measureFrame
Frame attached to the robot flange, e.g. the TCP of a
tool. Defines the position of the measurement point.
• AbstractFrame orientationFrame
Defines the orientation of the measurement point.
Note: Both parameters must always be transferred together.
The orientation may be null.
addCommandedJointPosi- Return value type: DataRecorder
tion(…)
Recording of the axis-specific setpoint position of the robot
which is transferred as a parameter (type: robot). As a sec-
ond parameter, the unit in which the axis angles are recorded
must be transferred (Enum of type: AngleUnit).
addCurrentJointPosition(…) Return value type: DataRecorder
Recording of the axis-specific actual position of the robot
which is transferred as a parameter (type: Robot). As a sec-
ond parameter, the unit in which the axis angles are recorded
must be transferred (Enum of type: AngleUnit).
Parameters:

• Robot robot
• AngleUnit angleUnit
‒ AngleUnit.Degree: Axis angle in degrees
‒ AngleUnit.Radian: Axis angle in rad
addCommandedCartesianPo- Return value type: DataRecorder
sitionXYZ(…)
Recording of the Cartesian setpoint position (translational sec-
tion)
The measurement point and reference coordinate system rel-
ative to which the position is recorded are transferred as pa-
rameters.

512/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Method Description
addCurrentCartesianPosition- Return value type: DataRecorder
XYZ(…)
Recording of the Cartesian actual position (translational sec-
tion)
The measurement point and reference coordinate system rel-
ative to which the position is recorded are transferred as pa-
rameters.
Parameters:

• AbstractFrame measureFrame
Frame attached to the robot flange, e.g. the TCP of a
tool. Defines the position of the measurement point.
• AbstractFrame referenceFrame
Defines the reference coordinate system.
Note: Both parameters must always be transferred together.
None of the parameters may be null.

Example

For an LBR, the following data are to be recorded using a DataRecorder

object:
• Axis torques which are measured on the robot
• Force on the TCP of a gripper mounted on the robot with the orienta-
tion of a base frame

public class ExampleApplication extends

RoboticsAPIApplication {
@Inject
private LBR robot;
@Inject
private Tool gripper;
// ...

@Override
public void run() {
// ...
gripper.attachTo(robot.getFlange());
// ...
DataRecorder rec = new DataRecorder();
rec.addInternalJointTorque(robot);
rec.addCartesianForce(gripper.getFrame("TCP"),
getApplicationData().getFrame("/Base"));
// ...
}
}

16.24.3 Starting data recording

Data recording can be started independently of robot motion (possible at

any point in the application) or synchronously with robot motion by means
of a trigger.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 513/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Independent of robot motion

Before motion-independent recording is started, the DataRecorder object

must be activated via the enable() method. Recording is started via the
startRecording() method.
When recording has ended, the DataRecorder object is automatically de-
activated. If data are to be recorded again with the same DataRecorder
object, the DataRecorder must be re-activated.
It is not possible for more than one DataRecorder object to be activated
at any one time.

Synchronous via a trigger

A condition of type ICondition and an action must be formulated for a trig-

ger. When this condition is met, the trigger is fired, causing the action to
be carried out.
(>>> 16.21.1 "Programming triggers" Page 500)
This action starts the data recording. An object of type StartRecordingAc-
tion must be transferred for this purpose. When the object is created, the
DataRecorder object to be used for data recording must be specified.
Constructor syntax:
StartRecordingAction(DataRecorder recorder)
The ICondition object and the StartRecordingAction object are subse-
quently linked to a motion command with triggerWhen(…).

Example 1

Data recording is to start when the robot has carried out the approach
motion to a pre-position. The DataRecorder object is activated before the
pre-position is addressed so as to reduce the delay when starting the re-
cording.

public class ExampleApplication extends

RoboticsAPIApplication {
@Inject
private LBR robot;
// ...

@Override
public void run() {
// ...
DataRecorder rec = new DataRecorder();
// ...
rec.enable();
// ...
robot.move(lin(getApplicationData()
.getFrame("/PrePosition")));
rec.startRecording();
// ...
}
}

Example 2

Data recording is to begin 2 s after the start of a motion. A MotionPath-

Condition object is parameterized for this.

public class ExampleApplication extends

RoboticsAPIApplication {
@Inject

514/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
private LBR robot;
// ...

@Override
public void run() {
// ...
DataRecorder rec = new DataRecorder();
// ...
StartRecordingAction startAct =
new StartRecordingAction(rec);
MotionPathCondition startCond = new MotionPathCondition(
ReferenceType.START, 0.0, 2000);
robot.move(lin(getApplicationData()
.getFrame("/Destination"))
.triggerWhen(startCond, startAct));
// ...
}
}

16.24.4 Ending data recording

Data recording can be ended independent of robot motion (possible at

any point in the application), or synchronous with robot motion by means
of a trigger.
In addition, recording is automatically ended when the application ends or
when the recording duration specified in the DataRecorder object used
has been reached.

Independent of robot motion

Recording can be stopped at any time via the stopRecording() method.

Synchronous via a trigger

A condition of type ICondition and an action must be formulated for a trig-

ger. When this condition is met, the trigger is fired, causing the action to
be carried out.
(>>> 16.21.1 "Programming triggers" Page 500)
This action ends the data recording. An object of type StopRecordingAc-
tion must be transferred for this purpose. When the object is created, the
DataRecorder object to be used for data recording must be specified.
Constructor syntax:
StopRecordingAction(DataRecorder recorder)
The ICondition object and the StopRecordingAction object are linked to a
motion command with triggerWhen(…).

16.24.5 Requesting states from the DataRecorder object

Overview

The following methods of the DataRecorder class are available:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 515/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Method Description
isEnabled() Return value type: Boolean
The system checks whether the DataRecorder object is activated (=
true).
isRecording() Return value type: Boolean
The system checks whether data recording is running (= true).
isFileAvailable() Return value type: Boolean
The system checks whether the file with the recorded data is already
saved on the robot controller and whether it is available for evaluation
(= true).
awaitFileAvailable(…) Return value type: Boolean
Blocks the calling application until the defined blocking duration has
expired or until the file with the recorded data is saved on the robot
controller and is available for evaluation (= true).
The blocking statement returns the value “false” if the file is not avail-
able within the maximum blocking duration.
Syntax:

• awaitFileAvailable(long timeout, java.util.concur-

rent.TimeUnit timeUnit)
Parameters:

• timeout: maximum blocking duration

• timeUnit: time unit for the maximum blocking time

16.24.6 Example program for data recording

The following are to be recorded during an assembly process: the torques

acting externally on the axes of an LBR and the Cartesian forces acting
on the TCP of a gripper on the robot flange. The data are to be recorded
every 10 ms.
Recording is to begin synchronously with robot motion when the force act-
ing from any direction on the TCP of the gripper exceeds 20 N. When the
assembly process ends, recording is to end as well.
The file is then to be evaluated if it is available after a maximum of 5 s.

public class ExampleApplication extends

RoboticsAPIApplication {
@Inject
private LBR robot;
@Inject
private Tool gripper;
// ...

@Override
public void run() {
// ...
gripper.attachTo(robot.getFlange());
// ...
DataRecorder rec = new DataRecorder();

rec.setFileName("Recording.log");
rec.setSampleRate(10);

516/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
rec.addExternalJointTorque(robot);
rec.addCartesianForce(gripper.getFrame("/TCP"), null);

StartRecordingAction startAction =
new StartRecordingAction(rec);
ForceCondition startCondition = ForceCondition
.createSpatialForceCondition(
gripper.getFrame("/TCP"), 20.0);

robot.move(ptp(getApplicationData()
.getFrame("/StartPosition")));
robot.move(lin(getApplicationData()
.getFrame("/MountingPosition"))
.triggerWhen(startCondition, startAction));
robot.move(lin(getApplicationData()
.getFrame("/DonePosition")));

rec.stopRecording();

if (rec.awaitFileEnable(5, TimeUnit.SECONDS)){
// Evaluation of the file if available
}
// ...
}
}

16.25 Defining user keys

Description

Functions can be freely assigned to the 4 user keys on the smartPAD. For
this purpose, various user key bars can be defined in the source code of
the robot or background applications.
The user keys are assigned functions using the user key bar. One user
key on the bar must be assigned a function, but it is not necessary for all
of the keys to be assigned. In addition, graphical or text elements illustrat-
ing the function of each user key are located on the side panel of the
smartHMI screen next to the user keys.

Fig. 16-21: User keys on the smartPAD (example)

1 User keys 2 Bar with LED icons

All the user key bars defined in the running robot application or a running
background application are available to the operator. For example, one

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 517/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

user key bar can be used for controlling a gripper, and in another bar the
Programming

same keys can be used to switch status signals.

User key bars are available until the task which created them has ended.

Overview

The following steps are required in order to program a user key bar:
Step Description
1 Create a user key bar.
(>>> 16.25.1 "Creating a user key bar" Page 518)
2 Add user keys to the bar (at least one).
(>>> 16.25.2 "Adding user keys to the bar" Page 519)
3 Define the function which is to be executed if the user key
is actuated.
(>>> 16.25.3 "Defining the function of a user key"
Page 521)
4 Assign at least one graphical or text element to the area
along the left side panel of the smartHMI next to the user
key.
(>>> 16.25.4 "Labeling and graphical assignment of the
user key bar" Page 523)
5 For user keys which trigger functions associated with a risk:
Define the warning message to be displayed when the user
key is actuated. The message appears before the function
can be triggered.
(>>> 16.25.5 "Identifying safety-critical user keys"
Page 526)
6 Publish a user key bar.
(>>> 16.25.6 "Publishing a user key bar" Page 527)

16.25.1 Creating a user key bar

Description

The following methods are required in order to create a user key bar:
• getApplicationUI()
This method is used to access the interface to the smartHMI graphical
user interface from a robot application or a background application.
Return value type: ITaskUI
• createUserKeyBar(…)
This method is used to create the user key bar. It is part of the ITas-
kUI interface.

Syntax

IUserKeyBar keybar =
getApplicationUI().createUserKeyBar("name");

518/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Explanation of the syntax

Element Description
keybar Type: IUserKeyBar
Name of the user key bar created with createUserKey-
Bar(…)
name Type: String
Name under which the user key bar is displayed on the
smartHMI (>>> Fig. 6-14)
The number of characters which can be displayed is limi-
ted.

• A maximum of 12 to 15 characters is recommended.

Example

A user key bar for controlling a gripper is created.

IUserKeyBar gripperBar =
getApplicationUI().createUserKeyBar("Gripper");

16.25.2 Adding user keys to the bar

Description

A newly created user key bar does not have any user keys to start with.
The user keys to be used must be added to the bar.
The IUserKeyBar interface provides the following methods for this pur-
pose:
• addUserKey(…)
Adds a single user key to the bar.
• addDoubleUserKey(…)
Combines 2 neighboring user keys to a double key and adds this to
the bar. The corresponding areas on the side panel of the smartHMI
screen are also combined into a larger area.
When adding a user key to a bar, the user defines the function to be exe-
cuted when the user key is actuated (e.g. opening a gripper, changing a
parameter, etc.). Depending on the programming, both pressing and re-
leasing the user key can be interpreted as actuation and linked to a func-
tion.
A user key bar must have at least one user key. Each user key is as-
signed a unique number. This number is transferred when a user key is
added.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 519/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 16-22: Numbering of the user keys

1 Single keys 2 Double keys

Syntax

Adding a single key:

IUserKey key = keybar.addUserKey(slot, listener, ignoreEvents);
Adding a double key:
IUserKey doubleKey = keybar.addDoubleUserKey(slot, listener,
ignoreEvents);

Explanation of the syntax

Element Description
keybar Type: IUserKeyBar
Name of the user key bar to which a user key is added
key Type: IUserKey
Name of the single key added to the bar
doubleKey Type: IUserKey
Name of the double key added to the bar
slot Type: int
Number of the user key which is added.
Single keys:

• 0 … 3
Double keys:

• 0, 2
listener Type: IUserKeyListener
Name of the listener used to define the function to be
executed when the user key is actuated
(>>> 16.25.3 "Defining the function of a user key"
Page 521)

520/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Element Description
ignore Type: Boolean
Events
Defines whether there is a reaction if the user key is re-
actuated while the key function is being executed

• true: If the key is actuated while the function is being

executed, it has no effect.
• false: It is counted how many times the key is actu-
ated while the function is being executed. The func-
tion is repeated this many times.

Example

The user keys are assigned the following functions for controlling a grip-
per:
• The top user key is to be used to open the gripper, and the key below
it is to close the gripper.
• The two lower user keys are combined in a double key. This is to be
used to increase and decrease the velocity of the gripper.
• The functions for opening and closing the gripper are not to be called
again until the respective function has ended.

IUserKeyBar gripperBar =
getApplicationUI().createUserKeyBar("Gripper");

IUserKeyListener openGripperListener = ...;

IUserKeyListener closeGripperListener = ...;
IUserKeyListener gripperVelocityListener = ...;

IUserKey openKey = gripperBar.addUserKey(0,

openGripperListener, true);
IUserKey closeKey = gripperBar.addUserKey(1,
closeGripperListener, true);
IUserKey velocityKey = gripperBar.addDoubleUserKey(2,
gripperVelocityListener, false);

16.25.3 Defining the function of a user key

Description

In order to define which function is to be executed when a user key is ac-

tuated, a listener object of type IUserKeyListener must be created. The
onKeyEvent(…) method is automatically declared when the object is cre-
ated.
The listener method onKeyEvent(…) is called when the following events
occur:
• The user key is pressed.
• The user key is released.

Only one OnKeyEvent(…) can be carried out even if different listeners

are used. For example, if the user triggers the OnKeyEvent(…) of user
key 2 while the OnKeyEvent(…) of user key 1 is being executed, the
second OnKeyEvent(…) will not start until the first has been completed.

Syntax

IUserKeyListener listener = new IUserKeyListener() {

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 521/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

@Override
Programming

public void onKeyEvent(IUserKey key, UserKeyEvent

event) {
// Reaction to event
}
};

Explanation of the syntax

Element Description
listener Type: IUserKeyListener
Name of the listener object
Input parameters of the listener method onKeyEvent(…):
key Type: IUserKey
User key which has been actuated
The parameter can be used to directly access the user
key, for example to change the corresponding labelling or
graphical assignment. In addition, it is possible to deter-
mine which user key has been actuated, especially when
the same reaction is used for different user keys.
event Type: Enum of type UserKeyEvent
Event called by the listener method onKeyEvent(…)
Enum values for single keys:

• UserKeyEvent.KeyDown: Key has been pressed.

• UserKeyEvent.KeyUp: Key has been released.
Enum values for double keys:

• UserKeyEvent.FirstKeyDown: Of the two keys, the

upper one has been pressed.
• UserKeyEvent.SecondKeyDown: Of the two keys,
the lower one has been pressed.
• UserKeyEvent.FirstKeyUp: Of the two keys, the up-
per one has been released.
• UserKeyEvent.SecondKeyUp: Of the two keys, the
lower one has been released.

Example

The user key bar for controlling a gripper is expanded by a method which
can be used to adapt the velocity of the gripper. The two lower user keys
combined in a double key are used for this purpose.
The attribute velocity is declared for setting the velocity. The attribute
specifies the current velocity as a proportion of the maximum velocity
(range of values: 0.1 … 1.0). Pressing the upper user key increases the
value by 0.1 and pressing the lower user key decreases it by 0.1.

double velocity = 0.1;

// ...
IUserKeyBar gripperBar = ...;
// ...
IUsertKeyListener gripperVelocityListener = new IUserKeyListener(){
@Override
public void onKeyEvent(IUserKey key, IUserKeyEvent event){
if (event == UserKeyEvent.FirstKeyDown && velocity <= 0.9) {

522/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
velocity = velocity + 0.1;
}
else if (event == UserKeyEvent.SecondKeyDown && velocity >= 0.2) {
velocity = velocity – 0.1;
}
}
};
// ...
IUserKey velocityKey = gripperBar.addDoubleUserKey(2, gripperVelocityListener,
false);

16.25.4 Labeling and graphical assignment of the user key bar

Description

At least one graphical or text element must be assigned to the area along
the left side panel of the smartHMI next to the user key. LED icons of var-
ious colors and sizes are available as graphical elements. These elements
can be adapted during the runtime of the robot application or the back-
ground task.
In order to clearly position the individual elements, the area next to the
user key is divided into a grid with 3x3 spaces. This also applies for user
keys that have been grouped together as a double key. In the case of
double keys, the grid stretches over both fields.

Fig. 16-23: Division of the grid

1 Single keys 2 Double keys

One element can be set in each grid space. This grid space is defined by
the value of the enum UserKeyAlignment. If a new element is allocated to
a grid space which has already been assigned, the existing element is de-
leted.

UserKey alignment

Grid space
Value
no.
1 UserKeyAlignment.TopLeft
2 UserKeyAlignment.TopMiddle
3 UserKeyAlignment.TopRight
4 UserKeyAlignment.MiddleLeft
5 UserKeyAlignment.Middle
6 UserKeyAlignment.MiddleRight
7 UserKeyAlignment.BottomLeft
8 UserKeyAlignment.BottomMiddle

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 523/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Grid space
Value
no.
9 UserKeyAlignment.BottomRight

16.25.4.1 Assigning a text element

Description

Each grid space can be assigned a text element. The setText(…) method
is used for this purpose. The method belongs to the IUserKey interface.

Syntax

key.setText(position, "text");

Explanation of the syntax

Element Description
key Type: IUserKey
User key to which a text element is assigned
position Type: Enum of type UserKeyAlignment
Position of the element (grid space)
(>>> "UserKey alignment" Page 523)
text Type: String
Text to be displayed
Often, a text length of 2 or more characters will exceed
the size of the grid space. The text display area is then
expanded. However, it is only practical to use a limited
number of characters. The possible number of characters
depends on the text elements of the neighboring grid
spaces and the characters used.

Example

The user key bar for controlling a gripper is to be expanded. A suitable la-
bel should be displayed continuously next to each of the user keys.
• Label for the user keys for opening and closing the gripper: OPEN
and CLOSE
• Label for the user keys for increasing and decreasing the gripper ve-
locity: plus sign and minus sign
In addition, the current velocity is to be displayed and automatically
updated each time a change is made.

double velocity = 0.1;

// ...
IUserKeyBar gripperBar = ...;
// ...
IUserKeyListener gripperVelocityListener = new IUserKeyListener() {
@Override
public void onKeyEvent(IUserKey key, IUserKeyEvent event) {
if (event == UserKeyEvent.FirstKeyDown && velocity <= 0.9) {
velocity = velocity + 0.1;
}
else if (event == UserKeyEvent.SecondKeyDown && velocity >= 0.2) {
velocity = velocity - 0.1;

524/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
}
// The following line formats the velocity display
// The first three characters are displayed
String value = String.valueOf(velocity).substring(0, 3);
key.setText(UserKeyAlignment.Middle, value);
}
}
};

IUserKey openKey = ...;

openKey.setText(UserKeyAlignment.TopLeft, "OPEN");

IUserKey closeKey = ...;

closeKey.setText(UserKeyAlignment.TopLeft, "CLOSE");

IUserKey velocityKey = ...;

velocityKey.setText(UserKeyAlignment.TopMiddle, "+");
velocitykey.setText(UserKeyAlignment.Middle, Double.toString(velocity));
velocityKey.setText(UserKeyAlignment.BottomMiddle, "-");

16.25.4.2 Assigning an LED icon

Description

Each grid space can be assigned an LED icon. The setLED(…) method is
used for this purpose. The method belongs to the IUserKey interface.

Syntax

key.setLED(position, led, size);

Explanation of the syntax

Element Description
key Type: IUserKey
User key to which a graphical element is assigned
position Type: Enum of type UserKeyAlignment
Position of the element (grid space)
(>>> "UserKey alignment" Page 523)
led Type: Enum of type UserKeyLED
Color of the LED icon

• UserKeyLED.Grey: gray
• UserKeyLED.Green: green
• UserKeyLED.Yellow: yellow
• UserKeyLED.Red: red
size Type: Enum of type UserKeyLEDSize
Size of the LED icon

• UserKeyLEDSize.Small: small
• UserKeyLEDSize.Normal: large

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 525/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Example

The user key bar for controlling a gripper is to be expanded. The user
keys for opening and closing the gripper should each be assigned a small
LED icon.
As long as the gripper is opening or closing, the LED icons should be dis-
played in green. If the gripper is stationary, the LED icons should be dis-
played in gray.

IUserKeyBar gripperBar = getApplicationUI().createUserKeyBar("Gripper");

IUserKeyListener openGripperListener = new IUserKeyListener(){

@Override
public void onKeyEvent(IUserKey key, UserKeyEvent event) {
key.setLED(UserKeyAlignment.BottomMiddle, UserKeyLED.Green,
UserKeyLEDSize.Small);
openGripper(); // Method for opening the gripper
key.setLED(UserKeyAlignment.BottomMiddle, UserKeyLED.Grey,
UserKeyLEDSize.Small);
}
};

IUserKeyListener closeGripperListener = new IUserKeyListener(){

@Override
public void onKeyEvent(IUserKey key, UserKeyEvent event) {
key.setLED(UserKeyAlignment.BottomMiddle, UserKeyLED.Green,
UserKeyLEDSize.Small);
closeGripper(); // Method for closing the gripper
key.setLED(UserKeyAlignment.BottomMiddle, UserKeyLED.Grey,
UserKeyLEDSize.Small);
}
};

IUserKeyListener gripperVelocityListener = ...;

// ...

IUserKey openKey = ...;

openKey.setText...;
openKey.setLED(UserKeyAlignment.BottomMiddle, UserKeyLED.Grey,
UserKeyLEDSize.Small);

IUserKey closeKey = ...;

closeKey.setText...;
closeKey.setLED(UserKeyAlignment.BottomMiddle, UserKeyLED.Grey,
UserKeyLEDSize.Small);

IUserKey velocityKey = ...;

16.25.5 Identifying safety-critical user keys

Description

User keys can trigger functions that are associated with a risk. In order to
prevent damage caused by the unintentional actuation of such user keys,
a warning message can be added identifying them as safety-critical. The
setCriticalText(…) method is used for this purpose. The method belongs to
the IUserKey interface.
If the operator actuates a user key designated as safety-critical, the mes-
sage defined with setCriticalText(…) is displayed on the smartHMI in a

526/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

window with the name Critical operation. The user key is then deactiva-

Programming
ted for approx. 5 s. Once this time has elapsed, the operator can trigger
the desired function by actuating the user key again within 5 s.
If the user key is not actuated within this time or if an area outside of the
Critical operation window is touched, the window is closed and the user
key is reset to its previous state.

Syntax

key.setCriticalText("text");

Explanation of the syntax

Element Description
key Type: IUserKey
User key which is provided with a warning message
text Type: String
Message text displayed when the user key is actuated

Example

The user key bar for controlling a gripper is to be expanded. If the user
key for opening the gripper is actuated, a warning message should ap-
pear. The operator is requested to ensure that no damage can result from
workpieces falling out when the gripper is opened.

IUserKeyBar gripperBar = getApplicationUI().createUserKeyBar("Gripper");

// ...
IUserKey openKey = ...;
openKey.setText...;
openKey.setLED...;

openKey.setCriticalText("Gripper opens when key is actuated again. Ensure

that no damage can result from workpieces falling out!");

16.25.6 Publishing a user key bar

Description

Once a user key bar has been equipped with all the necessary user keys
and functionalities, it must be published with the publish() method. Only
then can the operator access it on the smartPAD.
Once a user key bar has been published, further user keys may not be
added later in the program sequence. In other words, it is not possible to
add an unassigned user key and assign a function to it at a later time. It
is, however, possible to change the labeling or graphical element dis-
played next to the user key on the smartHMI at a later time.

Syntax

keybar.publish();

Explanation of the syntax

Element Description
keybar Type: IUserKeyBar
Name of the user key bar created with createUserKey-
Bar(…).

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 527/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Example

The user key bar created for controlling a gripper is published.

IUserKeyBar gripperBar = getApplicationUI().createUserKeyBar("Gripper");

// ...
gripperBar.publish();

16.26 Message programming

16.26.1 Programming user messages

Description

It is possible to program notification, warning and error messages which

are displayed on the smartHMI and written to the LOG file of the applica-
tion while the application is running. In addition, it is possible to program
messages which are not displayed on the smartHMI but are only written
to the LOG file.
In order to program a user message, an object of the ITaskLogger class is
integrated by means of dependency injection. At this object, the corre-
sponding methods can be called in order to generate a message display
with the appropriate LOG level.
Dependency injection makes it possible for messages to be displayed on
the smartHMI from all classes of an application, including those which are
not a task.
It is advisable to only display messages on the smartHMI which are ab-
solutely essential. Over-intensive use of the message display (perma-
nently > 10 messages/s) can have a negative effect on the runtime of
the application and the operation of the smartHMI.

For message output, it is advisable to use only the commands descri-

bed here and not other logging functionalities, e.g. the Java commands
System.out.println(…) or System.err.println(…). If these commands are
used, it is not possible to guarantee that the message will be displayed
on the smartHMI.

Syntax

Integrating a logger object:

@Inject
private ITaskLogger logger;
Notification message:
logger.info("Message");
Warning message:
logger.warn("Message");
Error message:
logger.error("Message");
Message that is only written to the LOG file:
logger.fine("Message");

528/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Explanation of the syntax

Element Description
logger Type: ITaskLogger
Name of the logger object, as it is to be used in the ap-
plication
Message Type: String
Message which is to be displayed on the smartHMI
and/or written to the LOG file

Example

Once the robot has reached an end point, a notification message is to be

displayed. If the motion ended with a collision, a warning notification is
displayed instead.

public class ExampleApplication extends

RoboticsAPIApplication {
@Inject
private ITaskLogger logger;
@Inject
private IApplicationData data;
@Inject
private LBR robot;

private ForceCondition collision

@Override
public void initialize() {
// initialize your application here
collision = ForceCondition
.createSpatialForceCondition(robot.getFlange(), 15.0);
}

@Override
public void run() {
// ...
IMotionContainer motion = robot.move(lin(getFrame("/P20"))
.breakWhen(collision));

if (motion.getFiredBreakConditionInfo() == null){
logger.info("End point reached.");
}
else {
logger.warn("Motion canceled after collision!");
}
// ...
}
}

16.26.2 Programming user dialogs

Description

User dialogs can be programmed in an application. These user dialogs

are displayed in a dialog window on the smartHMI while the application is
being run and require user action.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 529/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Various dialog types can be programmed via the method displayModalDia-

Programming

log(…). The following icons are displayed on the smartHMI according to

type:
Icon Type
INFORMATION
Dialog with information of which the user must take note
QUESTION
Dialog with a question which the user must answer
WARNING
Dialog with a warning of which the user must take note
ERROR
Dialog with an error message of which the user must take
note
The user answers by selecting a button that can be labeled by the pro-
grammer. Up to 12 buttons can be defined.
The application from which the dialog was called is stopped until the user
reacts. How program execution continues can be made dependent on
which button the user selects. The method displayModalDialog(…) returns
the index of the button which the user selects on the smartHMI. The index
begins at “0” (= index of the first button).

Syntax

getApplicationUI().displayModalDialog(Dialog type, “Dialog

text”, “Button_1”<, … “Button_12”>)

Explanation of the syntax

Element Description
Dialog type Type: Enum of type ApplicationDialogType

• INFORMATION: the dialog with the information icon

is displayed.
• QUESTION: the dialog with the question icon is dis-
played.
• WARNING: the dialog with the warning icon is dis-
played.
• ERROR: the dialog with the error icon is displayed.
Dialog text Type: String
Text which is displayed in the dialog window on the
smartHMI
Button_1 … Type: String
Button_12
Labeling of buttons 1 … 12 (proceeding from left to right
on the smartHMI)

Example

The following user dialog of type QUESTION is to be displayed on the

smartHMI:

530/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Fig. 16-24: Example of a user dialog

int direction = getApplicationUI().displayModalDialog(

ApplicationDialogType.QUESTION,
"Where do you want to go to?",
"To the left", "To the right", "To HOME-Position");

switch (direction) {
case 0:
robot.move(ptp(getApplicationData().getFrame("/Left")));
break;
case 1:
robot.move(ptp(getApplicationData().getFrame("/Right")));
break;
case 2:
robot.move(ptpHome());
break;
}

16.27 Program execution control

16.27.1 Pausing an application

Description

An application can be paused with the halt() method.

The halt() method pauses the motion currently being executed, and the
application state on the smartHMI switches to Motion paused.
halt() causes a blocking stop of the calling thread. If further threads are
running at the same time, these will continue to be executed. The applica-
tion execution is only stopped if halt() is called in the application thread. It
is therefore advisable not to call halt() in handling routines for path-related
switching actions or in handling routines for monitoring processes. Instead,
it is advisable to use the pause() method in these handling routines.
(>>> 16.27.3 "Pausing motion execution" Page 532)
The motion and paused thread may only be resumed via the Start key on
the smartPAD. Pressing the Start key causes the paused motion to re-
sume. The paused thread is resumed with the instruction following halt()
in the source code.

Syntax

getApplicationControl().halt();

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 531/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.27.2 Terminating an application

Description

Using the stopAllInstances() method, it is possible to terminate an

application from any section of the program code. If the application has
been terminated, it can be restarted and the program code will then be
executed from the beginning.
The method should be executed in a background task, e.g. as a reaction
to an input signal.
For example, the method is required for programming retraction strategies.
In these instances, it may be necessary to terminate the application fol-
lowing an EMERGENCY STOP and restart it from the beginning.

Syntax

getTaskManager().getTask(RobotApplication.class).stopAllIn-
stances();

Explanation of the syntax

Element Description
RobotAppli- Name of the robot application
cation

16.27.3 Pausing motion execution

Description

Motion execution can be paused with the pause() method.

The behavior corresponds to pausing the application via the smartPAD.
The pause() method pauses the motion currently being executed, and the
application state on the smartHMI switches to Motion paused.
pause() does not cause a blocking wait. The application continues to be
executed until a synchronous motion command is reached.
Motion execution may only be resumed via the Start key on the smart-
PAD.

Syntax

getApplicationControl().pause();

16.27.4 Canceling a motion command

Description

Asynchronously executed motion commands can be canceled using the

cancel() method while the motion is in progress.
Canceling an active motion modifies the path of the subsequent motions
compared with the path without cancellation.

Example

A motion is executed from P1 to P4. P2 and P3 are approximated with an

absolute approximation distance of 20 mm.

532/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
IMotionContainer m1 =
robot.moveAsync(lin(getApplicationData().getFrame("/P1")));
IMotionContainer m2 =
robot.moveAsync(lin(getApplicationData().getFrame("/P2"))
.setBlendingCart(20));
IMotionContainer m3 =
robot.moveAsync(lin(getApplicationData().getFrame("/P3"))
.setBlendingCart(20));
IMotionContainer m4 =
robot.moveAsync(lin(getApplicationData().getFrame("/P4")));

Fig. 16-25: Original path

During the motion, the linear motion command to point P3 is canceled

with cancel().

IMotionContainer m1 =
robot.moveAsync(lin(getApplicationData().getFrame("/P1")));
IMotionContainer m2 =
robot.moveAsync(lin(getApplicationData().getFrame("/P2"))
.setBlendingCart(20));
IMotionContainer m3 =
robot.moveAsync(lin(getApplicationData().getFrame("/P3"))
.setBlendingCart(20));
IMotionContainer m4 =
robot.moveAsync(lin(getApplicationData().getFrame("/P4")));
m2.await();
ThreadUtil.milliSleep(500);
m3.cancel();
m4.await();

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 533/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 16-26: cancel() during an active motion

16.27.5 FOR loop

Description

The FOR loop, also called counting loop, repeats a statement block as
long as a defined condition is met.
A counter is defined, which is increased or decreased by a constant value
with each execution of the loop. At the beginning of a loop execution, the
system checks if a defined condition is met. This condition is generally for-
mulated by comparing the counter with a limit value. If the condition is no
longer met, the loop is no longer executed and the program is continued
after the loop.
The FOR loop is generally used if it is known how often a loop must be
executed.
FOR loops can be nested.
(>>> 16.27.10 "Examples of nested loops" Page 542)

Syntax

for (int Counter = Start value; Condition; Counting statement){

Statement_1;
<...
Statement_n;
}

Explanation of the syntax

Element Description
Counter Counter for the number of loops executed
The counter is assigned a start value. With each execu-
tion of the loop, the counter is increased or decreased by
a constant value.
Start value Start value of the counter
Condition Condition for the loop execution
The counter is generally compared with a limit value. The
result of the comparison is always of type Boolean. The
loop is ended as soon as the comparison returns FALSE,
meaning that the condition is no longer met.

534/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
Element Description
Counting The counting statement determines the amount by which
statement the counter is changed with each execution of the loop.
The increment and counting direction can be specified in
different ways.
Examples:

• Start value ++|--: With each execution of the loop,

the start value is increased or decreased by a value
of 1.
• Start value +|- Increment: With each execution of the
loop, the start value is increased or decreased by the
specified increment.

Example

for (int i = 0; i < 10; i++) {

logger.info("Variable i =" + i);
}

The value of the variable i is increased by 1 with every cycle. The

current value of i is displayed on the smartHMI with every cycle. The
loop is executed a total of 10 times. The values of 0 to 9 are displayed in
the process. For output purposes, a logger object has been integrated
with dependency injection.

16.27.6 WHILE loop

Description

The WHILE loop repeats a statement block for as long as a certain condi-
tion is fulfilled. It is also called a rejecting loop because the condition is
checked before every loop execution.
If the condition is no longer met, the statement block of the loop is no lon-
ger executed and the program is resumed after the loop. If the condition
is not already fulfilled before the first execution, the statement block is not
executed at all.
The WHILE loop is generally used if it is unknown how often a loop must
be executed, e.g. because the repetition condition is calculated or is a
specific signal.
WHILE loops can be nested.
(>>> 16.27.10 "Examples of nested loops" Page 542)

Syntax

while (Repetition condition){

Statement_1;
<...
Statement_n;
}

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 535/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Explanation of the syntax

Element Description
Repetition Type: Boolean
condition
Possible:

• Variable of type Boolean

• Logic operation, e.g. a comparison, with a result of
type Boolean

Example 1

while (input1 == true) {

logger.info("Input 1 is TRUE.");
}
logger.info("Input 1 is FALSE.");

Before the loop is executed the system checks whether an input signal is
set. As long as this is the case, the loop will be executed again and again
and the smartHMI will display the input as TRUE. If the input signal has
been reset, the loop will not be executed (any longer) and the input will
be displayed as FALSE. For output purposes, a logger object has been in-
tegrated with dependency injection.

Example 2

int w = 0;
Random num = new Random();
while (w <= 21) {
w = w + (num.nextInt(6) + 1);
}

With every loop execution, the value of the variable w is increased by a

random number between 1 and 6. As long as the sum of all random num-
bers is less than 21, the loop will be executed. It is not possible to predict
the exact number of cycles. It is possible that the loop is ended after 4
cycles (3 x 6 and 1 x 3) or only after 21 cycles (21 x 1).

16.27.7 DO WHILE loop

Description

The DO WHILE loop repeats a statement block until a certain condition is

fulfilled. It is also called a post-test loop because the condition is only
checked after every loop execution.
The statement block is executed at least once. When the condition is met,
the loop is terminated and the program is resumed.
The DO WHILE loop is generally used if a loop must be executed at least
once, but it is unknown how often in total, e.g. because the break condi-
tion is being calculated or is a specific signal.
DO WHILE loops can be nested.
(>>> 16.27.10 "Examples of nested loops" Page 542)

Syntax

do {
Statement_1;

536/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

<...

Programming
Statement_n;
} while (Break condition);

Explanation of the syntax

Element Description
Break condi- Type: Boolean
tion
Possible:

• Variable of type Boolean

• Logic operation, e.g. a comparison, with a result of
type Boolean

Example

int num;
do {
num = (int) (Math.random() * 6 + 1);
} while (num != 6);

Random numbers between 1 and 6 are generated until the “dice” shows a
6. The dice must be thrown at least once.

16.27.8 IF ELSE branch

Description

The IF ELSE branch is also called a conditional branch. Depending on a

condition, either the first statement block (IF block) or the second state-
ment block (ELSE block) is executed.
The ELSE block is executed if the IF condition is not met. The ELSE
block may be omitted. If the IF condition is not met, then no further state-
ments are executed.
It is possible to check further conditions and to link them to statements af-
ter the IF block using else if. As soon as one of these conditions is
met and the corresponding statements are executed, the subsequent
branches are no longer checked.
Several IF statements can be nested in each other.

Syntax

if (Condition_1){
Statement_1;
<...
Statement_n;
}
<else if (Condition_2){
Statement_1;
<...
Statement_n;
}>
<else {
Statement_1;

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 537/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

<...
Programming

Statement_n;
}>

Explanation of the syntax

Element Description
Condition Type: Boolean
Possible:

• Variable of type Boolean

• Logic operation, e.g. a comparison, with a result of
type Boolean

Example 1

IF branch without else

int a;
int b;

if (a == 17) {
b = 1;
}

If variable a has the value 17, variable b is assigned the value 1.

Example 2

IF branch within a FOR loop without else

for (int a = 1; a <= 10; a++) {

if (a == 3) {
a = a + 5;
}
logger.info("Variable a =" + a);
}

The loop is executed 5 times. If variable a has the value 3, the value of a
is increased by 5 once only.
The values 1, 2, 8, 9 and 10 are displayed on the smartHMI. For output
purposes, a logger object has been integrated with dependency injection.

Example 3

IF ELSE branch with else if

double velAct = 0.0;

double velDesired = 130.0;

// ...

if (velAct < velDesired) {

accelerating();
} else if (velAct > velDesired) {
braking();
} else {
testrun();
}

538/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

In a program, a test run for a vehicle is to be carried out. This test run is

Programming
only meaningful at a specific command velocity.
The IF statement checks whether the actual velocity velAct is lower than
the command velocity velDesired. If this is the case, the vehicle accel-
erates. If this is not the case, it continues with else if.
The IF ELSE statement checks whether the actual velocity velAct is
higher than the command velocity velDesired. If this is the case, the
vehicle is braked. If this is not the case, the ELSE block is executed with
the test run.

16.27.9 SWITCH branch

Description

The SWITCH branch is also called a multiple branch. Generally, a

SWITCH branch corresponds to a multiply nested IF branch.
In a SWITCH block, different CASE blocks can be executed which are
designated by CASE labels (jump labels). Depending on the result of an
expression, the corresponding CASE block is selected and executed. The
program jumps to the CASE label and is resumed at this point.
The keyword break at the end of a CASE block means that the SWITCH
block is left. If no break follows at the end of an instruction block, all sub-
sequent instructions (not only instructions with CASE labels) are executed
until either a BREAK label is reached or all instructions have been execu-
ted.
A DEFAULT block can optionally be programmed. If no condition is met
for jumping to a CASE label, the DEFAULT block is executed.

Syntax

switch (expression){
case Constant_1:
Statement_1;
<...
Statement_n;>
< break;>
<...
case Constant_n:
Statement_1;>
<...
Statement_n;>
< break;>
< default:
Statement_1;>
<...
Statement_n;>
< break;>
}

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 539/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Explanation of the syntax

Element Description
Expression Type: int, byte, short, char, enum
Constant Type: int, byte, short, char, enum
The data type of the constant must match the data type
of the expression.
Note: Constants of type char must be specified with ' ,
e.g. case 'a'

Example 1

SWITCH branch with BREAK and DEFAULT instruction:

int a, b;
// ...
switch (a) {
case 1:
b = 10;
break;
case 2:
b = 20;
break;
case 3:
b = 30;
break;
default:
b = 40;
break;
}
// next command

If variable a has the value 1, the program jumps to the label case 1.
The variable b is assigned the value 10. The BREAK instruction causes
the SWITCH block to be left. Program execution is resumed with the next
command after the closing bracket of the SWITCH block.
If variable a has the value 2 at the start, variable b is assigned the value
20. If a has the value 3 at the start, b is assigned the value 30.
The DEFAULT statement is optional. It is nonetheless advisable for it al-
ways to be set. If variable a has a value at the start that is not covered
by a CASE statement (e.g. 0 or 5), the instructions in the DEFAULT block
are executed. In this example, this means that variable b is assigned the
value 40.

Example 2

The keyword break may be omitted in a CASE statement. Cases in

which this is practically applied include the following:
• The identical statement is to be executed in multiple CASE instances
(e.g. a = 1, 2 or 3). See SWITCH statement with fall-through (var-
iant 1).
• For a CASE instance, specific statements and additional statements
applicable to another instance are to be executed. See SWITCH state-
ment with fall-through (variant 2).
SWITCH statement with fall-through (variant 1):

540/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
int a, b;
// ...
switch (a) {
case 1:
// fall-through
case 2:
// fall-through
case 3:
b = 20;
break;
case 4:
b = 30;
break;
default:
b = 40;
break;
}
// next command

In variant 1, the statements to be executed are only written to the last of

the grouped CASE blocks. Omission of the BREAK statement in case 1
and case 2 makes the assignment of variable b in these CASE blocks
obsolete too, as variable b will be overwritten in case 3 anyway. To
make it evident that the BREAK statement has not been forgotten but in-
tentionally omitted, fall-through is entered as a comment.
SWITCH statement with fall-through (variant 2):

int a, b, c;
// ...
switch (a) {
case 1:
b = 10;
// fall-through
case 2:
c = 20;
break;
case 3:
b = 30;
break;
case 4:
c = 30;
break;
default:
b = 40;
c = 40;
break;
}
// next command

The behavior in variant 2 is as follows:

• If case 1 occurs, variable b is set to 10 and additionally variable c to
20.
In case 1 fall-through is entered as a comment to indicate that fur-
ther statements are to be executed, in this case those of case 2.
• If case 2 occurs, variable c is set to 20. Variable b is not changed.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 541/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

16.27.10 Examples of nested loops

The outer loop is first executed until the inner loop is reached. The inner
loop is then executed completely. The outer loop is then executed until
the end, and the system checks whether the outer loop must be executed
again. If this is the case, the inner loop must also be executed again.
There is no limit on the nesting depth of loops. The inner loops are al-
ways executed as often as the outer loop.

FOR in FOR loop

for (int i = 1; i < 4; i++) {

logger.info(i + ".Cycle begins");

for (int k = 10; k > 0; k--) {

logger.info("..." + k);
}
}

The outer loop determines that the inner loop is executed 3 times. The
counter of the outer loop starts with the value i = 1.
Once the smartHMI has displayed the start of the 1st cycle, the counter of
the inner loop starts with the value k = 10. The value of variable k is
decreased by 1 with every cycle. The current value of k is displayed on
the smartHMI with every cycle. If variable k has the value 1, the inner
loop will be executed for the last time.
Then the outer loop is ended and the value of variable i is increased by
1. The 2nd cycle begins. For output purposes, a logger object has been
integrated with dependency injection.

FOR in WHILE loop

int sum = 0;
int round = 1;
int diceRoll = 0;
Random num = new Random();

while (sum < 21) {

round++;

for (int i = 1; i <= 3; i++) {

diceRoll = (num.nextInt(6) + 1);
if (diceRoll % 2 == 0) {
sum += diceRoll;
}
}
}

The following rules apply in a dice game:

• The total sum of all rolls must be at least 21 (check with WHILE loop).
• The dice are rolled 3 times in each round (FOR loop).
• Only even numbers (2, 4 and 6) are counted (IF check with modulo).

542/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
16.28 Continuing a paused application in Automatic mode (recovery)

Description

If a paused application is to be continued in Automatic mode, the higher-

level controller must be able to determine whether the robot is still situ-
ated on its programmed path. If the robot is no longer situated on the
path, e.g. following a non-path-maintaining stop or because it was jogged
while the program was paused, there must be a suitable strategy for auto-
matically repositioning the robot.
This return strategy may only be applied if it can be ensured that there is
no risk of a collision while the robot is returning to the path. If this is not
ensured, the robot must be manually repositioned by the user.
RoboticsAPI provides the IRecovery interface for automatic repositioning.
It is possible to access the interface from robot and background applica-
tions:
• IRecovery getRecovery()

Overview

The IRecovery interface provides methods for requesting information

about whether robots must be repositioned in order to resume a paused
application and which return strategy is applied.
Method Description
isRecoveryRequired() Return value type: Boolean
Checks whether one or more robots used in the application
must be repositioned in a paused application.
true: At least one robot must be repositioned for the applica-
tion to be resumed.
false: The application can be resumed immediately.
isRecoveryRequired(…) Return value type: Boolean
Checks whether a specific robot must be repositioned in a
paused application. The robot is transferred as a parameter
(type: Robot).
true: The robot must be repositioned for the application to be
resumed.
false: The application can be resumed immediately.
getRecoveryStrategy(…) Return value type: RecoveryStrategy
Requests the strategy being applied in order to return a spe-
cific robot to the path. The robot is transferred as a
parameter (type: Robot).

• PTPRecoveryStrategy: The robot is repositioned with a

PTP motion.
The robot is moved at 20% of the maximum possible axis
velocity and the effective program override.
No further strategies are available at this time.
The method returns null in the following cases:

• No return strategy is required or available.

• The application is not paused.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 543/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

PTPRecovery
Strategy

The PTPRecoveryStrategy class provides “get” methods which are used

to request the characteristics of the PTP motion. With these methods, it is
possible to evaluate whether the return strategy may be carried out in Au-
tomatic mode.
Method Description
getStartPosition() Return value type: JointPosition
Requests the start position of the PTP motion (= axis position
from which the robot can be repositioned)
The start position is the currently commanded setpoint posi-
tion of the robot and not the currently measured actual posi-
tion.
getMotion() Return value type: PTP
Requests the PTP motion carried out on execution of the
strategy
Further information can be requested from the returned mo-
tion object:

• getDestination(): Target position of the PTP motion (= axis

position at which the robot left the path)
• getMode(): Controller mode of the motion which was inter-
rupted

External controller

The robot controller must inform the higher-level controller whether the ro-
bot must be repositioned. The higher-level controller may only allow the
return strategy to be carried out if this can be done without risk. Other-
wise, the robot may only be manually repositioned.
The following system signals are available:
• Output AutExt_AppReadyToStart
With this output, the robot controller communicates to the higher-level
controller whether or not the application may be resumed.
‒ If isRecoveryRequired(…) supplies the value false (= no reposi-
tioning required), the output can be set to TRUE.
‒ If getRecoveryStrategy(…) supplies null (= no return strategy
available), the output must be set to FALSE.
‒ If the evaluation of the return strategy shows that it can be execu-
ted in Automatic mode, the output can be set to TRUE.
If this is not the case, the output must be set to FALSE.
• Input App_Start
The higher-level controller informs the robot controller via a rising
edge that the application should resume. (Precondition: AutExt_Ap-
pReadyToStart is TRUE)
The higher-level controller must send the start signal App_Start twice:
1. Start signal for repositioning
2. Start signal for resuming the application

544/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
16.29 Error treatment

16.29.1 Handling of failed motion commands

Motion commands that are communicated to the robot controller can fail
for various reasons, e.g.:
• End point lies outside of a workspace
• End point cannot be reached with the given axis configuration
• The frame used is not present in the application data
As standard, a failed motion command results in termination of the appli-
cation. Handling routines can be defined in order to prevent the applica-
tion from terminating in case of error.
The following handling options are available depending on the error:
• Failed synchronous motion commands are handled using a try-catch
block
• Failed asynchronous motion commands are handled using an event
handler

16.29.2 Handling of failed synchronous motion commands

Description

Synchronously executed motion commands (.move(…);) are sent in

steps to the real-time controller and executed. The further execution of the
program is interrupted until the motion has been executed. Only then is
the next command sent.
Using a try-catch block, predictable runtime errors or exceptions can be
executed in the program sequence without the application being aborted.
A defined method for error treatment is triggered within a try-catch block.
When the keyword try is called, an attempt is made to execute the listed
command. If an error occurs during execution, the corresponding handling
routine is started in the catch block.

Syntax

try {
// Code in which a runtime error can occur when executed
}
catch (Exception e) {
// Code for treating the runtime error
}
< finally {
// Final treatment (optional)
}>

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 545/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Explanation of the syntax

Element Description
try {…} The try block contains a code which can result in a run-
time error.
If an error occurs, the execution of the try block is termi-
nated and the catch block is executed.
catch (…) The catch block contains the code for treating the run-
{…} time error.
The catch block will only be executed if an error occurs
in the try block.
Exception The error data type (here: Exception) can be used to de-
e fine the error type to be handled in the catch block. The
error type Exception is the superclass of most error da-
ta types.
However, it is also possible to focus on more specific er-
rors. Information about errors which have occurred can
be requested using the parameter e.
In particular, the error data type CommandInvalidExcep-
tion (package: com.kuka.roboticsAPI.executionModel) is
important for handling failed motion commands. It occurs,
for example, when the end point of the motion cannot be
reached.
finally The finally block is optional.
{…}
Here it is possible to specify a final treatment to be exe-
cuted in all cases, irrespective of whether or not an error
occurs in the try block.

Example

A robot executes a motion under impedance control with very low stiff-
ness. For this reason, it is not guaranteed to reach the end position. It is
then to move relatively by 50 cm in the positive Z direction of the flange
coordinate system. If the robot is in an unfavorable position following the
motion under impedance control, the linear motion cannot be executed
and a runtime error will occur. In order to prevent the application from
aborting in this case, the critical linear motion is programmed in a try-
catch block. If the motion planning fails, the robot should be moved to an
auxiliary point before the application is resumed.

public class ErrorHandler extends RoboticsAPIApplication {

@Inject
private ITaskLogger logger;
@Inject
private LBR robot;
// ...

@Override
public void run() {
// ...
CartesianImpedanceControlMode softMode =
new CartesianImpedanceControlMode();

softMode.parametrize(CartDOF.ALL).setStiffness(10.0);
robot.move(ptp(getFrame("/Start"))
.setMode(softMode).setJointVelocityRel(0.3));

546/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
try {
logger.info("1: Try to execute linear motion");
robot.move(linRel(0.0, 0.0, 500.0)
.setJointVelocityRel(0.5));
}

catch (CommandInvalidException e) {
logger.info("2: Motion not executable");
robot.move(ptp(getFrame("/AuxiliaryPoint"))
.setJointVelocityRel(0.5));
}

finally {
logger.info("3: Commands in finally block are executed");
}

logger.info("4: Application continues here.");

// ...
}

16.29.3 Handling of failed asynchronous motion commands

Description

In the case of asynchronously executed motion commands (.moveA-

sync(…);), the next program line is executed directly after the motion
command is sent.
An event handler is used in order to react to a failed asynchronous
motion command.
This event handler is an object of type IErrorHandler and defines the
method handleError(…). The transfer of further motion commands to the
real-time controller is blocked during execution of the method handleEr-
ror(…). The application remains at a standstill.
The handling routine is defined with handleError(…). Information on the
failed motion command can be accessed via the input parameters of the
method. The method returns a parameter of type ErrorHandlingAction.
The final reaction to the error is selected via this parameter.
The following reactions are available:
• The application is terminated with an error.
• The motion execution is paused and can only be resumed by the user
pressing the Start key on the smartPAD.
• The error is ignored and the application is resumed.
The defined event handler must be registered before it can be used in the
application. The method getApplicationControl().registerMoveAsyncErro-
rHandler(…) is used for this purpose. The method belongs to the IApplica-
tionControl interface.

Syntax

Defining the event handler:

IErrorHandler errorHandler = new IErrorHandler() {
@Override
public ErrorHandlingAction handleError
(Device device, IMotionContainer failedContainer,
List<IMotionContainer> canceledContainers) {
// Code which is executed in case of error

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 547/667

Programming KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

return ErrorHandlingAction.reaction;
}
};
Registering the event handler:
getApplicationControl().registerMoveAsyncErrorHandler(er-
rorHandler);

Explanation of the syntax

Element Description
errorHandler Type: IErrorHandler
Name of the event handler responsible for handling failed
asynchronous motion commands
Input parameters of the handleError(…) method:
device Type: device
The parameter can be used to access the robot for
which the failed motion command is commanded.
failed Type: IMotionContainer
Container
The parameter can be used to access the failed motion
command.
canceled Type: List<IMotionContainer>
Contain-
The parameter can be used to access a list of all deleted
ers
motion commands. It contains all motion commands
which have already been sent to the real-time controller
when the method handleError(…) is called.
reaction Type: Enum of type ErrorHandlingAction
Return value of the handleError(…) method by means of
which the final reaction to the error is defined:

• ErrorHandlingAction.EndApplication:
The application is terminated with an error.
• ErrorHandlingAction.PauseMotion:
The motion execution is paused until the user re-
sumes the application via the smartPAD.
• ErrorHandlingAction.Ignore:
The error is ignored and the application is resumed.

Example

Several asynchronous motion commands are to be executed in an appli-

cation. By registering an event handler of type IErrorHandler, a handling
routine is defined using the method handleError(…) for the event that one
of the asynchronous motion commands fails:
• The smartHMI displays which motion command has failed.
• The smartHMI displays which motion commands are no longer execu-
ted.
The handleError(…) method is ended with the return of the value Erro-
rHandlingAction.Ignore.

public class ErrorHandler extends RoboticsAPIApplication {

// fields which need to be injected
@Inject
private ITaskLogger logger;

548/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming
@Inject
private LBR robot;

// not injected fields

private IErrorHandler errorHandler;

@Override
public void initialize() {
errorHandler = new IErrorHandler() {
@Override
public ErrorHandlingAction handleError(Device device,
IMotionContainer failedContainer,
List<IMotionContainer> canceledContainers) {
logger.warn("Excecution of the following motion
failed: " + failedContainer.getCommand().toString());
logger.info("The following motions will not be
executed:");
for (int i = 0; i < canceledContainers.size(); i++) {
logger.info(canceledContainers.get(i)
.getCommand().toString());
}
return ErrorHandlingAction.Ignore;
};
};

getApplicationControl()
.registerMoveAsyncErrorHandler(errorHandler);
}

@Override
public void run(){
robot.move(ptpHome());
robot.move(ptp(getFrame("/PrePos")));

// ...

robot.moveAsync(ptp(getFrame("/P1")));
robot.moveAsync(ptp(getFrame("/P2")));

robot.moveAsync(lin(getFrame("/P3")));

robot.moveAsync(ptp(getFrame("/P4")));
robot.moveAsync(ptp(getFrame("/P5")));
robot.moveAsync(ptp(getFrame("/P6")));

robot.moveAsync(ptp(getFrame("/P7")));
robot.moveAsync(ptp(getFrame("/P8")));
robot.moveAsync(ptp(getFrame("/P9")));

// ...

robot.move(ptpHome());
}
}

To explain the system behavior, it is assumed that the linear motion to P3

cannot be planned. This means that the method handleError(…) is called.
In our example, the robot is situated at end point P2 at this time.
If, for example, the motion commands to P4, P5, P6 are already in the re-
al-time controller at the same time, these motion commands will be de-
leted and no longer executed.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 549/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Calling the method handleError(…) will block further motion commands

Programming

from being sent to the real-time controller. In this case, the application will
be stopped before the motion command to P7. If the handleError(…)
method is ended with the return of the value ErrorHandlingAc-
tion.Ignore, the application is resumed. The robot then moves directly
from its current position P2 to P7.

Fig. 16-27: Failed motion to P3 (example of path)

16.29.4 Unhandled exceptions

If an exceptional error of type RuntimeException or Error (or a derived

type) occurs during execution of an application within initialize() or run(),
this causes the application to be aborted. The error message relating to
the termination is displayed on the smartHMI (>>> 21.3 "Displaying error
messages" Page 617).
Exceptional errors in a callback function (listener) registered by the appli-
cation currently only lead to an entry in the log file ApplicationServer-
Log.txt. Later Sunrise.OS versions will also force termination of the appli-
cation in these cases.
Background tasks are terminated in the same way. Information about the
exception is contained in the log file of the background task, however.
One way of preventing termination is to protect all relevant functions with
a try-catch block. Exceptions should only be caught, however, at points at
which they can be handled in a logically meaningful manner.

550/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Background tasks
17 Background tasks

17.1 Using background tasks

Activities

Background tasks are used in order to be able to perform tasks in the

background, parallel to a running robot application, or to implement cycli-
cal processes that are to be run continuously in the background. Multiple
background tasks can run simultaneously and independently of the run-
ning robot application.
Background tasks are used, in particular, to control and monitor peripheral
devices and to implement the corresponding higher-level logic. Examples:
• Switching signal lamps
• Monitoring and evaluating sensor information
This means that no higher-level controller, e.g. a PLC, is required for
smaller applications, as the robot controller can perform such tasks by it-
self.
In the case of outputs that are switched by a background task, the fol-
lowing points must be observed:
• The outputs are switched, irrespective of whether a robot application
is currently being executed.
• The outputs are also switched if the robot application is paused due
to an EMERGENCY STOP or missing enabling signal.
• The outputs are also switched if a stop request from the safety con-
troller is active (this also applies if outputs are switched by a robot
application).

WARNING
Background tasks must not be used for moving the robot or influencing
parameters that might affect motions. This is the task of the robot appli-
cation. Calling motion commands or modifying motion-specific parame-
ters in a background task can result in unspecified behavior of the robot
and thus cause personal injury and damage to property.

Properties

Background tasks, like robot applications, are implemented as Java

classes. They are similar in structure to robot applications: they have a
run() method that contains the commands to be executed.
Background tasks are an integral feature of the Sunrise project. They are
created in Sunrise.Workbench and transferred to the robot controller when
the project is synchronized.
(>>> 5.4.4 "Creating a new background application" Page 61)
There are 2 types of background task that differ in terms of their duration:
• Cyclic background task
Executed cyclically. The cyclical behavior can be adapted by the pro-
grammer depending on the task to be performed.
• Non-cyclic background task
Executed once.
Background tasks also differ in terms of their start type:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 551/667

Background tasks KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

• Manual
The task must be started manually via the smartPAD. (This function is
not yet supported.)
• Automatic
The task is automatically started when the robot controller is booted
and stopped when it is shut down.
In background tasks many objects of the application can be accessed by
means of dependency injection.
(>>> 16.3.3 "Dependency injection" Page 409)
If a background task requires access to information from the running robot
application or other background tasks that are not accessible via depend-
ency injection, a separate interface is available for data exchange.
(>>> 17.4 "Data exchange between tasks" Page 556)

Synchronization behavior

When synchronizing the Sunrise project, the associated background tasks

with Automatic start type exhibit the following behavior:
• Tasks not yet present
Both cyclic and non-cyclic tasks are transferred to the controller and
subsequently started.
• Tasks already present
If the task to be synchronized (cyclic or non-cyclic) is already present
on the controller, it will be terminated if it is still running. The synchro-
nization is then executed and the task automatically restarted.
• Tasks no longer present
If a background task has been deleted from the associated project
and synchronization is carried out, the task is terminated before syn-
chronization on the controller. It is then no longer available after syn-
chronization.

Runtime behavior

After a non-cyclic task has been started, it is executed fully in accordance

with its programming. When it reaches the end of its run() method, it is
terminated and not restarted until the next synchronization or the next re-
boot of the controller.
When started, a cyclic task is first instanced. The run() method of the task
is then repeatedly called on a regular basis. These background tasks are
therefore permanently executed as long as the controller is running.
If an error which cannot be intercepted and rectified occurs in a task (cy-
clic or non-cyclic), the task is automatically terminated.
If a background task has been terminated because of an unhandled er-
ror, the task can only be restarted by rebooting the robot controller or
carrying out project synchronization of Sunrise.Workbench on the robot
controller.

552/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Background tasks
17.2 Cyclic background task

Structure

Fig. 17-1: Structure of a cyclic background task

Item Description
1 This line contains the name of the package in which the task is
located.
2 Import section
The section contains the imported classes which are required
for programming the task
3 Header of the task
The cyclic background task is a subclass of RoboticsAPICyclic-
BackgroundTask.
4 Declaration section
The data arrays of the task that are required for its execution
are declared here.
As an example, the controller is automatically integrated via de-
pendency injection when the task is created.
5 initialize() method
Initial values are assigned here to data arrays that are not inte-
grated using dependency injection.
The initializeCyclic(…) method is available as standard. This
method is used to define the cyclical behavior of the task.
(>>> "Initialization" Page 553)
Note: The method must not be deleted or renamed.
6 runCyclic() method
The code that is to be executed cyclically is programmed here.
Note: The method must not be deleted or renamed.

Initialization

initializeCyclic(…) is used to define the cyclical behavior of the back-

ground task.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 553/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

When a cyclical background task is created, the call for initializeCyclic(…)

Background tasks

is automatically inserted. The input parameters of the method are as-

signed initial values, which can lead to the following cyclical behavior:
• Delay: 0 ms
• Period: 500 ms
• Behavior if the defined period is exceeded: execution of runCyclic()
continues.
The initial values can be changed by the programmer.
initializeCyclic(long initialDelay, long period, TimeUnit
timeUnit, CycleBehavior behavior);
Element Description
initialDelay Delay after which the cyclical background task is execu-
ted for the first time after the start. All further cycles are
executed without a delay.
The time unit is defined with timeUnit.
period Period (= time between 2 calls of runCyclic())
The period is maintained even if the execution time of
runCyclic() is less than the defined period. The behavior
in the event of runCyclic() exceeding the period is de-
fined by behavior.
The time unit is defined with timeUnit.
timeUnit Time unit of initialDelay and period
The Enum TimeUnit is an integral part of the standard
Java library.
behavior Timeout behavior
The behavior of the background task if the period defined
with period is exceeded by the runtime of runCyclic() is
defined here.

• CycleBehavior.BestEffort
runCyclic() is executed completely and then called
again.
• CycleBehavior.Strict
Execution of the background task is canceled with an
error of type CycleExceededException.

Example

A robot is to assemble workpieces that it takes from a magazine. The

magazine can contain a maximum of 100 workpieces and is loaded man-
ually. If the remaining number of workpieces in the magazine falls below
20, this is signaled to the robot controller via a digital input. An LED is
then to flash every 500 ms to signal to the operator that the magazine
needs filling. Another LED is to flash if the force determined at the robot
flange exceeds a limit of 150 N.
A cyclic background task is used for data evaluation and activation of the
LEDs. The background task is executed every 500 ms.

public class LEDTask extends

RoboticsAPICyclicBackgroundTask {
@Inject
private LBR robot;
@Inject
private ProcessParametersIOGroup processParaIOs;

554/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Background tasks
@Inject
private ProcessParametersLEDsIOGroup LED_IOs;

public void initialize() {

initializeCyclic(0, 500, TimeUnit.MILLISECONDS,
CycleBehavior.BestEffort);
}

public void runCyclic() {

/**
* Check if refill is required (value true)
*/
if (processParaIOs.getSensor_RefillRequired()) {
/**
* If refill is required, the appropriate LED changes
* its state with every execution of runCyclic()
*/
LED_IOs.setLED_RefillRequired(!LED_IOs
.getLED_RefillRequired());
} else {
/**
* If refill is not required, the LED remains off
*/
LED_IOs.setLED_RefillRequired(false);
}

/**
* Query the applied force
*/
Vector forceVector = robot.getExternalForceTorque(
robot.getFlange()).getForce();

/**
* Check if absolute force (length of vector)
* exceeds 150 N
*/
if (forceVector.length() > 150.0) {
/**
* If the force limit is exceeded, the appropriate LED
* changes its state with every execution of runCyclic()
*/
LED_IOs.setLED_ForceExceeded(!LED_IOs
.getLED_ForceExceeded());
} else {
LED_IOs.setLED_ForceExceeded(false);
}
}
}

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 555/667

Background tasks KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

17.3 Non-cyclic background task

Structure

Fig. 17-2: Structure of a non-cyclic background task

Item Description
1 This line contains the name of the package in which the task is
located.
2 Import section
The section contains the imported classes which are required
for programming the task
3 Header of the task
The non-cyclic background task is a subclass of RoboticsAPI-
BackgroundTask.
4 Declaration section
The data arrays of the task that are required for its execution
are declared here.
As an example, the controller is automatically integrated via de-
pendency injection when the task is created.
5 initialize() method
Initial values are assigned here to data arrays that are not inte-
grated using dependency injection.
Note: The method must not be deleted or renamed.
6 run() method
The code that is to be executed once is programmed here. The
runtime is not limited.
Note: The method must not be deleted or renamed.

17.4 Data exchange between tasks

Description

The mechanism described here can be used to exchange data between

running tasks. One task can provide task functions (providing task) that
can be accessed by other tasks (requesting tasks).

556/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Example: Accessing and processing information from the running robot

Background tasks
application in a background task.
It is not relevant for programming whether data are exchanged between a
background task and a robot application or between 2 background tasks.
The providing task may be either a robot application or a background
task. For this reason, background tasks and robot applications are grou-
ped together as tasks.

Overview

The following steps are required in order for the providing task and the re-
questing task to be able to communicate with one another:
Step Description
1 Create an interface and declare the desired task functions.
(>>> 17.4.1 "Declaring task functions" Page 558)
2 Implement the interface in which the task functions are de-
clared.
The interface can be implemented directly by the providing
task or by a specially created class. The declared task
functions must be programmed in the implementing class.
(>>> 17.4.2 "Implementing task functions" Page 558)
3 Create the providing task.
The providing task must contain a parameterless public
method with the annotation @TaskFunctionProvider which
returns the implementation of the interface.
(>>> 17.4.3 "Creating the providing task" Page 560)
4 In the requesting task, use the getTaskFunction(…) method
to request the interface in which the task functions are de-
clared. The method is available in all task classes.
The ITaskFunctionMonitor interface can be used to check
whether the task functions are available.
(>>> 17.4.4 "Using task functions" Page 562)

Example

The data exchange between tasks is described step by step in the sec-
tions below, using the following example:
An assembly process is to be implemented using the robot application
“AssemblyApplication”. An LED is to flash during the assembly process. If
the robot leaves the path during the application and has to be reposi-
tioned, a further LED is to flash.
The LEDs are activated by the background task “LEDTask”. In this exam-
ple, the background task is the requesting task.
The robot application is the providing task. It must enable access to your
Recovery interface, which is used to check whether repositioning of the
robot is required. Furthermore, it must also signal the start and end of the
assembly process.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 557/667

Background tasks KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

17.4.1 Declaring task functions

Description

The desired task functions must be declared in a specially created inter-

face.
The interface may only declare those methods that are to be made
available to the requesting task. It is thus advisable not to use set meth-
ods for setting fields in the interface. Instead, such methods can be of-
fered by the implementing class.

Example

Declaration of the task functions via the interface IApplicationInformation-

Function
The following methods are to be available to the providing task (here the
background task) and are declared by the IApplicationInformationFunction
interface:
• isAssemblyRunning(): checks whether an assembly process is current-
ly being executed
• isManualRepositioningRequired(): checks whether repositioning of the
robot is required

1 public interface IApplicationInformationFunction {

2
3 /**
4 * Signifies whether assembly is currently executed
5 * @return true, if assembly is executed
6 */
7 public boolean isAssemblyRunning();
8
9 /**
10 * Returns whether the application requires
11 * repositioning of the robot
12 * @return true if repositioning is required
13 */
14 public boolean isManualRepositioningRequired();
15
16 }

Line Description
1 … 16 Interface IApplicationInformationFunction
7 Method isAssemblyRunning()
Called by the requesting task to check whether the assem-
bly process is currently running.
14 Method isManualRepositioningRequired()
Called by the requesting task to check whether reposition-
ing of the robot is required.

17.4.2 Implementing task functions

Description

A class must be made available that implements the interface and in

which the declared task functions are programmed. The providing task or
a specially created class can be used as the implementing class.

558/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Background tasks
Example

Implementation of the IApplicationInformationFunction interface using the

ApplicationInformation class
The following methods are only to be available to the providing task (here
the robot application) and are declared and implemented by the Applica-
tionInformation class:
• setAssemblyRunning(…)
Announces the start and end of the assembly process
• setApplicationRecoveryInterface(…)
Enables access to the Recovery interface of the robot application

1 public class ApplicationInformation implements

2 IApplicationInformationFunction {
3
4 private boolean assembly;
5 private IRecovery recovery;
6
7 @Override
8 public boolean isAssemblyRunning() {
9 return assembly;
10 }
11
12 /**
13 * Called from application when assembly is
14 * started and finished
15 * @param assembly Set to true when assembly is
started.
16 * Reset when assembly is stopped.
17 */
18 public void setAssemblyRunning(boolean isRunning) {
19 assembly = isRunning;
20 }
21
22 @Override
23 public boolean isManualRepositioningRequired() {
24 return recovery.isRecoveryRequired();
25 }
26
27 /**
28 * Called from application to give access to its
29 * recovery interface
30 * @param applicationRecoveryInterface Recovery
31 * interface of the application
32 */
33 public void setApplicationRecoveryInterface(
34 IRecovery recoveryInterface) {
35 recovery = recoveryInterface;
36 }
37 }

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 559/667

Background tasks KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Line Description
1 … 37 Class ApplicationInformation
The task functions are programmed in the class.
4, 5 Declaration of the data arrays

• boolean assembly: Indicates whether a joining process

is currently active.
• IRecovery recovery: refers to the Recovery interface of
the robot application
7 … 10 Method isAssemblyRunning()
Called by the requesting task to check whether the assem-
bly process is currently running.
18 … 20 Method setAssemblyRunning(…)
Called by the robot application when the assembly process
is started or ended.
22 … 25 Method isManualRepositioningRequired()
Called by the requesting task to check whether reposition-
ing of the robot is required.
33 … 36 Method setApplicationRecoveryInterface(…)
Called by the robot application for making its Recovery in-
terface available.

17.4.3 Creating the providing task

Description

A task can provide task functions of various interfaces. For each interface
whose task functions are provided by the task, a parameterless public
method with the annotation @TaskFunctionProvider must be inserted
which returns the implementation of the interface.

Syntax

@TaskFunctionProvider
public Interface Method name()
return Interface instance;
}

Explanation of the syntax

Element Description
Interface Interface whose task functions the task provides
Method Name of the method that returns the implementation of
name the interface (the name can be freely selected)
Interface in- Instance of the implementing class
stance

If the providing task does not, itself, implement the interface derived
from ITaskFunction, it requires an instance of the implementing class. It
is advisable to create this instance as an array.

560/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Background tasks
If the providing task implements the interface itself, transfer the instance
of the task for the Interface instance parameter:
return this;

Each interface may only be provided once. This means that there must
not be 2 tasks that return the same interface in their @TaskFunctionPro-
vider annotation.

Example

The robot application contains a data array of type ApplicationInformation.

Its method setApplicationRecoveryInterface(…) provides the Recovery in-
terface of the robot application. Calling the method setAssembly(…) an-
nounces that the assembly process is being carried out.

public class AssemblyApplication extends

RoboticsAPIApplication {
@Inject
private LBR robot;
private ApplicationInformation appInfo;

@Override
public void initialize() {

appInfo = new ApplicationInformation();

// Gives access to recovery interface
appInfo.setApplicationRecoveryInterface(getRecovery());

@Override
public void run() {

// Moves robot to initial pose

robot.move(ptp(getFrame("/StartPos")));

// Announces that assembly is running

appInfo.setAssemblyRunning(true);
assembly();

// Announces that assembly is finished

appInfo.setAssemblyRunning(false);

// Moves robot to initial pose

robot.move(ptp(getFrame("/StartPos")));

/**
* Implements the assembly process
*/
private void assembly() {
// ...
}

/**
* TaskFunctionProvider method that has to be
* implemented by the task
*/
@TaskFunctionProvider

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 561/667

Background tasks KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

public IApplicationInformationFunction getAppInfoFunction()

{
return appInfo;
}
}

17.4.4 Using task functions

Task functions provided by a task can be used by other tasks.

Enabling access

The following steps are required in order to enable access to the task
functions of an interface in the requesting task:
1. Create a data array of the type of the interface.
private Interface Interface instance;
2. Request the interface with the getTaskFunction(…) method. The task
functions of the interface are saved in the data array just created.
Interface instance = getTaskFunction(Interface.class);
Explanation of the syntax:

• Interface: interface whose task functions the task wants to access

• Interface instance: instance of the interface in which the task functions
are declared
Example:
In the requesting background task “LEDTask”, access to the functions de-
fined by IApplicationInformationFunction is to be enabled. The interface in-
stance required for this is created as a data array and generated in the
initialize() method of the task:

public class LEDTask extends

RoboticsAPICyclicBackgroundTask {
// ...
private IApplicationInformationFunction appInfoFunction;

public void initialize() {

initializeCyclic(0, 500, TimeUnit.MILLISECONDS,
CycleBehavior.BestEffort);

// Get Task Function Interface

appInfoFunction = getTaskFunction(
IApplicationInformationFunction.class);

Checking availability

The task functions of the providing task are only available when the pro-
viding task is being executed or is paused.
If a task function is not available when it is called, a runtime error may
occur in the requesting task (InstanceNotRunningException). If this error
is not handled, execution of the task is aborted.

The methods of the ITaskFunctionMonitor interface can be used to check

whether the task functions of the providing task are available.
The following steps are required in order to make the methods of the in-
terface available in the requesting task:
1. Create a data array of the type of the interface.
private ITaskFunctionMonitor monitor;

562/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Background tasks
2. Use the TaskFunctionMonitor.create(…) method to initialize the monitor
for the task functions to be monitored. The instance of the interface in
which the task functions are declared is transferred to the method as
a parameter.
monitor = TaskFunctionMonitor.create(Interface instance);
Explanation of the syntax:

• monitor: instance of the ITaskFunctionMonitor interface

• Interface instance: instance of the interface in which the task functions
are declared
The following methods are available in the ITaskFunctionMonitor interface:
Method Description
isAvailable() Return value type: boolean
Specifies whether the task functions of the providing task
are available (true = available).
await(time, Return value type: boolean
unit)
If the task functions are not available when the providing
task is called, the system waits a defined time for them
to become available (true = task functions available with-
in the defined wait time).
Parameter:

• time (type: long): maximum waiting time The unit is

defined by the parameter unit.
• unit (type: TimeUnit): unit of time
Example:
In the method runCyclic() of the background task “LEDTask”, a check is to
be carried out to ascertain whether the assembly process is currently be-
ing executed. For this, the interface IApplicationInformationFunction offers
the method isAssemblyRunning().
The requesting background task “LEDTask” can only check whether the
assembly process is being executed if the robot application is running or
paused. For this reason, the availability of the function must be checked
before isAssemblyRunning() is called:

public class LEDTask extends

RoboticsAPICyclicBackgroundTask {
// ...
private IApplicationInformationFunction appInfoFunction;
private ITaskFunctionMonitor appInfoMonitor;

public void initialize() {

initializeCyclic(0, 500, TimeUnit.MILLISECONDS,
CycleBehavior.BestEffort);

// Get Task Function Interface

appInfoFunction = getTaskFunction(
IApplicationInformationFunction.class);

/**
* Create ITaskFunctionMonitor for
* IApplicationInformationFunction
*/
appInfoMonitor = TaskFunctionMonitor.create(
appInfoFunction);

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 563/667

Background tasks KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

public void runCyclic() {

// Check if task functions are available
if (appInfoMonitor.isAvailable()) {
/**
* Use task function to check if assembly is
* currently executed
*/
if (appInfoFunction.isAssemblyRunning()) {
// ...
}
}

Overall example

The requesting task “LED Task” is executed cyclically every 500 ms. It
first checks whether the required task functions of the robot application
are available. If they are available, a check is carried out to ascertain
whether the assembly process is running and the corresponding LED is
activated. The system then checks whether repositioning of the robot is
required. If this is the case, a further LED is activated.

public class LEDTask extends

RoboticsAPICyclicBackgroundTask {
@Inject
private ProcessParametersLEDsIOGroup LED_IOs;
private IApplicationInformationFunction appInfoFunction;
private ITaskFunctionMonitor appInfoMonitor;

public void initialize() {

initializeCyclic(0, 500, TimeUnit.MILLISECONDS,
CycleBehavior.BestEffort);

// Get Task Function Interface

appInfoFunction = getTaskFunction(
IApplicationInformationFunction.class);

/**
* Create ITaskFunctionMonitor for
* IApplicationInformationFunction
*/
appInfoMonitor = TaskFunctionMonitor
.create(appInfoFunction);
}

public void runCyclic() {

// Check if task functions are available
if (appInfoMonitor.isAvailable()) {
/**
* Use task function to check if assembly is
* currently executed
*/
if (appInfoFunction.isAssemblyRunning()) {
/**
* If assembly is running, the appropriate LED
changes
* its state with every execution of runCyclic()
*/
boolean currentStateAssemblyLED = LED_IOs
.getLED_Assembly();

564/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Background tasks
LED_IOs.setLED_Assembly(!currentStateAssemblyLED);
} else {
LED_IOs.setLED_Assembly(false);
}

/**
* Use task function to check whether the application
* requires repositioning
*/
boolean recoveryRequired =
appInfoFunction.isManualRepositioningRequired();

if (recoveryRequired) {
/**
*If recovery is required,
*the appropriate LED changes
* its state with every execution of runCyclic()
*/
boolean currentStateRecoveryLED = LED_IOs
.getLED_RecoveryRequired();
LED_IOs.setLED_ForceExceeded(
!currentStateRecoveryLED);
} else {
LED_IOs.setLED_RecoveryRequired(false);
}
} else {
// If application is not running, LEDs remain off
LED_IOs.setLED_Assembly(false);
LED_IOs.setLED_RecoveryRequired(false);
}
}
}

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 565/667

Background tasks KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

566/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

KUKA Sunrise.EnhancedVelocityControl
18 KUKA Sunrise.EnhancedVelocityControl

18.1 Overview of KUKA Sunrise.EnhancedVelocityControl 1.0

KUKA Sunrise.EnhancedVelocityControl 1.0 (EVC) is an add-on option for

the limitation of Cartesian robot velocity.

Description

EVC regulates the velocity of the following frames:

• Robot flange
• TCP
EVC automatically adapts the robot velocity so that the following Cartesian
velocity limits are not exceeded by these frames:
• Cartesian velocity limits that are active on the safety controller
Cartesian velocity monitoring functions can be combined in the safety
configuration with the “Brake” safety reaction.
(>>> 18.1.1 "“Brake” safety reaction" Page 568)
• Mode-specific Cartesian velocity limitation of 250 mm/s that is active in
T1 or CRR mode
• Device-specific Cartesian velocity limitation that is set by the applica-
tion
(>>> 18.1.2 "Cartesian velocity limitation via application" Page 570)
• Aggregated Cartesian velocity limitation
If multiple Cartesian velocity limitations are active simultaneously, the
velocity is reduced to the lowest of these limits.

Motion types

EVC limits Cartesian velocities in position-controlled spline motions:

• Impedance-controlled motions and motions that are not spline motions,
e.g. manual guidance motions, are not compatible with EVC.

Functional principle

EVC takes safety-oriented velocity limits into account, thereby preventing

the robot from being stopped with a safety stop:
• If a Cartesian velocity monitoring function is active, the velocity of the
commanded TCP and the flange is automatically reduced so that the
monitored velocity limit is not exceeded by these frames. The robot
structure and the safety-oriented frames of active tools are not taken
into consideration.
• If multiple Cartesian velocity monitoring functions are active simultane-
ously, the velocity is automatically reduced so that the lowest currently
monitored velocity limit is not exceeded.
The velocity is always reduced to 90% of the lowest current velocity limit
in order to maintain a buffer between the exact limit and the target veloci-
ty. If, for example, only the mode-specific Cartesian velocity limitation of
250 mm/s is active, EVC regulates the velocity to 225 mm/s.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 567/667

KUKA Sunrise.EnhancedVelocityControl KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

18.1.1 “Brake” safety reaction

Description

With EVC, the “Brake” safety reaction is available for safety functions of
the PSM mechanism used for monitoring the Cartesian velocity.
Brake can only be used as a reaction if the safety function (PSM row)
contains the Cartesian velocity monitoring AMF. The PSM row can contain
further AMFs. An exception is extended AMFs, such as the Time delay
AMF. Extended AMFs cannot be used in conjunction with the “Brake” re-
action.

Benefits

The “Brake” safety reaction can be used to prevent the robot being stop-
ped with a safety stop if its velocity is higher than the configured limit
when the velocity monitoring is activated.
With very high accelerations, it is possible, in rare cases, that the veloc-
ity limitation does not act quickly enough. This can result in the robot
stopping with a safety stop 1. Possible remedy: Reduce the acceleration
for the motions in which this occurs.

The “Brake” safety reaction is only compatible with position-controlled

spline motions. In the case of incompatible motion and control types
(e.g. manual guidance, impedance control), there is no automatic brak-
ing with the drives. If the velocity does not decrease, the safety control-
ler triggers a safety stop 1. For this reason, it is advisable not to use
the “Brake” safety reaction with incompatible motion and control types.
Unlike safety stop 1 (path-maintaining), safety stop 1 leads to increased
response times and the programmed path is left.

If the “Brake” safety reaction is used, it must be taken into consideration

that the robot velocity is only reduced to the limit value of the Cartesian
velocity monitoring configured in a PSM row for as long as all other
AMFs of the PSM row are violated. If the violation state of these other
AMFs is rapidly switched backwards and forwards, it is possible that the
“Brake” safety reaction does not lead to a reduction in velocity.
For every PSM row with the “Brake” safety reaction, a check must be
made to see whether there could be an increased risk due to rapid
switching to and from the violation state of the AMFs with which the
Cartesian velocity monitoring is linked. This is the responsibility of the
safety maintenance technician.

Example 1

Cartesian velocity monitoring is activated with an input signal (LOW), e.g.

a laser scanner.
AMF1 AMF2 AMF3 Reaction
Input signal Cartesian velocity - Brake
monitoring
If the laser scanner detects a person and the robot is too fast, i.e. its ve-
locity is above the configured limit, the “Brake” reaction is triggered. The
resulting braking process is monitored and the velocity continues being re-
duced until it is below the configured limit. The Cartesian velocity monitor-
ing AMF is then no longer violated and the “Brake” reaction is terminated.
As long as the input signal has the LOW level, EVC keeps the velocity
below this limit value.

568/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

KUKA Sunrise.EnhancedVelocityControl
Example 2

Cartesian velocity monitoring is combined with protected space monitoring.

AMF1 AMF2 AMF3 Reaction
Cartesian protected Cartesian velocity - Brake
space monitoring monitoring
In a collaboration zone (HRC zone), the Cartesian velocity is to be re-
duced in order to minimize the risk for the operator. This can be achieved
by combining Cartesian velocity monitoring with protected space monitor-
ing.
As soon as the robot enters the protected space, the velocity monitoring
is active. If the velocity is too high on entering the protected space, the
“Brake” reaction is triggered. The resulting braking process is monitored
and the velocity continues being reduced until it is below the configured
limit.
The Cartesian velocity monitoring AMF is then no longer violated and the
“Brake” reaction is terminated. As long as the protected space is violated,
EVC keeps the velocity below the configured limit. If the robot leaves the
protected space again, the velocity monitoring is no longer active and
EVC no longer limits the velocity.

Brake ramp monitoring

Fig. 18-1: Braking ramp monitoring

1 Monitoring time
v Velocity
t Time
t1 Moment in time at which the “Brake” reaction is triggered (PSM
row is violated)
t2 Moment in time at which the “Brake” reaction is stopped (Cartesian
velocity monitoring AMF is no longer violated)
vR Robot velocity (blue curve)
vS Velocity limit of the Cartesian velocity monitoring AMF
v0 Velocity at time t1 at which the “Brake” reaction is triggered

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 569/667

KUKA Sunrise.EnhancedVelocityControl KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

v1 Start value of the monitoring ramp (green curve)

v1 = v0 + 250 mm/s

18.1.2 Cartesian velocity limitation via application

EVC can limit the Cartesian robot velocity via the application. Once set,
this device-specific Cartesian velocity limitation can be deactivated again
via the application. Additionally, information about all Cartesian velocity
limitations carried out by EVC can be requested by the robot.

18.1.2.1 Setting and deactivating velocity limitation

Description

The robot class contains the methods that can be used to set device-spe-
cific Cartesian velocity monitoring in the application and then deactivate it
again.

Syntax

Set velocity limitation:

robot.setDeviceCartesianVelocityLimit(limit);
Deactivate velocity limitation:
robot.deactivateDeviceCartesianVelocityLimit();

Explanation of the syntax

Element Description
robot Type: Robot
Instance of the robot used in the application
limit Type: int
Value > 0 that is set as the Cartesian velocity limit for
the robot (unit: mm/s)

Example

public class RobotApplication extends

RoboticsAPIApplication {
@Inject
private LBR robot;
// ...

@Override
public void initialize() {
// initialize your application here
}

@Override
public void run() {
// your application execution starts here
int integerValue = 69; //in mm/s

robot.move(ptpHome());

//Sets "integerValue" as the new device limit

robot.setDeviceCartesianVelocityLimit(integerValue);

570/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

KUKA Sunrise.EnhancedVelocityControl
//Deactivates the device limit
robot.deactivateDeviceCartesianVelocityLimit();
}
}

18.1.2.2 Requesting information about velocity limitation functions

Description

The method getCartesianVelocityLimitInfo() can be used to request infor-

mation about the Cartesian velocity limitations from the robot and store it
in a container of the CartesianVelocityLimitInfo class.
The following information is stored:
• The mode-specific Cartesian velocity limitation
• The device-specific Cartesian velocity limitation that is set by the appli-
cation
• The Cartesian velocity limit that is active on the safety controller
• The aggregated Cartesian velocity limitation
• The sources from which the value for the aggregated Cartesian veloc-
ity limitation was formed
The information stored in the container can be read.

Syntax

CartesianVelocityLimitInfo infoObject =
robot.getCartesianVelocityLimitInfo();

Explanation of the syntax

Element Description
infoObject Type: CartesianVelocityLimitInfo
Variable for the information requested from the robot us-
ing getCartesianVelocityLimitInfo()
robot Type: Robot
Instance of the robot used in the application

Overview

The information stored in the containers can be read using the following
methods:
Method Description
getDeviceVelocityLimit() Return value type: Integer
Returns the device-specific Cartesian velocity limitation that is
currently set by an application (unit: mm/s).
The return value -1 means that the device-specific Cartesian
velocity limitation is deactivated.
getOperationModeVelocity Return value type: Integer
Limit()
Returns the mode-specific Cartesian velocity limitation (unit:
mm/s).
The return value -1 means that the Cartesian velocity is not
currently limited by an operating mode.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 571/667

KUKA Sunrise.EnhancedVelocityControl KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Method Description
getSafetyVelocityLimit() Return value type: Integer
Returns the Cartesian velocity limit that is active on the safety
controller (unit: mm/s).
The return value -1 means that there is currently no Cartesian
velocity limit active on the safety controller.
getAggregatedVelocityLimit() Return value type: Integer
Returns the minimum of all currently active and valid Cartesi-
an velocity limitations (unit: mm/s). This aggregated velocity
value is the actual limitation that regulates the robot velocity.
The return value -1 means that the Cartesian velocity is not
currently limited. In other words, it is not currently limited by
either the operating mode or the application and there is no
active Cartesian velocity limit on the safety controller.
getVelocityLimitSources() Return value type: Set<CartVelocityLimitSourceType>
Returns an Enum data set with the sources from which the
value for the aggregated Cartesian velocity limitation was
formed.
The Enum CartVelocityLimitSourceType contains the following
values:

• DEVICE
Array for device-specific Cartesian velocity limitation
• OPERATIONMODE
Array for mode-specific Cartesian velocity limitation
• SAFETY
Array for Cartesian velocity limit that is active on the safe-
ty controller

Example

public class RobotApplication extends

RoboticsAPIApplication {
@Inject
private LBR robot;
private Integer deviceVelocityLimit;
private Integer safetyVelocityLimit;
private Integer operationModeVelocityLimit;
private Integer aggregatedVelocityLimit;
private Set<CartVelocityLimitSourceType>
velocityLimitSources;

@Override
public void initialize() {
// initialize your application here
}

@Override
public void run() {
// your application execution starts here
int integerValue = 69; //in mm/s

robot.move(ptpHome());

//All limit data is queried from the robot

572/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

KUKA Sunrise.EnhancedVelocityControl
CartesianVelocityLimitInfo infoObject = robot
.getCartesianVelocityLimitInfo();

deviceVelocityLimit = infoObject.getDeviceVelocityLimit();
safetyVelocityLimit = infoObject.getSafetyVelocityLimit();
operationModeVelocityLimit = infoObject
.getOperationModeVelocityLimit();

aggregatedVelocityLimit = infoObject
.getAggregatedVelocityLimit();
velocityLimitSources = infoObject
.getVelocityLimitSources();

//Sets "integerValue" as the new device limit

robot.setDeviceCartesianVelocityLimit(integerValue);

//Deactivates the device limit

robot.deactivateDeviceCartesianVelocityLimit();
}
}

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 573/667

KUKA Sunrise.EnhancedVelocityControl KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

574/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

KUKA Sunrise.StatusController
19 KUKA Sunrise.StatusController

19.1 Overview of KUKA Sunrise.StatusController

Description

KUKA Sunrise.StatusController is a programming interface that can be

used to signal various system states. It can be used in robot and back-
ground applications.
The status controller distinguishes between status group and status. Vari-
ous statuses are grouped together in a status group, e.g. the status group
SAFETY_STOP contains the statuses that belong to a safety stop.
Examples of statuses of the status group SAFETY_STOP:
• E-STOP actuated on smartPAD
• Safety configuration not activated
• Safety stop 0 active
• etc.

Functional principle

Some statuses are automatically set by the station monitoring, e.g. wheth-
er a safety stop is active. Additionally, user-defined statuses can be set
via the status monitor of a task. A status listener can then be used to re-
spond to status changes, e.g. switching on of a red lamp in the case of
an error state.

Fig. 19-1: Functional principle of status controller

Installation

KUKA Sunrise.StatusController is contained in the software catalog of

Sunrise.Workbench and must be installed in the Sunrise project:

Procedure

1. Open the station configuration (file StationSetup.cat) in the project.

2. Set the check mark next to the entry KUKA Sunrise.StatusController
in the Install column on the Software tab.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 575/667

KUKA Sunrise.StatusController KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

3. Save the station configuration and apply changes to the project.

The software expansions installed in the Sunrise project must be trans-

ferred to the robot controller. The System Software must be reinstalled
on the robot controller for this.

Interfaces

KUKA Sunrise.StatusController provides the following interfaces:

• IStatusController
Interface with the methods of the status controller
‒ Automatically set statuses and statuses set by the system integra-
tor on a status monitor are signaled to the status controller.
‒ If a status listener is registered on the status controller, the status
listener is notified of status changes.
‒ All currently active statuses and status groups can be requested
via the status controller.
• IStatusMonitor
Interface for setting the status from robot and background applications
• IStatusListener
Interface for responding to status changes

Classes

KUKA Sunrise.StatusController provides the following classes:

• DefaultStatusGroups class
The class contains predefined status groups.
• StatusGroup class
Objects of the class each represent a status group.
• Status class
Objects of the class each represent a status of a status group.

19.1.1 Predefined status groups

The following status groups are defined in the class DefaultStatusGroups.

For some of these groups, the statuses are automatically set if certain
preconditions are met. For other groups, the statuses must be generated
and set by the user.
Status groups whose statuses are only set automatically (cannot be
used by the user):
Status group Description
APPLICATION_READY A robot application is present and can be started.
The status is set if the following preconditions are met:

• Motion enable signal has been received for all kinematic

systems.
• All robots are mastered.
• AUT mode
• There is at least one robot application on the robot con-
troller.
• No robot application running
APPLICATION_RUNNING A robot application is running in AUT mode and is not
paused.

576/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

KUKA Sunrise.StatusController
Status group Description
SAFETY_STOP A safety stop has been triggered, e.g. by pressing an EMER-
GENCY STOP.
Status groups whose statuses are set automatically (can also be
used by the user):
Status group Description
ERROR_GENERAL A general, non-safety-oriented error is active, e.g. application
has been terminated with an error.
WARNING_NON_CRITICAL There is a non-critical warning which does not affect operabil-
ity of the station.
Status groups whose statuses are only set by the user:
Status group Description
WARNING_CRITICAL There is a critical warning which affects operability of the sta-
tion.
INTERACTION_ Manual intervention on the robot is required to be able to
REQUIRED_HAPTIC continue the program, e.g. jogging to a specific position.
INTERACTION_ Manual intervention on the smartHMI is required (e.g. ac-
REQUIRED_HMI knowledging a dialog) to be able to continue the program.
HRC_ACTIVE The robot is in HRC mode.

19.1.2 Creating status and status groups

Description

In order to be able to define a new status, a status group is necessary. If

the new status matches one of the predefined status groups, this status
group can be used.
If the new status does not match any of the predefined status groups,
new status groups can be created. The designation of the status group
must enable clear identification of the group.
If new status groups are created and used, these cannot be processed
automatically by the supplied status handlers, e.g. the flexFELLOW sta-
tus handler. In all cases, user-defined status groups must be handled by
the user.

Constructor syntax

New status:
Status(StatusGroup statusGroup<, String description>)

Explanation of the syntax

Element Description
statusGroup Status group for which the new status is being created
description Description of the new status (optional)
The description can be used in status listeners.

Constructor syntax

New status group:

StatusGroup(String id)

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 577/667

KUKA Sunrise.StatusController KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Explanation of the syntax

Element Description
id ID of the new status group
If several status groups exist with the same ID, these are
treated as one status group.

Examples

For the status group WARNING_CRITICAL, a new status lackOfParts

is created:

Status lackOfParts = new Status(

DefaultStatusGroups.WARNING_CRITICAL, "palette empty");

A new status group and a new status are created here:

StatusGroup myStatusGroup =
new StatusGroup("myStatusGroup");
Status myStatus = new Status(
myStatusGroup, "myStatus description");

19.1.3 Using the IStatusController interface

Description

The IStatusController interface can be used, for example, for requesting

all active statuses and status groups or for registering to be notified of
status changes. An instance of IStatusController can be integrated into
tasks by means of dependency injection.
The methods for requesting statuses and status groups always return all
requested statuses and status groups, irrespective of the IStatusMonitor
instance on which they were set.

Overview

The IStatusController interface provides the following methods:

Method Description
getActiveStatusGroups() Return value type: List<StatusGroup>
Returns the list of currently active status groups.
getActiveStatuses() Return value type: List<Status>
Returns the list of currently set statuses.
getActiveStatuses( Return value type: List<Status>
StatusGroup)
Returns the list of currently set statuses belonging to the
transferred status group.
isSet(Status) Return value type: Boolean
Checks whether the transferred status is set.

• true: Status is set.

• false: Status is not set.

578/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

KUKA Sunrise.StatusController
Method Description
addStatusListener( Return value type: void
IStatusListener, StatusGroup)
Registers the transferred status listener so that it is notified of
status changes.
Any number of status groups can be transferred after the pa-
rameter IStatusListener. The listener is then only informed of
changes in the transferred status groups. If no status groups
are transferred, the listener is informed of all status changes.
removeStatusListener( Return value type: void
IStatusListener)
Unregisters the transferred status listener so that it is no lon-
ger notified of status changes.

19.1.4 Setting and deleting the status via the status monitor

Description

To set and delete a status in a task, a status monitor is required.

Instances of IStatusMonitor can be integrated into a task by means of de-
pendency injection. A separate instance is generated for each task. The
lifecycle of the status monitor depends on the task into which it is integra-
ted. If a task is ended, this has the following effect on the status monitor
injected for this task:
• All statuses set on the monitor are automatically deleted.
• The monitor can no longer be used.
Instances of IStatusMonitor have separate validity ranges. This means
that a status that is set on one instance of IStatusMonitor cannot be de-
leted on a different instance of IStatusMonitor. This also means that a sta-
tus which has been set in one task cannot be deleted from another task.

Overview

The interface IStatusMonitor provides the methods for setting and deleting
a status:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 579/667

KUKA Sunrise.StatusController KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Method Description
clear(Status) Return value type: void
Deletes the transferred status.
The following exceptions can occur:

• IllegalArgumentException: Status is null

• StatusNotSetException: Status is not currently set.
• StatusOutOfScopeException: Status is set, but by a different sta-
tus monitor.
set(Status) Return value type: void
Sets the transferred status.
Any number of statuses from any number of status groups can be set
simultaneously on a status monitor.
The following exceptions can occur:

• IllegalArgumentException: Status is null

• StatusAlreadySetException: Status is already set.
• StatusOutOfScopeException: Status is already set by a different
status monitor.

To compare status objects, the status controller internally uses their ob-
ject identity. If 2 new status objects are generated with identical status
groups and description, the status controller handles them as different
statuses.

Example

The status lackOfParts is set by a status monitor to signal that there is

a lack of parts. The status is cleared again when new parts are available.

private Status lackOfParts = new Status(

DefaultStatusGroups.WARNING_CRITICAL, "palette empty");
@Inject private IStatusMonitor statusMonitor;
//...

@Override
public void run() {
//...
//set status if a lack of parts was detected
statusMonitor.set(lackOfParts);
//...
//wait for new parts to be available
statusMonitor.clear(lackOfParts);
//...
}

19.1.5 Implementing a status listener

Description

In order to be able to respond to status changes in a task, the interface

IStatusListener must be implemented in a cyclical background application.
The status listener itself must be registered on the status controller using
the addStatusListener(…) method. Any number of status groups can be
transferred during registration of the status listener. The listener is then

580/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

only informed of changes in the transferred status groups. If no status

KUKA Sunrise.StatusController
groups are transferred, the listener is informed of all status changes.
If a status of a subscribed status group is set or deleted, the onStatus-
Set(StatusEvent) or onStatusCleared(StatusEvent) method of the status
listener is called. The procedure for implementing these methods is illus-
trated in the example.

Syntax

Registering a status listener:

statusController.addStatusListener(statusListener<, statusGroup1,
… statusGroup1+n>);

Explanation of the syntax

Element Description
statusCon- Type: IStatusController
troller
Status controller on which the listener is registered
statusListen- Type: IStatusListener
er
Listener that is registered
status- Type: StatusGroup
Group1 …
Status groups to which the listener is to respond
status-
Group1+n If no status groups are specified, the listener responds to
status changes in all groups.

Overview

The following information is available for StatusEvent objects:

Method Description
getStatusGroup() Returns the status group to which the set or
cleared status belongs.
getDate() Returns the time at which the status was set or
cleared.
hasChangedActive Specifies whether setting or clearing the status
StatusGroups() has altered the number of active status groups.
getStatusDescription() Description that was specified when creating
the status.
Can return null if the set or cleared status
has no description.

Example

Implementation of a status listener in a cyclic background application:

1 public class BackgroundTask

2 extends RoboticsAPICyclicBackgroundTask
3 implements IStatusListener {
4
5 @Inject
6 private IStatusController statusController;
7 @Inject
8 private ITaskLogger logger;
9
10 @Override
11 public void initialize() {

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 581/667

KUKA Sunrise.StatusController KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

12 //initialize your task here

13 initializeCyclic(0, 500, TimeUnit.MILLISECONDS,
14 CycleBehavior.BestEffort);
15
16 //add status listener
17 statusController.addStatusListener(this,
18 DefaultStatusGroups.SAFETY_STOP,
19 DefaultStatusGroups.ERROR_GENERAL);
20 }
21
22 @Override
23 public void runCyclic() {
24
25 }
26
27 @Override
28 public void onStatusSet(StatusEvent statusEvent) {
29 logger.info("Status of group " +
30 statusEvent.getStatusGroup() + " set: " +
31 statusEvent.getStatusDescription());
32 }
33
34 @Override
35 public void onStatusCleared(StatusEvent statusEvent) {
36 logger.info("Status of group " +
37 statusEvent.getStatusGroup() + " cleared: " +
38 statusEvent.getStatusDescription());
39 }
40
41 @Override
42 public void dispose() {
43 //remove status listener
44 statusController.removeStatusListener(this);
45 }
46 }

Line Description
3 The BackgroundTask class implements the IStatusListener
interface with implements IStatusListener.
5, 6 A status controller of type IStatusController is integrated in-
to the task by means of dependency injection.
7, 8 A logger object of type ITaskLogger is integrated into the
task by means of dependency injection.
The logger object can be used to display status information
on the smartHMI.
16 … 19 In the initialize() method, the status listener is registered on
the status controller.
The keyword this is used to add the BackgroundTask
class to itself as a status listener.
The status groups SAFETY_STOP and ERROR_GENERAL
are transferred during registration. In this way, the listener
is only informed of status changes in these status groups.
27 … 32 The onStatusSet method is called if a status is set with one
of the subscribed status groups. The status group and the
description of the set status are then logged.

582/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

KUKA Sunrise.StatusController
Line Description
34 … 39 The onStatusCleared method is called if a status is cleared
with one of the subscribed status groups. The status group
and the description of the cleared status are then logged.
41 … 45 In the dispose() method, the status listener is unregistered.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 583/667

KUKA Sunrise.StatusController KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

584/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming with a compliant robot

20 Programming with a compliant robot

20.1 Sensors and control

Without additional equipment, a standard industrial robot can only be op-

erated under position control. The aim of position control is to keep the
difference between the specified and actual robot position as small as
possible at all times.
In addition to position sensors for determining the current axis position,
sensitive robots also have an axis torque sensor in every axis for measur-
ing the current torque. These data enable the use of an impedance con-
troller in addition to position control, thus making it possible to implement
compliant behavior of the robot. The underlying model is a virtual spring
damper system with configurable values for stiffness and damping. Fur-
thermore, additional forces and force oscillations can be overlaid.
The special sensor technology and the available controller mechanisms
enable sensitive robots to react very quickly to process forces that occur.
This makes them particularly suitable for joining tasks and for
collaboration with humans.

20.2 Overview of controllers

Sensitive robots can be operated with different controllers. For each con-
trol type, a separate class is provided by the RoboticsAPI in the package
com.kuka.roboticsAPI.motionModel.controlModeModel. The shared super-
class is AbstractMotionControlMode.
Controller Description
Position controller Data type: PositionControlMode
The aim of position control is to execute the specified path
with the maximum possible positional accuracy and without
path deviation. As standard, external influences such as ob-
stacles or process forces are not taken into account.
Cartesian impedance control- Data type: CartesianImpedanceControlMode
ler
The Cartesian impedance controller is modeled on a virtual
spring damper system with configurable values for stiffness
and damping. This spring is extended between the setpoint
and actual positions of the TCP. This allows the robot to react
in a compliant manner to external influences.
Cartesian impedance control- Data type: CartesianSineImpedanceControlMode
ler with overlaid force oscilla-
Special form of the Cartesian impedance controller. In addi-
tion
tion to the compliant behavior, constant force setpoints and si-
nusoidal force oscillations can be overlaid. This controller can
be used, for example, to implement force-dependent search
runs and vibration motions for joining processes.
Axis-specific impedance con- Data type: JointImpedanceControlMode
troller
The axis-specific impedance controller is modeled on a virtual
spring damper. The values for stiffness and damping can be
configured for each axis.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 585/667

Programming with a compliant robot KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

20.3 Using controllers in robot applications

Description

In robot applications, the controller to be used is set separately for every

motion command. As standard, the following steps are required for this:

Procedure

1. Create the controller object of the desired controller data type.

2. Parameterize the controller object to define the control response.
3. Set the controller as the motion parameter for a motion command.

20.3.1 Creating a controller object

Description

To be able to use a controller, a variable of the desired controller data

type must first be created and initialized. As standard, the controller object
is generated using the standard constructor.

Syntax

ControlMode controlMode;
controlMode = new ControlMode();

Explanation of the syntax

Element Description
ControlMode Data type of the controller (subclass of AbstractMotion-
ControlMode)
controlMode Name of controller object

Example

Creating a Cartesian impedance controller:

CartesianImpedanceControlMode cartImpCtrlMode;
cartImpCtrlMode = new CartesianImpedanceControlMode();

20.3.2 Defining controller parameters

The parameters that can be set depend on the type of the controller used.
The individual controller classes in the KUKA RoboticsAPI provide specific
“set” and “get” methods for each parameter.
(>>> 20.5.2 "Parameterization of the Cartesian impedance controller"
Page 590)
(>>> 20.6.3 "Parameterization of the impedance controller with overlaid
force oscillation" Page 598)
(>>> 20.8 "Axis-specific impedance controller" Page 608)

586/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming with a compliant robot

20.3.3 Transferring the controller object as a motion parameter

Description

The controller object is transferred to a motion as a parameter using the

command setMode(…). If no controller object is transferred as a parame-
ter to a motion, the motion is automatically executed with position control.
Motions which use the Cartesian impedance controller must not contain
any poses in the proximity of singularity positions.

Syntax

object.move(motion.setMode(controlMode));

Explanation of the syntax

Element Description
motion Type: Motion
Motion to be executed
controlMode Type: Subclass of AbstractMotionControlMode
Name of controller object

20.4 Position controller

With position control, the motors are controlled in such a way that the cur-
rent position of the robot always matches the setpoint position specified
by the controller with just a minimal difference. The position controller is
particularly suitable in cases where precise positioning is required.
The position controller is represented by the class PositionControlMode.
The data type has no configurable parameters for adapting the robot.
If the controller mode of a motion is not explicitly specified, then the posi-
tion controller is used.

20.5 Cartesian impedance controller

The Cartesian impedance controller is represented by the class Cartesia-

nImpedanceControlMode.
As standard, the impedance controller refers to the coordinate system with
which the motion command is executed.
Examples:

• robot.move(…);
The impedance controller refers to the flange coordinate system of the
robot.
• gripper.move(…);
The impedance controller refers to the standard frame defined for grip-
per motions.
• gripper.getFrame("/TipCenter").move(...);
The impedance controller refers to the tool coordinate system that ex-
tends from the “TipCenter” frame on the gripper.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 587/667

Programming with a compliant robot KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Behavior of the robot

Under impedance control, the robot’s behavior is compliant. It is sensitive

and can react to external influences such as obstacles or process forces.
The application of external forces can cause the robot to leave the plan-
ned path.
The underlying model is based on virtual springs and dampers, which are
stretched out due to the difference between the currently measured and
the specified position of the TCP. The characteristics of the springs are
described by stiffness values, and those of the dampers are described by
damping values. These parameters can be set individually for every trans-
lational and rotational dimension.
If the robot is moved under impedance control, the programmed robot
configuration, e.g. the status value, cannot be guaranteed.

20.5.1 Calculation of the forces on the basis of Hooke’s law

If the measured and specified robot positions correspond, the virtual

springs are slack. As the robot’s behavior is compliant, an external force
or a motion command results in a deviation between the setpoint and ac-
tual positions of the robot. This results in a deflection of the virtual
springs, leading to a force in accordance with Hooke’s law.
The resultant force F can be calculated on the basis of Hooke’s law using
the set spring stiffness C and the deflection Δx:
F = C · Δx

Fig. 20-1: Virtual spring with spring stiffness C

1 Deflection Δx 4 Resulting force F

2 Virtual spring 5 Setpoint position
3 Actual position
If the robot is at a resistance, it exerts the calculated force. If it is posi-
tioned in free space, it moves toward the setpoint position. Due to internal
friction forces in the joints, path deviations occur on the way to the set-
point position, whose magnitude depends on the set spring stiffness. High-
er stiffness values lead to smaller deviations.
If the robot is already at the setpoint position and an external force is ap-
plied to the system, the robot yields to this force until the forces resulting
from compliance control cancel out the external forces.

Examples

The force exerted at the contact point depends on the difference between
the setpoint position and the actual position and the set stiffness.

588/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming with a compliant robot

Fig. 20-2: Force exerted on contact

As shown in the figure (>>> Fig. 20-2), a large position difference and low
stiffness can result in the same force as a smaller position difference and
greater stiffness. If the force is increased by a motion in a contact situa-
tion, the time required to reach this force differs if the Cartesian velocity is
identical.
If higher stiffness values are used, a desired force can be reached earlier,
as only a small position difference is required. Since the setpoint position
is reached quickly, a jerk can be produced in this way.

Fig. 20-3: Force over time (high stiffness, small position difference)

In the case of a large position difference and low stiffness, the force is
built up more slowly. This can be used, for example, if the robot moves to
the contact point and the impact loads are to be reduced.

Fig. 20-4: Force over time (low stiffness, large position difference)

Setpoint/actual deviations in more than one direction lead to deflection of

all the affected virtual springs. The magnitude and direction of the overall
force results from vector addition of the individual forces for each direc-
tion.
The deflection in the X direction by Δx and in the Y direction by Δy result
in force Fx in the X direction and Fy in the Y direction. The vector addition
results in the overall force Fres.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 589/667

Programming with a compliant robot KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 20-5: Overall force in the case of deflection in 2 directions

20.5.2 Parameterization of the Cartesian impedance controller

Under impedance control, the robot behaves like a spring. The character-
istics of this spring are defined by different parameters. This results in the
behavior of the robot.
With a Cartesian impedance controller, forces can be overlaid for all Car-
tesian degrees of freedom. Forces acting about an axis generate a torque.
For this reason, the overlaid torque and not the overlaid force is specified
for the rotational degrees of freedom. For the sake of simplification, the
terms “force” and “force oscillation” are taken to include the terms “torque”
and “torque oscillation” for the rotational degrees of freedom in the follow-
ing text.
CAUTION
In impedance control, inaccurate sensor information or incorrectly selec-
ted parameters (e.g. incorrect load data, incorrect tool) can be interpre-
ted as external forces, resulting in unpredictable motions of the robot.

The following controller properties can be defined individually for each

Cartesian degree of freedom:
• Stiffness
• Damping
• Force to be applied in addition to the spring
The following controller properties can be defined irrespective of the de-
gree of freedom:
• Stiffness of the redundancy degree of freedom
• Damping of the redundancy degree of freedom
• Limitation of the maximum force on the TCP
• Maximum Cartesian velocity
• Maximum Cartesian path deviation

20.5.2.1 Representation of Cartesian degrees of freedom

In the RoboticsAPI, the degrees of freedom of the Cartesian impedance

controller are represented by the Enum CartDOF (package: com.kuka.ro-
boticsAPI.geometricModel). The values of this Enum can be used to de-
scribe either each degree of freedom individually or the combination of a
number of degrees of freedom.

590/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming with a compliant robot

Enum value Description
CartDOF.X Translational degree of freedom in the X direction
CartDOF.Y Translational degree of freedom in the Y direction
CartDOF.Z Translational degree of freedom in the Z direction
CartDOF. Combination of the translational degrees of freedom
TRANSL in the X, Y and Z directions
CartDOF.A Rotational degree of freedom about the Z axis
CartDOF.B Rotational degree of freedom about the Y axis
CartDOF.C Rotational degree of freedom about the X axis
CartDOF.ROT Combination of rotational degrees of freedom about
the X, Y and Z axes
CartDOF.ALL Combination of all Cartesian degrees of freedom

20.5.2.2 Defining controller parameters for individual degrees of freedom

Description

Some parameters of the Cartesian impedance controller can be defined

individually for each Cartesian degree of freedom.
During programming, the Cartesian degrees of freedom for which the con-
troller parameter is to apply are specified first. The parametrize(…) meth-
od of the controller data types is used for this purpose. To define the de-
grees of freedom, one or more parameters of the type CartDOF are trans-
ferred to this method.
After this, the “set” method of the desired controller parameter is called
via the dot operator. This controller parameter is set to the value specified
as the input parameter of the set method for all degrees of freedom speci-
fied in parametrize(…).

Syntax

controlMode.parametrize(CartDOF.degreeOfFreedom_1
<, CartDOF.degreeOfFreedom_2,…>).setParameter(value);

Explanation of the syntax

Element Description
controlMode Type: CartesianImpedanceControlMode
Name of controller object
degreeOf- Type: CartDOF
Freedom_1,
List of degrees of freedom to be described
degreeOf-
Freedom_2,
…
setParame- Method for setting a controller parameter
ter(value)
A separate method is available for each settable parame-
ter (value = value of the parameter).

Example

A LIN motion is to be executed to a defined point under impedance con-

trol. The Cartesian impedance controller is configured in such a way that
the currently used TCP – here the robot flange frame – is compliant in the
Z direction.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 591/667

Programming with a compliant robot KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

CartesianImpedanceControlMode cartImpCtrlMode = new

CartesianImpedanceControlMode();

cartImpCtrlMode.parametrize(CartDOF.X,
CartDOF.Y).setStiffness(3000.0);
cartImpCtrlMode.parametrize(CartDOF.Z).setStiffness(1.0);
cartImpCtrlMode.parametrize(CartDOF.ROT).setStiffness(300.0);
cartImpCtrlMode.parametrize(CartDOF.ALL).setDamping(0.7);

robot.move(lin(getApplicationData().getFrame("/
P1")).setCartVelocity(800).setMode(cartImpCtrlMode));

20.5.2.3 Controller parameters specific to the degrees of freedom

Overview

The following methods are available for the parameters of the Cartesian
impedance controller that are specific to the degrees of freedom:
Method Description
setStiffness(…) Spring stiffness (type: double)
The spring stiffness determines the extent to which the robot yields to
an external force and deviates from its planned path.
Translational degrees of freedom (unit: N/m):

• 0.0 … 5000.0
Default: 2000.0
Rotational degrees of freedom (unit: Nm/rad):

• 0.0 … 300.0
Default: 200.0
Note: If no spring stiffness is specified for a degree of freedom, the
default value is used for this degree of freedom.
setDamping(…) Spring damping (type: double)
The spring damping determines the extent to which the virtual springs
oscillate after deflection.
For all degrees of freedom (without unit: Lehr’s damping ratio):

• 0.1 … 1.0
Default: 0.7
Note: If no spring damping is specified for a degree of freedom, the
default value is used for this degree of freedom.

592/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming with a compliant robot

Method Description
setAdditionalControl Force applied in addition to the spring (type: double)
Force(…)
The additional force results in a Cartesian force at the TCP. This
force acts in addition to the forces resulting from the spring stiffness.
Translational degrees of freedom (unit: N):

• Negative and positive values possible

Default: 0.0
Rotational degrees of freedom (unit: Nm):

• Negative and positive values possible

Default: 0.0
Note: As standard, the maximum Cartesian force that can be applied
is limited. If required, this limit value can be increased with setMax-
ControlForce(…).
Note: If no additional force is specified for a degree of freedom, the
default value is used for this degree of freedom.
Note: The force is overlaid without a delay. If the force to be overlaid
is too great, this can result in overloading of the robot and
cancelation of the program. The class CartesianSineImpedanceCon-
trolMode has the option of overlaying forces after a delay.

20.5.2.4 Controller parameters independent of the degrees of freedom

Some settings apply irrespective of the Cartesian degrees of freedom. The

set methods used to define these controller parameters belong to the
class CartesianImpedanceControlMode and are called directly on the con-
troller object.

Overview

The following methods are available for the parameters of the Cartesian
impedance controller that are independent of the degrees of freedom:
Method Description
setNullSpace Spring stiffness of the redundancy degree of freedom (type: double,
Stiffness(…) unit: Nm/rad)
The spring stiffness determines the extent to which the robot yields to
an external force and deviates from its planned path.

• ≥ 0.0
Note: If no spring stiffness is specified for the redundancy degree of
freedom, a default value is used for this degree of freedom.
setNullSpace Spring damping of the redundancy degree of freedom (type: double)
Damping(…)
The spring damping determines the extent to which the virtual springs
oscillate after deflection.

• 0.3 … 1.0
Note: If no spring stiffness is specified for the redundancy degree of
freedom, a default value is used for this degree of freedom.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 593/667

Programming with a compliant robot KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Method Description
setMaxControl Limitation of the maximum force on the TCP
Force(…)
The maximum force applied to the TCP by the virtual springs is limi-
ted. The maximum force required to deflect the virtual spring is thus
also defined. Whether or not the motion is to be aborted if the maxi-
mum force at the TCP is exceeded is also defined.
Syntax:

• setMaxControlForce(maxForceX, maxForceY, maxForceZ,

maxTorqueA, maxTorqueB, maxTorqueC, addStopCondition)
Explanation of the syntax:

• maxForceXΙYΙZ: maximum force at the TCP in the corresponding

Cartesian direction (type: double, unit: N)
‒ ≥ 0.0
Default: value stored in the machine data; can be requested
by the controller object using the method getMaxControl-
Force().
• maxTorqueAΙBΙC: maximum torque at the TCP in the correspond-
ing rotational direction (type: double, unit: Nm)
‒ ≥ 0.0
Default: value stored in the machine data; can be requested
by the controller object using the method getMaxControl-
Force().
• addStopCondition: cancelation of the motion if the maximum force
at the TCP is exceeded (type: boolean)
‒ true: motion is aborted.
‒ false: motion is not aborted.
Note: If the force limitation is only to be applied for individual degrees
of freedom, correspondingly high values must be assigned to those
degrees of freedom that are not to be limited.
Note: If no force limitation is defined, the default value from the ma-
chine data is used.
setMaxCartesian Maximum Cartesian velocity
Velocity(…)
The motion is aborted if the defined velocity limit is exceeded.
Syntax:

• setMaxCartesianVelocity(maxVelocityX, maxVelocityY,
maxVelocityZ, maxVelocityA, maxVelocityB, maxVelocityC)
Explanation of the syntax:

• maxVelocityXΙYΙZ: maximum permissible translational velocity at

the TCP in the corresponding Cartesian direction (type: double,
unit: mm/s)
‒ ≥ 0.0
• maxVelocityAΙBΙC: maximum permissible rotational velocity at the
TCP in the corresponding rotational direction (type: double, unit:
rad/s)
‒ ≥ 0.0
Note: If the velocity limitation is only to be applied for individual de-
grees of freedom, correspondingly high values must be assigned to
those degrees of freedom that are not to be limited.

594/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming with a compliant robot

Method Description
setMaxPath Maximum Cartesian path deviation
Deviation(…)
Defines the maximum permissible Cartesian path deviation from the
currently planned setpoint position for a compliant motion. The motion
is aborted if the defined maximum path deviation is exceeded.
Syntax:

• setMaxPathDeviation(maxDeviationX, maxDeviationY, max-

DeviationZ, maxDeviationA, maxDeviationB, maxDeviationC)
Explanation of the syntax:

• maxDeviationXΙYΙZ: maximum permissible path deviation at the

TCP in the corresponding Cartesian direction (type: double, unit:
mm)
‒ ≥ 0.0
• maxDeviationAΙBΙC: maximum permissible rotational deviation at
the TCP in the corresponding rotational direction (type: double,
unit: rad/s)
‒ ≥ 0.0
Note: If the path deviation is only to be applied for individual degrees
of freedom, correspondingly high values must be assigned to those
degrees of freedom that are not to be limited.

Example 1

A robot under impedance control is to be compliant in its redundant de-

gree of freedom in order to be able to respond to obstacles during the
motion. For this, stiffness and damping of the redundant degree of free-
dom are parameterized for the impedance controller.

CartesianImpedanceControlMode mode =
new CartesianImpedanceControlMode();
mode.setNullSpaceStiffness(10.0);
mode.setNullSpaceDamping(0.7);

Example 2

A robot is to move along a table plate in compliant mode. A Cartesian im-

pedance controller is parameterized for this. A high stiffness value is set
for the Z direction of the tool coordinate system in the TCP. An additional
force of 20 N is also to be applied. The motion is aborted if a force limit
of 50 N in the Z direction is exceeded. A low stiffness value is set in the
XY plane. The Cartesian deviation in the X and Y directions must not ex-
ceed 10 mm, however. Suitable higher values are specified for all other
parameters.

CartesianImpedanceControlMode mode =
new CartesianImpedanceControlMode();

mode.parametrize(CartDOF.Z).setStiffness(3000.0);
mode.parametrize(CartDOF.Z).setAdditionalControlForce(20.0);
mode.setMaxControlForce(100.0, 100.0, 50.0, 20.0, 20.0,
20.0, true);

mode.parametrize(CartDOF.X, CartDOF.Y).setStiffness(10.0);
mode.setMaxPathDeviation(10.0, 10.0, 50.0, 2.0, 2.0, 2.0);

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 595/667

Programming with a compliant robot KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

20.6 Cartesian impedance controller with overlaid force oscillation

The Cartesian impedance controller with overlaid force oscillation is a spe-

cial form of the Cartesian impedance controller. The force can be overlaid
separately for each Cartesian degree of freedom.
Force oscillations about an axis generate torque oscillations. Overlaying
torque oscillations can result in the generation of rotational oscillations.
Overlaying constant or sinusoidal forces causes the robot to move. Suita-
ble combinations of oscillations in the individual degrees of freedom can
be used to generate different motion patterns.
Using overlaid oscillations, it is possible to implement compliant pendulum
motions for search runs and vibrations in the tool for joining processes.
The Cartesian impedance controller with overlaid force oscillation is repre-
sented by the class CartesianSineImpedanceControlMode.

Behavior of the robot

In this form of impedance control, the overlaid force causes the robot to
leave the planned path in a targeted way. The new path is thus deter-
mined by a wide range of different parameters.
In addition to stiffness and damping, further parameters can be defined,
e.g. frequency and amplitude. The programmed velocity of the robot also
plays a significant role for the actual path.
Overlaying additional forces has a strong influence on the robot motion
and the forces exerted by the robot. For example, low stiffness and high
overlaid forces can cause the robot to accelerate suddenly.
Parameterization must therefore be carried out with caution if working
with force activations. For example, begin by overlaying low forces and
approach the appropriate force values step by step. In addition, the mo-
tion resulting from the overlaid force must always be tested in T1 mode
first.

20.6.1 Overlaying a simple force oscillation

By overlaying a simple force oscillation, the working point is diverted from

the planned path (= path without overlaid oscillations) and is instead
moved from the start point to the end point of the motion in a sinusoidal
path.

Example

The robot executes a relative motion in the Y direction of the tool coordi-
nate system in the TCP. A sinusoidal force oscillation in the X direction is
overlaid. The result is a wave-like path in the XY plane of the coordinate
system.

596/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming with a compliant robot

Fig. 20-6: Overlaying a simple force oscillation

1 Original path 4 Amplitude

2 Deflection Δx 5 New path
3 Wavelength
The maximum deflection Δx is the deviation from the original path in the
positive and negative X directions. The maximum deflection is determined
by the stiffness and amplitude which are defined for the impedance con-
troller in the Cartesian X direction, e.g.:
• Cartesian stiffness: C = 500 N/m
• Amplitude: F = 5 N
The maximum deflection results from Hooke’s law:
Δx = F / C = 5 N / (500 N/m) = 1 / (100 1/m) = 1 cm
The wavelength can be used to determine how many oscillations the robot
is to execute between the start point and end point of the motion. The
wavelength is determined by the frequency which is defined for the impe-
dance controller with overlaid force oscillation, as well as by the program-
med robot velocity.
Wavelength λ is calculated as follows:
λ = c / f = robot velocity / frequency

20.6.2 Overlaying superposed force oscillations (Lissajous curves)

Lissajous curves result when a sinusoidal force oscillation is overlaid in 2

different Cartesian directions. The superposition of the two oscillations
makes it possible to create very different forms for the path. The exact
path depends on a number of parameters.

Application

Two sinusoidal force oscillations of different frequencies can be super-

posed to generate vibrations at the TCP. For example, such vibrations can
remove tension and jamming which occur during an assembly process.

Example

A sinusoidal force oscillation is overlaid in both the X and Y directions of

the tool coordinate system in the TCP. The maximum deflections Δx and
Δy are determined by the stiffness and amplitude, which are defined for
the impedance controller in the Cartesian X and Y directions.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 597/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

In addition to the known parameters of the impedance controller, the

Programming with a compliant robot

phase offset between the two oscillations plays a significant role in the
path.

Fig. 20-7: Path of a Lissajous curve

1 Path without phase offset (frequency ratio X:Y = 2:1)

2 Path with phase offset (frequency ratio X:Y = 3:1)
The form of the path is mainly determined by the ratio of the two frequen-
cies and the phase offset between the two oscillations. The resulting
curve is always axisymmetric and point-symmetric. The set power ampli-
tude and stiffness for an oscillation direction results in its position ampli-
tude. The ratio between the two position amplitudes determines the ratio
between the width to the height of the curve.

20.6.3 Parameterization of the impedance controller with overlaid force oscil-

lation

The Cartesian impedance controller with overlaid force oscillation is a spe-

cial form of the standard impedance controller.
With a Cartesian impedance controller with overlaid force oscillation,
forces can be overlaid for all Cartesian degrees of freedom. Forces acting
about an axis generate a torque. For this reason, the overlaid torque and
not the overlaid force is specified for the rotational degrees of freedom.
For the sake of simplification, the terms “force” and “force oscillation” are
taken to include the terms “torque” and “torque oscillation” for the rotation-
al degrees of freedom in the following text.
CAUTION
In impedance control, inaccurate sensor information or incorrectly selec-
ted parameters (e.g. incorrect load data, incorrect tool) can be interpre-
ted as external forces, resulting in unpredictable motions of the robot.

The Cartesian impedance controller with overlaid force oscillation is para-

meterized in the same way as the standard impedance controller. The
controller parameters specific to the degrees of freedom and the controller
parameters independent of the degrees of freedom as described for the
standard impedance controller can be used in the same way for the impe-
dance controller with overlaid force oscillation.
(>>> 20.5.2 "Parameterization of the Cartesian impedance controller"
Page 590)

598/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming with a compliant robot

Exception: The setAdditionalControlForce(…) method of the class Carte-
sianImpedanceControlMode for overlaying a force to be applied in addi-
tion to the spring is available for the class CartesianSineImpedanceCon-
trolMode, but should not be used.
The setBias(…) method is available for overlaying constant forces in the
class CartesianSineImpedanceControlMode.

The following additional controller properties can be defined individually for

each Cartesian degree of freedom:
• Amplitude of the force oscillation
• Frequency of the force oscillation
• Phase offset of the force oscillation
• Superposed constant force
• Force limitation of the force oscillation
• Limitation of the deflection due to the force oscillation
The following additional controller properties can be defined irrespective of
the degree of freedom:
• Rise time of the force oscillation
• Hold time of the force oscillation
• Fall time of the force oscillation
• Overall duration of the force oscillation

20.6.3.1 Controller parameters specific to the degrees of freedom

Overview

The following methods are available for the parameters of the Cartesian
impedance controller with overlaid force oscillation that are specific to the
degrees of freedom:
Method Description
setAmplitude(…) Amplitude of the force oscillation (type: double)
Amplitude and stiffness determine the position amplitude.
Translational degrees of freedom (unit: N):

• ≥ 0.0
Default: 0.0
Rotational degrees of freedom (unit: Nm):

• ≥ 0.0
Default: 0.0
Note: If no amplitude is specified for a degree of freedom, the default
value is used for this degree of freedom.
setFrequency(…) Frequency of the force oscillation (type: double; unit: Hz)
Frequency and Cartesian velocity determine the wavelength of the
force oscillation.

• 0.0 … 15.0
Default: 0.0
Note: If no frequency is specified for a degree of freedom, the default
value is used for this degree of freedom.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 599/667

Programming with a compliant robot KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Method Description
setPhaseDeg(…) Phase offset of the force oscillation at the start of the force overlay
(type: double; unit: °)

• ≥ 0.0
Default: 0.0
Note: If no phase offset is specified for a degree of freedom, the de-
fault value is used for this degree of freedom.
setBias(…) Constant force overlaid (type: double)
Using setBias(…), a constant force can be overlaid in addition to the
overlaid force oscillation. This force adds to the force resulting from
the spring stiffness and defined force oscillation.
If a constant force is overlaid without an additional force oscillation,
this results in a force characteristic which rises as a function of the
rise time defined with setRiseTime(…) and then remains constant. se-
tRiseTime(…) belongs to the controller parameters that are independ-
ent of the degrees of freedom.
(>>> 20.6.3.2 "Controller parameters independent of the degrees of
freedom" Page 601)
If a constant force is overlaid in addition to a force oscillation, the
force oscillation is offset in the defined direction.
Translational degrees of freedom (unit: N):

• Negative and positive values possible

Default: 0.0
Rotational degrees of freedom (unit: Nm):

• Negative and positive values possible

Default: 0.0
Note: As standard, the maximum Cartesian force that can be applied
is limited. If required, this limit value can be increased with setMax-
ControlForce(…).
Note: If no additional constant force is overlaid for a degree of free-
dom, the default value is used for this degree of freedom.
setForceLimit(…) Force limitation of the force oscillation (type: double)
Defines the limit value that the overall force, i.e. the sum of the ampli-
tude of the force oscillation and additionally overlaid constant force,
must not exceed. If the overall force exceeds the limit value, the over-
laid force is reduced to the limit value.
Translational degrees of freedom (unit: N):

• ≥ 0.0
Default: Not limited
Rotational degrees of freedom (unit: Nm):

• ≥ 0.0
Default: Not limited
Note: If no force limit is specified for a degree of freedom, the default
value is used for this degree of freedom.

600/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming with a compliant robot

Method Description
setPositionLimit(…) Maximum deflection due to the force oscillation (type: double)
If the maximum permissible deflection is exceeded, the force is deac-
tivated. The force is reactivated as soon as the robot is back in the
permissible range.
Translational degrees of freedom (unit: mm):

• ≥ 0.0
Default: Not limited
Rotational degrees of freedom (unit: rad):

• ≥ 0.0
Default: Not limited
Note: If no maximum deflection is specified for a degree of freedom,
the default value is used for this degree of freedom.

Example

During a joining process, an oscillation about the Z axis of the tool coordi-
nate system in the TCP is to be generated. The Cartesian impedance
controller with overlaid force oscillation is used for this. With a stiffness of
10 Nm/rad and an amplitude of 15 Nm, the position amplitude is approx.
1.5 rad. The frequency is set to 5 Hz. In order to exert an additional
pressing force in the direction of motion, a constant force of 5 N is gener-
ated in the Z direction and superposed on the overlaid force oscillation
about the Z axis.

CartesianSineImpedanceControlMode sineMode =
new CartesianSineImpedanceControlMode();

sineMode.parametrize(CartDOF.Z).setStiffness(4000.0);
sineMode.parametrize(CartDOF.Z).setBias(5.0);

sineMode.parametrize(CartDOF.A).setStiffness(10.0);
sineMode.parametrize(CartDOF.A).setAmplitude(15.0);
sineMode.parametrize(CartDOF.A).setFrequency(5.0);

tool.getFrame("/TCP").move(linRel(0.0, 0.0, 10.0)

.setCartVelocity(10.0)
.setMode(sineMode));

20.6.3.2 Controller parameters independent of the degrees of freedom

Some settings apply irrespective of the Cartesian degrees of freedom. The

set methods used to define these controller parameters belong to the
class CartesianSineImpedanceControlMode and are called directly on the
controller object.

Overview

The following methods are available for the parameters of the Cartesian
impedance controller with overlaid force oscillation that are independent of
the degrees of freedom:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 601/667

Programming with a compliant robot KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Method Description
setTotalTime(…) Overall duration of the force oscillation (type: double; unit: s)
(>>> "Overall duration of the force oscillation" Page 602)

• ≥ 0.0
Default: Unlimited
setRiseTime(…) Rise time of the force oscillation (type: double; unit: s)

• ≥ 0.0
Default: 0.0
Note: If no rise time is specified for a degree of freedom, the default
value is used. This means that the amplitude rises abruptly to the de-
fined value without a transition. If the force to be overlaid is too great,
this can result in overloading of the robot and cancelation of the pro-
gram.
setHoldTime(…) Hold time of the force oscillation (type: double; unit: s)

• ≥ 0.0
Default: Unlimited
Note: If no hold time is specified for a degree of freedom, the default
value is used. This means that the overlaid force oscillation ends with
the corresponding motion.
setFallTime(…) Fall time of the force oscillation (type: double; unit: s)

• ≥ 0.0
Default: 0.0
Note: If no fall time is specified for a degree of freedom, the default
value is used. This means that the amplitude falls abruptly to zero
without a transition. If the drop in force is too great, this can result in
overloading of the robot and cancelation of the program.
setStayActiveUntil Response if the motion duration is exceeded (type: boolean)
PatternFinished(…)
If the force oscillation lasts longer than the motion, it is possible to
define whether the oscillation is terminated or continued after the end
of the motion.

• true: Oscillation is continued after the end of the motion.

• false: Oscillation is terminated at the end of the motion.
Default: false
Note: If the response when the motion duration is exceeded is not
specified, the default value is used.

Overall duration of the force oscillation

The overall duration is the sum of the rise time, hold time and fall time of
the force oscillation:
• Rise time
Time in which the amplitude of the force oscillation is built up.
• Hold time
Time in which the force oscillation is executed with the defined ampli-
tude.
• Fall time
Time in which the amplitude of the force oscillation is reduced back to
zero.

602/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Rise time, hold time and fall time of the force oscillation can be defined

Programming with a compliant robot

individually, or indirectly by defining the overall duration of the force oscil-
lation.
If the overall duration is defined using setTotalTime(…), the rise time and
fall time are defined automatically.
Calculation:

• Rise time = fall time = (1/frequency) 0.5

• Of the frequencies defined for the force oscillation (relative to all de-
grees of freedom), the frequency that results in the largest possible
rise and fall times is used for the calculation.
• If exclusively constant forces are overlaid, the frequency of all degrees
of freedom is 0.0 Hz. Rise and fall time are set to 0.0 s.
• If the calculated sum of rise time and fall time exceeds the defined
overall duration, the rise time and fall time are each set to 25% of the
overall duration and the hold time to 50%.
If the overall duration of the force oscillation is shorter than the duration of
the corresponding motion, the force oscillation ends before the end of the
motion. The response if the motion duration is exceeded is defined using
setStayActiveUntilPatternFinished(…).

20.7 Static methods for impedance controller with superposed force oscilla-
tion

Overview

The Cartesian impedance controller with overlaid force oscillation can also
be configured via static methods of the class CartesianSineImpedance-
ControlMode. This simplifies the programming, in particular of Lissajous
curves, as the user only has to specify a few parameters. The remaining
parameters which are important for the implementation are calculated and
set automatically. Default values are used for all other parameters. Addi-
tional settings are made as described using the parametrize(…) function
and the set methods of CartesianSineImpedanceControlMode.
• createDesiredForce(…): Static method for constant force
• createSinePattern(…): Static method for simple force oscillations
• createLissajousPattern(…): Static method for Lissajous curves
• createSpiralPattern(…): Static method for spirals

Specification of Cartesian planes

In contrast to simple oscillations, no individual degree of freedom is trans-

ferred to Lissajous curves and spirals, but rather the plane in which the
path is to run. The plane is specified via the Enum CartPlane (the pack-
age com.kuka.roboticsAPI.geometricModel).
Enum value Description
CartPlane.XY Path in the XY plane
CartPlane.XZ Path in the XZ plane
CartPlane.YZ Path in the YZ plane

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 603/667

Programming with a compliant robot KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

20.7.1 Overlaying a constant force

Description

The createDesiredForce(…) method overlays a constant force, that does

not change over time, in one Cartesian direction.

Syntax

controlMode = CartesianSineImpedanceControlMode
.createDesiredForce(CartDOF.degreeOfFreedom, force, stiff-
ness);

Explanation of the syntax

Element Description
controlMode Type: CartesianSineImpedanceControlMode
Name of controller object
degreeOf Type: CartDOF
Freedom
Degree of freedom for which the constant force is to be
overlaid.
force Type: double
Value of the overlaid constant force. Corresponds to the
call of setBias(…) for the specified degree of freedom.
Translational degrees of freedom (unit: N):

• ≥ 0.0
Rotational degrees of freedom (unit: Nm):

• ≥ 0.0
stiffness Type: double
Stiffness value for the specified degree of freedom
Translational degrees of freedom (unit: N/m):

• 0.0 … 5000.0
Rotational degrees of freedom (unit: Nm/rad):

• 0.0 … 300.0

20.7.2 Overlaying a simple force oscillation

Description

The createSinePattern(…) method overlays a simple force oscillation in

one Cartesian direction.

Syntax

controlMode = CartesianSineImpedanceControlMode.createSi-
nePattern(CartDOF.degreeOfFreedom, frequency, amplitude, stiff-
ness);

604/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming with a compliant robot

Explanation of the syntax

Element Description
controlMode Type: CartesianSineImpedanceControlMode
Name of controller object
degreeOf- Type: CartDOF
Freedom
Degree of freedom for which the force oscillation is to be
overlaid.
frequency Type: double
Frequency of the oscillation (unit: Hz)

• 0.0 … 15.0
amplitude Type: double
Amplitude of the oscillation which is overlaid in the direc-
tion of the specified degree of freedom
Translational degrees of freedom (unit: N):

• ≥ 0.0
Rotational degrees of freedom (unit: Nm):

• ≥ 0.0
stiffness Type: double
Stiffness value for the specified degree of freedom
Translational degrees of freedom (unit: N/m):

• 0.0 … 5000.0
Rotational degrees of freedom (unit: Nm/rad):

• 0.0 … 300.0

Example

From the current position, a relative motion of 15 cm is to be executed in

the Y direction. The motion is to run in a wave path with a deflection of
approx. 10 cm (derived from the amplitude and stiffness) and a frequency
of 2 Hz in the X direction.

CartesianSineImpedanceControlMode sineMode;

sineMode =
CartesianSineImpedanceControlMode.createSinePattern(CartDOF.X
, 2.0, 50.0, 500.0);

robot.move(linRel(0.0, 150.0,
0.0).setCartVelocity(100).setMode(sineMode));

20.7.3 Overlaying a Lissajous oscillation

Description

The createLissajousPattern(…) method is used to generate a 2-dimension-

al oscillation in one plane. The plane is transferred as a value of type
CartPlane. The other transferred parameters refer to the first degree of
freedom of the specified plane (example: for CartPlane.XY, the specified
values are relative to CartDOF.X).

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 605/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The parameters of the second degree of freedom of the plane are calcu-
Programming with a compliant robot

lated to produce a Lissajous curve with the following characteristics:

• Amplitude ratio, 1st degree of freedom : 2nd degree of freedom: 1 : 1
• Frequency ratio, 1st degree of freedom : 2nd degree of freedom: 1 :
0.4
• Phase offset between 1st and 2nd degree of freedom: ½ · pi

Syntax

controlMode = CartesianSineImpedanceControlMode.createLis-
sajousPattern(CartPlane.plane, frequency, amplitude, stiff-
ness);

Explanation of the syntax

Element Description
controlMode Type: CartesianSineImpedanceControlMode
Name of controller object
plane Type: Enum of type CartPlane
Plane in which the Lissajous oscillation is to be overlaid
frequency Type: double
Frequency of the oscillation for the first degree of free-
dom of the specified plane (unit: Hz)

• 0.0 … 15.0
The frequency for the second degree of freedom is cal-
culated as follows:

• frequency · 0.4
amplitude Type: double
Amplitude of the oscillation for both degrees of freedom
of the specified plane (unit: N)

• ≥ 0.0
stiffness Type: double
Stiffness values for both degrees of freedom of the speci-
fied plane (unit: N/m)

• 0.0 … 5000.0

Example

An oscillation in the form of a Lissajous curve with a frequency ratio X : Y

of 1 : 0.4 and a phase offset in Y of pi/2 is to be generated on the robot
flange. Path without phase offset (= blue line (>>> Fig. 20-7)).

CartesianSineImpedanceControlMode lissajousMode;

lissajousMode =
CartesianSineImpedanceControlMode.createLissajousPattern(Cart
Plane.XY, 10.0, 50.0, 500.0);

robot.move(linRel(0.0, 150.0,
0.0).setCartVelocity(100).setMode(lissajousMode));

606/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming with a compliant robot

20.7.4 Overlaying a spiral-shaped force oscillation

Description

The createSpiralPattern(…) method is used to generate a spiral-shaped

force oscillation in one plane.
The force characteristic is created by overlaying 2 sinusoidal force oscilla-
tions. The oscillations are shifted in phase by π/2 (90°). The amplitudes of
the oscillations rise constantly up to the defined value and then return to
zero. This results in a spiral pattern which extends up to the defined am-
plitude value and then contracts again.
In the resulting robot motion, the TCP moves along this spiral. The Carte-
sian extent of the spiral depends on the values defined for stiffness and
amplitude as well as any obstacles present.
The plane in which the spiral-shaped oscillation is to be overlaid is trans-
ferred as a value of type CartPlane. The values defined for the parame-
ters stiffness, frequency and amplitude are identical for both degrees of
freedom of the plane.
In addition, a value is transferred for the total time of the force oscillation.
The time is divided evenly between the upward and downward motion of
the oscillation:
Rise time = Total time / 2
Hold time = 0
Fall time = Total time / 2

Syntax

controlMode = CartesianSineImpedanceControlMode.createS-
piralPattern(CartPlane.plane, frequency, amplitude, stiffness,
totalTime);

Explanation of the syntax

Element Description
controlMode Type: CartesianSineImpedanceControlMode
Name of controller object
plane Type: Enum of type CartPlane
Plane in which the spiral-shaped oscillation is to be over-
laid
frequency Type: double
Frequency of the oscillation for both degrees of freedom
of the specified plane (unit: N)

• 0.0 … 15.0
amplitude Type: double
Amplitude of the oscillation for both degrees of freedom
of the specified plane (unit: N)

• ≥ 0.0
stiffness Type: double
Stiffness values for both degrees of freedom of the speci-
fied plane (unit: N/m)

• 0.0 … 5000.0

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 607/667

Programming with a compliant robot KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Element Description
totalTime Type: double
Total time for the spiral-shaped oscillation. The time is
divided evenly between the upward and downward mo-
tion of the oscillation (unit: s).

• ≥ 0.0

Example

At the current position of the robot flange, a spiral-shaped force oscillation

is to be overlaid in the XY plane of the flange coordinate system. The
force is to rise helically up to a maximum value of 100 N. Once per sec-
ond, the force characteristic is to turn around the start point of the spiral
(frequency of the force oscillation: 1.0 Hz). The force spiral must rise and
fall within 10 seconds.

CartesianSineImpedanceControlMode spiralMode;
spiralMode =
CartesianSineImpedanceControlMode.createSpiralPattern(CartPla
ne.XY, 1.0, 100, 500, 10);
robot.move(positionHold(spiralMode, 10, TimeUnit.SECONDS));

The number of turns is a function of the total time for a turn (tperiod). The
time for a turn corresponds to the duration of an oscillation period, e.g.:
• Frequency of the force oscillation: f = 1.0 Hz
• Total time: t = 10 s
The number of turns is calculated as follows:
NumberTurns = Total time / tPeriod = 10 s / 1 s = 10
tPeriod = 1 / f = 1 / 1.0 Hz = 1 s
The maximum deflection results from Hooke’s law:
Δx = F / C = 100 N / (500 N/m) = 0.2 m = 20 cm

20.8 Axis-specific impedance controller

The axis-specific impedance controller is represented by the class JointIm-

pedanceControlMode. In this control mode, the robot’s behavior is compli-
ant.
The underlying model uses virtual springs and dampers. Unlike with the
Cartesian impedance controller, however, these springs and dampers are
stretched out due to the difference between the currently measured and
the specified axis positions. For this reason, singularity positions of the ro-
bot have no influence on the impedance behavior.

20.8.1 Parameterization of the axis-specific impedance controller

CAUTION
In impedance control, inaccurate sensor information or incorrectly selec-
ted parameters (e.g. incorrect load data, incorrect tool) can be interpre-
ted as external forces, resulting in unpredictable motions of the robot.

608/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming with a compliant robot

If the application is paused with the spring tensioned under impedance
control, the motion command is interrupted. When the application is re-
sumed, the spring is tensioned again. This can result in jerky motion of
the robot.

The following controller properties can be defined individually for each ax-
is:
• Stiffness
• Damping

20.8.2 Methods of the axis-specific impedance controller

Overview

The following set methods are available for the axis-specific impedance
controller:
Method Description
setStiffness(…) Spring stiffness (Type: double[]; unit: Nm/rad)
The axis-specific spring stiffness determines the degree of compliance
of an axis when force is applied.

• ≥ 0.0
Default: 1000
Note: The spring stiffness must be specified for every axis.
setDamping(…) Spring damping (type: double[]; without unit: Lehr’s damping ratio)
The axis-specific spring damping determines the extent to which the
virtual springs oscillate after deflection.

• 0.0 … 1.0
Default: 0.7
Note: The spring damping must be specified for every axis.
setStiffness Spring stiffness (type: double, unit: Nm/rad)
ForAllJoints(…)
A value determines the degree of compliance of all axes when force
is applied.

• ≥ 0.0
setDamping Spring damping (type: double; without unit: Lehr’s damping ratio)
ForAllJoints(…)
A value determines the extent to which the virtual springs in all axes
oscillate after deflection.

• 0.0 … 1.0

Constructor syntax

JointImpedanceControlMode jointImp =
new JointImpedanceControlMode(stiffnessJ1 ... stiffnessJ7);

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 609/667

Programming with a compliant robot KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Explanation of the syntax

Element Description
jointImp Type: JointImpedanceControlMode
Name of controller object
stiffnessJ1 Type: double; unit: Nm/rad
…
Axis-specific spring stiffnesses
stiffnessJ7
The number of values is dependent on the axis selection
(here: 7 axes).

Example 1

7 axes are to be controlled using the axis-specific impedance controller.

Initial values for the axis-specific spring stiffnesses are defined in the con-
structor of the controller. The stiffness for axis A4 is to be modified subse-
quently. The spring damping is to be identical for all axes.

JointImpedanceControlMode jointImp =
new JointImpedanceControlMode(2000.0, 2000.0, 2000.0,
2000.0, 100.0, 100.0, 100.0);
//...
jointImp.setStiffness(2000.0, 2000.0, 2000.0, 1500.0,
100.0, 100.0, 100.0);
jointImp.setDampingForAllJoints(0.5);

Example 2

7 axes are to be controlled using the axis-specific impedance controller.

Initial values for the axis-specific spring stiffnesses are defined in the con-
structor of the controller. The spring stiffness and spring damping are sub-
sequently to be identical for all axes.

JointImpedanceControlMode jointImp =
new JointImpedanceControlMode(2000.0, 2000.0, 2000.0,
2000.0, 100.0, 100.0, 100.0);
//...
jointImp.setStiffnessForAllJoints(100);
jointImp.setDampingForAllJoints(0.5);

20.9 Holding the position under servo control

Description

Using the motion command positionHold(…), the robot can hold its Carte-
sian setpoint position over a set period of time and remain under servo
control.
If the robot is operated in compliance control, it can remove itself from its
setpoint position. Whether, how far and in which direction the robot moves
from the current Cartesian setpoint position (= position at the start of the
command positionHold(…)) depends on the set controller parameters and
the resulting forces. In addition, the compliant robot under servo control
can be forced off its setpoint position by external forces.

Syntax

object.move(positionHold(controlMode, time, unit));

610/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Programming with a compliant robot

Explanation of the syntax

Element Description
controlMode Type: subclass of AbstractMotionControlMode
Name of controller object
time Type: long
Indicates how long the specified controlMode is to be
held. The value must be >= 0. A value of < 0 indicates
infinite.
The time unit is defined with unit.
unit Type: enum of type TimeUnit
Unit of the specified time
The Enum TimeUnit is an integral part of the standard
Java library.

Example

The robot is to be held in its current position for 10 seconds. During this
time, the robot is switched to “soft” mode in the Cartesian X direction.

CartesianImpedanceControlMode controlMode = new

CartesianImpedanceControlMode();

controlMode.parametrize(CartDOF.X).setStiffness(1000.0);
controlMode.parametrize(CartDOF.ALL).setDamping(0.7);

robot.move(positionHold(controlMode, 10, TimeUnit.SECONDS));

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 611/667

Programming with a compliant robot KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

612/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Diagnosis
21 Diagnosis

21.1 Field bus diagnosis

WorkVisual can be used for precise error analysis. Additional

information about field bus diagnosis with WorkVisual is contained in the
WorkVisual documentation.

If the robot controller is used as a PROFINET master or device, hard-

ware problems can result in an inability to access bus devices. In this
case, use of a diagnostic tool, such as WorkVisual, Step 7 or Wire-
Shark, is recommended.

21.1.1 Displaying general field bus errors

Description

The general error state of the connected field buses can be displayed on
the smartHMI.

Procedure

1. Select the robot controller tile at the Station level.

The status indicator of the Field buses tile indicates the collective
state of all field buses connected to the controller.
2. Select the Field buses tile.
The detail view opens with error information about the currently con-
nected field buses.

21.1.2 Displaying the error state of I/Os and I/O groups

Description

The status indicator in the I/O groups area of the navigation bar of the
smartHMI displays the state of the configured I/O groups.
• The lower indicator shows the collective state of all configured I/O
groups.
• The upper indicator shows the state of the selected I/O group.

Procedure

• In the navigation bar, select the desired I/O group from I/O groups.
The detail view of the I/O group opens. Any faulty inputs/outputs are
indicated.

If PROFINET is used and errors occur at individual terminals, not only

the affected inputs/outputs, but all configured PROFINET I/Os are
marked as faulty.

21.2 Displaying a log

Description

A log of the events and changes in state of the system can be displayed
on the smartHMI.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 613/667

Diagnosis KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Procedure

1. Open the Station level or the Robot level.

2. Select the Log tile. The Log view opens.
If the view is opened via the Robot level, only those log entries are
displayed as standard which affect the robot selected in the navigation
bar.

21.2.1 “Log” view

Overview

Fig. 21-1: View of log

Item Description
1 Refresh button
Refreshes the displayed log entries. As standard, the most re-
cent entry is shown at the top of the list after refreshing. If a
time filter is active, the oldest entry is shown at the top of the
list.
2 List of log entries
(>>> "Log event" Page 615)

614/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Diagnosis
Item Description
3 Filter settings button
Opens the Filter settings window in which the log entries can
be filtered according to various criteria.
4 Filter settings display
The currently active filters are displayed here.

Log event

The log entries contain various information pertaining to each log event.

Fig. 21-2: Information about the log event

Item Description
1 Log level of the event
(>>> "Log level" Page 615)
2 Date and time of the log event (system time of the robot con-
troller)
3 Source of the log event (robot or station)
4 Button to maximize/minimize the detail view
The button is only available if more than 2 symptoms are
present.
5 Symptoms of the log event (detail view)
As standard, up to 2 symptoms are displayed per event.
6 Category or brief description of the log event

Log level

The following icons display the log level of an event:

Icon Description
Error
Critical event which results in a system error state
Warning
Critical event which can result in an error
Information
Non-critical event or information pertaining to the change in
state

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 615/667

Diagnosis KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

21.2.2 Filtering log entries

Precondition

• The Log view is open.

Procedure

1. Touch the Filter settings button. The Filter settings window opens.
2. Select the desired filters with the appropriate buttons.
3. Touch the Filter settings button or an area outside the window.
The Filter settings window is closed and the selected filters are acti-
vated.

The filters are reset when the Log view is closed. When the view is re-
opened, the default settings are reactivated.

Description

Fig. 21-3: “Filter settings” window

Item Description
1 Filter Source(s)
The log entries can be filtered according to the sources that
caused the log event.

• Station: All log entries are displayed which affect the station
and the inputs/outputs of field buses.
• Robot: Only those log entries are displayed which affect the
robot selected in the navigation bar.
Default for log at Station level: All sources are selected.
Default for log at Robot level: The source is the robot selected
in the navigation bar.
2 Filter Timespan
A time filter can be activated to display only the log entries of a
specific timespan.
Default: All (no time filter active)

616/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Diagnosis
Item Description
3 Filter Level
The log entries can be filtered according to their log level.
Default: Info, warning, error (no filter active for log level)

21.3 Displaying error messages

If errors occur while a robot application is being executed, the correspond-

ing error messages are displayed on the smartHMI (application view). Er-
rors during execution of background tasks are not displayed there.

Fig. 21-4: Structure of error message (example)

Item Description
1 Time stamp
Time at which the error occurred
2 Level
Log level of the message
Errors have the log level Error.
3 Error message
4 Information when application is terminated, e.g. following a real-
time error

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 617/667

Diagnosis KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Item Description
5 Error type
Errors are defined as Java classes. The name of the class and
the corresponding package are displayed. The error message
follows (see item 3).
6 Stack trace
The method calls which led to the error are displayed in as-
cending order. The methods are specified with their full identifi-
ers. In addition, the number of the program line in which the er-
ror occurred is displayed.
The stack trace can be used to determine the program position
at which the method which ultimately caused the error was
called.
Example, read from the bottom to the top:

• Origin of the error: run() method of the application Inexecu-

tableMotion.java, line 37
• In line 37 of the application, the move(…) method of the ro-
bot class was called. In the source code of the Robot.java
class, the error occurred in line 612 when the move(…)
method of the PhysicalObject class was called.
• ...
• The actual error occurred in line 220 in the source code of
the ExecutionContainer.java class when the validate(…)
method was called.
Often, an error is the result of a chain of preceding errors. In this case,
the entire error chain is displayed in descending order.

Fig. 21-5: Display of error chain (example)

618/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Diagnosis
Item Description
1 Consequential error
The last element in the error chain is displayed here. In the ex-
ample, this is an error of type RuntimeException which occurred
during execution of the run() method in line 38 of the applica-
tion EmbeddedExceptionApplication.java.
2 Causative error
The display of the causative error is always initiated as follows:

• Caused by: Error type

In the example, the causative error is of type Exception and oc-
curred when the calculateValue(…) method of the Utils class
was called. The entire error chain is thus displayed up to the
actual cause of error.

21.4 Displaying messages of the virus scanner

Description

The Virus scanner view contains the following data:

• Virus scanner state: active / inactive
• Version of virus definition file: Version of the virus definition file
• Messages about detected viruses
The message generated when a virus is found contains the following
data:
‒ Name of the virus
‒ Name of the file in which the virus is located, including path speci-
fication
‒ Date and time of detection
If viruses are found, the status display of the Virus scanner tile
switches to “Warning”. The status of the files affected by the viruses is
automatically set to “Quarantine”.

If the robot can no longer be moved due to a virus infection, the follow-
ing options are available:
• Reinstall the System Software on the robot controller.
• If the robot can still not be moved, create the diagnosis package
KRCDiag and contact KUKA Service.

Precondition

• Virus scanner is installed.

Procedure

• Select the robot controller tile at the Station level and then the Virus
scanner tile. The Virus scanner view opens.

Messages from the virus scanner can also be displayed using the Log
tile.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 619/667

Diagnosis KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

21.5 Collecting diagnostic information for error analysis at KUKA

For error analysis, KUKA Customer Support requires diagnostic data from
the robot controller.
For this purpose, a ZIP file called KRCDiag is created, which can be ar-
chived on the robot controller under D:\DiagnosisPackages or on a USB
stick connected to the robot controller. The diagnosis package KRCDiag
contains the data which KUKA Customer Support requires to analyze an
error. These include information about the system resources, machine da-
ta and much more.
Sunrise.Workbench can also be used to access the diagnostic information.
For this purpose, either an existing diagnosis package is loaded from the
robot controller or a new package is created.
Projects and applications are not included in the diagnosis package. It is
advisable to transfer these data separately, as they can contain impor-
tant information for troubleshooting.

Recommendation: If possible, only collect diagnostic information when

the robot is stationary.

If the collection of diagnostic information fails while an application is run-

ning, stop and cancel the application and restart the diagnostic process.

21.5.1 Creating a diagnosis package with the smartHMI

Description

With this procedure, the diagnosis package KRCDiag can be created and
archived on the robot controller under D:\DiagnosisPackages or on a USB
stick.

Procedure

1. For archiving to a USB stick: Plug the USB stick into the robot control-
ler and wait until the LED on the USB stick remains permanently lit.
2. In the main menu, select Diagnosis > Create diagnosis package
and select the desired file location.
• Hard drive
• USB stick
The diagnostic information is compiled. Progress is displayed in a win-
dow. Once the operation has been completed, this is also indicated in
the window. The window is then automatically hidden again.

21.5.2 Creating a diagnosis package with the smartPAD

Description

This procedure uses keys on the smartPAD instead of menu items. It can
thus also be used if the smartHMI is not available.
The KRCDiag diagnosis package is created and archived on the robot
controller under D:\DiagnosisPackages.
The key sequence described in the procedure must be executed within
2 seconds.

620/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Diagnosis
Procedure

1. Press the “Main menu” key and hold it down.

2. Press the keypad key twice.
3. Release the “Main menu” key.
The diagnostic information is compiled. Progress is displayed in a win-
dow. Once the operation has been completed, this is also indicated in
the window. The window is then automatically hidden again.

21.5.3 Creating a diagnosis package with Sunrise.Workbench

Precondition

• Network connection to the robot controller

Procedure

1. Right-click on the project in the Package Explorer and select Sunrise

> Create diagnosis package from the context menu. The wizard for
creating the diagnosis package opens.
2. Select Browse... and navigate to the directory in which the diagnosis
package KRCDiag is to be created. If necessary, create a folder for
the diagnosis package by clicking on Create new folder. Confirm with
OK.
3. Click on Next >. The diagnosis package is created in the specified
folder.
4. To navigate to the folder in which the diagnosis package was created,
e.g. to send it directly by e-mail, click on Open target folder in Win-
dows Explorer.
5. Click on Finish. The wizard is closed.

Projects and applications are not included in the diagnosis package. It is

advisable to transfer these data separately, as they can contain impor-
tant information for troubleshooting.

21.5.4 Loading existing diagnosis packages from the robot controller

Precondition

• Network connection to the robot controller

Procedure

1. Right-click on the project in the Package Explorer and select Sunrise

> Create diagnosis package in the context menu. The wizard for cre-
ating the diagnosis package opens.
2. Select Browse... and navigate to the directory in which the diagnosis
package KRCDiag is to be copied. If necessary, create a folder for the
diagnosis package by clicking on Create new folder. Confirm with
OK.
3. Activate the radio button Load existing diagnosis packages from
controller and select the desired diagnosis packages.
4. Click on Next >. The diagnosis packages are copied into the specified
folder.
If the folder already contains a diagnosis package of the same name,
a user dialog is displayed. The copying operation can be canceled.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 621/667

Diagnosis KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

5. To navigate to the folder into which the diagnosis packages were cop-
ied, e.g. to send them directly by e-mail, click on Open target folder
in Windows Explorer.
6. Click on Finish. The wizard is closed.

622/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Remote debugging
22 Remote debugging
Precondition

The remote debugging functionality is deactivated by default. In order to

be able to use the functionality, the following preconditions must be met:
• The parameter Allow debugging of applications is activated in the
station configuration.
(>>> 10.4.2 "Allow debugging of applications" Page 209)
• The modified station configuration has been installed on the robot con-
troller.
(>>> 10.5.1 "Installing system software on the robot controller"
Page 213)
If these preconditions are not met, an error message will be displayed on
attempting to start remote debugging with Sunrise.Workbench on the robot
controller:
• Setup of remote connection failed.

Target group

Use of remote debugging requires the following user knowledge:

• Advanced knowledge of Java and Eclipse

Description

Remote debugging is used for the discovery and diagnosis of errors in

programs.
Remote debugging is carried out using Sunrise.Workbench for applications
and background tasks running on the controller.
Since remote debugging is largely identical for applications and back-
ground tasks, the term “task” is used generically below.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 623/667

Remote debugging KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

22.1 Debugging session sequence

Step Description
1 Starting a debugging session
When starting a debugging session, a remote connection is
established between Sunrise.Workbench and the robot con-
troller. The project in the workspace of Sunrise.Workbench
and the active project on the robot controller are automati-
cally checked for consistency and synchronization is re-
quested if required.
(>>> 22.1.2 "Starting the debugging session" Page 625)
2 Performing remote debugging of the task
The programmer uses break points to define the positions
in the program code at which execution of the task is to be
interrupted during remote debugging.
If remote debugging is to be carried out for an application
that has not yet been started, the application must be star-
ted manually via the smartPAD once the remote connection
has been established.
Once task execution has been stopped at a break point,
further program execution can be controlled by Sun-
rise.Workbench by executing the source code of the task
step by step. On completion of a step, task execution is au-
tomatically stopped.
(>>> 22.3.2 "Break points" Page 631)
3 Using debugging functions
While task execution is interrupted, debugger functions,
such as the observation and modification of variable values,
can be used. Adaptation of the source code is also possi-
ble.
(>>> 22.3.6 "Variables view" Page 646)
(>>> 22.3.7 "Monitoring processes" Page 650)
(>>> 22.3.8 "Modifying source code" Page 653)
4 Ending a debugging session
When ending a debugging session, the remote connection
to the controller is disconnected. Execution of the running
task can now no longer be influenced by Sunrise.Work-
bench. If modifications have been made to the code, project
synchronization is offered.
If, when the remote debugging connection is terminated,
the task is currently paused at a break point, the program
is automatically resumed after this termination.
(>>> 22.1.3 "Ending the debugging session" Page 626)

22.1.1 Remote debugging of tasks

Description

Remote debugging is used to detect and diagnose errors in programs and

tasks.

624/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Tools that support this process are called debuggers. The remote debug-

Remote debugging
ger integrated into Sunrise.Workbench is based on the standard Java and
Eclipse debugger.
Eclipse enables the debugging of applications that are executed in a dif-
ferent Java runtime environment or on different physical machines. In the
case of remote debugging of tasks, the Sunrise.Workbench debugger is
used; the task itself is executed on the controller.
During remote debugging, a connection is established between Sun-
rise.Workbench and the robot controller. A debugging session is started in
this way. During remote debugging, the execution of tasks running on the
controller can be monitored via Sunrise.Workbench and it is possible to in-
fluence program execution. Errors can be diagnosed and the source code
can be optimized.
The Debugging perspective contains the most important views for remote
debugging.
While a debugging session is running, the smartPAD is used for starting
applications and issuing the motion enable signal.

All safety functions configured for the project are also active during re-
mote debugging.

Remote debugging of tasks running on the controller is described below.

General knowledge of remote debugging is assumed. The most important
fundamentals are summarized in the chapters. (>>> 22.3 "Fundamentals
of remote debugging" Page 630)

Overview

The functionalities offered by the debugger include the following:

• Performance of online diagnosis
• Stopping program execution at defined positions using break points
• Line-by-line or section-by-section execution of the source code of run-
ning tasks
• Tracking of the process by means of observation of variables and
monitoring expressions
• Modification of variable values
• Setting of break points if definable exceptions occur during program
execution

22.1.2 Starting the debugging session

Description

To start a debugging session, a remote connection must be established

between Sunrise.Workbench and the robot controller.
Once the first active break point has been reached, execution of the cor-
responding task is paused and the functions of the debugger can be used.
(>>> 22.3.2 "Break points" Page 631)

Precondition

• Network connection between robot controller and development com-

puter
• The project that is active on the robot controller is located in the work-
space of Sunrise.Workbench.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 625/667

Remote debugging KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Procedure

1. Select the desired project in the Project Explorer.

2. Click on the Debug project button.
The system scans the robot controller for existing project data. If the
scan fails, the cause of the error is displayed in a message.
3. If the scan is successful, the Project synchronization window opens.
Select the desired synchronization direction. (>>> 9.5 "Project synchro-
nization" Page 199)
There must be no project on the controller at the time of synchroni-
zation, or the existing project must differ from the local project. If the
projects are identical, the synchronization dialog is not displayed and
the remote debugging session is started immediately.

4. Click on Execute.
5. The system signals that the remote connection to the robot controller
has been established successfully. The remote connection is establish-
ed with OK and the debugging session is started.
6. When the first active break point is reached, the corresponding task is
paused.
If the Debugging perspective is not active, the dialog Confirm
change of perspective is displayed in Sunrise.Workbench. It is rec-
ommended that the dialog is ended with Yes to switch to the Debug-
ging perspective of Sunrise.Workbench.
In the case of a change of perspective, the decision in the dialog
box can be saved with Remember my decision.

(>>> 22.3.1 "Overview of user interface – “Debugging” perspective"

Page 630)
Once the task has been paused, its source code is opened in the edi-
tor area. The current position of the command pointer is indicated by
the fact that the next command line to be executed is selected.
(>>> 22.3.3 "Command pointer" Page 637)

22.1.3 Ending the debugging session

Description

In order to end the debugging session correctly, the remote connection

between Sunrise.Workbench and the robot controller must be disconnec-
ted. If modifications have been made to the code during remote debug-
ging, synchronization of the project is offered.

Precondition

• Network connection between robot controller and development com-

puter
• The project that is active on the controller is located in the workspace
of Sunrise.Workbench.

Procedure

1. Click on Stop debug mode.

During an active debugging session, this replaces the Debug project
button.
2. If modifications were made to the source code of the task during the
debugging session, the Retain project changes dialog opens:

626/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Remote debugging
• Synchronize project is used to synchronize the project and trans-
fer the changes to the controller.
• With Cancel, the changes are only saved permanently for the
project in the workspace of Sunrise.Workbench. On the controller,
the changes are deleted after switching off and back on.

NOTICE
It is advisable to use the Synchronize project option, as the system re-
sponse may otherwise be different after a reboot. If the reboot is not
carried out immediately, these changes in behavior may be unexpected
and could result in damage to the machine.

NOTICE
If execution of a task is paused when the connection is disconnected,
task execution is resumed automatically immediately after disconnection.
This also applies to the running application. In Automatic mode, and in
the Test modes if the enabling switch and Start button are pressed, the
robot may move. It is thus advisable to disconnect the remote connec-
tion only if the application has been terminated, or to pause motion exe-
cution first by pressing the Start button on the smartPAD.

22.2 Debugging tasks

Remote debugging influences the time response of tasks. The time re-
sponse may therefore deviate from the real time response during
normal execution of the task.

NOTICE
Irrespective of the mode, the system response may change. Debugging
of a task in Automatic mode must be carried out with particular care.
Interventions that result in a change of state must be tested in Manual
Reduced Velocity mode (T1).
Interventions and commands that cause a change of state include:
• Modification of program execution
• Execution of additional commands
• Motion commands
• Modification of variables
• Modification of the source code during debugging
• Setting inputs/outputs
• Changes of values, e.g. by calling set methods
This can lead to deviations from the program execution of the task. The
deviations may have an effect beyond the duration of the debugging
session. Unexpected robot motions are also possible.

Overview

Debugging can be performed for all tasks running on the controller. In or-
der to debug an application, it may be necessary to start the application
via the smartPAD.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 627/667

Remote debugging KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The smartPAD is also required during the debugging of tasks, e.g.:

• Issuing motion enable signal
• Starting applications
• Pausing motion commands
• Executing motion commands in the test modes
• Stopping an application prematurely

As soon as the first active break point is reached after the remote connec-
tion has been established, execution of the corresponding task can be
controlled via Sunrise.Workbench. Various functions are available for this.
The selected function determines the command line up to which the task
is continued.
If task execution is paused during debugging, additional functions are
available and changes can be made to the source code:
• Available functions:
(>>> 22.3.5 "Overview of the toolbar in the “Debugging” view"
Page 640)
• Additional functions of the debugger:
(>>> 22.3.6 "Variables view" Page 646)
(>>> 22.3.7 "Monitoring processes" Page 650)
• Information about modification of the source code during debugging:
(>>> 22.3.8 "Modifying source code" Page 653)

22.2.1 Remote debugging of a robot application

Description

A possible procedure for debugging a robot application is described below.

A running application can be ended via the smartPAD during debugging.
In this case, all break points are temporarily deactivated to ensure that
the application is terminated correctly.

If the application for which debugging is being carried out does not con-
tain any active break points, it is executed completely without stopping
and then terminated.

Precondition

• Debugging session started

• Application started in accordance with the selected operating mode

Procedure

1. On reaching an active break point, the application is stopped by the

debugger. Program execution can now be influenced by Sunrise.Work-
bench.
2. At the break point, pressing the corresponding button in the toolbar of
the Debugging view or using the corresponding keyboard shortcut de-
fines the step at which the application is to be resumed.
3. The application is resumed until the command line defined by select-
ing the function is reached. If a code section to be executed contains
motion commands, this has a special effect on the sequence.
4. In order to continue the application on reaching a synchronous motion
command or to execute an asynchronous motion command, the follow-

628/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

ing actions must additionally be carried out on the smartPAD in ac-

Remote debugging
cordance with the operating mode:
• T1, T2:
‒ Press and hold down the enabling switch.
‒ Press and hold down the Start key.
• AUT:
In AUT mode, no additional operator action is required. The
motion is executed immediately.
5. Once the program section has been executed, the application is stop-
ped.
Exception: With Resume, the application is continued until the next
break point or the end of the application is reached.
6. Debugging functions, such as the observation of variables or the
changing of values, can be used between the individual steps.

22.2.2 Remote debugging of a background task

Description

Debugging can also be carried out for background tasks. If a background

task contains active break points, execution of the background task is
stopped at these points during a debugging session.
Debugging of background tasks is essentially carried out in the same way
as debugging of applications. Manual background tasks must be started
manually by the user. Furthermore, background tasks should not contain
motion commands. Debugging of background tasks is thus not affected by
the selected operating mode.

Precondition

• Existing remote connection

• All background tasks are running automatically on the controller.
Non-automatic background tasks must be started manually by the
user.

Procedure

1. On reaching an active break point, the background task is stopped by

the debugger. Program execution can now be influenced by Sun-
rise.Workbench.
2. At the break point, pressing the corresponding button in the toolbar of
the Debugging view or using the corresponding keyboard shortcut de-
fines the step at which the application is to be resumed.
3. The background task is resumed until the command line defined by
selecting the function is reached.
4. Once the program section has been executed, the background task is
stopped.
Exception: With Resume, the background task is continued until the
next break point or the end of a non-cyclic background task is
reached.
5. Debugging functions, such as the observation of variables or the
changing of values, can be used between the individual steps.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 629/667

Remote debugging KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

22.3 Fundamentals of remote debugging

22.3.1 Overview of user interface – “Debugging” perspective

The Debugging perspective contains a suitable arrangement of views that

are useful for remote debugging.
A configuration of the Debugging perspective is displayed below. The De-
bug perspective can be expanded to include additional views.

Fig. 22-1: Overview of user interface – “Debugging” perspective

Item Description
1 Debug view
Displays threads of the virtual machine connected for debug-
ging.
2 Debugging toolbar
Program execution during remote debugging is controlled by
means of the buttons. The toolbar can be displayed using the
drop-down arrows or the “Show Debug Toolbar” button.
3 Variables view
The variables are displayed and managed here. The variables
refer to the currently selected context (line/method) in the “De-
bug” view (item 1). Modification of values is possible.
4 Breakpoints view
Break points are displayed and managed here.

630/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Remote debugging
Item Description
5 Editor area
During remote debugging, the source code currently being exe-
cuted can be displayed here. If task execution is paused, the
current command line is highlighted. Modifications to the source
code are generally possible and are applied in the running task.
An exception is changes to the schema that cannot be applied
in the running task.

22.3.2 Break points

Overview

The use of break points is a major component of remote debugging. The

programmer uses break points in the source code to define specific points
in the program at which the program is to be stopped during remote de-
bugging.
Break points are created and managed in Sunrise.Workbench. Break
points only pause the task during a debugging session. It is not taken into
consideration during normal program execution.
The creation, deletion, activation and deactivation of break points and the
modification of their properties are possible before and during remote de-
bugging.
Depending on the position in the code at which the break point is used, a
distinction is made between different types of break point.
• Line break point
The line break point is the most commonly used break point. The line
break point is placed next to a command line. Program execution is
stopped when the break point is reached. The command line next to it
is not executed until remote debugging is resumed.
• Monitoring point
A monitoring point is placed next to the declaration of a field. Program
execution is stopped before read and/or write access to the field.
• Method break point
A method break point is placed next to the header of a method. Pro-
gram execution before the method is entered and/or left.
• Exception break point
An exception break point stops program execution when an error oc-
curs. Exception break points are displayed and created in the Break
points view.
In order to define more precisely the response on reaching the break
point, certain properties can be parameterized for each break point. Differ-
ent settings are possible, depending on the type of break point.

22.3.2.1 Creating and deleting break points

Description

Break points are created in the editor area of Sunrise.Workbench.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 631/667

Remote debugging KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 22-2: Creating break points

Item Description
1 Editor bar
Break points are displayed next to the corresponding command
line in the bar with a gray background at the left-hand edge of
the editor. Break points can be added to the editor bar, deleted,
activated or deactivated.
2 Monitoring point (in this case for the array “robot”)

• Break point inserted next to the declaration of an array

• Indicated by means of a pair of glasses and/or a pencil
3 Line break point (in this case for the command ro-
bot.move(ptpHome());)

• Break point inserted next to a command line

• Indicated by a blue circle
4 Method break point (here: mainTask() method)

• Break point inserted next to the header of a method

• Indicated by a blue circle with arrow

Procedure

1. Open the class in the editor area of Sunrise.Workbench.

2. Search for the command line next to which a break point is to be set.
3. Double-click next to the desired command line in the editor bar. A new
break point is inserted and indicated by the corresponding icon on the
bar.
4. To remove a break point for a command line, double-click on the cor-
responding icon.

632/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Remote debugging
Break points can also be added and removed by right-clicking on the
corresponding point of the editor bar. Select the entry Break point
on/off in the context menu that appears.

22.3.2.2 Deactivating and activating break points

Description

If a break point is not to be deleted completely, but merely ignored tempo-

rarily during remote debugging, deactivation of the break point is possible.
It remains available with all its properties and can be reactivated again if
required.

Procedure

1. Open the class in the editor area.

2. Search for the command line containing the break point that is to be
deactivated.
3. Right-click on the icon of the break point and select Deactivate break
point from the context menu. The break point is deactivated. The icon
for the break point is grayed out.
4. To activate a deactivated break point, right-click on the icon of the
break point and select Activate break point from the context menu.
The break point is active again.

22.3.2.3 Editing the properties of the break points

Description

The properties of a break point define the conditions for stopping a task
when the break point is reached. The settings are dependent on the type
of break point.

Procedure

1. Open the class in the editor area.

2. Search for the command line containing the break point whose proper-
ties are to be edited.
3. Right-click on the icon of the break point and select Breakpoint prop-
erties from the context menu. The Properties dialog opens.
4. Select Breakpoint properties. Edit the properties of the break point.
5. Confirm with OK. The dialog is closed.

22.3.2.4 Overview of the “Break points” view

The view contains a list of the break points of all classes in the work-
space of Sunrise.Workbench. The view offers the following functions:
• Display of all break points
• Activation, deactivation and deletion of break points
• Modification of break point properties
• Addition of exception break points

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 633/667

Remote debugging KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 22-3: “Break points” view

Overview

Item Description
1 Activation of the break point
Check box active: Break point is activated.
Check box not active: Break point is not activated.
2 Designation of the break point
The designation is composed of special properties of the break
point in order to enable unambiguous identification.
3 Break point list
List of the break points of all classes in the workspace
4 Break point properties
The properties of the break point selected in the list can be dis-
played and edited in this area.
The functionalities offered by the buttons in the toolbar include the follow-
ing:
Button Description
Remove selected break points
Deletes the break points selected in the break point list.
Remove all break points
Deletes all break points in the list.
Go to file for break point
The class containing the break point selected in the list is
opened in the editor area in the foreground and the corre-
sponding command line is selected.

634/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Remote debugging
Button Description
Skip all break points
If this button is active, all break points are deactivated and
do not cause the execution of the corresponding task to be
stopped.
Add break point for Java exception condition
Opens the dialog for adding an exception break point.

22.3.2.5 Conditional break point

Description

For break points, a condition can be formulated as an additional property.

Such a conditional break point only causes the corresponding task to stop
if a condition defined by the user is met when the break point is reached.
Conditions can be defined for the following break points:
• Line break point
• Method break point
In the case of a conditional break point, a question mark is added next to
the icon for the break point in the editor bar.
NOTICE
The condition is evaluated every time the break point is reached. This
influences the time response of the task.
It is recommended not to use state-changing commands in the condi-
tion. Interventions and commands that cause a change of state include:
• Motion commands
• Modification of variables
• Modification of the source code
• Setting inputs/outputs
• Changes of values, e.g. by calling set methods

Fig. 22-4: Setting the properties

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 635/667

Remote debugging KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Overview

Item Description
1 Check box for activation of the condition

• Check box not active: The condition is not active.

The corresponding task is stopped every time the break
point is reached.
• Check box active: The condition is active.
Depending on the result of the evaluated condition, the cor-
responding task is stopped when the break point is reached.
2 Selection of the event
Defines the event that causes the corresponding task to be
stopped.

• Suspend when 'true'

The task is stopped exactly on reaching the break point if
the defined condition is met (return value TRUE).
• Suspend when value changes
The task is stopped exactly on reaching the break point if
the state of the condition has changed since the last time
the break point was reached (change of state from condition
met to condition not met or vice versa).
3 List of recently entered conditions
If a condition is selected from the list, it is entered in the editor
box and the previous contents of the box are deleted.
4 Editor box
The condition is entered in the editor box.
Certain rules must be observed. Simple Boolean expressions
can be entered, e.g.:

• input == FALSE
• counter <= 510
Complex Java instructions can also be formulated. The com-
mands are then executed every time the break point is reached.
A Boolean value must be returned at the end of the sequence
of instructions in order to enable evaluation of the condition.
Correct syntax must be observed.
Variables and commands that are also available at the position
of the break point in the source code of the task or class can
be used when formulating the conditions.
Evaluation of the conditions results in a significant change in
the time response. It is advisable to limit the number and dura-
tion of the commands used to an absolute minimum, as the
conditions are evaluated every time the break point is reached.

Example

An application is to be interrupted before the start of a joining operation if

the applied force is insufficient. In this example, the applied force is con-
sidered to be insufficient if the force acting on the Z axis of the flange is
less than 5 N.
The following break point properties are set for this:

636/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Remote debugging
Fig. 22-5: Conditional break point

The application is only stopped if the result of evaluation of the condition

is TRUE. The condition consists of a sequence of instructions that are
executed every time the break point is reached. First of all, the calculated
force at the robot flange is requested. The system then checks whether
the Z component of the force vector falls below -5 Nm. The result of the
evaluation is returned.

22.3.2.6 Suspend thread property

Description

The selection of Suspend thread in the properties of a break point must

not be changed.
NOTICE
Suspend VM must not be selected. Otherwise, all Java processes are
stopped and the robot controller must be restarted.

Fig. 22-6: Defining processes

22.3.3 Command pointer

During debugging, program execution is controlled manually.

The command pointer indicates the current position in the source code
and the next command to be executed. During program execution, the
command pointer jumps from one command line to the next.
During remote debugging, the command pointer is moved through the
source code of the task, and the classes used by it, by Sunrise.Work-
bench. The command lines that the command pointer moves past are
executed.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 637/667

Remote debugging KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 22-7: Command pointer

Item Description
1 Position of the command pointer (blue arrow)
The command pointer indicates the next command to be execu-
ted. The current position of the command pointer in the source
code is indicated by a blue arrow.
2 Next command line to be executed
In the paused thread, the currently selected row in the stack
trace.

22.3.4 Overview of the “Debugging” view

Description

The Debug view contains the toolbar and a list of all Java threads
running on the controller. The task for which debugging is carried out is
one of the threads running on the controller.
In the Debug view, the corresponding stack trace is displayed beneath a
thread. The stack trace contains the current method calls of a thread and
is used for tracking program execution.

Fig. 22-8: Overview of “Debugging” view

Item Description
1 Toolbar
Program execution during remote debugging is controlled by
means of the buttons.
2 Task thread
Task-relevant part of stack trace of the application thread. The
designation contains the name of the executed tasks (here ap-
plication.ExampleApplication). The corresponding stack trace is
located beneath the thread.

638/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Remote debugging
Item Description
3 Stack trace
The stack trace of the task thread contains the methods that
are relevant for execution of the task. The called methods are
specified with their identifiers. In this way, the user can identify
the relevant methods.
The methods are specified in the order in which they are called.

Example

In a robot application, the assembly() method is called in the run()

method in order to assemble a component. The assembly() method
then calls the checking() method to check whether the assembly proc-
ess has been successfully completed:

public void run(){

// ...
assembly();
// ...
}

public void assembly(){

// ...
boolean result = checking();
// ...
}

public boolean checking(){

// ...
return result;
}

Execution is interrupted at a break point in the checking() method. The

command pointer is located before the next command line to be executed.
The checking() method is selected in the stack trace of the task thread:

Fig. 22-9: Position of command pointer in the checking() method

If the run() method is selected in the stack trace of the task thread, the
current position of the command pointer in the run() method is displayed:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 639/667

Remote debugging KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 22-10: Position of command pointer in the run() method

The filled white arrow icon indicates the call of assembly(), and thus the
progress of the task in the run() method.

22.3.5 Overview of the toolbar in the “Debugging” view

Program execution is controlled by means of the buttons in the toolbar.

Keyboard commands can alternatively be used for most functions.
Button Name/description
Resume
Key: F8
Execution of a task is continued until the next break point
or the end of the task is reached.
(>>> 22.3.5.1 "Continuing execution (Resume)" Page 641)
Step in
Key: F5
If the current command line contains an instruction, it is
executed.
If the current command line is a method call, the command
pointer jumps to the start of the called method.
(>>> 22.3.5.2 "Jump into the method (Step in)" Page 641)
Step over
Key: F6
The current command line is executed completely. If the
line contains a method call, the method is executed com-
pletely (exception: the method has breakpoints of its own).
(>>> 22.3.5.3 "Executing a method completely (Step over)"
Page 642)

640/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Remote debugging
Button Name/description
Step back
Key: F7
The method currently being executed is executed through
to the end as long as there are no breakpoints present be-
fore the end of the method. Task execution then stops in
the calling method.
(>>> 22.3.5.4 "Terminating the executed method (Step
back)" Page 643)
Back to frame
No key assigned
This function can be used to jump to a point in the source
code that has already been executed.
(>>> 22.3.5.5 "Executing code sections again (Back to
frame)" Page 644)
Pause
No key assigned
Pauses execution.
(>>> 22.3.5.7 "Debugging: pausing threads (Pause)"
Page 646)
--- Execution to line (only available as a keyboard shortcut)
Key combination: Ctrl+R
Task execution is resumed until the command pointer rea-
ches a command line defined by the user.
(>>> 22.3.5.6 "Defining the code section to be executed
(Execution to line)" Page 645)

22.3.5.1 Continuing execution (Resume)

The Resume button is used to continue execution of a task until the next
break point or the end of the task is reached.

22.3.5.2 Jump into the method (Step in)

Description

If the current command line contains a method call, the command pointer
jumps to the start of the called method when Step in is used.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 641/667

Remote debugging KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The source code of the called method is only displayed if the source
code of this method is available. If the source code is not available, the
warning Source not found is displayed.
• Execution can be resumed.
• The user has no way of viewing the command currently being exe-
cuted.
• In this case, Step back takes the user back to source code that can
be displayed.
(>>> 22.3.5.4 "Terminating the executed method (Step back)"
Page 643)
• Use of Step over is recommended for jumping into a motion com-
mand (robot.move(…)).
(>>> 22.3.5.3 "Executing a method completely (Step over)"
Page 642)

If the current command line contains not a method call, but an individual
instruction, the command line is executed and the command pointer jumps
to the next command line.

Example

The application was interrupted before the call of the pickupWorkpiece()

method. Step in causes the command pointer to jump to the start of the
method:

Fig. 22-11: Jump to method

22.3.5.3 Executing a method completely (Step over)

Description

Step over executes the current command line and the command pointer
jumps to the next program line.
If the command line contains a method call, the method is executed com-
pletely as long as it does not contain a break point.

Formatting

Since the source code is executed step by step during remote debugging,
the formatting of the source text influences the number of steps required
for complete execution of the commands when using Step over.
Formatting example: Object of type CartesianImpedanceControlMode
With the following formatting, 3 steps are required when using Step over:

642/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Remote debugging
CartesianImpedanceControlMode mode =
new CartesianImpedanceControlMode();
mode.parametrize(CartDOF.Z).setStiffness(500);

If the code is divided by further line breaks, the code section is completely
executed after a total of 4 steps with the following formatting when using
Step over:

CartesianImpedanceControlMode mode =
new CartesianImpedanceControlMode();
mode.parametrize(CartDOF.Z)
.setStiffness(500);

Example

The application was interrupted before execution of the pickupWorkpiece()

method. Step over completely executes the method and the command
pointer jumps to the following command line.

Fig. 22-12: “Step over” method

22.3.5.4 Terminating the executed method (Step back)

Description

Step back causes the method in which the command pointer is currently
located to be executed completely (as long as there are no further break
points present). The command pointer returns to the calling method and
jumps to the following command line. Program execution is paused.
If, when Step back is used, program execution is interrupted before the
end of the method has been reached and resumed with Resume, the
pause requested by Step back is invalidated. In this case, execution of
the task is not interrupted at the end of the method.

Example

The command pointer is located inside the pickupWorkpiece() method that

was called by the run() method. With Step back, the pickupWorkpiece()
method is executed completely and execution of the application is stopped
before the next command line in the run() method:

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 643/667

Remote debugging KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Fig. 22-13: “Step back” to calling method

22.3.5.5 Executing code sections again (Back to frame)

NOTICE
Back to frame changes the normal program execution. If state-chang-
ing interventions are carried out in the current method or its subme-
thods, this can result in unexpected system behavior and unexpected
robot motions.
Interventions and commands that cause a change of state include:
• Motion commands
• Modification of variables
• Modification of the source code
• Setting inputs/outputs
• Changes of values, e.g. by calling set methods

Description

Back to frame can be used to run program sections that have already
been executed again. As standard, the command pointer jumps to the
start of the method that is currently being executed. Program execution is
then paused.
In the Debugging view, it is possible to return to each call level of the
task using the stack trace. To do so, the desired method is selected in the
stack trace. Back to frame causes the command pointer to jump to the
start of this method.
Once the command pointer has been placed at a previously executed po-
sition in the code by means of Back to frame, the following code can be
executed (again).
When Back to frame is used, modifications to arrays or external data
that were not carried out in the affected code section are not undone.

Example

The command pointer is currently located in the pickupWorkpiece() meth-

od. As standard, Back to frame causes it to jump back to the start of the
method. Execution of the task is resumed from there.

644/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Remote debugging
Fig. 22-14: Back to frame (jump to start of current method)

If the run() method is first selected in the stack trace of the task, Back to
frame causes the command pointer to jump to the start of the run() meth-
od:

Fig. 22-15: Back to frame (jump to start of run() method)

22.3.5.6 Defining the code section to be executed (Execution to line)

Description

With Execution to line, the program is resumed until the command point-
er reaches a command line defined by the user. Execution to line is not
available in the Debugging view.

Procedure

1. Left-click into the line to which the task is to be executed. The line is
highlighted with a blue background.
2. Task execution is resumed as far as the selected line or a preceding
break point by means of the keyboard shortcut Ctrl+R.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 645/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Alternatively, the function can be selected from the context menu Execu-
Remote debugging

tion to line after right-clicking into the desired command line.

The request for pausing task execution at the selected command line is
only valid once. If execution is stopped before the command line is
reached, and then resumed with Resume, execution is not stopped
when the command line is reached.

22.3.5.7 Debugging: pausing threads (Pause)

Task execution can be paused manually by pressing the Pause button.

If the Pause function is used, the user must ensure that the correspond-
ing thread task is selected in the Debugging view. The functioning of
the controller may otherwise be adversely affected to such an extent
that a reboot of the controller is required.
Motion commands that have already been sent to the controller are not
paused by the Pause function, but processed in the controller and exe-
cuted.

When pausing, as when reaching a break point, the current command line
is displayed in the editor area. If the corresponding source code is not
available when using Pause, the warning Source not found is displayed
in the editor area.
The Start/Pause key on the smartPAD is only used to pause motion
commands. Pausing via the smartPAD only affects execution of the ap-
plication if a synchronous motion command is due to be executed, as
the command pointer only jumps to the next motion line after the motion
command has been completed.

22.3.6 Variables view

The Variables view is integrated into the Debugging perspective.

It contains a table with all variables that are available at the currently indi-
cated position of the command pointer.
The variables are not available during execution of a task. The updated
values are only displayed while execution is paused.
If variable values change during remote debugging, program execution
will be modified.

646/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Remote debugging
Fig. 22-16: Variables view

Item Description
1 Table of available variables
The table contains the currently available arrays and local varia-
bles and their values. Only those variables that are available at
the position of the command pointer in the selected method in
the stack trace of the Debugging view are displayed.
The Name column contains the variable name. Variables with a
complex type are displayed hierarchically. Variables with com-
plex data types can be expanded and their arrays displayed us-
ing the icon to the left of the name.
The current value of the variable is displayed in the Value col-
umn. In the case of variables with complex data types, the re-
sult of the call of the toString() method is displayed as
standard. The values of primitive data types and string values
can be modified directly in the table.
2 Detailed information
This area contains detailed information about the variable selec-
ted in the table. The variable value is displayed for primitive da-
ta types and strings. In the case of complex data types, the re-
sult of the call of the toString() method is displayed as standard.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 647/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

22.3.6.1 Displaying and modifying variables

Remote debugging

Description

Irrespective of their visibility, variables and their values can be displayed

and modified in the Variables view.

Fig. 22-17: Displaying variables

Item Description
1 Instance
The variable this refers to the instance of the class whose
method has been selected in the stack trace and in whose
source code the command pointer is currently displayed. During
remote debugging of a task, the robot that is being used can be
accessed, e.g. via the instance of the class. Here, this is the
application for which remote debugging is being carried out.
2 Representation of complex data types
Variables with a complex data type (here the class CartesianSi-
neImpedanceControlMode) are displayed in a hierarchical struc-
ture. Expanding the structure displays the arrays of the refer-
enced object. Arrays of primitive data types and strings are at
the bottom level.
3 Changes of values
The values of primitive data types and string values can be
modified directly in the table. Once a value has been modified,
the variable is highlighted in yellow in the table.

Precondition

• Task execution is paused.

648/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Remote debugging
Procedure

As standard, only those variables that are available at the position of the
command pointer in the selected method in the stack trace of the Debug-
ging view are displayed:
1. In order to display variables that are available in a different method,
select the method in the stack trace of the Debugging view.
2. In order to modify variables of primitive data types, left-click on the
value of the variable displayed in the Value column.
3. Enter the new value and confirm with the Enter key.

If incorrect values are entered, a message is displayed and the old val-
ue is retained. However, only incorrect entries that are recognized as
such by the autocorrect function of the Java editor are prevented.

New values can be assigned to variables with complex data types in the
dialog Change object value:
1. Right-click on the desired variable in the table and select Change val-
ue... from the context menu. The Change object value dialog opens.
2. Enter the corresponding instructions in the editor box.

When making entries, it must be ensured that syntactically correct Java

source code is used and that a value with a suitable data type is re-
turned at the end of the sequence of instructions.

22.3.6.2 Advanced context help for variables

If task execution is paused during remote debugging, the Java editor has
advanced context help for variables. The advanced context help is then
available for all variables that are available at the position of the
command pointer in the selected method in the stack trace.
To display the context help, the mouse pointer is moved over the desired
variable in the source code. A window opens, displaying information about
the variables (data type, name, current value).
Complex data types are displayed in a hierarchical structure, like in the
Variables view. Expanding the structure displays the arrays of the refer-
enced object. Elementary data types and strings are located at the bottom
hierarchy level.

Fig. 22-18: Advanced context help

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 649/667

Remote debugging KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Item Description
1 Variable (source code)
Variable in the source code for which the advanced context
help is displayed.
2 Variable (context help)
Advanced context help for the variable. The designation and
value are displayed. In the case of complex data types, the da-
ta type is also specified.
Variables with a complex type are displayed hierarchically in a
tree structure.
3 Details
Details of the selected component are displayed here. In the
case of variables with primitive data types and strings, the cor-
responding value is displayed; in the case of variables with a
complex data type, the result of the call of toString() is dis-
played as standard.

22.3.7 Monitoring processes

Description

During remote debugging, data can also be monitored that are not availa-
ble as variables. These include, for example, the current position of the
robot.
Monitoring expressions can be formulated in Sunrise.Workbench. The
monitoring expressions are managed in the Expressions view and evalu-
ated each time task execution is stopped during a debugging session.
Both individual expressions and more complex instruction sequences can
be entered. Correct syntax must be observed.
Configured monitoring expressions are not deleted after the end of the de-
bugging session and are thus also taken into consideration in subsequent
debugging sessions.
NOTICE
It is recommended that monitoring expressions are only used for re-
questing states and that no state-changing commands are used in the
expressions.
Interventions and commands that cause a change of state include:
• Motion commands
• Modification of variables
• Modification of the source code
• Setting inputs/outputs
• Changes of values, e.g. by calling “set” methods

Procedure

Display the Expressions view:

• Menu sequence Window > Show View
• The Expressions view can be selected via the Other… menu item.
The view can be found in the “Debugging” group.

650/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Remote debugging
Overview

Fig. 22-19: “Expressions” view

Item Description
1 Table of created monitoring expressions
The Name column contains the source code of the monitoring
expression. If available, the return value of the expression is
specified under Value.
2 Line for new expression
New expressions can be entered in the first unoccupied line of
the table.
3 Details
Detailed information about the selected expression is displayed
in this area. As standard, complex data types are the result of
the call of toString() on the return value of the monitoring ex-
pression. For variables of primitive data types and strings, the
corresponding value is displayed.
4 Evaluation error
If an expression cannot be evaluated, an error message is dis-
played in the Value column.

22.3.7.1 Adding new monitoring expressions

Precondition

• Expressions view opened.

Procedure

1. Left-click into the first blank line (indicated by a green + symbol) in the
Name column.
2. Enter the monitoring expression in the Name column and confirm with
the Enter key. The monitoring expression is added.
If a debugging session is active and task execution has been stopped,
the expression is evaluated immediately.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 651/667

Remote debugging KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

NOTICE
Monitoring expressions are not automatically deleted after the end of
the debugging session and are thus also active in subsequent debug-
ging sessions. The use of monitoring expressions may modify program
execution. It is recommended not to use state-changing commands in
monitoring expressions. Unexpected behavior may otherwise result.

22.3.7.2 Deleting monitoring expressions

Monitoring expressions can be deleted.

Precondition

• Expressions view opened.

Procedure

• Right-click in the line with the monitoring expression that is to be de-

leted.
Select the entry Delete from the context menu.

22.3.7.3 Evaluating monitoring expressions

Description

During remote debugging of a task, monitoring expressions are automati-

cally re-evaluated and updated in the following situations:
• On stopping execution at a break point
• On stopping execution by means of the debugging function Pause
• At the end of execution of one of the following debugging functions:
‒ Step in
‒ Step over
‒ Step back
‒ Back to frame
‒ Execute to line
If task execution is interrupted during debugging, evaluation of a monitor-
ing expression can be explicitly requested.

Procedure

• Right-click in the line with the expression that is to be monitored.

Select the entry Re-evaluate monitoring expression in the context
menu.
Evaluation of a monitoring expression is only successful if the command
at the current position of the command pointer in the method selected in
the stack trace of the task thread can be executed.

Example

During remote debugging of a task, the current Cartesian position of the

tool TCP is to be displayed after every execution step. A monitoring ex-
pression is formulated for this.
The identifier of the robot array of the application is robot (data type:
LBR). The gripper is represented by the gripper array (data type:
com.kuka.roboticsAPI.geometricModel.Tool). The following command call is
thus required for requesting the current position of the gripper TCP:

652/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Remote debugging
robot.getCurrentCartesianPosition(gripper.getDefaultMotionFra
me());

This command is entered in the Name column in the Expressions view:

Fig. 22-20: Entering a monitoring expression

The monitoring expression is re-evaluated every time task execution is

paused. The returned value is of type com.kuka.geometricModel.Frame.
Complex data types are displayed hierarchically. Expanding the tree struc-
ture displays the arrays of the returned object.

Fig. 22-21: Evaluating a monitoring expression

22.3.8 Modifying source code

During an active debugging session, it is possible to perform certain mod-

ifications in the source code of tasks and other classes.

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 653/667

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

The following must always be observed in the case of modifications to the

Remote debugging

source code during an active debugging session:

• Only modify source code while execution of the task is paused. Do
not modify source code during execution of the task.
• Save modifications to the source code before starting or resuming ex-
ecution of the task.

22.3.8.1 Impermissible modification of the source code

The following modifications to the source code may lead to complications

and should thus not be made during an active debugging session:
• Addition of new methods or fields
• Modification of the designation of a method or field
• Modification of the data type of a field
• Modification of the return type of a method
• Modification of the number of transfer parameters of a method
• Modification of the data type of transfer parameters of a method
• Generation of syntax errors in the code

After saving an impermissible modification of the source code during re-

mote debugging, a dialog opens with a corresponding warning message.
• Next button: The debugging session can be resumed.
• Disconnect button: The debugging session can be aborted and the
remote connection disconnected. It is advisable to abort the debug-
ging session and reestablish the remote connection.

22.3.8.2 Permissible modification of the source code

The following must be taken into consideration if, during debugging of a

task, modifications are made in the source code of this task or in the
source code of the classes used in it:
• If modifications are made to the source code in a method that is cur-
rently located in the stack trace of the task thread, the command
pointer jumps to the start of this method after saving the change.

NOTICE
The jump by the command pointer to the start of a method on saving
modifies the normal program sequence. This can result in unexpected
system behavior and unexpected robot motions.

654/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Appendix
23 Appendix

23.1 Compatibility and migration of projects

From Version 1.8 onwards, KUKA Sunrise.OS contains new features that
affect the upward compatibility of projects created using an earlier soft-
ware version (< 1.8).
• Task functions in the RoboticsAPI
Some task functions have been renamed or are now used differently.
The migration of projects that use these task functions can thus lead
to compiler errors. The programming must be adapted.
(>>> 23.1.1 "Modified task functions – adapting the programming"
Page 655)
• I/O configuration
The current version of WorkVisual generates a changed folder struc-
ture when exporting the I/O configuration in Sunrise.Workbench (the
folder generatedFiles now contains the folder IOConfiguration).
If a project is synchronized that still has the old folder structure, the
I/O configuration is not transferred and no I/Os are available on the ro-
bot controller.
In order to generate the new folder, the I/O configuration of the project
must be opened in WorkVisual and exported again in Sunrise.Work-
bench. Precondition: The option package supplied with the new soft-
ware (KOP file Sunrise) is installed in WorkVisual. Only then is the
new folder generated on exporting.
If, following the export, the folder generatedFiles contains the folder
IOConfiguration, the project can be synchronized on the robot con-
troller.

23.1.1 Modified task functions – adapting the programming

The modified task functions and the adaptations required in the tasks are
described here in order to be able to continue using tasks created with a
software version < 1.8.

ITaskLogger

If using ITaskLogger references:

Modify the package name for ITaskLogger:
• Previously: import com.kuka.roboticsAPI.applicationModel
.tasks.ITaskLogger;
• Now: import com.kuka.task.ITaskLogger;

ITaskFunction

If using the interface ITaskFunction (>>> 17.4 "Data exchange between

tasks" Page 556):
The interface ITaskFunction has been dispensed with. The following refer-
ences in the interface in which the task functions are declared must there-
fore be deleted:
• Delete the following addition in the header of the interface:
extends ITaskFunction

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 655/667

Appendix KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

• Delete the following import:

import com.kuka.roboticsAPI.applicationMo-
del.tasks.ITaskFunction;
The interface ITaskFunctionProvider and the @ProvidedFunctions annota-
tion have been replaced by the @TaskFunctionProvider annotation. For
this reason, the following changes are required in the task that provides
the task functions (providing task):
• Delete the following annotation: @ProvidedFunctions(…)
• Delete the following addition in the header of the task:
implements ITaskFunctionProvider
• Delete the method createTaskFunctions() and the corresponding Map
instance:
public Map<Class<? extends ITaskFunction>, ITaskFunc-
tion> createTaskFunctions(){
...
}
• For each interface whose task functions the task provides, insert a pa-
rameterless public method with the annotation @TaskFunctionProvider
that returns implementation of the interface:
@TaskFunctionProvider
public Interface Method name()
return Interface instance;
}
‒ Interface: Interface whose task functions the task provides
‒ Method name: Name of the method that returns the implementa-
tion of the interface (the name can be freely selected)
‒ Interface instance: Instance of the implementing class

If the providing task implements the interface itself, transfer the in-
stance of the task for the parameter Interface instance:
return this;

• Delete the following import:

import com.kuka.roboticsAPI.applicationModel.tasks.*
The method getTaskFunction(…) now directly returns the interface in
which the task functions are declared. For this reason, the following
changes are required in the task that accesses the task functions (re-
questing task):
• Change the type of data array used to access the task functions:
‒ Data type previously: ITaskFunctionAccessor<Interface>
‒ Interface: Interface in which the task functions are declared.
‒ Data type now: Interface
The method getTaskFunction(…) now directly returns the interface.
‒ Remove the .get() method from the calls of the modified variable.
• If the accessor methods isAvailable() or await(…) have been used,
create a new data array of type ITaskFunctionMonitor and initialize it
with the method TaskFunctionMonitor.create(…). The instance of the
interface in which the task functions are declared is transferred to the
method as a parameter.
private ITaskFunctionMonitor Monitor;
Monitor = TaskFunctionMonitor.create(Interface instance);

656/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

KUKA Service
24 KUKA Service

24.1 Requesting support

Introduction

This documentation provides information on operation and operator con-

trol, and provides assistance with troubleshooting. For further assistance,
please contact your local KUKA subsidiary.

Information

The following information is required for processing a support re-

quest:
• Description of the problem, including information about the duration
and frequency of the fault
• As comprehensive information as possible about the hardware and
software components of the overall system
The following list gives an indication of the information which is rele-
vant in many cases:
‒ Model and serial number of the kinematic system, e.g. the manip-
ulator
‒ Model and serial number of the controller
‒ Model and serial number of the energy supply system
‒ Designation and version of the system software
‒ Designations and versions of other software components or modifi-
cations
‒ Diagnostic package KRCDiag
Additionally for KUKA Sunrise: existing projects including applica-
tions
For versions of KUKA System Software older than V8: archive of
the software (KRCDiag is not yet available here.)
‒ Application used
‒ External axes used

24.2 KUKA Customer Support

The contact details of the local subsidiaries can be found at:

www.kuka.com/customer-service-contacts

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 657/667

KUKA Service KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

658/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Index Axis torque condition....................................474

Axis torque monitoring................................. 313
“Brake” safety reaction................................. 568
Axis torque monitoring (AMF)..... 258, 261, 313
“Ready for motion”, checking.......................461
Axis torque referencing................................ 327
3-point method..............................................146
Axis torques, requesting...............................449
6D mouse.................................................72, 75
Axis velocity monitoring (AMF)... 258, 260, 294

A
ABC 2-point method.....................................143
B
ABC world method....................................... 145 Background application, new......................... 61
Accessories.............................................. 23, 27 Background application, starting.......... 117, 118
Activating, safety configuration.................... 284 Background application, stopping................ 117
Activation delay, for safety function.............312 Background task, cyclic................................553
Actual position, axis-specific........................ 119 Background tasks......................................... 551
Actual position, Cartesian............................ 120 Backup Manager.................................. 124, 217
addCartesianForce(…)................................. 512 Backup Manager, configuration................... 212
addCartesianTorque(…)................................512 Base-related TCP force component
addCommandedCartesianPositionXYZ(…).. 512 (AMF)...................................258, 261, 319, 351
addCommandedJointPosition(…)................. 512 Base calibration............................................ 146
addControllerListener(…)..................... 462, 467 Base coordinate system........................ 95, 146
Base for jogging........................................... 175
addCurrentCartesianPositionXYZ(…)...........513
Blocking wait.................................................508
addCurrentJointPosition(…)..........................512
BooleanIOCondition......................................472
addDoubleUserKey(…).................................519
Brake defect................................................... 41
addExternalJointTorque(…).......................... 511
Brake ramp monitoring, Brake.....................569
addInternalJointTorque(…)............................511
Brake test..................................................... 153
addUserKey(…)............................................ 519
Brake test application, template.................. 156
Administrator........................................ 196, 197
Brake test, evaluation...................................165
Allow muting via input..................................356
Brake test, performing..................................169
AMF................................................................ 20
Brake test, programming interface.............. 160
API.................................................................. 20
Brake test, requesting result........................167
App_Enable.......................................... 236, 245
Brake test, result (display)........................... 170
App_Start..............................................236, 544
Brake test, starting execution...................... 164
Appendix....................................................... 655
Brake test, starting position......................... 159
Application data (view)................................... 54
Brake, defective............................................155
Application mode............................................ 98
BrakeState (enum)....................................... 168
Application override............... 97, 115, 116, 469
BrakeTest (class)..................................160, 163
Application tool............................................. 101
BrakeTestResult (class)................................166
Application, pausing..................................... 531
Braking distance............................................. 28
Approximate positioning............................... 382
Break conditions for motions....................... 495
Approximate positioning point...................... 382
Break conditions, evaluating........................ 496
areAllAxesGMSReferenced()........................466
Break point, conditional................................635
areAllAxesPositionReferenced()................... 466
Break point, view..........................................633
areDataValid()............................................... 161
Break points..................................................631
Asynchronous motion execution.................. 416
breakWhen()................................................. 495
attachTo(…).......................................... 435, 436
breakWhen(…)..............................................497
AUT (operating mode)....................................28
Bus I/Os, mapping........................................231
AutExt_Active................................................237
AutExt_AppReadyToStart.....................237, 544
Auto-complete...............................................399
Automatic (operating mode)...........................28 C
Automatic mode..............................................47 Calibration.....................................................140
Automatic mode (AMF)............... 257, 259, 287 Calibration, base...........................................146
Auxiliary point.......................................374, 418 Calibration, tool.............................................140
awaitFileAvailable(…)................................... 516 cancel()......................................................... 532
Axis-specific impedance controller...... 585, 608 Cartesian impedance controller.. 585, 587, 596
Axis-specific monitoring spaces, defining....307 Cartesian position, requesting..................... 456
Axis-specific robot position, requesting....... 455 Cartesian protected space monitoring
Axis limit....................................................... 307 (AMF)........................................... 258, 260, 304
Axis range.............................................. 28, 307 Cartesian protected spaces, defining.......... 304
Axis range monitoring (AMF)...... 257, 260, 307

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 659/667

KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Cartesian setpoint/actual value difference, Data types.................................................... 406

requesting..................................................... 457 Data, backing up manually.......................... 128
Cartesian velocity monitoring (AMF).. 258, 260, Data, recording and evaluating....................510
295 Data, restoring manually.............................. 128
Cartesian workspace monitoring (AMF)....258, DataRecorder................................................510
260, 303 Debug (perspective)....................................... 55
Cartesian workspaces, defining................... 302 Debug project (button)................................... 56
CartesianTorqueCondition............................ 472 Debugging.....................................................205
CE mark..........................................................28 Debugging session, ending..........................626
Checksum, safety configuration................... 284 Debugging session, starting.........................625
CIRC............................................................. 418 Debugging, view........................................... 638
CIRC, motion type........................................374 Declaration....................................................407
Circular motion............................................. 418 Declaration of conformity............................... 27
Cleaning work.................................................48 Declaration of incorporation.....................27, 28
clipApplicationOverride(…)........................... 470 Decommissioning............................................48
clipManualOverride(…)................................. 470 Default application.................63, 235, 239, 248
Collision detection........................................ 314 Default frame for motions............................ 187
Collision detection (AMF)............ 258, 261, 315 Default user group.........................90, 196, 197
Command pointer......................................... 637 DefaultApp_Error.......................................... 237
Compatibility................................................. 655 Dependency injection.................. 409, 410, 412
Complex conditions...................................... 473 detach().........................................................438
Complex data types..................................... 408 Diagnosis...................................................... 613
Condition for Boolean signals......................493 Diagnosis package, creating............... 620, 621
Condition for the range of values of a signal Diagnosis package, loading from the robot
......................................................................494 controller....................................................... 621
Condition, Cartesian torque......................... 483 Diagnostic information, collecting.................620
Conditional branch........................................537 Display child frames (button)....................... 107
Connecting cables....................................23, 27 displayModalDialog(…).................................530
Connection manager................................72, 74 Disposal.......................................................... 48
Constant force, overlaying........................... 604 Distance component condition..................... 492
Continuous Path........................................... 373 Distance condition........................................ 491
Controller object, creating............................ 586 DO WHILE loop............................................536
Controller parameters, defining....................586 Documentation, industrial robot..................... 19
Coordinate system, for jog keys....................80
Coordinate systems........................................95
Counting loop............................................... 534 E
CP motion.....................................................373 EC declaration of conformity......................... 27
CP spline block............................................ 373 Effective program override...........115, 116, 469
CP spline block, creating............................. 422 EMC Directive.................................................28
Create child frame (button)................. 106, 108 EMERGENCY STOP............................... 72, 74
Create frame (button).......................... 106, 107 EMERGENCY STOP device............. 34, 35, 37
createAndEnableConditionObserver(…)...... 506 EMERGENCY STOP smartPAD (AMF)....258,
createConditionObserver(…)........................ 506 287
createDesiredForce(…)................................ 603 EMERGENCY STOP, external................ 35, 37
createLissajousPattern(…)........................... 603 enable(), DataRecorder................................ 514
createNormalForceCondition(…)..........476, 477 Enabling device........................................34, 36
createShearForceCondition(…)............476, 479 Enabling device, external........................ 35, 37
createSinePattern(…)................................... 603 Enabling switches...........................................36
createSpatialForceCondition(…)...................476 equals(…)..................................................... 497
createSpatialTorqueCondition(…)........ 484, 485 Error treatment............................................. 545
createSpiralPattern(…)................................. 603 ESM........................................................20, 271
createTiltingTorqueCondition(…).......... 484, 486 ESM mechanism.......................................... 276
createTurningTorqueCondition(…)....... 484, 485 ESM state, deleting...................................... 280
createUserKeyBar(…)...................................518 ESM state, new............................................ 276
CRR................................................................ 91 EtherCAT........................................................ 20
CRR (operating mode)................................... 29 Ethernet interface.....................................20, 21
EVC.................................................................20
Event-driven Safety Monitoring.................... 256
D Exception........................................................ 20
Danger zone................................................... 28 Exceptions, unhandled................................. 550

660/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Expert..................................................... 90, 197 getEmergencyStopEx().................................464

Extended AMF..............................................261 getEmergencyStopInt()................................. 464
External control.............................................235 getEnablingDeviceState()............................. 465
External E-STOP.......................................... 288 getExecutionMode()......................................468
External position referencing....................... 329 getExternalForceTorque(…)................. 451, 452
getExternalTorque()...................................... 449
getFiredBreakConditionInfo()........................496
F getFiredCondition()...................... 497, 498, 502
Fast entry, Java............................................399 getFlange()....................................................436
Faults.............................................................. 42 getForce()..................................................... 452
Field bus diagnosis...................................... 613 getForceInaccuracy().................................... 453
Field bus, Ethernet-based............................ 209 getFrame(…)........................................ 437, 439
Field buses, overview...................................223 getFriction()...................................................166
File, closing.....................................................55 getGammaRad()........................................... 458
Filter settings................................................ 615 getGravity()................................................... 166
Flange coordinate system.............................. 95 getHomePosition()........................................ 460
Fonts............................................................. 406 getLogLevel()................................................ 167
FOR loop...................................................... 534 getManualOverride()..................................... 469
Force component condition..........................481 getMaxAbsTorqueValues()............................161
Force condition............................................. 475 getMaxBrakeHoldingTorque()....................... 166
ForceComponentCondition........................... 471 getMeasuredBrakeHoldingTorque().............. 166
ForceCondition..............................................471 getMeasuredTorque()....................................449
Frame..............................................................20 getMinBrakeHoldingTorque()........................ 166
Frame management..................................... 173 getMissedEvents()........................................ 502
Frame, creating............................................ 107 getMotion()....................................................544
Frame, creating for application.................... 174 getMotionContainer().................................... 502
Frame, deleting.............................................176 getMotorHoldingTorque().............................. 166
Frame, designating as base........................ 175 getMotorIndex().............................................166
Frame, moving..............................................176 getMotorMaximalTorque()............................. 166
Frame, properties, application data............. 177 getObserverManager()......................... 506, 508
Frame, properties, object templates............ 185 getOperationMode()......................................465
Frame, teaching with hand guiding device..110 getOperationModeVelocityLimit()..................571
FrameDistanceComponentCondition............472 getOperatorSafetyState()..............................465
FrameDistanceCondition.............................. 472 getPositionInfo()............................................497
Frames, manually addressing...................... 110 getPositionInformation()....................... 457, 502
Frames, reteaching.......................................108 getPositionInformation(…)............................ 455
Frames, view................................................ 105 getRecovery()............................................... 543
FSoE............................................................... 21 getRecoveryStrategy(…).............................. 543
Function test................................................... 44 getRotationOffset()........................................458
getSafetyState()............................................ 463
getSafetyStopSignal()................................... 465
getSafetyVelocityLimit()................................ 572
G getSingleMaxAbsTorqueValue(...).................161
General safety measures............................... 41
getSingleTorqueValue(…)............................. 449
Get_State......................................................236
getStartPosition().......................................... 544
getAggregatedVelocityLimit()........................ 572
getStartTimestamp()..................................... 161
getAlphaRad()...............................................458
getState()...................................................... 167
getApplicationData().getFrame(...)................179
getStatusDescription().................................. 581
getApplicationOverride()............................... 469
getStatusGroup().......................................... 581
getApplicationUI()......................................... 518
getStoppedMotion().............................. 497, 499
getAxis()........................................................166
getStopTimestamp()......................................161
getBetaRad().................................................458
getTestedTorque()......................................... 167
getBrakeIndex()............................................ 166
getTimestamp()............................................. 167
getCommandedCartesianPosition()..............502
getTorque()....................................................452
getCommandedCartesianPosition(…).......... 455
getTorqueInaccuracy().................................. 453
getCommandedJointPosition()............. 455, 502
getTorqueValues().........................................449
getCurrentCartesianPosition().............. 455, 502
getTranslationOffset()................................... 457
getCurrentJointPosition()......................455, 503
getTriggerTime()........................................... 502
getDate()....................................................... 581
getVelocityLimitSources()............................. 572
getDeviceVelocityLimit()................................571
GMS................................................................21
getEffectiveOverride()................................... 469

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 661/667

KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Graphics card................................................. 51 isAxisPositionReferenced(…)....................... 466

isEnabled()....................................................516
isFileAvailable().............................................516
H isForceValid(…)............................................ 453
halt()..............................................................531 isInHome().................................................... 460
Hand guiding device enabling activated isMastered().................................................. 461
(AMF)........................................... 258, 259, 291 isReadyToMove().......................................... 461
Hand guiding device enabling deactivated isRecording().................................................516
(AMF)...........................................258, 259, 290 isRecoveryRequired()................................... 543
Handguiding support............................ 205, 209 isRecoveryRequired(…)................................543
handGuiding().......................................381, 427 IStatusController, interface...................576, 578
Handling of failed motion commands.......... 545 IStatusListener, interface.............................. 576
hasActiveMotionCommand().........................463 IStatusMonitor, interface...................... 576, 579
hasChangedActiveStatusGroups()............... 581 isTorqueMeasured()...................................... 162
High-velocity mode (AMF)...........257, 259, 287 isTorqueValid(…)...........................................453
HOME position............................................. 459 ISunriseControllerStateListener.................... 467
HOME position, changing............................ 459 IT security....................................................... 43
HOME position, requesting.......................... 460 ITaskFunction................................................655
Hooke’s law.................................................. 588 ITaskFunctionMonitor....................................562
HRC................................................................ 21 ITaskLogger.................................................. 655
ITorqueSensitiveRobot (interface)................ 449
ITriggerAction, interface............................... 500
IUserKeyBar (interface)................................ 519
I
I/O configuration, exporting.......................... 233
I/O configuration, new.................................. 224
I/O configuration, opening............................ 224 J
I/O group, creating....................................... 228 Java Editor....................................................397
I/O group, deleting........................................229 Java Editor, opening a file........................... 397
I/O group, editing..........................................228 Java file, renaming......................................... 68
I/O group, exporting as a template............. 230 Java package, new........................................ 60
I/O group, importing from a template.......... 230 Java project, new........................................... 66
I/O Mapping (window)..........................231, 232 Java projects, referencing.............................. 67
IAnyEdgeListener..........................................504 Javadoc...........................................................21
IApplicationOverrideControl (interface)........ 469 Javadoc (view)................................................55
ICallbackAction, interface............................. 501 Javadoc browser, configuration................... 403
ICondition (inferface).................................... 471 Javadoc information, displaying................... 401
IControllerStateListener................................ 462 Jog keys.................................. 72, 75, 102, 103
Identification plate.................................... 73, 77 Jog mode........................................................40
IF ELSE branch............................................537 Jog override..................................................101
IFallingEdgeListener..................................... 504 Jog velocity.....................................................97
IForceSensitiveRobot (interface).................. 451 Jogging options (button)........................ 80, 100
Industrial robot......................................... 23, 27 Jogging type (button)...............................81, 98
Information about robot and robot Jogging, axis-specific............................. 99, 102
controller....................................................... 124 Jogging, Cartesian................................. 99, 103
Initialization................................................... 408 Jogging, robot.................................................99
initialize()...................................... 398, 553, 556 Joint Path......................................................373
initializeCyclic(…)..........................................553 JointTorqueCondition.................................... 471
Input signal (AMF).......................257, 259, 288 JP motion......................................................373
Inputs/outputs, displaying............................. 121 JP spline block............................................. 373
Installation.....................................................205 JP spline block, creating..............................423
Installation, KUKA Sunrise.Workbench..........51 JRE................................................................. 21
Intended use...................................................26
Introduction..................................................... 19
IORangeCondition........................................ 472 K
IP address ranges, blocked........................... 57 Keyboard key........................................... 72, 75
IP address, robot controller......................... 124 Keypad............................................................83
IRecovery, interface......................................543 KLI..................................................21, 205, 208
IRisingEdgeListener......................................504 KMP................................................................ 21
ISafetyState (interface).................................464 Knowledge, required.......................................19
isAxisGMSReferenced(…)............................466 KRCDiag....................................................... 620

662/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

KUKA Customer Support.....................124, 657 Message window.......................................... 112

KUKA Line Interface.....................................208 Methods, extracting...................................... 400
KUKA PSM...........................................270, 286 Mode selection............................................... 38
KUKA RoboticsAPI......................................... 21 Mode selector switch............................... 72, 74
KUKA Service...............................................657 Monitoring of processes...................... 473, 503
KUKA smartHMI.......................................21, 80 Monitoring spaces........................................ 300
KUKA smartPAD................................21, 29, 71 Monitoring, physical safeguards.....................37
KUKA smartPAD-2................................... 21, 29 Motion command, canceling........................ 532
KUKA Sunrise Cabinet...................................21 Motion enable (AMF)...................257, 259, 287
KUKA Sunrise.EnhancedVelocityControl..... 567 Motion execution, pausing........................... 532
KUKA Sunrise.OS.......................................... 21 Motion programming, basic principles......... 373
KUKA Sunrise.SafetyVisualization............... 359 Motion types................................................. 373
KUKA Sunrise.StatusController....................575 MotionBatch.................................................. 420
MotionPathCondition.....................................472
Mounting orientation........................ 58, 95, 205
L move(…)...................................... 416, 439, 545
Labeling.......................................................... 40 moveAsync(…).............................416, 439, 547
Language..................................................81, 89 Multiple branches......................................... 539
Language package, installing...................... 219
Language selection (button).......................... 81
Liability............................................................ 27 N
Licenses..........................................................22 Navigation bar................................................ 81
LIN................................................................ 418 Network settings, adapting...........................206
LIN REL........................................................ 419 New frame, creating..................................... 106
LIN, motion type........................................... 374 New Java class (button)................................ 57
Linear motion....................................... 418, 419 New Java package (button)...........................57
Lissajous oscillation, overlaying................... 605 New Sunrise application (button)...................56
Load data......................................................182 New Sunrise project (button)......................... 56
Log entries, filtering......................................616 Non-cyclic background task......................... 556
Log, displaying..............................................613 Non-safety-oriented functions.........................38
Log, view...................................................... 614 Normal force................................................. 475
Loops, nesting.............................................. 542 NotificationType, Enum.................................506
Low Voltage Directive.....................................28 Null space motion.........................................103

M O
Machinery Directive........................................ 28 Object management..................................... 180
Main menu key........................................ 72, 75 Object properties, displaying/editing............ 183
Main menu, calling......................................... 87 Object template, copying..............................188
Maintenance................................................... 47 Object templates (view)..................................54
Manipulator..................................23, 27, 29, 32 ObserverManager.................................506, 508
Manual guidance mode................................427 Offset, teaching............................................ 134
Manual guidance, axis limitation..................431 Old project, loading...................................... 216
Manual guidance, motion type.....................381 onIsReadyToMoveChanged(…)....................462
Manual guidance, programming.................. 427 onKeyEvent(…), IUserKeyListener...............521
Manual guidance, velocity limitation............ 432 onSafetyStateChanged(…)...........................467
Manual mode..................................................46 onTriggerFired(…).........................................501
Manual override..................... 97, 114, 116, 469 Open-source................................................... 22
Mapping, inputs/outputs............................... 233 Operating hours meter................................. 124
Mass of the heaviest workpiece.................. 357 Operating mode, changing.............................92
Mastering...................................................... 132 Operating time.............................................. 124
Mastering state, requesting..........................461 Operation, KUKA smartPAD.......................... 71
Mastering, checking......................................137 Operation, KUKA Sunrise.Workbench........... 53
Mastering, deleting....................................... 139 Operator......................................... 90, 196, 197
Mastering, with tool...................................... 136 Operator safety........................................ 35, 37
Mastering, without tool................................. 133 Operators................................................31, 473
Media flange................................................. 211 Option package, installing............................ 217
Media flange Touch............................. 288, 290 Option package, removing from robot
Menu bar........................................................ 54 controller....................................................... 221
Message programming.................................528 Option package, uninstalling........................ 220

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 663/667

KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Option packages...........................................217 Project, synchronization............................... 199

Options..................................................... 23, 27 Project, transferring to the robot controller. 200
Orientation control........................................ 426 Project, updating...........................................201
Orientation control, LIN, CIRC, SPL............384 Projects, archiving.......................................... 64
Output, changing.......................................... 121 Projects, loading to workspace............... 64, 65
Overload......................................................... 41 Properties (view).............................................55
Override........................................101, 114, 115 Protected space................................... 300, 304
Override (button)...................................... 81, 97 Protective equipment......................................40
Override, changing and requesting............. 469 PSA.................................................................30
Overview of the industrial robot.....................23 PSM................................................................ 21
Overview, controllers.................................... 585 PSM mechanism.......................................... 273
Overview, motion parameters..............424, 430 PTP............................................................... 417
Overview, Sunrise project............................ 173 PTP, motion type.......................................... 373
Overview, Sunrise.RolesRights.................... 197 PTPRecoveryStrategy (class)...................... 544

P R
Package Explorer (view)................................ 54 RAM................................................................ 51
Panic position................................................. 36 Reaction distance........................................... 28
Password, changing..................................... 198 Ready for motion signal, reacting to
Path-related condition...................................489 changes........................................................ 462
Path-related switching actions.............473, 499 Recommissioning................................... 43, 131
Pausing, robot application....................115, 116 Reduced-velocity mode (AMF)....257, 259, 287
PDS firmware update................................... 131 Redundancy angle........................................390
Performance Level......................................... 34 Redundancy information...................... 178, 389
Permanent Safety Monitoring.......................255 Reference, canceling......................................67
Personal protective equipment...................... 30 Referencing application, creating.................329
Personnel........................................................30 Referencing state, requesting...................... 466
Perspective, selection.....................................54 Rejecting loop...............................................535
Perspectives, displaying................................. 55 Release notes, displaying.............................. 69
Plant integrator............................................... 30 Remote debugging...............................209, 623
PLC................................................................. 22 Renaming variables......................................398
Point-to-point.................................................373 Repair............................................................. 47
Point-to-point motion.................................... 417 Requesting, robot position........................... 455
Position and axis torque referencing...........325 Reset (button)............................................... 116
Position controller.................................585, 587 Resetting, robot application..........................116
Position referencing Retraction, robot............................................. 91
With internal mastering sensors in Robot activity, checking................................462
kinematic system.....................................326 Robot application, pausing...................115, 116
Position referencing (AMF)......... 258, 260, 292 Robot application, resetting..........................116
positionHold(…)............................................ 610 Robot application, selecting..........................111
Post-test loop................................................536 Robot application, starting automatically..... 115
Preventive maintenance work........................ 48 Robot application, starting manually............ 115
Primitive data types......................................408 Robot base coordinate system...................... 95
Processor........................................................51 Robot controller........................................23, 27
Product description.........................................23 Robot controller, switching off......................131
PROFINET......................................................21 Robot controller, switching on......................131
PROFIsafe...................................................... 21 Robot controller, switching on/off.................131
Program execution........................................ 111 Robot level......................................................85
Program execution control........................... 531 Robot position, requesting........................... 455
Program run mode, changing and Robot, repositioning......................................116
requesting..................................................... 468 RoboticsAPI.................................................... 21
Program run mode, setting.......................... 113 run()...................................................... 398, 556
Program run modes......................................114 runCyclic().....................................................553
Programming................................................ 397
Programming (perspective)............................ 55
Programming, compliant robot..................... 585 S
Project management.................................... 173 Safe operational stop................................... 311
Project synchronization................................ 199 Safe operational stop, external............... 35, 38
Project, loading from the robot controller....202 Safeguards, external...................................... 40

664/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

Safety..............................................................27 setJointJerkRel(…)............................... 425, 426

Safety-oriented functions................................34 setJointLimitsEnabled(…)............................. 430
Safety-oriented reactions..............................253 setJointLimitsMax(…)................................... 430
Safety-oriented stop reactions....................... 32 setJointLimitsMin(…).................................... 430
Safety-oriented tool, configuring.................. 188 setJointLimitViolationFreezesAll(…)............. 430
Safety-oriented tools.....................................336 setJointVelocityLimit(…)................................431
Safety-oriented tools, mapping.................... 282 setJointVelocityRel(…)......................... 425, 426
Safety acceptance overview........................ 330 setLED(…), IUserKey................................... 525
Safety concept..............................................251 setMaxCartesianVelocity(…).........................594
Safety configuration......................................251 setMaxControlForce(…)................................594
Safety configuration, activating.................... 284 setMaxPathDeviation(…).............................. 595
Safety configuration, deactivating................ 285 setNullSpaceDamping(…)............................ 593
Safety configuration, opening...................... 270 setNullSpaceStiffness(…)............................. 593
Safety configuration, restoring..................... 285 setOrientationReferenceSystem(…).....387, 426
Safety controller, resuming.............................94 setOrientationType(…)......................... 384, 426
Safety function, new for ESM......................279 setPermanentPullOnViolationAtStart(…)...... 430
Safety function, new for PSM......................274 setPhaseDeg(…).......................................... 600
Safety functions.............................................. 34 setPositionLimit(…).......................................601
Safety functions, configuration..................... 273 setRiseTime(…)............................................ 602
Safety functions, configuring........................ 276 setSafetyWorkpiece(…)................................ 443
Safety functions, deactivation via an input..268 setStayActiveUntilPatternFinished(…)..........602
Safety instructions.......................................... 19 setStiffness(…)..................................... 592, 609
Safety interfaces...........................................254 setStiffnessForAllJoints(…)...........................609
Safety maintenance......................................197 setText(…), IUserKey................................... 524
Safety maintenance technicians.................... 90 setTotalTime(…)............................................602
Safety signals, requesting state...................463 Shear force................................................... 475
Safety stop......................................................29 Simple force oscillation, overlaying............. 604
Safety stop 0.................................................. 29 Single point of control.................................... 48
Safety stop 1.................................................. 29 Singletons.............................................412, 441
Safety stop 1 (path-maintaining)....................29 Singularities.................................................. 392
Safety stop, external................................35, 37 System-dependent...................................394
Safety zone........................................29, 31, 32 Singularity..................................................... 385
Safety, general................................................27 smartHMI.................................................. 21, 80
SafetyConfiguration.sconf (file).............. 60, 270 smartPAD.....................................22, 29, 42, 71
Serial number, robot.....................................124 smartPAD enabling switch deactivated
Serial number, robot controller.................... 124 (AMF)....................................................258, 287
Service life...................................................... 28 smartPAD enabling switch panic activated
Set base for jogging (button).......................107 (AMF)................................................... 258, 287
Set methods......................................... 424, 430 smartPAD unplugging allowed..................... 355
setAdditionalControlForce(…).......................593 smartPAD, connecting.................................... 78
setAmplitude(…)........................................... 599 smartPAD, disconnecting............................... 77
setApplicationOverride(…)............................470 smartPAD, software update........................... 79
setBias(…).................................................... 600 Software................................................... 23, 27
setBlendingCart(…)...................................... 426 Software components.....................................23
setBlendingOri(…)........................................ 426 Software limit switches...................................40
setBlendingRel(…)........................................426 Spiral-shaped force oscillation, overlaying.. 607
setCartAcceleration(…).................................425 SPL, motion type..........................................375
setCartJerk(…)..............................................425 Spline segment.............................................375
setCartVelocity(…)........................................ 425 Spline, motion type.......................................375
setCartVelocityLimit(…)................................ 431 SPOC..............................................................48
setCriticalText(…), IUserKey................ 526, 527 Standard frame for motions......................... 183
setDamping(…).................................... 592, 609 Standstill monitoring..................................... 311
setDampingForAllJoints(…).......................... 609 Standstill monitoring of all axes (AMF)....258,
setExecutionMode(…).................................. 468 261, 312
setFallTime(…)..............................................602 Start-up...................................................43, 131
setForceLimit(…).......................................... 600 Start backwards key................................ 72, 75
setFrequency(…).......................................... 599 Start key...................................... 72, 73, 75, 76
setHoldTime(…)............................................ 602 startEvaluation()............................................160
setHomePosition(…).....................................459 Starting, robot application.............................115
setJointAccelerationRel(…).................. 425, 426 startRecording()............................................ 514

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 665/667

KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

StartRecordingAction.................................... 514 Templates, user-specific............................... 400

Station configuration.....................................205 Terms used..................................................... 20
Station configuration, overview.................... 205 Terms, safety.................................................. 28
Station level.................................................... 83 Test mode (AMF).........................257, 259, 287
Station_Error.................................................237 Tilting torque................................................. 484
StationSetup.cat (file).............................60, 206 Time delay (AMF)........................258, 262, 312
Status............................................................390 Tool-related velocity component (AMF)....258,
Status display................................................. 82 260, 298
Status monitor.............................................. 579 Tool calibration..............................................140
Stop category 0.............................................. 29 Tool Center Point..........................................140
Stop category 1.............................................. 30 Tool coordinate system..........................95, 140
Stop category 1 (path-maintaining)............... 30 Tool frame, creating......................................184
STOP key.................................................72, 75 Tool load data, determining......................... 148
Stop reactions, safety-oriented...................... 32 Tool orientation (AMF).................258, 260, 310
stopEvaluation()............................................ 160 Tool orientation, monitoring.......................... 308
Stopping distance............................ 28, 32, 302 Tool, creating................................................ 181
stopRecording()............................................ 515 Tool, integrating............................................ 434
StopRecordingAction.................................... 515 Tool, switching off.........................................287
Storage........................................................... 48 Toolbars.......................................................... 54
Structure, robot application.......................... 397 Torque........................................................... 484
Sunrise applications....................................... 60 Torque component condition........................ 487
Sunrise I/Os, changing.................................229 Torque referencing (AMF)........... 258, 260, 293
Sunrise I/Os, creating...................................225 Torque value determination..........................159
Sunrise I/Os, deleting...................................229 TorqueComponentCondition......................... 472
Sunrise project................................................22 TorqueEvaluator (class)....................... 157, 160
Sunrise project, new.......................................57 Torques, axis-specific................................... 121
Sunrise project, overview............................. 173 TorqueStatistic (class)................. 157, 160, 161
Sunrise.RolesRights, overview.....................197 Touch screen.................................................. 71
Sunrise.StatusController............................... 575 Trademarks..................................................... 20
Sunrise.Workbench, starting.......................... 53 Training........................................................... 19
Sunrise.Workbench, user interface................ 53 Transportation................................................. 43
SunriseExecutionService.............................. 468 Trigger.................................................. 473, 499
SunriseSafetyState (class)........................... 464 Trigger information, evaluating.....................502
Support request............................................ 657 Triggers, programming................................. 500
Surface normal............................................. 475 triggerWhen(…)............................................ 500
SWITCH branch........................................... 539 Turn...............................................................391
Symbols........................................................ 406 Type, robot....................................................124
Synchronize project (button).......................... 56
Synchronous motion execution.................... 416
System integrator.............................. 28, 30, 31 U
System requirements, PC.............................. 51 Uninstallation, option package..................... 220
System software, installing...........................213 Uninstallation, Sunrise.Workbench.................51
System states, requesting............................460 Unmastering..................................................139
User.......................................................... 28, 30
User administration.......................................196
T User dialogs, programming.......................... 529
T1 (operating mode).......................................30 User group (button)........................................ 81
T2 (operating mode).......................................30 User group, changing.....................................91
Target group................................................... 19 User groups.................................................... 90
Task functions...............................................655 User interface, KUKA smartHMI....................80
Task, remote debugging...............................624 User interface, Sunrise.Workbench............... 53
Tasks (view)....................................................55 User key bar, creating..................................518
TCP................................................ 22, 140, 184 User key selection (button)............................94
TCP force monitoring................................... 316 User keys................................................. 72, 75
TCP force monitoring (AMF)....258, 261, 316, User keys (button)..........................................81
350 User keys, activating...................................... 93
Teach pendant......................................... 23, 27 User keys, defining.......................................517
Teaching....................................... 107, 108, 110 User messages, programming..................... 528
Template, Sunrise project...............................57 User PSM..................................................... 270
Templates......................................................399 UserKeyAlignment (enum)........................... 523

666/667 | www.kuka.com KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021

 KUKA Sunrise.OS 1.17 KUKA Sunrise.Workbench 1.17

V
Variables, renaming......................................398
Velocity..........................................................101
Velocity monitoring functions........................293
Velocity monitoring, T1...................................39
Version, System Software............................ 124
View, Backup Manager................................ 125
View, frames................................................. 105
View, log....................................................... 614
Views, repositioning........................................55
Virus scanner................................................217
Virus scanner, displaying messages............619
Virus scanner, installing............................... 219

W
waitFor(…).................................................... 508
Warnings......................................................... 19
WHILE loop.................................................. 535
Workpiece frame, creating........................... 184
Workpiece load data, entering..................... 195
Workpiece, creating......................................181
Workpiece, integrating..................................434
Workpieces, safety-oriented use..................193
Workspace................28, 31, 32, 300, 302, 307
Workspace, new............................................. 63
Workspace, Sunrise.Workbench.................... 63
Workspace, switching.....................................64
Workspaces, switching................................... 64
World coordinate system................................95

X
XYZ 4-point method..................................... 141

KUKA Sunrise.OS 1.17 SI V2 | Issued: 18.03.2021 www.kuka.com | 667/667