KUKA Robots

The following chapter describes the installation of the voraus.core with KUKA robots.

Note

Supported KUKA Cabinets

The installation described in this chapter applies to the following cabinets:

• KR C4, KR C4 compact, KR C5, and KR C5 micro with KSS 8.6.X

• KR C5 micro-2 with iiQKA.OS2 and KSS 9.3.X

For other cabinets or other KUKA software versions, please contact voraus support.

Warning

When using, operating and interacting with a KUKA robot, always obey the instructions of the original KUKA manual.

The voraus.core can only control the KUKA robot in the operating mode AUT or EXT. For the resulting safety requirements, see Safety Information for Physical Robots.

The following sections assume that the KUKA robot is set up and can be moved with the KUKA smartPAD and the default KUKA controller software. If the robot is not set up yet, please follow the official KUKA documentation. Also, it is assumed that the user knows the basic steps on how to operate the robot with the KUKA smartPAD like switching the operating mode and starting/stopping KUKA programs.

In order to connect the voraus.core to a KUKA system, the KUKA controller has to be prepared first. For this, follow the chapters Connecting a PC to the KUKA robot controller and Setting up the RSI interface.

Connecting a PC to the KUKA Robot Controller

To deploy files to the KUKA controller, you must first establish a connection between your computer and the KUKA controller. Connect your computer to the KUKA controller KLI interface via Ethernet:

• On KR C4 and KR C4 compact, the KLI is on X66.

• On KR C5 micro-2, the KLI is on XF4 (upper right Ethernet port).

Configure the KLI IP Address

The IP address of the KLI interface is 172.31.1.147, which can be configured on the robot’s smartPAD.

The following overview provides examples of IP configurations for smartPADs running various operating systems.

KSS 8.6.X

The following steps were tested on a KR C4 compact with KSS 8.6.10.

Navigate to Main menu -> Start-up -> Network configuration.

Fig. 14 KR C4 compact (KSS 8.6.10) smartPAD network configuration menu

iiQKA.OS2

The following steps were tested on a KR C5 micro-2 with iiQKA.OS2 and KSS 9.3.2.

On the smartPAD, navigate to Main menu (Fig. 15/➊) -> System Settings (Fig. 15/➋).

Fig. 15 KR C5 micro-2 (iiQKA.OS2) smartPAD network configuration menu (1)

Click Network (Fig. 16/➊) and select KLI (Fig. 16/➋).

Fig. 16 KR C5 micro-2 (iiQKA.OS2) smartPAD network configuration menu (2)

Note

In this example, the default KLI IP changed from 172.31.1.147 to 192.168.100.145 (which will also be used for RSI communication).

Configure the Computer IP Address

Configure the connected Ethernet port of your computer to be in the same network as the KLI interface of the KUKA robot (see exemplary IP address in Fig. 17).

Fig. 17 IP configuration of the local machine

Note

To verify the connection, you can ping the KUKA robot controller from your computer. If the ping is successful, the connection is established.

Connect with the KUKA Software

To connect to the KUKA robot controller (for example, to upload or edit files on it), it is recommended to use the official KUKA software. The required software depends on the controller’s operating system.

KSS 8.6.X

WorkVisual is used for robot controllers running the KSS 8.X operating systems. In this example, WorkVisual 6.0 is used with a KR C4 controller running KSS 8.6.10.

1. Get the software installation file, e.g., from https://my.kuka.com (Version 6.0 or compatible).

2. Extract and install the software using the default settings.

3. Connect your computer to the controller as described above.

4. Start WorkVisual on your computer.

5. After the software starts, click Open Project from the file menu (Fig. 18/➊).

   

   Fig. 18 WorkVisual first steps (1)

6. On the new window, click Search (Fig. 19/➊). The robot should be found automatically. If not, search for the robot IP manually as illustrated in Fig. 19/➋ and ➌.

   

   Fig. 19 WorkVisual first steps (2)

7. The files on the robot control can now be displayed by clicking Programming and diagnosis (Fig. 20/➊). If necessary, the robot control can be selected using the corresponding checkbox (Fig. 20/➋). The main directory is shown in Fig. 20/➌. It might be necessary to click Load files and folders from controller in the toolbar at the top to synchronize your WorkVisual workspace with the one of your controller (Fig. 20/➍).

   

   Fig. 20 WorkVisual first steps (3)

Note

If the buttons are grayed out, you might need to click Establish controller state (Fig. 21/➊) first.

Fig. 21 WorkVisual first steps (4)

iiQKA.OS2

iiQWorks.Sim is used for robot controllers running the iiQKA.OS2 operating system. In this example, iiQWorks.Sim Basic 1.3 is used with a KR C5 micro-2 controller running iiQKA.OS2 and KSS 9.3.2.

