ros2_control Demos

This repository provides templates for the development of ros2_control-enabled robots and a simple simulations to demonstrate and prove ros2_control concepts.

First-Time Users

If you're just starting out, we suggest to look at the minimal example: ros2_control_demo_bringup/launch/rrbot_system_position_only.launch.py.

Also pay attention to these files:

ros2_control_demo_description/rrbot_description/ros2_control/rrbot_system_position_only.ros2_control.xacro -- this file defines the ros2_control interfaces for each joint, e.g. position or velocity. The simulation can be launched with Gazebo or simulated with RViz only.
rrbot_controllers.yaml -- list the controllers that will be launched.

Goals

The repository has three goals:

Implements the example configuration described in the ros-controls/roadmap repository file components_architecture_and_urdf_examples.
It provides templates for faster implementation of custom hardware and controllers;
The repository is a validation environment for ros2_control concepts, which can only be tested during run-time (e.g., execution of controllers by the controller manager, communication between robot hardware and controllers).

Build status

ROS2 Distro	Branch	Documentation
Rolling	`master`	Documentation API Reference
Rolling - last Focal	`master`	Documentation API Reference
Galactic	`galactic`	Documentation API Reference
Foxy	`foxy`	Documentation API Reference

Explanation of different build types

NOTE: There are three build stages checking current and future compatibility of the package.

Binary builds - against released packages (main and testing) in ROS distributions. Shows that direct local build is possible.

Uses repos file: src/$NAME$/$NAME$-not-released.<ros-distro>.repos
Semi-binary builds - against released core ROS packages (main and testing), but the immediate dependencies are pulled from source. Shows that local build with dependencies is possible and if fails there we can expect that after the next package sync we will not be able to build.

Uses repos file: src/$NAME$/$NAME$.repos
Source build - also core ROS packages are build from source. It shows potential issues in the mid future.

Description

The repository is inspired by the ros_control_boilerplate repository from Dave Coleman. The examples have three parts/packages according to usual structure of ROS packages for robots:

The bringup package ros2_control_demo_bringup, holds launch files and runtime configurations for demo robots.
Description packages rrbot_description and diffbot_description (inside ros2_control_demo_description), store URDF-description files, rviz configurations and meshes for the demo robots.
Hardware interface package ros2_control_demo_hardware, implements the hardware interfaces described in the roadmap.

The examples of RRBot and DiffBot are trivial simulations to demonstrate and test ros2_control concepts. This package does not have any dependencies except ros2 core packages and can, therefore, be used on SoC-hardware or headless systems.

This repository demonstrates the following ros2_control concepts:

Creating a *HardwareInterface for a System, Sensor, and Actuator.
Creating a robot description in the form of URDF files.
Loading the configuration and starting a robot using launch files.
Control of a differential mobile base DiffBot.
Control of two joints of RRBot.
Using simulated robots and starting ros2_control with Gazebo simulator.
Implementing a controller switching strategy for a robot.
Using joint limits and transmission concepts in ros2_control.

Quick Hints

These are some quick hints, especially for those coming from a ROS1 control background:

There are now three categories of hardware components: Sensor, Actuator, and System. Sensor is for individual sensors; Actuator is for individual actuators; System is for any combination of multiple sensors/actuators. You could think of a Sensor as read-only. All components are used as plugins and therefore exported using PLUGINLIB_EXPORT_CLASS macro.
ros(1)_control only allowed three hardware interface types: position, velocity, and effort. ros2_control allows you to create any interface type by defining a custom string. For example, you might define a position_in_degrees or a temperature interface. The most common (position, velocity, acceleration, effort) are already defined as constants in hardware_interface/types/hardware_interface_type_values.hpp.
Joint names in <ros2_control> tags in the URDF must be compatible with the controller's configuration.
In ros2_control, all parameters for the driver are specified in the URDF. The ros2_control framework uses the <ros2_control> tag in the URDF.
Joint names in <ros2_control> tags in the URDF must be compatible with the controller's configuration.

Build from source

git clone https://github.com/ros-controls/ros2_control
git clone https://github.com/ros-controls/ros2_controllers
git clone https://github.com/ros-controls/ros2_control_demos

NOTE: ros2_control and ros2_controllers packages are released for foxy and can be installed using a package manager. We provide officially released and maintained debian packages, which can easily be installed via aptitude. However, there might be cases in which not-yet released demos or features are only available through a source build in your own workspace.

Install dependencies:

rosdep install --from-paths src --ignore-src -r -y

Build everything, e.g. with:
```
colcon build --symlink-install
```
Do not forget to source setup.bash from the install folder!

Getting Started with demos

