ROS 2 Bridge

For ROS 2 users to easily work with RDK, the APIs of RDK are wrapped into ROS packages in the [flexiv_ros2] repository. Key functionalities like real-time joint torque and position control are supported, and the integration with ros2_control framework and MoveIt! 2 is also implemented.

Compatibility

Supported OS	Supported ROS 2 distribution
Ubuntu 20.04	Foxy Fitzroy
Ubuntu 22.04	Humble Hawksbill

Overview

flexiv_ros2 contains the following packages:

Package	Description
flexiv_bringup	Launch and run-time configurations for controllers and demos.
flexiv_controllers	Implementation of custom controllers.
flexiv_description	Robot URDF and mesh files.
flexiv_hardware	Hardware interface between Flexiv robots and ros2_control framework.
flexiv_moveit_config	MoveIt configuration for Flexiv robots.
flexiv_msgs	Definition of messages used in RDK.
flexiv_test_nodes	Demo nodes and examples.

More details can be found in section Packages.

Environment setup

Note

The following instructions are for ROS 2 Humble. For ROS 2 Foxy, please replace foxy with humble in the commands, and clone the foxy branch of [flexiv_ros2].

1. Install ROS 2 Humble via Debian Packages (ros-humble-desktop)

2. Install additional packages:

   sudo apt install -y \
   python3-colcon-common-extensions \
   python3-rosdep2 \
   libeigen3-dev \
   ros-humble-xacro \
   ros-humble-tinyxml2-vendor \
   ros-humble-ros2-control \
   ros-humble-realtime-tools \
   ros-humble-control-toolbox \
   ros-humble-moveit \
   ros-humble-ros2-controllers \
   ros-humble-test-msgs \
   ros-humble-joint-state-publisher \
   ros-humble-joint-state-publisher-gui \
   ros-humble-robot-state-publisher \
   ros-humble-rviz2
   

3. Create a ROS 2 workspace and clone flexiv_ros2:

   mkdir -p ~/flexiv_ros2_ws/src
   cd ~/flexiv_ros2_ws/src
   git clone https://github.com/flexivrobotics/flexiv_ros2.git
   cd flexiv_ros2/
   git submodule update --init --recursive
   

4. Install dependencies:

   cd ~/flexiv_ros2_ws
   rosdep update
   rosdep install --from-paths src --ignore-src --rosdistro humble -r -y
   

5. Compile flexiv_rdk library and install to the ~/rdk_install directory:

   cd ~/flexiv_ros2_ws/src/flexiv_ros2/flexiv_hardware/rdk/thirdparty
   bash build_and_install_dependencies.sh ~/rdk_install
   cd ~/flexiv_ros2_ws/src/flexiv_ros2/flexiv_hardware/rdk
   mkdir build && cd build
   cmake .. -DCMAKE_INSTALL_PREFIX=~/rdk_install
   

6. Build and source the workspace:

   cd ~/flexiv_ros2_ws
   source /opt/ros/humble/setup.bash
   colcon build --symlink-install --cmake-args -DCMAKE_PREFIX_PATH=~/rdk_install
   source install/setup.bash
   

Important

Whenever a new Terminal is opened, the ROS 2 Humble environment and flexiv_ros2 workspace must be sourced before running any ROS 2 commands:

source /opt/ros/humble/setup.bash
source ~/flexiv_ros2_ws/install/setup.bash

Packages

Below are detailed descriptions of all available packages, whose structure is based on that of ros2_control_demos.

flexiv_bringup

This package contains launch files: the main driver launcher, the MoveIt launch file and demo examples. To run the main launcher:

ros2 launch flexiv_bringup rizon.launch.py robot_sn:=[robot_sn]

Note

The required arguments for the launch file is:

• robot_sn: the serial number of the robot. Remove any space, for example: Rizon4s-123456

To show all available arguments, run ros2 launch flexiv_bringup rizon.launch.py --show-args.