1. Get the software installation file, e.g., from https://my.kuka.com (Version 1.3 or compatible).

2. Install the software using the default settings.

3. Connect your computer to the controller as described above.

4. Start iiQWorks.Sim on your computer.

5. After iiQWorks.Sim starts, click FILE.

   

   Fig. 22 iiQWorks.Sim open project from controller (1)

6. Click Open -> Online, enter the KLI IP address, and double-click the controller name to open the controller tree. Log in as “Expert” and double-click your project.

   

   Fig. 23 iiQWorks.Sim open project from controller (2)

Note

To set up the robot, please follow the official KUKA documentation and tutorials. Helpful video tutorials for iiQWorks.Sim can also be found on the KUKA YouTube channel.

Setting up the RSI Interface

Before the voraus.operator can be used for controlling the KUKA robot, some additional network configurations have to be done, and certain files have to be uploaded to the KUKA control.

RSI Option Package

For RSI communication, the KUKA.RobotSensorInterface option package must be installed on the KUKA controller. The required version depends on the operating system of the KUKA controller and is listed in the KUKA requirements.

The installed KUKA option packages can be checked via WorkVisual or iiQWorks.Sim, depending on the operating system of the KUKA controller:

KSS 8.6.X

The following steps were tested on a KR C4 compact with KSS 8.6.10.

Enter the Configuration and commissioning tab in the bottom left corner (Fig. 24/➊). Afterwards, open the file explorer and then the Options folder of your control (Fig. 24/➋).

Fig. 24 KUKA option packages

iiQKA.OS2

The following steps were tested on a KR C5 micro-2 with iiQKA.OS2 and KSS 9.3.2.

Assigned option packages are located in the window Devices -> Option Packages (Fig. 25/➊).

Available and assigned option packages can also be found in the window Component Properties. To do so, select your robot in the window Devices (Fig. 25/➋) and scroll in the window Component Properties down to the section Option packages configuration (Fig. 25/➌).

Fig. 25 KUKA option packages in iiQWorks.Sim

Connect the voraus.ipc to the KLI

RSI communication uses the KLI interface. Connect the Ethernet port of the voraus.ipc that is used for RSI communication to the KLI port of the KUKA controller. The location of the KLI port depends on the controller and is described in Connecting a PC to the KUKA Robot Controller.

The IP address used for RSI on the KUKA controller must be in the same network range as this Ethernet port of the voraus.ipc. Its IP address is configured in configuration of the runtime (referred to as <IP_of_the_voraus.ipc>).

Depending on the operating system, an additional virtual network interface must be set up on the KUKA controller to enable communication between voraus.operator and the KUKA controller.

Follow the next steps to set up the RSI interface between the robot and the voraus.core:

KSS 8.6.X

The following steps were tested on a KR C4 compact with KSS 8.6.10.

On the KR C4, an additional virtual network interface must be set up on the KUKA controller to enable communication between voraus.operator and the KUKA controller. This virtual interface uses the same physical port (X66) as the KLI interface. Depending on the task, plug the Ethernet cable either into your computer (e.g., to transfer files with WorkVisual) or into the voraus.ipc (for RSI communication).

Create a virtual network interface

Use the robot’s smartPAD to create a new virtual network interface in the robot’s advanced network settings (e.g., virtual6, see Fig. 26). This interface requires a different IP address than the KLI interface shown in Fig. 14, but uses the same physical network port of the KRC.

If a second virtual network had already been created, it can be used for the voraus.operator as well. In the interface settings, the receiving task must be set to UDP. The virtual network interface must have the same network range as the IP address configured in configuration of the runtime (referred to as <IP_of_the_voraus.ipc>).

Fig. 26 RSI IP address on KUKA control

iiQKA.OS2

The following information applies to a KR C5 micro-2 with iiQKA.OS2 and KSS 9.3.2.

No additional virtual network required.

The RSI interface can be set up directly in the network settings of the robot’s smartPAD as already described in Connecting a PC to the KUKA Robot Controller (see Fig. 15 and Fig. 16).

Import the RSI Files to the KUKA Controller

For the required voraus files, please refer to Robot Requirements, where all necessary files are listed.

KSS 8.6.X

The following steps were tested on a KR C4 compact with KSS 8.6.10.

1. Import the RSI context file vorausRSI.rsix via WorkVisual. For that, switch to the Programming and diagnosis tab in the bottom left corner (Fig. 27/➊). From there, you can create new folders by right-clicking an existing folder and selecting the New folder option (Fig. 27/➋) and add files directly via drag & drop. Alternatively, you can open the workspace in the default Windows Explorer by right-clicking a folder and selecting Open in Windows Explorer (Fig. 27/➌).

   

   Fig. 27 Uploading files

   The vorausRSI.rsix context file should be moved to “RSI/” -> “SensorInterface/” (Fig. 28/➌).