This repository provides the following simple example robots: a 2 degrees of freedom manipulator - RRBot - and a mobile differential drive base - DiffBot. The first two examples demonstrate the minimal setup for those two robots to run. Later examples show more details about ros2_control-concepts and some more advanced use-cases.

RRBot

RRBot, or ''Revolute-Revolute Manipulator Robot'', is a simple 3-linkage, 2-joint arm that we will use to demonstrate various features. It is essentially a double inverted pendulum and demonstrates some fun control concepts within a simulator and was originally introduced for Gazebo tutorials. The RRBot URDF files can be found in the urdf folder of rrbot_description package.

To check that RRBot descriptions are working properly use following launch commands:

RRBot
```
ros2 launch rrbot_description view_robot.launch.py
```
NOTE: Getting the following output in terminal is OK: Warning: Invalid frame ID "odom" passed to canTransform argument target_frame - frame does not exist. This happens because joint_state_publisher_gui node need some time to start. The joint_state_publisher_gui provides a GUI to generate a random configuration for rrbot. It is immediately displayed in Rviz.
To start RRBot example open a terminal, source your ROS2-workspace and execute its launch file with:
```
ros2 launch ros2_control_demo_bringup rrbot.launch.py
```
The launch file loads and starts the robot hardware, controllers and opens RViz. In starting terminal you will see a lot of output from the hardware implementation showing its internal states. This is only of exemplary purposes and should be avoided as much as possible in a hardware interface implementation.

If you can see two orange and one yellow rectangle in in RViz everything has started properly. Still, to be sure, let's introspect the control system before moving RRBot.
Check if the hardware interface loaded properly, by opening another terminal and executing:
```
ros2 control list_hardware_interfaces
```
You should get:
```
command interfaces
     joint1/position [claimed]
     joint2/position [claimed]
state interfaces
      joint1/position
      joint2/position
```
Marker [claimed] by command interfaces means that a controller has access to command RRBot.

Check is controllers are running:

ros2 control list_controllers

You should get:

joint_state_broadcaster[joint_state_broadcaster/JointStateBroadcaster] active
forward_position_controller[forward_command_controller/ForwardCommandController] active

If you get output from above you can send commands to Forward Command Controller, either:

a. Manually using ros2 cli interface:
```
ros2 topic pub /position_commands std_msgs/msg/Float64MultiArray "data:
- 0.5
- 0.5"
```
B. Or you can start a demo node which sends two goals every 5 seconds in a loop:
```
ros2 launch ros2_control_demo_bringup test_forward_position_controller.launch.py
```
You should now see orange and yellow blocks moving in RViz. Also, you should see changing states in the terminal where launch file is started.

Files used for this demos:

Launch file: rrbot.launch.py
Controllers yaml: rrbot_controllers.yaml
URDF file: rrbot.urdf.xacro
- Description: rrbot_description.urdf.xacro
- ros2_control tag: rrbot.ros2_control.xacro
RViz configuration: rrbot.rviz
Hardware interface plugin: rrbot_system_position_only.cpp

Controllers from this demo:

Joint State Broadcaster (ros2_controllers repository): doc
Forward Command Controller (ros2_controllers repository): doc

DiffBot

DiffBot, or ''Differential Mobile Robot'', is a simple mobile base with differential drive. The robot is basically a box moving according to differential drive kinematics. The DiffBot URDF files can be found in urdf folder of diffbot_description package.

To check that DiffBot description is working properly use following launch commands:
```
ros2 launch diffbot_description view_robot.launch.py
```
NOTE: Getting the following output in terminal is OK: Warning: Invalid frame ID "odom" passed to canTransform argument target_frame - frame does not exist. This happens because joint_state_publisher_gui node need some time to start.
To start DiffBot example open a terminal, source your ROS2-workspace and execute its launch file with:
```
ros2 launch ros2_control_demo_bringup diffbot.launch.py
```
The launch file loads and starts the robot hardware, controllers and opens RViz. In the starting terminal you will see a lot of output from the hardware implementation showing its internal states. This excessive printing is only added for demonstration. In general, printing to the terminal should be avoided as much as possible in a hardware interface implementation.

If you can see an orange box in RViz everything has started properly. Still, to be sure, let's introspect the control system before moving DiffBot.

Check if the hardware interface loaded properly, by opening another terminal and executing:

ros2 control list_hardware_interfaces

You should get:

command interfaces
     left_wheel_joint/velocity [claimed]
     right_wheel_joint/velocity [claimed]
state interfaces
      left_wheel_joint/position
      left_wheel_joint/velocity
      right_wheel_joint/position
      right_wheel_joint/velocity

