ROS2 stack for KUKA iiwa 14 collaborative robots. This package contains launch and configuration setups to quickly get started using the driver.

• integration with ros2_control
• robot drivers for KUKA Fast Robot Interface (FRI) protocol for position, velocity and torque control
• dedicated sensors and broadcasters to get data from the robot
• dedicated controllers
• integration with Gazebo
• integration with Moveit2

• iiwa_bringup - launch and run-time configurations
• iiwa_controllers - implementation of dedicated controllers
• iiwa_description - robot description and configuration files
• iiwa_hardware - hardware interfaces for communication with the robot
• iiwa_moveit2 - some tools for Moveit2 integration

Required setup : Ubuntu 20.04 LTS

1. Install ros2 packages. The current developpment is based of ros2 galactic. Installation steps are decribed here.
2. Source your ros2 environment:

   source /opt/ros/galactic/setup.bash

   NOTE: The ros2 environment needs to be sources in every used terminal. If only one distribution of ros2 is used, it can be added to the ~/.bashrc file.
3. Install colcon and its extensions :

   sudo apt install python3-colcon-common-extensions

4. Create a new ros2 workspace:

   mkdir ~/ros2_ws/src

5. Pull relevant packages, install dependencies, compile, and source the workspace by using:

   cd ~/ros2_ws
   git clone https://github.com/ICube-Robotics/iiwa_ros2.git src/iiwa_ros2
   rosdep install --ignore-src --from-paths . -y -r
   colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release --symlink-install
   source install/setup.bash

⚠️ SAFETY FIRST⚠️ An industrial robot is not a toy and you may harm yourself due to misuse. In general it is best practice to test your code at first in simulation and then in low speed (T1) mode. Before using the robot, make yourself familiar with the safety instructions provided by the KUKA manuals.

Step 1: The used drivers allow the communication with the KUKA iiwa robot using KUKA's Fast Robot Interface (FRI). Therefore, the Fast Robot Interface Extension needs to be installed and configured on the robot.

HINT: In the proposed default setup of this package, the robot and the control PC are communicating through FRI on the KUKA Option Network Interface (KONI) with the following setup:

• Robot : IP = 192.170.10.2, SubnetMask = FFFFFF00
• Control PC : IP = 192.170.10.5, SubnetMask = FFFFFF00

For further instructions concerning the installation and setup of FRI, please refere to KUKA FRI documentation.

Step 2: This step consists in installing the iiwa_ros2.java application from the iiwa_sunrise directory in the application package of your robot Sunrise Project. This application allows you to establish a communication with the control PC and initialize one of the following control modes:

• POSITION - position and velocity commands can be passed to the robot and exectued, the robot sends its current status
• TORQUE - torque commands can be passed to the robot and exectued, the robot sends its current status
• MONITORING - no commands can be passed to the robot, the robot only sends its current status

NOTE: Depending on you application, the following parameters need to be tuned in the application:

• INITIAL_POSITION (default: same as iiwa_description/config/initial_positions.yaml) - the initial joint configuration of the robot/
• CLIENT_IP (default: 192.170.10.5) - IP of the control PC allowed to send data to the robot.
• TS (default: 5ms) - Communication period. The robot throws an Error if no data recieved during the specified period.

NOTE: For torque mode, there has to be a command value at least all 5ms.

Step 3: To control the robot using iiwa_ros2 execute the application on the robot and select the desired control mode.

NOTE: All security modes (T1, T2, AUTO) are supported.

The iiwa_bringup package contains 3 launch files: 2 example and the main driver launcher

• iiwa_gazebo.launch.py - launches the robot in Gazebo and spawns the the default iiwa_arm_controller.
• joy_servo_teleop.launch.py - launches a fake robot controlled by a joystick using moveit_servo
• iiwa_pose_tracking.launch.py - launches a fake robot tracking a pose pusblished in topic \target_pose using pose tracking capabilities ofmoveit_servo
• iiwa.launch.py - is the main launcher giving access to all feaures of the driver.

The arguments for launch files can be listed using

ros2 launch iiwa_bringup <launch_file_name>.launch.py --show-args

The most relevant arguments of iiwa.launch.py are:

• runtime_config_package (default: "iiwa_description") - name of the package with the controller's configuration in config folder. Usually the argument is not set, it enables use of a custom setup.
• controllers_file (default: "iiwa_controllers.yaml"- YAML file with the controllers configuration.
• description_package (default: "iiwa_description") - Description package with robot URDF/xacro files. Usually the argument is not set, it enables use of a custom description.
• description_file (default: "iiwa.config.xacro") - URDF/XACRO description file with the robot.
• prefix (default: "") - Prefix of the joint names, useful for multi-robot setup. If changed than also joint names in the controllers' configuration have to be updated.
• use_sim (default: "false") - Start robot in Gazebo simulation.
• use_fake_hardware (default: "true") -Start robot with fake hardware mirroring command to its states.
• robot_controller (default: "iiwa_arm_controller") - Robot controller to start.
• start_rviz (default: "true") - Start RViz2 automatically with this launch file.
• robot_ip (default: "192.170.10.2") - Robot IP of FRI interface.
• robot_port (defaut: "30200") - Robot port of FRI interface.
• initial_positions_file (default: "initial_positions.yaml") - Configuration file of robot initial positions for simulation.
• command_interface (default: "position") - Robot command interface [position|velocity|effort].

As an example, to run the velocity_controller on the real hardware with default ip and port, run

ros2 launch iiwa_bringup iiwa.launch.py use_fake_hardware:="false" command_interface:="velocity" robot_controller:="velocity_controller"

HINT: list all loaded controllers using ros2 control list_controllers command.

NOTE: The package can simulate hardware with the ros2_control FakeSystem. This is the default behavior. This emulator enables an environment for testing of "piping" of hardware and controllers, as well as testing robot's descriptions. For more details see ros2_control documentation for more details.

1. Start the simulated hardware, in a sourced terminal run

   ros2 launch iiwa_bringup iiwa.launch.py

   add the parameter use_fake_hardware:="false" to control the real robot.
2. Send joint trajectory goals to the hardware by using a demo node from ros2_control_demos package by running

   ros2 launch iiwa_bringup iiwa_test_joint_trajectory_controller.launch.py

After a few seconds the robot should move.

As by default ROS2 streams all data on the network, in order to avoid message interference, it is preferred to isolate the communications by defining domains per project/application.

To do so run export ROS_DOMAIN_ID= [your_domain_id], with [your_domain_id] between 0 and 255.

ICube Laboratory, University of Strasbourg, France

Maciej Bednarczyk: [email protected], @github: mcbed

This work was supported in part by the French Government Research Program Investissements d’Avenir under the IDEX of the University of Strasbourg.