2. Using WorkVisual, copy the vorausRSI.xml file to the same directory as the RSI context file. If needed, modify the IP address of the voraus.ipc:

   <ROOT>
      <CONFIG>
         <IP_NUMBER>IP_of_the_voraus.ipc</IP_NUMBER>
         <PORT>59152</PORT>
         <SENTYPE>ImFree</SENTYPE>
         <ONLYSEND>FALSE</ONLYSEND>
      </CONFIG>
   

3. Copy the file voraus_cell.sub to the program directory of the robot, e.g., to “KRC” -> “R1/” -> “Program/” -> “vorausRSI/” (Fig. 28/➊).

4. Copy the file voraus_rsi.src to the program directory of the robot, e.g., to “KRC” -> “R1/” -> “Program/” -> “vorausRSI/” (Fig. 28/➋).

5. Afterwards, the files have to be uploaded to the robot. You have to be logged in at least as “Expert” on the KUKA smartPAD for this. Click Transfer changes to the controller as shown in Fig. 28/➍. Confirm the operation in the pop-up. When asked for remote access on the KUKA smartPAD, confirm it as well. When the pop-up disappears in WorkVisual, the process is complete.

   

   Fig. 28 File management view in WorkVisual

iiQKA.OS2

The following steps were tested on a KR C5 micro-2 with iiQKA.OS2 and KSS 9.3.2.

1. Import the RSI context files vorausRSI.rsix and vorausRSI.xml via iiQWorks.Sim. Expand the iiQKA.RobotSensorInterface folder in the tree view of the controller and select either Contexts to upload the vorausRSI.rsix or Ethernet configurations to upload vorausRSI.xml (Fig. 29/➊). Click Import in the toolbar of the Properties window (Fig. 29/➋) and select the corresponding file from your computer.

   

   Fig. 29 Import RSI files using iiQWorks.Sim

2. Click the PROGRAM tab in the top menu (Fig. 30/➊). Afterwards, click KRL -> PROGRAMS (Fig. 30/➋) and select Extended program view (Fig. 30/➌).

3. Select the folder “R1/” -> “Program/” and click Add folder in the toolbar to create the folder vorausRSI in the program directory of the robot, i.e., “R1/” -> “Program/” -> “vorausRSI/” (Fig. 30/➍).

4. Use Import KRL files (Fig. 30/➎) to import the KRL files voraus_cell.sub and voraus_rsi.src into the newly created folder vorausRSI.

   

   Fig. 30 Import voraus KRL files into the program directory of the robot in iiQWorks.Sim

5. Deploy the files to the robot by clicking CONFIGURATION (Fig. 31/➊) -> Deploy Configuration onto Controller (Fig. 31/➋).

   

   Fig. 31 Deploy configuration onto Controller

Add a User-Defined Variable

Add the following line into the section Userdefined Variables of System/$config.dat

INT VORAUS_TOOL_ID = 16

Configure the Submit Interpreter

On the smartPAD, configure the voraus_cell.sub in the submit interpreter. This is only possible when logged in at least as “Expert”.

KSS 8.6.X

The following steps were tested on a KR C4 compact with KSS 8.6.10.

• Enter the Submit interpreter menu on the KUKA smartPAD (Fig. 32/➊).

• Click Display/Assign (Fig. 32/➋).

Fig. 32 KUKA submit interpreter

• Enter Current Display/Assign (Fig. 33/➊).

• Select the voraus_cell script in EX1 (Fig. 33/➌).

• Click Select/Start (Fig. 33/➋).

• Check that voraus_cell is running (Fig. 33/➍).

Fig. 33 KUKA submit interpreter 2

• Enter the Cold start-configuration section (Fig. 34/➊) and select voraus_cell at EX1 (Fig. 34/➋).

• Leave the screen (Fig. 34/➌).

Fig. 34 KUKA submit interpreter 3

iiQKA.OS2

The following steps were tested on a KR C5 micro-2 with iiQKA.OS2 and KSS 9.3.2.

• Enter the Submit interpreter menu on the KUKA smartPAD (Fig. 35/➊).

• Click the configuration symbol (Fig. 35/➋).

Fig. 35 KUKA submit interpreter

• Select the voraus_cell script in Extended1 (Fig. 36/➊).

• Click Transfer to cold start configuration (Fig. 36/➋).

• Start the submit script (Fig. 36/➌).

• Close the configuration menu (Fig. 36/➍).

Fig. 36 Configure voraus_cell.sub in the submit interpreter on KUKA smartPAD