The [claimed] marker on command interfaces means that a controller has access to command DiffBot.

Check if controllers are running:

ros2 control list_controllers

You should get:

diffbot_base_controller[diff_drive_controller/DiffDriveController] active
joint_state_broadcaster[joint_state_broadcaster/JointStateBroadcaster] active

If everything is fine, now you can send a command to Diff Drive Controller using ros2 cli interface:
```
ros2 topic pub --rate 30 /diffbot_base_controller/cmd_vel_unstamped geometry_msgs/msg/Twist "linear:
 x: 0.7
 y: 0.0
 z: 0.0
angular:
 x: 0.0
 y: 0.0
 z: 1.0"
```
You should now see an orange box circling in RViz. Also, you should see changing states in the terminal where launch file is started.

Files used for this demos:

Launch file: diffbot.launch.py
Controllers yaml: diffbot_controllers.yaml
URDF file: diffbot.urdf.xacro
- Description: diffbot_description.urdf.xacro
- ros2_control tag: diffbot.ros2_control.xacro
RViz configuration: diffbot.rviz
Hardware interface plugin: diffbot_system.cpp

Controllers from this demo:

Joint State Broadcaster (ros2_controllers repository): doc
Diff Drive Controller (ros2_controllers repository): doc

Examples of ros2_control concepts

Each of the described example cases from the roadmap has its own launch and URDF file.

General notes about examples

Each example is started with a single launch file which starts up the robot hardware, loads controller configurations and it also opens RViz.

The RViz setup can be recreated following these steps:
- The robot models can be visualized using RobotModel display using /robot_description topic.
- Or you can simply open the configuration from rviz folder in rrbot_description or diffbot_description package manually or directly by executing:
```
rviz2 --display-config `ros2 pkg prefix rrbot_description`/share/rrbot_description/config/rrbot.rviz
```
To check that robot descriptions are working properly use following launch commands:
```
ros2 launch rrbot_description view_robot.launch.py
```
Optional arguments for specific example (the robot visualization will be the same for all examples):
```
description_file:=rrbot_system_multi_interface.urdf.xacro
```

NOTE: Getting the following output in terminal is OK: Warning: Invalid frame ID "odom" passed to canTransform argument target_frame - frame does not exist. This happens because joint_state_publisher_gui node need some time to start.

To start an example open a terminal, source your ROS2-workspace and execute a launch file with:
```
ros2 launch ros2_control_demo_bringup <example_launch_file>
```
To stop RViz2 from auto-start use start_rviz:=false launch file argument.

To check if the hardware interface loaded properly, open another terminal and execute:

ros2 control list_hardware_interfaces

You should get something like:

command interfaces
      joint1/position [unclaimed]
      joint2/position [unclaimed]
state interfaces
      joint1/position
      joint2/position

Check which controllers are running using:

ros2 control list_controllers

You should get something like:

forward_position_controller[forward_command_controller/ForwardCommandController] unconfigured
joint_state_broadcaster[joint_state_broadcaster/JointStateBroadcaster] active

Check Controllers and moving hardware section to move RRBot.

NOTE: The examples reuse the same, configurable base-launch file rrbot_base.launch.py. This also demonstrates how launch files are usually reused for different scenarios when working with ros2_control.

Example 1: "Industrial Robots with only one interface"

Files:

Launch file: rrbot_system_position_only.launch.py
Controllers yaml: rrbot_controllers.yaml
URDF: rrbot_system_position_only.urdf.xacro
ros2_control URDF tag: rrbot_system_position_only.ros2_control.xacro

Interfaces:

Command interfaces:
- joint1/position
- joint2/position
State interfaces:
- joint1/position
- joint2/position

Available controllers:

joint_state_broadcaster[joint_state_broadcaster/JointStateBroadcaster]
forward_position_controller[forward_command_controller/ForwardCommandController] (position)

Moving the robot:

see below description of forward_position_controller

Available launch file options:

use_fake_hardware:=true - start FakeSystem instead of hardware. This is a simple simulation that mimics joint command to their states. This is useful to test ros2_control integration and controllers without physical hardware.

Example 1-Sim: "Industrial Robots with only one interface" (Gazebo simulation)

TBA

Example 2: "Robots with multiple interfaces"

Files:

Launch file: rrbot_system_multi_interface.launch.py
Controllers yaml: rrbot_multi_interface_forward_controllers.yaml
URDF: rrbot_system_multi_interface.urdf.xacro
ros2_control URDF tag: rrbot_system_multi_interface.ros2_control.xacro

Interfaces:

