Skip to main content
Version: 9

KUKA Cybertech Hardware Setup Guide

This how-to guide covers steps for setting up and configuring a KUKA Cybertech series robot arm running KUKA System Software (KSS) with the Robot Sensor Interface (RSI) option package to run with MoveIt Pro.

note

This guide is based on the kroshu/kuka_drivers project. The MoveIt Pro configuration uses PickNik forks with modifications for improved integration, including an async hardware interface with internal threading and parameterized client ports for multi-arm support. For detailed information about the underlying RSI driver, see the KSS RSI wiki documentation.

Required Hardware​

The MoveIt Pro Technical Specifications Document details the hardware and software requirements for running MoveIt Pro along with a list of the current features.

The full list of parts needed to perform this hardware installation is:

  • 1x computer to run MoveIt Pro and robot drivers (real-time capable recommended)
  • 1x Windows machine for WorkVisual configuration (can be the same machine with dual boot)
  • 2x Ethernet cables (one for KLI interface, one for RSI interface)
  • 1x KUKA Cybertech series robot arm (e.g., KR16 R2010-2)
  • 1x KUKA KR C4 or KR C5 controller with:
    • KUKA System Software (KSS) 8.6.11+ or 8.7.5+
    • Robot Sensor Interface (RSI) option package 4.1.3+ or 5.0.2+
  • (Optional) External linear axis (rail) for extended workspace

Tested Configurations​

ControllerRobotKSS VersionRSI Version
KR C4 OPS–8.6.114.1.3
KR C5 OPS–8.7.55.0.2
KR C5KR 120 R2700-28.7.55.0.2
KR C5KR 6 R900-28.7.55.0.2

1. Assemble the Arm Hardware​

Follow the KUKA-provided documentation to assemble and mount your Cybertech robot arm and controller. Ensure the arm is securely mounted and has sufficient workspace clearance.

If using an external linear axis (rail), mount the arm on the rail carriage according to KUKA's external axis documentation.

2. Set Up Computer​

For the best hardware performance, we recommend setting up the control computer to run Debian Bookworm with a real-time PREEMPT_RT kernel. Detailed instructions for setting up the real-time kernel are available in the kuka_drivers Realtime wiki.

A Windows machine is also required to connect to WorkVisual for controller configuration (if RSI is not yet installed or needs configuration updates).

3. Configure Controller Network​

Windows runs behind the SmartHMI on the Teach Pendant. The Windows interface of the controller and the PC with ROS must be connected to the same subnet.

Controller Network Configuration​

  1. Log in as Expert or Administrator on the Teach Pendant.
  2. Navigate to Network configuration (Start-up > Network configuration > Activate advanced configuration).
  3. Verify there is already an interface configured as the Windows interface (KLI).
  4. Add a new network interface for RSI:
    • Press the Advanced button and New interface.
    • Select Mixed IP address and keep the default settings:
      • Receiving task: Target subnet
      • Real-time receiving Task: UDP
    • Set the IP address to a different subnet than the KLI interface (e.g., 192.168.2.1/24).
    • Leave Default gateway empty.
    • Ensure Windows interface checkbox is NOT checked.
  5. Reboot the controller with a cold restart (Shutdown > Check Force cold start and Reload files > Reboot control PC).

For more details, see the Controller Network Configuration section in the kroshu wiki.

4. Change Computer Network Settings​

The computer requires two network interfaces: one to connect to the Internet and another to connect to the robot.

Client IP Configuration​

  • Set a fixed IP in the subnet of the KLI interface for the Windows machine (required for WorkVisual project transfer).
  • Set a fixed IP in the subnet of the RSI interface for the real-time machine (required for RSI commands). For example, if the RSI interface is 192.168.2.1/24, set the computer to 192.168.2.10.

Linux Network Setup​

To set up the network on the control computer:

  1. Click the arrow in the upper right corner of the screen, then click "Settings" > "Network".
  2. For the Internet connection:
    • Click the gear icon next to the Wired adapter connected to your network.
    • Under the "Identity" tab, give this profile a name (like "Internet").
    • Click "Apply" to accept the default values.
  3. For the Robot connection:
    • Click the gear icon next to the other network adapter.
    • Under the "Identity" tab, assign a name (such as "Robot RSI").
    • Under the "IPv4" tab, select "Manual" as the "IPv4 Method".
    • Enter the IP address in the RSI subnet (e.g., 192.168.2.10) and Netmask 255.255.255.0.
    • Click "Apply".

5. Upload RSI Configuration Files to Controller​

Several configuration files are required for RSI operation. These files can be found in the kuka-external-control-sdk repository under kuka_external_control_sdk/krc_setup/kss/.