• Check that voraus_cell is running (see Fig. 37).

Fig. 37 Running submit scripts

• Check that voraus_cell is configured in the cold start configuration (see Fig. 38).

Fig. 38 Submit interpreter cold start configuration

After this procedure, the KUKA robot is ready to communicate with the voraus.core.

Configuration of Automatic External (AUT EXT)

This section describes the configuration of a KUKA robot for Automatic External (AUT EXT) operation.

The purpose of the Automatic External configuration is to allow the voraus.core to control the KUKA robot via digital I/O signals while the robot is in the EXT operating mode.

This enables the voraus.core to:

• Establish the RSI connection by automatically starting the voraus_rsi.src script on the KRC

• Switch the regulators on and off

• Acknowledge faults

Note

The KUKA signals and the smartPAD refer to the regulators as drives. In this section, both terms describe the same state.

Configuration on the KUKA Controller

The following steps prepare the KRC for AUT EXT operation: deploying the required files, configuring the AUT EXT signals, and setting up the fieldbus connection to the voraus.ipc.

Required KRC Files

For the required voraus files, please refer to Robot Requirements, where all necessary files are listed.

The AUT EXT configuration builds on the RSI interface. Before continuing, make sure that all steps described in Setting up the RSI interface have been completed and that the files deployed there are up-to-date.

In addition, the file cell.src, which is listed in Robot Requirements as only needed for AUT EXT, must be deployed to “KRC” -> “R1/” -> “cell.src”.

Also check that the following variable is added to the Userdefined Variables section in “KRC” -> “R1/” -> “System/” -> “$config.dat”:

BOOL VORAUS_RUN_RSI=TRUE

Automatic External Signal Configuration

The following Automatic External signals are used to communicate with the voraus.core. Each signal is assigned to a KUKA digital input $IN[..] or output $OUT[..], which is then mapped to the fieldbus, see Fieldbus Configuration. The fieldbus transfers the signals to the voraus.ipc, where the Automatic External script processes them, see Automatic External Script on the voraus.ipc.

Configuration of Automatic External Signals

The Automatic External signals are configured on the KUKA smartPAD:

1. Set the operating mode to T1.

2. Log in as Expert.

KSS 8.6.X

The following steps were tested on a KR C4 compact with KSS 8.6.10.

Open Main menu -> Configuration -> Inputs/outputs -> Automatic External to view and configure the signal mapping (see Fig. 39).

Fig. 39 Configuration of Automatic External signals

iiQKA.OS2

The following steps were tested on a KR C5 micro-2 with iiQKA.OS2 and KSS 9.3.2.

Open Main menu (Fig. 40/➊) -> System Settings (Fig. 40/➋) -> Automatic External (Fig. 41/➌).

Fig. 40 Configuration and overview of Automatic External signals (1)

Select the signal type in the tabs at the top (Fig. 41/➍). Configure the signal mapping in the column Assigned to (Fig. 41/➎). The current signal states are shown in the column Value (Fig. 41/➏).

Fig. 41 Configuration and overview of Automatic External signals (2)

Alternatively, the Automatic External signals can be configured in iiQWorks.Sim:

1. Click CONFIGURATION (Fig. 42/➊) -> I/O Mapping Editor (Fig. 42/➋).

2. In the right pane, expand Variables and select Automatic Extern (Fig. 42/➌).

3. Right-click Automatic Extern and select Show Connections (Fig. 42/➍).

4. The configured connections between the KUKA I/Os and the Automatic External signals are shown at the bottom (Fig. 42/➎). To add a connection, select the KUKA I/O in the left pane and the Automatic External signal in the right pane, then right-click -> Connect.

5. Deploy the changes to the controller via CONFIGURATION -> Deploy Configuration onto Controller.

Fig. 42 Configuration and overview of Automatic External signals in iiQWorks.Sim

In this example, the KUKA I/Os start at $IN[1] and $OUT[1]. Replace them with your own I/O list.

Input Configuration

The inputs that the voraus.ipc sends to the KUKA controller are listed in Table 1. The corresponding input configuration is shown below.

Table 1 Automatic External inputs (voraus.ipc → KUKA)

Signal	Example	Function	Type
$EXT_START	$IN[1]	Starts or resumes the selected program (CELL)	Rising edge
$MOVE_ENABLE	$IN[2]	Motion enable from the voraus.ipc; must stay TRUE during operation	Level
$CONF_MESS	$IN[3]	Acknowledges errors	Rising edge
$DRIVES_ON	$IN[4]	Switches the drives on	Pulse ≥ 20 ms
$DRIVES_OFF	$IN[5]	Switches the drives off (low-active)	Pulse ≥ 20 ms
PGNO_VALID	$IN[6]	Program number on the bus is valid	Rising edge
$I_O_ACT	$IN[1025]	Enables the AUT EXT interface (usually left on the always-TRUE input)	Level