Command interfaces:
- joint1/position
- joint2/position
- joint1/velocity
- joint2/velocity
- joint1/acceleration
- joint2/acceleration
State interfaces:
- joint1/position
- joint2/position
- joint1/velocity
- joint2/velocity
- joint1/acceleration
- joint2/acceleration

Available controllers:

joint_state_broadcaster[joint_state_broadcaster/JointStateBroadcaster]
forward_position_controller[position_controllers/JointGroupPositionController]
forward_velocity_controller[velocity_controllers/JointGroupVelocityController]
forward_acceleration_controller[forward_command_controller/ForwardCommandController]
forward_illegal1_controller[forward_command_controller/ForwardCommandController]
forward_illegal2_controller[forward_command_controller/ForwardCommandController]

Notes:

The example shows how to implement multi-interface robot hardware taking care about interfaces used. The two illegal controllers demonstrate how hardware interface declines faulty claims to access joint command interfaces.

Moving the robot:

when using velocity controller:

ros2 topic pub /forward_velocity_controller/commands std_msgs/msg/Float64MultiArray "data:
- 5
- 5"

when using acceleration controller

ros2 topic pub /forward_acceleration_controller/commands std_msgs/msg/Float64MultiArray "data:
- 10
- 10"

Useful launch-file options:

robot_controller:=forward_position_controller - starts demo and spawns position controller. Robot can be then controlled using forward_position_controller as described below.
robot_controller:=forward_acceleration_controller - starts demo and spawns acceleration controller. Robot can be then controlled using forward_acceleration_controller as described below.

Example 3: "Industrial robot with integrated sensor"

Launch file: rrbot_system_with_sensor.launch.py
Controllers: rrbot_with_sensor_controllers.yaml
URDF: rrbot_system_with_sensor.urdf.xacro
ros2_control URDF: rrbot_system_with_sensor.ros2_control.xacro
Command interfaces:
- joint1/position
- joint2/position
State interfaces:
- joint1/position
- joint2/position
- tcp_fts_sensor/force.x
- tcp_fts_sensor/torque.z

Available controllers:

forward_position_controller[forward_command_controller/ForwardCommandController]
fts_broadcaster[force_torque_sensor_broadcaster/ForceTorqueSensorBroadcaster]
joint_state_broadcaster[joint_state_broadcaster/JointStateBroadcaster]

Notes:

Wrench messages are may not be displayed properly in Rviz as NaN values are not handled in Rviz and FTS Broadcaster may send NaN values.

Commanding the robot: see the commands below.

Accessing Wrench data from 2D FTS:

ros2 topic echo /fts_broadcaster/wrench

Example 4: "Industrial Robots with externally connected sensor"

Launch file: rrbot_system_with_external_sensor.launch.py
Controllers: rrbot_with_external_sensor_controllers.yaml
URDF: rrbot_with_external_sensor_controllers.urdf.xacro
ros2_control URDF:
- robot: rrbot_system_position_only.ros2_control.xacro
- sensor: external_rrbot_force_torque_sensor.ros2_control.xacro
Command interfaces:
- joint1/position
- joint2/position
State interfaces:
- joint1/position
- joint2/position
- tcp_fts_sensor/force.x
- tcp_fts_sensor/force.y
- tcp_fts_sensor/force.z
- tcp_fts_sensor/torque.x
- tcp_fts_sensor/torque.y
- tcp_fts_sensor/torque.z

Available controllers:

forward_position_controller[forward_command_controller/ForwardCommandController]
fts_broadcaster[force_torque_sensor_broadcaster/ForceTorqueSensorBroadcaster]
joint_state_broadcaster[joint_state_broadcaster/JointStateBroadcaster]

Commanding the robot: see the commands below.

Accessing Wrench data from 2D FTS:

ros2 topic echo /fts_broadcaster/wrench

Example 5: "Modular Robots with separate communication to each actuator"

Launch file: rrbot_modular_actuators.launch.py
Controllers: rrbot_modular_actuators.yaml
URDF: rrbot_modular_actuators.urdf.xacro
ros2_control URDF: rrbot_modular_actuators.ros2_control.xacro
Command interfaces:
- joint1/position
- joint2/position
State interfaces:
- joint1/position
- joint2/position

Available controllers:

forward_position_controller[forward_command_controller/ForwardCommandController]
joint_state_broadcaster[joint_state_broadcaster/JointStateBroadcaster]

Commanding the robot: see the commands below.

Controllers and moving hardware

To move the robot you should load and start controllers. The JointStateBroadcaster is used to publish the joint states to ROS topics. Direct joint commands are sent to this robot via the ForwardCommandController and JointTrajectoryController. The sections below describe their usage. Check the Results section on how to ensure that things went well.