Required Files​

  • Config/User/Common/SensorInterface/rsi_ethernet.xml: Specifies RSI data transfer and client IP configuration.
    • Modify the IP_NUMBER tag to match your control computer's RSI interface IP address.
    • The default PORT is 59152 but can be changed if needed.
  • Config/User/Common/SensorInterface/rsi_joint_pos.rsix: Contains the RSI context (can be visualized with RSIVisual).
  • KRC/R1/Program/RSI/rsi_helper.dat and rsi_helper.src: Used for configuring RSI context based on current robot position.
  • KRC/R1/Program/RSI/rsi_joint_pos_4ms.src: KRL program that starts external control with 4 ms cycle time.
note

If you are using an older version of RSI (≤4.0.3), the RSI context must be defined using three separate files (rsi_joint_pos.rsi, rsi_joint_pos.rsi.diagram, and rsi_joint_pos.rsi.xml) instead of a single .rsix file. These are available in the deprecated directory.

note

For external axis configurations, use rsi_ext_ethernet.xml and rsi_ext_joint_pos.rsix instead, which include support for external axis (E1-E6) position data.

warning

Use the 4 ms RSI mode. PickNik recommends using rsi_joint_pos_4ms.src for all configurations. The 4 ms mode is required for external axis control because the 12 ms mode attempts to compensate for axis movement to maintain endpoint pose, which interferes with external axis coordination.

Upload Methods​

Method 1 (USB):

  1. Copy the files to a USB stick.
  2. Plug it into the teach pad or controller.
  3. Log in as Expert or Administrator on the controller.
  4. Copy krc_setup/kss/KRC/R1/Program contents to KRC:\R1\Program.
  5. Copy krc_setup/kss/Config/User/Common contents to C:\KRC\ROBOTER\Config\User\Common.

Method 2 (WorkVisual):

  1. Connect to the KRC with WorkVisual.
  2. Log in as Expert or Administrator on the controller.
  3. Copy the files to the appropriate locations in WorkVisual.
  4. Deploy the project.

For more details, see the Update and upload configuration files section in the kroshu wiki.

6. MoveIt Pro Robot Configuration​

If you have not already installed MoveIt Pro, follow the Quick Start Installation Guide.

Next, clone the moveit_pro_kuka_config workspace:

mkdir -p ~/moveit_pro
cd ~/moveit_pro
git clone https://github.com/PickNikRobotics/moveit_pro_kuka_config.git
cd moveit_pro_kuka_config
git submodule update --recursive --init
note

The MoveIt Pro KUKA configuration uses PickNik forks of the upstream kroshu repositories with the following modifications:

  • Async hardware interface: The ros2_control hardware interface runs with is_async="true", with the blocking RSI Read/Write operations moved into an internal thread within the hardware interface itself.
  • Thread-safe communication: The RSI hardware interface is thread-safe for concurrent read/write operations.
  • Parameterized client port: The client_port is configurable via URDF parameters, enabling multi-arm setups with different ports per arm.
  • External axis support: Extended message parsing for external axes (E1-E6) with linear axis (mm) unit handling.
  • Standard controller manager: Uses the stock ros2_control controller manager rather than a custom lifecycle-based manager.

These changes allow the driver to integrate seamlessly with MoveIt Pro's standard launch and configuration patterns.

Now customize the cybertech_hw robot configuration package for your hardware:

  • Verify the robot_model and robot_family parameters in the robot configuration package's config.yaml match your robot (e.g., kr16_r2010_2 and cybertech).
  • Update the client_ip and client_port parameters to match your RSI network configuration.

To tell MoveIt Pro to launch with the cybertech_hw configuration, run moveit_pro configure and update the workspace path to ~/moveit_pro/moveit_pro_kuka_config and the MoveIt Pro robot configuration package to cybertech_hw.

Lastly, build the Docker image and user workspace:

moveit_pro build

Your hardware is now ready for use with MoveIt Pro!

7. Launch MoveIt Pro​

Use the following command to launch MoveIt Pro:

moveit_pro run

MoveIt Pro will start the controller manager and hardware interface automatically. The hardware interface will begin listening for RSI connections from the robot controller.

Starting External Control on the Teach Pendant​

Once MoveIt Pro is running, you need to start the RSI program on the robot controller:

  1. On the teach pad, navigate to KRC:\R1\Program\RSI\rsi_joint_pos_4ms.src.
  2. Select the program and press Start to begin execution.
  3. Step through the program until it reaches the RSI_MOVECORR() command.
  4. In T1 mode, you will see a warning: !!! Attention - Sensor correction goes active !!!
  5. Confirm the warning to start external control.

On successful connection, the robot brakes will release and external control begins. You should see the robot state update in MoveIt Pro's visualization.

tip