Note

Two KUKA inputs are fixed: $IN[1025] is always TRUE and $IN[1026] is always FALSE.

Note

The $MOVE_ENABLE input remains valid even in other operating modes. For example, in T1, error KSS01376 “Active commands inhibited” may occur if the input is not set. In this case, the input must be set to high or 1025 (always high).

KSS 8.6.X

The following configuration was tested on a KR C4 compact with KSS 8.6.10.

Fig. 43 Configuration of Automatic External inputs

iiQKA.OS2

The following configuration was tested on a KR C5 micro-2 with iiQKA.OS2 and KSS 9.3.2.

Fig. 44 shows the input connections in iiQWorks.Sim, configured as described in Fig. 42.

Fig. 44 Configuration of Automatic External inputs in iiQWorks.Sim

Output Configuration

The outputs that the KUKA controller reports to the voraus.ipc are listed in Table 2. The corresponding output configuration is shown below.

Table 2 Automatic External outputs (KUKA → voraus.ipc)

Signal	Example	Meaning when TRUE
$ON_PATH	$OUT[1]	Robot is on the programmed path
$STOPMESS	$OUT[2]	A stop message/error is present; acknowledge with $CONF_MESS
$PERI_RDY	$OUT[3]	Drives are on
$IN_HOME	$OUT[4]	Robot is in the HOME position
$PRO_ACT	$OUT[5]	A program is active on the robot controller
$ALARM_STOP	$OUT[1013] (default)	The safety circuit is closed (low-active); FALSE means that an emergency stop is pressed or the safety circuit is open

KSS 8.6.X

The following configuration was tested on a KR C4 compact with KSS 8.6.10.

Fig. 45 Configuration of Automatic External outputs

iiQKA.OS2

The following configuration was tested on a KR C5 micro-2 with iiQKA.OS2 and KSS 9.3.2.

Fig. 46 shows the output connections in iiQWorks.Sim, configured as described in Fig. 42.

Fig. 46 Configuration of Automatic External outputs in iiQWorks.Sim

Note

The KUKA I/Os can be chosen freely. In Fig. 46, the outputs start at $OUT[101] instead of $OUT[1] because $OUT[1] to $OUT[5] were already in use.

Consider this later when mapping the KUKA I/Os to the fieldbus I/Os.

Automatic External Signal Monitoring

The current state of the Automatic External variables can be monitored on the smartPAD:

KSS 8.6.X

The following steps were tested on a KR C4 compact with KSS 8.6.10.

Open Main menu (Fig. 47/➊) -> Display (Fig. 47/➋) -> Inputs/outputs (Fig. 47/➌) -> Automatic External (Fig. 47/➍).

Fig. 47 Display of Automatic External signals

iiQKA.OS2

The following steps were tested on a KR C5 micro-2 with iiQKA.OS2 and KSS 9.3.2.

Open Main menu -> System Settings -> Automatic External, as described in Automatic External Signal Configuration. The current signal states are shown in the column Value (Fig. 41/➏).

Configuration of Externally Acknowledgeable Messages

By default, KUKA restricts remote clearing of many system errors, forcing operators to switch to T1 mode to clear them manually.

The “Config:/” -> “User/” -> “Common/” -> “KRCExtConfMsg.xml” file is a configuration file used in KUKA Robot Controllers (KRC2, KRC4, and KRC5) in which an allow-list is defined that enables external acknowledgment of specific error messages via the $CONF_MESS digital input signal while the robot is in the operating mode EXT.

Note

Not all errors can be added to KRCExtConfMsg.xml. There are still errors that can only be reset manually on the smartPAD.

Adding Message Numbers to KRCExtConfMsg.xml

KSS 8.6.X

The following steps were tested on a KR C4 compact with KSS 8.6.10.

1. Open the uploaded project with WorkVisual and set the controller as active (right-click the controller -> Set as active controller).

2. In the Project Structure window, select the Files tab (Fig. 48/➊).

3. Add your message number (Fig. 48/➌) to the configuration file “KRCExtConfMsg.xml” (Fig. 48/➋).

It is recommended to add the message number 1030 to the list:

Fig. 48 Configuration of confirmable errors in Automatic External

Note

The message number displayed on the smartPAD always includes a leading zero (e.g., 01030). When entering the number into the XML, the leading zero must be omitted, so the number becomes 1030. An entry such as Number="01030" is silently rejected and not confirmable.

iiQKA.OS2

The following information applies to a KR C5 micro-2 with iiQKA.OS2 and KSS 9.3.2.

