ROS 2 Packages ============== 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. .. note:: ROS 1 users can refer to the `[flexiv_ros] `_ repository. 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 :ref:`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. Build and source the workspace:: cd ~/flexiv_ros2_ws source /opt/ros/humble/setup.bash colcon build --symlink-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: 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_ip:=[robot_ip] local_ip:=[local_ip] .. note:: The required arguments for the launch file are: 1. ``robot_ip``: IP address of the robot server (remote). 2. ``local_ip``: IP address of the workstation PC (local). 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_ip:=dont-care local_ip:=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. 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 :ref:`ros2_demo`. 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_ip:=[robot_ip] local_ip:=[local_ip] 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 local_ip:=dont-care use_fake_hardware:=true .. _ros2_demo: 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_ip:=[robot_ip] local_ip:=[local_ip] 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_ip:=[robot_ip] local_ip:=[local_ip] 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_ip:=[robot_ip] local_ip:=[local_ip] 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``.