NOTE: Before doing any action with controllers check their state using command:

ros2 control list_controllers

JointStateBroadcaster

Open another terminal and load, configure and start joint_state_broadcaster:

ros2 control set_controller_state joint_state_broadcaster start

Check if controller is loaded properly:

ros2 control list_controllers

You should get the response:

joint_state_broadcaster[joint_state_broadcaster/JointStateBroadcaster] active

Now you should also see the RRbot represented correctly in RViz.

Using ForwardCommandController

If you want to test hardware with ForwardCommandController first load a controller (not always needed):
```
ros2 control load_controller forward_position_controller
```
Check if the controller is loaded properly:
```
ros2 control list_controllers
```

Then configure it:

ros2 control set_controller_state forward_position_controller configure

Check if the controller is loaded properly:

ros2 control list_controllers

You should get the response:

forward_position_controller[forward_command_controller/ForwardCommandController] inactive

Now start the controller:

ros2 control switch_controllers --start forward_position_controller

Check if controllers are activated:

ros2 control list_controllers

You should get active in the response:

joint_state_broadcaster[joint_state_broadcaster/JointStateBroadcaster] active
forward_position_controller[forward_command_controller/ForwardCommandController] active

Send a command to the controller, either:

a. Manually using ros2 cli interface:
```
ros2 topic pub /forward_position_controller/commands std_msgs/msg/Float64MultiArray "data:
- 0.5
- 0.5"
```
B. Or you can start a demo node which sends two goals every 5 seconds in a loop:
```
ros2 launch ros2_control_demo_bringup test_forward_position_controller.launch.py
```
You can adjust the goals in rrbot_forward_position_publisher.yaml.

Using JointTrajectoryController

If you want to test hardware with JointTrajectoryController first load and configure a controller (not always needed):

ros2 control load_controller position_trajectory_controller --set-state configure

Check if the controller is loaded and configured properly:

ros2 control list_controllers

You should get the response:

position_trajectory_controller[joint_trajectory_controller/JointTrajectoryController] inactive

Now start the controller (and stop other running contorller):

ros2 control switch_controllers --stop forward_position_controller --start position_trajectory_controller

Check if controllers are activated:

ros2 control list_controllers

You should get active in the response:

joint_state_broadcaster[joint_state_broadcaster/JointStateBroadcaster] active
position_trajectory_controller[joint_trajectory_controller/JointTrajectoryController] active

Send a command to the controller using demo node which sends four goals every 6 seconds in a loop:
```
ros2 launch ros2_control_demo_bringup test_joint_trajectory_controller.launch.py
```
You can adjust the goals in rrbot_joint_trajectory_publisher.yaml.

Result

Independently from the controller you should see how the example's output changes. Look for the following lines

[RRBotSystemPositionOnlyHardware]: Got state 0.0 for joint 0!
[RRBotSystemPositionOnlyHardware]: Got state 0.0 for joint 1!

If you echo the /joint_states or /dynamic_joint_states topics you should also get similar values.
```
ros2 topic echo /joint_states
ros2 topic echo /dynamic_joint_states
```
You should also see the RRbot moving in RViz.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

ros2_control Demos

First-Time Users

Goals

Build status

Explanation of different build types

Description

Quick Hints

Build from source

Getting Started with demos

RRBot

DiffBot

Examples of ros2_control concepts

General notes about examples

Example 1: "Industrial Robots with only one interface"

Example 1-Sim: "Industrial Robots with only one interface" (Gazebo simulation)

Example 2: "Robots with multiple interfaces"

Example 3: "Industrial robot with integrated sensor"

Example 4: "Industrial Robots with externally connected sensor"

Example 5: "Modular Robots with separate communication to each actuator"

Controllers and moving hardware

JointStateBroadcaster

Using ForwardCommandController

Using JointTrajectoryController

Result

Files

README.md

Latest commit

History

README.md

File metadata and controls

ros2_control Demos

First-Time Users

Goals

Build status

Explanation of different build types

Description

Quick Hints

Build from source

Getting Started with demos

RRBot

DiffBot

Examples of ros2_control concepts

General notes about examples

Example 1: "Industrial Robots with only one interface"

Example 1-Sim: "Industrial Robots with only one interface" (Gazebo simulation)

Example 2: "Robots with multiple interfaces"

Example 3: "Industrial robot with integrated sensor"

Example 4: "Industrial Robots with externally connected sensor"

Example 5: "Modular Robots with separate communication to each actuator"

Controllers and moving hardware

JointStateBroadcaster

Using ForwardCommandController

Using JointTrajectoryController

Result