With iiQWorks.Sim 1.3, there is currently no known way to edit KRCExtConfMsg.xml or to configure externally acknowledgeable messages otherwise.

Note

If you need to add externally acknowledgeable messages, please contact KUKA support.

Fieldbus Configuration

Note

An example that uses PROFINET communication will be available soon.

The following example illustrates fieldbus communication between the voraus.ipc and the KUKA controller using a Beckhoff EtherCAT bridge (EL6695) and a Beckhoff EtherCAT coupler (EK1100), see Fig. 49.

The Automatic External EtherCAT communication is completely separate from RSI communication. Do not make any changes to the RSI settings or cabling.

Fig. 49 Example of an EtherCAT communication between voraus.ipc and KUKA using Beckhoff I/O modules

Physical Installation

KSS 8.6.X

The following steps were tested on a KR C4 compact with KSS 8.6.10.

1. Power off: Turn off and lock out the robot controller (KR C4) completely before opening the cabinet.

2. Mount the modules: Snap the EtherCAT coupler (e.g., Beckhoff EK1100) and the EtherCAT bridge (e.g., Beckhoff EL6695) onto the DIN rail inside the controller cabinet.

3. Connect to the bus: Plug the bus cable from the coupler (EK1100) into the internal KUKA Extension Bus port (SYS-X44).

4. Connect to the voraus.ipc: Plug the bus cable from the bridge input (EL6695) into the voraus.ipc. The Ethernet port of the voraus.ipc will later be defined within the Docker Compose file of the voraus EtherCAT Master.

5. Power supply: Connect the external 24 V DC power supply to the power contacts of the EK1100 and the EL6695.

iiQKA.OS2

The following steps were tested on a KR C5 micro-2 with iiQKA.OS2 and KSS 9.3.2.

1. Connect to the KR C5 micro-2: Plug the bus cable from the coupler (EK1100) into the XF3 (KUKA Extension Interface) input of the KR C5 micro-2.

2. Connect to the voraus.ipc: Plug the bus cable from the bridge input (EL6695) into the voraus.ipc. The Ethernet port of the voraus.ipc will later be defined within the Docker Compose file of the voraus EtherCAT Master.

3. Power supply: Connect an external 24 V DC power supply to the power contacts of the EK1100 and the EL6695.

Setting Up the KUKA Extension Bus

The following steps describe how to set up the SYS-X44 and how to add and configure the EK1100 and the EL6695.

KSS 8.6.X

The following steps were tested on a KR C4 compact with KSS 8.6.10.

1. Start WorkVisual without selecting a project.

2. Import the device descriptions: File -> Import/Export -> Import device description file, select the Beckhoff ESI XML files (which can be downloaded from the Beckhoff website). Skip this step if the devices already appear in the DTM catalog.

3. Open your project via File -> Open Project and set the controller as active (right-click the controller -> Set as active controller).

4. In the Hardware tab, expand the controller -> Bus structure -> KUKA Extension Bus (SYS-X44). If the extension bus is not present, right-click Bus structure -> Add -> select the KUKA Extension Bus (SYS-X44) (see Fig. 50).

   

   Fig. 50 Configuration of the Extension Bus SYS-X44

5. Right-click KUKA Extension Bus (SYS-X44) -> Add -> select the EK1100 from the Beckhoff catalog (see Fig. 51).

   

   Fig. 51 Add the EK1100 coupler to the Extension Bus SYS-X44

6. Right-click EK1100 -> Add -> select the EL6695 from the Beckhoff catalog (see Fig. 52).

   

   Fig. 52 Add the EL6695 bridge to the EK1100 coupler

7. Double-click the EL6695 in the device tree and navigate to the tab Slave settings. Then configure 8 bits each for the inputs and outputs, as shown in Fig. 53.

   

   Fig. 53 Input and Output configuration of the EL6695 bridge

iiQKA.OS2

The following steps were tested on a KR C5 micro-2 with iiQKA.OS2 and KSS 9.3.2.

The extension bus SYS-X44 is set up in iiQWorks.Sim. KUKA provides a step-by-step video tutorial for this on the KUKA YouTube channel (video title: “iiQWorks Tutorial - Configure the Fieldbus and add Extension Modules”).

In this example, an EK1100 and an EL6695 (KUKA Edition) were added.

Fig. 54 Configuration of the KUKA Extension Bus (SYS-X44)

Mapping the KUKA I/Os to the Fieldbus

After setting up the SYS-X44 and the Beckhoff modules, connect the internal KUKA I/Os that are used for the Automatic External signals (see Table 1 and Table 2) to the I/Os of the EL6695.

KSS 8.6.X