It will establish connection with the robot server, load the default rizon_arm_controller, and visualize the robot in RViZ. This controller uses position_command_interface, and will put the robot into joint position mode.

If you don’t have an real robot connected, you can test with the simulated hardware:

ros2 launch flexiv_bringup rizon.launch.py robot_sn:=dont-care use_fake_hardware:=true

which will use the mock_components simulated hardware interface instead of flexiv_hardware for real robot.

flexiv_controllers

This package contains custom ros2_control controllers and broadcasters. For example, the joint_impedance_controller converts joint motion inputs to torque outputs.

flexiv_description

This package contains xacro files to generate URDF with accurate kinematics but approximated dynamics parameters, as well as mesh files for visualization. In addition, it contains a launch file that visualizes the robot without accessing a real robot:

ros2 launch flexiv_description view_rizon.launch.py gui:=true

flexiv_hardware

This package contains the flexiv_hardware plugin needed by ros2_control. The plugin is passed to the controller manager via the robot_description topic, and provides for each joint:

• position state interface: measured joint position.

• velocity state interface: measured joint velocity.

• effort state interface: measured joint torque.

• position command interface: desired joint position.

• velocity command interface: desired joint velocity.

• effort command interface: desired joint torque.

flexiv_moveit_config

This package contains the configuration for MoveIt 2. The planning group is called rizon_arm. The joint values for the Home pose configuration is [0, -40, 0, 90, 0, 40, 0] (deg).

flexiv_msgs

This package contains messages for the measured or estimated information of the robot.

flexiv_test_nodes

This package contains the demo nodes for the examples in Demos. This package is adapted from ros2_control_test_nodes.

MoveIt

To run the MoveIt example with the real robot:

ros2 launch flexiv_bringup rizon_moveit.launch.py robot_sn:=[robot_sn]

You should be able to use the MotionPlanning plugin in RViZ to plan and execute motions with the robot.

To run MoveIt with the simulated hardware:

ros2 launch flexiv_bringup rizon_moveit.launch.py robot_ip:=dont-care use_fake_hardware:=true

Demos

This section provides examples with the executable nodes in the flexiv_test_nodes package.

Mode switching demo

First start the robot with the default rizon_arm_controller:

ros2 launch flexiv_bringup rizon.launch.py robot_sn:=[robot_sn]

Then load joint_impedance_controller and switch to it:

ros2 control load_controller joint_impedance_controller --set-state configured
ros2 control switch_controllers --deactivate rizon_arm_controller --activate joint_impedance_controller

The robot will stop joint position control and start joint torque control.

To start joint_impedance_controller directly, run the rizon.launch.py launch file with an additional argument robot_controller:=joint_impedance_controller.

Note

1. To list all available and claimed hardware interfaces, use command: ros2 control list_hardware_interfaces.

2. To list all loaded controllers, use command: ros2 control list_controllers.

Joint position control

First start the robot with rizon_arm_controller:

ros2 launch flexiv_bringup rizon.launch.py robot_sn:=[robot_sn] robot_controller:=rizon_arm_controller

Then in a new terminal run the test program to send joint position commands to the controller:

ros2 launch flexiv_bringup test_joint_trajectory_controller.launch.py

After a few seconds, the robot joints will move to the position goals defined in flexiv_bringup/config/joint_trajectory_position_publisher.yaml

Joint impedance control

First start the robot with joint_impedance_controller:

ros2 launch flexiv_bringup rizon.launch.py robot_sn:=[robot_sn] robot_controller:=joint_impedance_controller

Important

The command starts the robot in the joint torque mode. In this mode, gravity and friction are compensated only for the robot without any attached objects (e.g. the gripper, camera).

Then in a new terminal run the test program to send joint torque commands to the controller:

ros2 launch flexiv_bringup sine_sweep_impedance.launch.py

The robot will run a sine-sweep motion from the current joint positions using impedance control.

Caution

The gains used in joint_impedance_controller are only for demo purpose, and can be changed in flexiv_bringup/config/rizon_controllers.yaml.