The hardware interface has a connection timeout of approximately 10 seconds. Make sure to start the RSI program on the teach pendant promptly after launching MoveIt Pro, or restart MoveIt Pro if the timeout expires.

(Optional) External Linear Axis Configuration​

The MoveIt Pro KUKA configuration supports an optional external linear axis (rail), which extends the robot's workspace by mounting it on a movable carriage. When enabled, the system operates as a 7-axis configuration (6 robot joints + 1 linear axis).

Controller-Side Setup​

For external axis control, use the dedicated RSI configuration files from the kuka-external-control-sdk repository:

  1. Replace the standard RSI files with the external axis variants:

    • Use Config/User/Common/SensorInterface/rsi_ext_ethernet.xml instead of rsi_ethernet.xml
    • Use Config/User/Common/SensorInterface/rsi_ext_joint_pos.rsix instead of rsi_joint_pos.rsix

  2. Configure the external axis in RSI:

    • The rsi_ext_ethernet.xml file includes E1 axis data in the <SEND> and <RECEIVE> sections
    • Modify the IP_NUMBER and PORT tags to match your network configuration (same as standard setup)

  3. Upload the files to the controller using the same methods described in Section 5.

note

The external axis configuration assumes linear axes (position in millimeters) rather than rotational axes (position in degrees). The driver automatically converts between mm and meters for ROS 2 compatibility.

MoveIt Pro Configuration​

Ensure your MoveIt Pro robot configuration package is set up for external axis support. The linear axis joint (E1) should be included as the last joint in the kinematic chain, after the 6 robot axes (A1-A6). Rebuild the workspace after any configuration changes:

moveit_pro build

Important Notes​

  • 4 ms mode is required: External axis control only works with rsi_joint_pos_4ms.src. The 12 ms mode attempts endpoint pose compensation that interferes with coordinated external axis motion.
  • Joint ordering: The external axis (E1) appears as the last joint in the joint state, after the 6 robot axes (A1-A6).
  • Joint limits: Verify that the linear axis joint limits in the robot configuration package match the physical rail limits.

(Optional) Multi-Arm Configuration​

The MoveIt Pro KUKA configuration supports multi-arm setups. Each arm requires:

  1. Unique RSI port: Configure a different client_port for each arm in the respective robot configuration package. The default port is 59152; additional arms might use 59153, 59154, etc.
  2. Matching controller configuration: Update the PORT value in each arm's rsi_ethernet.xml file on the KUKA controller to match the configured client_port.
  3. Separate RSI programs: Each arm runs its own RSI program instance.

Ensure the network configuration allows UDP communication on all configured ports.

(Optional) GPIO Configuration​

The RSI driver supports real-time I/O control. For GPIO configuration, refer to the I/O Configuration section in the kroshu wiki for detailed instructions on:

  • Controller-side GPIO configuration (rsi_gpio_joint_pos.rsix, rsi_gpio_ethernet.xml)
  • Client-side GPIO configuration (gpio_config.xacro, gpio_controller_config.yaml)

Simulation​

To test the driver without hardware, use mock mode. First, launch the driver with mock hardware:

ros2 launch kuka_rsi_driver startup_with_rviz.launch.py mode:=mock

In a separate terminal, start the RSI simulator:

ros2 launch kuka_rsi_simulator kuka_rsi_simulator.launch.py

The robot should appear in RViz and respond to motion commands.

Stopping External Control​

To stop external control safely:

  1. Stop any active motion commands in MoveIt Pro.
  2. On the teach pendant, stop the RSI program execution.
  3. Shut down MoveIt Pro with Ctrl+C or through the UI.
warning

For an emergency stop, always use the safety stop button on the Teach Pendant. Do not rely on software shutdown for safety-critical stops.

Troubleshooting​

Connection Timeout​

If MoveIt Pro times out waiting for the controller connection:

  1. Verify network configuration on both the controller and computer.
  2. Ensure the RSI interface IP and port in rsi_ethernet.xml match the computer's network settings and the client_port parameter.
  3. Check that the RSI program has reached RSI_MOVECORR() on the controller.
  4. Verify UDP traffic is not blocked by firewalls.

Real-Time Performance Issues​

For optimal real-time performance:

  1. Ensure the PREEMPT_RT kernel is properly installed and running.
  2. Verify network interfaces are configured for low latency.
  3. Use the 4 ms RSI cycle time for smoother motion.

For detailed real-time setup instructions, see the Realtime wiki page.

Robot Not Moving​

If the robot connects but does not respond to motion commands:

  1. Verify the robot is in the correct mode on the teach pendant (external control active).
  2. Check that joint limits in the robot configuration package match the robot's configured limits.
  3. Review the MoveIt Pro logs for planning or execution errors.

Additional Resources​