# Connect KUKA to Wandelbots NOVA

> Learn how to connect KUKA robots to Wandelbots NOVA. Follow step-by-step setup instructions, safety guidelines, and supported controller requirements for reliable integration.

> **Info:** Wandelbots NOVA includes a real-time kernel and `robot-realtime` tuned profile by default to meet the latency and jitter requirements of KUKA controllers and avoid RSI disconnects.

Using a KUKA with Wandelbots NOVA offers a wide range of possibilities for automating your production processes.
There are 4 things you need to know before you start:

Which KUKA controller types and models are supported by Wandelbots NOVA?

[Supported models](#supported-models)

Wandelbots NOVA provides you with virtual controllers for path planning, app development and simulation purposes.

[Use virtual controller](#use-virtual-controller)

You can connect your KUKA controller to Wandelbots NOVA for real-world automation.

[Set up and connect KUKA controller](#set-up-and-connect-kuka-controller)

## Supported models

### Controllers

| Controller | Supports | Requirements |
| - | - | - |
| KRC4 | industrial | Option package: EthernetKRL Interface 2.2, Robot Sensor Interface 3.3/4.1, MultiSubmitInterpreter 1.0. Optional: Safe Operation package for safety zones, TCP geometries, safety limits of joint positions and velocity. If installed, safe operation reference switch is required.; Firmware: >=KSS 8.3.18 |
| KRC4 compact | industrial | Option package: EthernetKRL Interface 2.2, Robot Sensor Interface 3.3/4.1, MultiSubmitInterpreter 1.0. Optional: Safe Operation package for safety zones, TCP geometries, safety limits of joint positions and velocity. If installed, safe operation reference switch is required.; Firmware: >=KSS 8.3.18 |
| KRC5 | industrial | Option package: EthernetKRL Interface 3.2, Robot Sensor Interface 5.0. Optional: Safe Operation package for safety zones, TCP geometries, safety limits of joint positions and velocity. If installed, safe operation reference switch is required.; Firmware: >=KSS 8.7 |
| KRC5 micro | industrial/cobot | Option package: EthernetKRL Interface 3.2, Robot Sensor Interface 5.0. Optional: Safe Operation package for safety zones, TCP geometries, safety limits of joint positions and velocity. If installed, safe operation reference switch is required.; Firmware: >=KSS 8.7 |

### Motion groups

#### Robotic arms

**Cobots**

| Robot arm |
| - |
| KR LBR iisy 11 R1300 |
| KR LBR iisy 6 R1300 |

**Industrial robots**

| Robot arm |
| - |
| KR 10 R1100 |
| KR 10 R1100 2 |
| KR 10 R900 |
| KR 10 R900 2 |
| KR 12 R1810-2 |
| KR 120 R2700 |
| KR 120 R3100-2 |
| KR 120 R3900-2K |
| KR 150 R2 |
| KR 150 R2700-2 |
| KR 16 R1610-2 |
| KR 16 R2010-2 |
| KR 20 R1810 |
| KR 20 R1810-2 |
| KR 210 R2700 |
| KR 210 R2700-2 |
| KR 210 R3100-2 |
| KR 210 R3300-2K |
| KR 240 R2700 |
| KR 240 R2900 ultra |
| KR 240 R3700-2 |
| KR 25 R2700-2 |
| KR 250 R2700-2 |
| KR 270 R2700 ultra |
| KR 3 R540 |
| KR 30 R2100 |
| KR 30 R3 |
| KR 360 L240-3 |
| KR 360 R2830 |
| KR 4 R600 |
| KR 50 R2500 |
| KR 500 L340-3 |
| KR 6 700-2 |
| KR 6 R1820 |
| KR 6 R700 Sixx |
| KR 6 R900 |
| KR 6 R900-2 |
| KR 60-3 |
| KR 70 R2100 |

#### External axes

| External axis |
| - |
| DKP 500-2 |
| DKP 750-2 |
| KL1500 |

## Use virtual controller

### Step 1: Open the home screen

Open your cloud instance via NOVA Cloud or type in your physical instance's/virtual instance's IP address to access the home screen.
Get an overview on the home screen and its functionalities [here](/nova/26.8/architecture).

### Step 2: Add robot to your cell

If you want to start using the Wandelbots API, do so now and [add a robot via the Wandelbots NOVA API](/nova/26.8/nova-api/overview#add-a-robot-to-the-cell).

OR add a robot to your cell in Setup:

1. Open the cell's `Robots` page.
   → The robot overview is displayed.
2. Click `Add robot` to add a robot to your cell.\
   If the `Add robot` button is greyed out, your license might not support adding more robots. Please contact your administrator.
   → A side panel opens guiding you through adding a robot.
   → `Virtual` is selected by default. 
   You can also reuse a previous configuration from `Recent connections`.
3. Name the robot.
4. Select `KUKA` as manufacturer.
5. Select the desired robot model.
6. Click `Add robot`.
   → A progress indicator is displayed while the robot is being added to the cell.
   → The robot is displayed in the cell overview.

### Step 3: Add a TCP

To replicate a physical robot's behavior accurately, you can define TCPs for virtual robots in the Setup app.

1. Click on the robot.
   → The robot's details page is displayed.
2. Click `Manage TCPs`.
   → A side panel displays all existing TCPs of the robot.
   → Clicking a physical robot instead shows a `See all TCPs` button: TCPs for physical robot controllers can only be viewed here, not added, since they need to be configured on the robot controller itself.
3. Use `Add TCP`.
   → Options to add a new TCP are displayed.
4. Define the TCP's translation and rotation relative to the robot's flange.
5. Save the new TCP.
   → The new TCP is displayed in the side panel and can be selected in Robot Pad.

You've successfully added a virtual robot to plan programs with. Open Robot Pad or download Visual Studio Code and get started ✨.

## Set up and connect KUKA controller

Cloud instances are not suited to control a physical robot and you need to use a VM or use an IPC instead.
More information on available NOVA instance types [here](/nova/26.8/installation/installation#instance-types).

### About setup instructions

The provided setup instructions do not replace a thorough understanding
of the robot manufacturer's original operating instruction and only apply to the supported models mentioned above.

The setup instructions include the following steps:

1. Preparing the robot for the connection with Wandelbots NOVA.
2. Physically connecting the IPC to the robot controller.
3. Using the KUKA controller on Wandelbots NOVA: Wandelbots NOVA detects the IPC's network address automatically.
4. Troubleshooting common issues that may arise during the setup process, including configuring the IPC's network settings manually if your installation doesn't support automatic assignment yet.

In order to connect the KUKA controller to Wandelbots NOVA,
Wandelbots NOVA needs to be integrated into the robotic cell according to these [cell designs](/nova/26.8/setup/cell-design).

Ensure that the KUKA controller you're about to connect to Wandelbots NOVA is listed in the [supported models](#supported-models) section.

Note that setting a correct mounting pose in the robot controller is crucial, especially for cobots, as they are sensitive to gravity direction.

### Qualified user groups

Preparing a controller for the use of Wandelbots NOVA is a task that requires a certain level of expertise.
The following instructions are intended for qualified user groups only.

> **⚠️ CAUTION:** **Danger in case of insufficient qualification of users**
>
> People can be injured if unqualified user groups set up the physical robot environment.
>
> - Only qualified user groups designated by the operating company may set up the physical robot environment.
> - Keep unqualified user groups away from the area of risk.

If a high experience level, e.g. admin user, is recommended to complete the step, the following label will be displayed next to the header:

[Admin]

### Step 1: Prepare the KUKA [Admin]

#### Activate Administrator user group and stop programs

1. Using the original robot's control panel, switch from automatic mode to T1 mode.
2. Open `Main menu` → `Configuration` → `User group`.
3. Select `Administrator` and enter the password.
4. If the `R` in the header has a green background color, click on it.
5. Cancel the robot program.
6. If the `S` in the header has a green background color, click on it.
7. Stop and deselect all submit interpreters.

#### Install option packages

1. Download the required option packages listed in the requirements of the [supported controllers](##controllers)
   as well as the [Wandelbots custom .kop option package](/nova-cloud/downloads) to a personal computer.

**Continue with USB flash drive**

2. Save the required option packages listed in the requirements of the [supported controllers](##controllers)
   as well as the [Wandelbots custom .kop option package](/nova-cloud/downloads) on an USB flash drive.
3. Insert the USB flash drive into the original robot's control panel or the robot controller.
4. Ensure that `Administrator` is still selected as user group.
5. Open `Main menu` → `Start-up` → `Service` → `Minimize HMI`.\
   → The windows home screen appears.
6. Copy the option package from the USB flash drive to `D:\KUKA_OPT`
7. Select the HMI in the windows task bar.
8. Open `Main menu` → `Start-up` → `Additional software`.
9. Click `New software`.
10. IMPORTANT: First, install the required option packages to enable the installation of the Wandelbots custom option package.
11. Only install the custom .kop option package AFTER installing the required option packages.
    > **Warning:** To avoid installation conflicts, remove the previous version of the Wandelbots NOVA KOP file before installing the latest version.

For further information read the chapter `Installation via smartHMI` in the respective option package documentation.

**Continue in KUKA WorkVisual**

2. Download [KUKA WorkVisual](https://my.kuka.com/s/product/kukaworkvisual-60/01t58000005rL3eAAE) and install it.
3. Follow the installation and connection instructions provided by the robot manufacturer to connect to the robot controller
   and install the option packages in the following order:
   1. First, install the required option packages to enable the installation of the Wandelbots custom option package.
   2. Only install the custom .kop option package AFTER installing the required option packages.
      > **Warning:** To avoid installation conflicts, remove the previous version of the Wandelbots NOVA KOP file before installing the latest version.

#### Get overview on IP addresses

During the setup of the KUKA robot controller, a variety of IP addresses are required.
To facilitate understanding who defines the IP addresses and for what they are used, the following table provides an overview:

| IP address | Value | Defined by |
| - | - | - |
| KUKA KLI IP address | e.g. `172.31.1.147`, notice that the subnet is 1. This IP address is assigned to the controller to access it within the company's network. | the operating company |
| KUKA RSI IP address | e.g. `172.31.2.147`, notice that the subnet is 2, thus different than the KLI subnet. This IP address is used to communicate with the IPC. | the operating company |
| IPC in company network | e.g. `172.160.3.55`, notice that the subnet is 3, thus different than the KLI and RSI subnets. This IP address is used to access the IPC in the company's network. | during Wandelbots NOVA installation |
| IPC's KLI IP address | e.g. `172.31.1.55`, notice that the subnet is 1, thus the same as the KUKA KLI subnet. This IP address is used by the IPC to establish communication to the robot controller. | automatically, during Setup |
| IPC's RSI IP address | e.g. `172.31.2.55`, notice that the subnet is 2, thus the same as the KUKA RSI subnet. This IP address is used by the IPC to establish communication with the robot controller. | user during KUKA setup |

#### Log in

_Using the original robot's control panel_

1. Switch from automatic mode to T1 mode.
2. Open `Main menu` → `Configuration` → `User group`.
3. Select `Expert` and enter the password.
4. Click `Log on`.

#### Add required network interfaces

1. Open `Main menu` → `Start-up` → `Network configuration`.\
   → The network configuration is displayed.
   If you can't access the network configuration, a program might be running. Cancel the program and try again.
2. Click on the `Advanced…` button.
3. Enter the following values to configure the `KLI` interface:
   | Field | Value |
   | - | - |
   | Interface designation | `KLI` |
   | Address type | `Fixed IP address` |
   | IP address | `172.31.1.147` |
   | Subnet mask | `255.255.255.0` |
   | Windows interface | Selected (default) |
4. Click on the `Add interface` button.
5. Enter the following values to configure the `RSI` interface:
   | Field | Value |
   | - | - |
   | Interface designation | `RSI` |
   | Address type | `Mixed IP address` |
   | IP address | `172.31.2.147` This IP address can be any valid IP address that you can think of. It can't be in the same subnet as the KLI address. |
   | Subnet mask | `255.255.255.0` |
   | Windows interface | Not selected |
6. Click on `Save`.\
   → A popup is displayed.
7. Confirm the changes to add both interfaces.

#### Restart the robot controller

1. Open `Main menu` → `Shutdown`.
2. In section `Settings for next shutdown`, select the options `Force cold start` and `Reload files`.
3. In section `Shutdown actions`, click on the `Reboot control PC` button.\
   → A popup is displayed.
4. Confirm the reboot of the controller to apply the network changes.

### Step 2: Connect IPC to the robot controller [Admin]

**KRC4**

1. Connect an ethernet cable to the IPC's LAN-1 port.
2. Connect the ethernet cable to the robot controller's X66 port.
3. Turn on the IPC.

**KRC5**

1. Connect an ethernet cable to the IPC's LAN-1 port.
2. Connect the ethernet cable to the robot controller's XF5 port.
3. Turn on the IPC.

By default, Wandelbots NOVA detects which physical port the controller is wired to and assigns the IPC's KLI address automatically when you [add the robot](#use-kuka-controller-on-nova). The RSI interface IP address is suggested but still needs your confirmation, since it's required to add the robot. If Setup doesn't do the automatic part for you, see [Troubleshooting](#i-dont-see-a-guide-me-or-scan-network-button).

### Step 3: Use KUKA controller on NOVA

1. Type in your physical instance's IP address to access the NOVA OS instance.
   → The home screen is displayed.
2. Open Setup and, in the sidebar, go to your robot cell's `Robots` page.
   → The robot overview is displayed.
3. Click `Add robot` to add a robot to your cell.\
   → A side panel opens guiding you through adding a robot.
   If the `Add robot` button is greyed out, your license might not support adding more robots. Please contact your administrator.
4. Toggle to `Physical`.
   → The side panel updates to display options for adding a physical robot.
5. Use `Guide me` for a step-by-step walkthrough, or use `Advanced options` → `Scan network` if you don't know the controller's IP address.
   > **Info:** On the previous version of Setup, there's no `Guide me` walkthrough, autofill, or `Scan network`: you need to [configure the IPC's network settings manually](#i-dont-see-a-guide-me-or-scan-network-button) and then enter the controller's IP address, network interface, and controller port manually.
   > See the [FAQ](/nova/26.8/faq#setup-still-shows-a-previous-version-after-updating) to check which version of Setup your NOVA OS home screen displays.
6. Name the robot.
7. Select `KUKA` as the manufacturer.
   → Under `NOVA instance`, an entry field for the RSI interface IP address is displayed additionally.
8. Under `Robot controller`, enter the robot controller's IP address: The KLI IP address of the controller entered in the [KLI interface](#add-required-network-interfaces), and confirm it.\
   → Under `NOVA instance`, the NOVA instance's port and corresponding interface IP address to which the robot controller is connected to is autofilled.
   If you want to use a specific network setup, you can overwrite the autofilled entries.
9. Under `NOVA instance`, enter the `RSI interface IP address`: The IP address must be within the same subnet as the robot controller's RSI IP address and must not be assigned to another device on the subnet.\
   The RSI Server Port is fixed, so you no longer need to give each controller a different port when connecting more than one KUKA controller to the same instance. The RSI cycle rate is likewise fixed at 4 ms, the rate a KUKA controller always runs at.
10. Click on `Add robot`.\
    → Wandelbots NOVA verifies that the selected port has a link, that the suggested addresses aren't already taken, and that the controller answers at its IP. If a check fails, you can fix the input or choose `Add anyway` to continue.
    → A progress indicator is displayed while the robot is being added to the cell.
    → The robot is displayed in the cell overview.
11. Set the robot to one of the operating modes: Manual or automatic.

#### Manual mode

1. Press enabling switch on the original robot control panel and keep pressing it.
2. Confirm all safety messages.\
   → The robot program starts automatically.
3. Press the green button on the backside (or the play button on the front side) of the original robot control panel once.\
   → The robot's motor breaks will be released.
4. Press the green button on the backside (or the play button on the front side) again and hold.
5. Ensure the program pointer is below the comment "DO NOT CANCEL THIS PROGRAM IF YOU WANT TO MOVE THE ROBOT WITH WANDELBOTS".
6. Activate the motion group in Robot Pad in the safety bar or via the Wandelbots NOVA API Motion Group endpoint `POST /cells/{cell}/motion-groups/all`. \
   As soon as you stop pressing the enabling switch and the green button on the backside, the robot will stop moving immediately.

#### Automatic mode

1. Confirm all safety messages.\
   → The robot program starts automatically.
2. Press the green button on the backside (or the play button on the front side) of the original robot control panel 2 times.
3. Ensure the program pointer is below the comment "DO NOT CANCEL THIS PROGRAM IF YOU WANT TO MOVE THE ROBOT WITH WANDELBOTS".
4. Activate the motion group in Robot Pad in the safety bar or via the Wandelbots NOVA API Motion Group endpoint `POST /cells/{cell}/motion-groups/all`.

#### External automatic mode

To start a robot program in external automatic mode, internal variables have to be triggered in the right order:

1. `$MOVE_ENABLE`
2. `$CONF_MESS`
3. `$DRIVES_ON`
4. `$EXT_START`

For more information about the use and the communication flow of these internal variables read the KUKA System Integrator documentation of the respective KSS version.

All variables need to be mapped to inputs to enable triggering them
via a higher-level controller such as a PLC, physical buttons or a BUS I/O communication device.

**via robot control panel**

5. Select `Main menu` → `Configuration` → `Inputs/outputs` → `Automatic External`.
6. In the `Value` column, select the desired cell and press `Edit`.
7. Enter the desired input number and press `OK` to save.
8. Repeat steps 2 and 3 for all desired values.
9. Close the window.\
   → The changes are saved.

**via KUKA WorkVisual**

5. Map the inputs in `KRC/STEU/Mada/custom.dat`, e.g., `SIGNAL $CONF_MESS $IN[100] ;EXTERNE QUITTUNG`

#### TCPs

To use TCPs for connected physical controllers on NOVA, you need to set them up on the robot controller first.
Refer to the original [KUKA documentation](https://www.kuka.com/en-at).

TCPs will then be displayed on the robot's details page in the Setup app (click `See all TCPs`) and can be selected for path planning in Robot Pad.

#### KUKA brake test guide

The KUKA brake test is a safety feature that ensures the robot's brakes are functioning correctly. Before operating the robot with Wandelbots NOVA, it is essential to perform the brake test to prevent any unexpected movements or accidents.

1. Ensure that you have the latest option package for KUKA from Wandelbots (.kop file) installed.
2. Using the robot control panel, open System → `wb_safe_func.src` and write an invocation of the desired safety check function into it.
3. Subscribe to, or poll, `Output #3023` to be notified when `BrakeTest` or `SafeReferenceDrive` are required.
4. It may be required to enter Monitoring Mode so leave `PositionControl` if necessary.
5. Set `Output #3022` to `1`.
6. Observe that your function in `wb_safefunc.src` is executed.\
   → If the `safe_func()` satisfies the controller's safety requirements, `OUT#3023` will turn to `0` at the end.
7. Reenable `PositionControl`.\
   → The robot has passed the brake test successfully and can be operated safely.

## Troubleshooting

### I can't log in or I am not part of the Expert user group

In order to prepare the KUKA for Wandelbots NOVA you need to be part of the Expert user group.
If you can't log in, ask a sufficiently qualified user to log in and set up the robot for you.

### I don't see a Guide me or Scan network button.

This means your NOVA OS installation hasn't been updated to a backend version that supports automatic network configuration yet, so Setup still shows its previous version.
See the [FAQ](/nova/26.8/faq#setup-still-shows-a-previous-version-after-updating) for more information.

Until then, configure the IPC's KLI and RSI addresses manually:

1. Open `https://<ipc-ip-address>:9090`, e.g. `https://172.345.538.2:9090`, in a browser on your personal computer.\
   If the IPC is not connected to the same network as your personal computer, you can connect a keyboard, a mouse and a display to the IPC. Then open `localhost:9090` in a web browser.

   > **Warning:** Only one personal computer is allowed to connect to the instance's IP address.
   > In case multiple personal computers control a physical robot, e.g. via API and the RobotPad, simultaneously, the robot will not move.
   >
   > - Close all applications on other personal computers and try again.
   > - Unplug the robot's ethernet cable from the physical instance and wait a couple of minutes to restart Wandelbots NOVA foundation services. Plug it into the LAN port again and try again.
2. Log in with the user credentials created during the Wandelbots NOVA installation.\
   → The IPC's settings are displayed.
   → A popup prompts you to enable administrative access.
3. Enable administrative access and enter the admin password.
4. Select the Network tab in the sidebar.\
   → The IPC's network settings are displayed.
5. Toggle the button next to the `enp3s0` port (corresponding to the IPC's LAN-1 port) to enable network activity.
6. Click `edit` next to the IPv4.\
   → The IPv4 menu opens.
7. Set the address dropdown to `Manual`.
8. Set the prefix to 255.255.255.0 (will automatically change to 24).
9. Delete the prefilled gateway value.
10. Create an IP address that will be used as IPC KLI IP address. It has to be in the same subnet as the KUKA's KLI IP address, e.g. `172.31.1.55`.
11. Click on the `+` button to add another IP address.
12. Create an IP address that will be used as IPC RSI IP address. It has to be in the same subnet as the KUKA's RSI IP address, e.g. `172.31.2.55`.
13. Save the settings.\
    → Wandelbots NOVA can now connect to the robot. Enter these addresses as the `Host` and RSI address when adding the robot.

### Find the KUKA's IP address

_Using the original robot control panel_

1. Log in with the Expert user group.
2. Switch from automatic mode to T1 mode.
3. Open the main menu.
4. Go to Main menu > Start-up > Network configuration.\
   → The network configuration is displayed, including the KLI IP address.
5. Open `Advanced…` to get the RSI IP address.\
   → The controller's IP addresses, including RSI and KLI, are displayed.

### Downloading WorkVisual project fails while submit interpreters are running

WorkVisual project can be downloaded to the KUKA robot while submit interpreters are running.\
Resolve the download issue:

1. Select `Download Option Packages` when you retrieve the project.
2. Set the robot to manual mode.
3. Log in as admin.
4. Verify that the project configuration is error-free.

### Connection issues

If you have been experiencing RSI disconnects with KUKA robots or general performance issues,
your Wandelbots NOVA instance might not be running on a real-time-enabled kernel.

> **Info:** Starting with Wandelbots NOVA 26.1, the real-time kernel is included by default in all NOVA installations.
> If you're using an older version, you may need to upgrade or manually install the RT kernel.

If the issue persists, read more in the [FAQ section on robot connectivity](/nova/26.8/faq#wandelbots-nova-instance-is-physically-connected-to-the-robot-but-the-robot-is-not-moving).

### Warning "Stop by $CORRECTION function (reset or block selection required)" or error "Object ETHERNET1 returns error RSITimeout"

The network setup might be unstable or incorrect.

Verify the setup of the RSI interfaces on both the KUKA controller and the IPC:

1. Ensure that the RSI IP address of the
   KUKA controller is reachable from the IPC and vice versa.
2. Restart the controller.

### KUKA robots stop with torque limit errors (KSS01073, KSS01074)

These errors indicate that the robot has reached its torque limits on at least one axis. To resolve the issue:

1. Ensure that the robot's payload settings are correctly configured.
2. If incorrect, adjust the payload settings in the KUKA controller to match the actual payload of the robot.
3. If the payload settings are correct and there is still an error, investigate if the commanded trajectory exceeds torque limits.
4. If yes, lower axis torque limits on the failed trajectory.