The following steps were tested on a KR C4 compact with KSS 8.6.10.

1. Open the I/O Mapping window (Editors -> I/O Mapping). In the left pane, select KR C I/Os -> Digital inputs or Digital outputs. In the right pane, select Fieldbuses and the EL6695 channels.

2. Connect the KUKA inputs to the EL6695 channels by selecting the KUKA I/O on the left and the EL6695 I/O on the right, then right-click -> Connect. Repeat for all configured Automatic External inputs and outputs listed in Table 1 and Table 2. The result is shown in Fig. 55.

   

   Fig. 55 Mapping between KUKA I/Os and EL6695

3. Click Extras -> Generate code, then File -> Deploy (or Install) and confirm the activation on the smartPAD (user group Expert, operating mode T1).

iiQKA.OS2

The following steps were tested on a KR C5 micro-2 with iiQKA.OS2 and KSS 9.3.2.

1. Map the digital KUKA I/Os to the EL6695 I/Os in the I/O Mapping Editor of iiQWorks.Sim. KUKA provides a step-by-step video tutorial for this on the KUKA YouTube channel (video title: “iiQWorks Tutorial - Link the Fieldbus Input and Outputs”).

   

   Fig. 56 Example mapping between KUKA I/Os and the EL6695

2. Deploy the configuration to the controller via CONFIGURATION -> Deploy Configuration onto Controller (see Fig. 31).

Configuration on the voraus.ipc

On the voraus.ipc, an Automatic External script processes the signals received via the fieldbus and connects them to the voraus.core.

Configuration of the voraus EtherCAT Master on the voraus.ipc

The voraus EtherCAT Master handles the communication between the voraus.ipc and the EtherCAT I/O modules. It runs in a separate Docker container alongside the voraus.core.

To configure the voraus EtherCAT Master, follow the instructions in the voraus EtherCAT Master documentation.

Key steps are:

• Create an ENI file for the EtherCAT I/O modules. It can be generated by an EtherCAT engineering tool such as Beckhoff TwinCAT.

• Add the voraus EtherCAT Master to the Docker Compose file and mount the ENI file to the container.

• Generate the Python code.

An example implementation of the voraus EtherCAT Master in the Docker Compose file is shown in Listing 1.

Listing 1 Service definition of the voraus EtherCAT Master in the Docker Compose file

ethercat-master:
  image: voraus.jfrog.io/docker/voraus-ethercat-master:2.2.0
  network_mode: host  # needed for raw socket communication
  pid: host           # needed for CodeMeter runtime on host
  cap_add:
    - CAP_NET_ADMIN # needed for setting the interface into promiscuous mode
    - CAP_NET_RAW   # needed for raw socket communication
    - CAP_IPC_LOCK  # needed for memory locking
    - CAP_SYS_NICE  # needed for using SCHED_FIFO with a priority
  devices:
    - /dev/cpu_dma_latency:/dev/cpu_dma_latency # needed for sleep state prevention
  volumes:
    - ./data/:/root/data/ # contains ENI file and logs
  environment:
    - ECAT_ENI=/root/data/eni.xml  #<-- replace with your ENI file path
    - ECAT_CYCLETIME=2000
    - ECAT_INTERFACE=${INTERFACE} #<-- connection to EL6695
    - ECAT_LOG_DIR=/root/data/log
    - ECAT_OPCUA_PORT=${OPCUA_PORT} #<-- e.g., 48409
    - ECAT_CPU_AFFINITY=2
    - ECAT_PRIORITY=49
  restart: on-failure

Automatic External Script on the voraus.ipc

Finally, a Python script needs to run on the voraus.ipc to read and write the I/O signals and to step through the Automatic External sequence. To request an example script, contact voraus support.

Add the Python script to the Docker Compose file so that it starts automatically with the other containers. The Python script has the following tasks:

• It steps through the Automatic External process, e.g., it acknowledges errors and switches the regulators on and off ($CONF_MESS, $DRIVES_ON, $DRIVES_OFF, see Table 1).

• It reads and writes the I/O signals from and to the KUKA controller via the fieldbus.

• It communicates with the voraus.core and sets an error if $ALARM_STOP is triggered, see Table 2.

• It reacts to the commands from the voraus.core for switching the regulators on and off and for resetting errors.

An example service definition for the Automatic External script (EtherCAT) in the Docker Compose file is shown in Listing 2 and the needed Dockerfile is shown in Listing 3.

Listing 2 Service definition of the Automatic External script (EtherCAT) in the Docker Compose file

autext:
  depends_on:
    ethercat-master:
      condition: service_healthy
  build:
    context: .
    args:
      PIP_INDEX_URL: https://artifactory.vorausrobotik.com/artifactory/api/pypi/pypi/simple
  network_mode: host
  restart: on-failure
  volumes:
    - .:/app
  command: ["python", "autExtEtherCatTask.py"]

Show Dockerfile

Listing 3 Dockerfile for the Automatic External script

FROM python:3.12-slim

WORKDIR /app

# Requires build-time network access to wibu-packages.vorausrobotik.com (VPN/company network).
RUN apt-get update && apt-get install -y --no-install-recommends \
        gnupg2 curl libusb-1.0-0 \
    && curl -sf --compressed https://wibu-packages.vorausrobotik.com/ubuntu/wibu-packages-maintainers.gpg \
        | gpg --dearmor -o /usr/share/keyrings/wibu-package-maintainers.gpg \
    && echo "deb [arch=amd64 signed-by=/usr/share/keyrings/wibu-package-maintainers.gpg] https://wibu-packages.vorausrobotik.com/ubuntu/ ./" \
        > /etc/apt/sources.list.d/voraus-wibu.list \
    && apt-get update \
    && apt-get install -y --no-install-recommends codemeter-lite axprotector \
    && rm -rf /var/lib/apt/lists/*

RUN sed -i 's/^IsNetworkServer=.*/IsNetworkServer=0/' /etc/wibu/CodeMeter/Server.ini \
    && printf '\n[ServerSearchList\\Server2]\nAddress=licenses.vorausrobotik.com\n' \
        >> /etc/wibu/CodeMeter/Server.ini

# Requires build-time network access to artifactory.vorausrobotik.com.
ARG PIP_INDEX_URL=https://artifactory.vorausrobotik.com/artifactory/api/pypi/pypi/simple
ENV PIP_INDEX_URL=${PIP_INDEX_URL} \
    PYTHONUNBUFFERED=1

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]

Testing the Automatic External Behavior

Check the Automatic External behavior as follows:

1. Start the voraus Docker stack and the KUKA controller.

2. Switch the KUKA controller to the operating mode EXT (Fig. 57/➊).

   • /R1/CELL is selected automatically (Fig. 57/➋).

   • The regulators are off (Fig. 57/➌), and RSI_MOVECORR is not active.

   • On the voraus side, the robot is in the STANDBY state.

   

   Fig. 57 Initial state after switching to EXT on the KUKA smartPAD

3. Switch the regulators on from the voraus side, either in the voraus.operator or by starting a voraus Robot Arm script:

   • The regulators turn on (Fig. 58/➊).

   • /R1/voraus_rsi is running (Fig. 58/➋) in step RSI_MOVECORR (Fig. 58/➌).

   • On the voraus side, the robot is in the READY state, and its pose is updated in the voraus 3D Visualization.

   

   Fig. 58 KUKA Automatic External with regulators on

4. Switch the regulators off from the voraus side, either in the voraus.operator or by waiting until a voraus Robot Arm script has been completed without errors:

   • The regulators turn off (Fig. 59/➊).

   • /R1/voraus_rsi is still selected (Fig. 59/➋), but stopped (indicated by a red R, Fig. 59/➌).

   • RSI_MOVECORR is no longer active (Fig. 59/➍).

   • On the voraus side, the robot is in the STANDBY state.

   

   Fig. 59 KUKA Automatic External with regulators off

5. The regulators can be turned on again, as described in step 3.

6. Trigger an error, for example, by pressing and releasing the emergency stop button without acknowledging it:

   • The regulators turn off (Fig. 60/➊).

   • /R1/voraus_rsi is still selected (Fig. 60/➋), but stopped (indicated by a red R, Fig. 60/➌).

   • RSI_MOVECORR is no longer active (Fig. 60/➍).

   • On the voraus side, the robot is in the ERROR state.

   

   Fig. 60 KUKA Automatic External after an error occurred

7. Send a reset request via the voraus.operator or voraus-error-handler.

   • The system tries to reset all errors on the voraus and KUKA side. KUKA messages that cannot be acknowledged externally by default can be added to the KRCExtConfMsg.xml file (depending on the operating system), see Configuration of Externally Acknowledgeable Messages.

   • After a successful reset, the regulators can be turned on again. The robot is in the same state as described in step 2.

   • /R1/CELL is selected (Fig. 61/➊).

   • The regulators are off (Fig. 61/➋), and RSI_MOVECORR is not active (Fig. 61/➌).

   • On the voraus side, the robot is in the STANDBY state.

   

   Fig. 61 KUKA Automatic External after a successful error reset

Next Steps

The installation of the voraus.core is now complete. Continue with the configuration of the software stack for your setup as described in Configuration for the voraus.core.

After the configuration, the voraus.core can be started and activated as described in Starting, Stopping, and Activating the voraus.core.