ROS 2 用户指南
This topic explains how to setup and use ROS 2 with PX4.
It provides an overview of the ROS2-PX4 bridge architecture and application pipeline, along with instructions on how to install all the needed software and build ROS 2 applications.
Overview
The application pipeline for ROS 2 is very straightforward, thanks to the native communications middleware (DDS/RTPS). The microRTPS Bridge consists of a client running on PX4 and an agent running on the Mission/Companion Computer, which communicate to provide bi-directional data exchange and message translation between UORB and ROS 2 message formats. This allows you to create ROS 2 subscribers or publisher nodes that interface directly with PX4 UORB topics! This is shown in the diagram below.
ROS 2 uses the px4_msgs
and px4_ros_com
packages to ensure that matching message definitions are used for creating both the client and the agent code (this is important), and also to remove the requirement for PX4 to be present when building ROS code.
px4_msgs
contains PX4 ROS message definitions. When this project is built it generates the corresponding ROS 2-compatible typesupport, used by ROS 2 nodes, and IDL files, used byfastddsgen
to generate the microRTPS agent code.px4_ros_com
contains the microRTPS agent code templates for the agent publishers and subscribers. The build process runs afastddsgen
instance to generate the code for themicrortps_agent
, which compiles into a single executable.
The PX4 Autopilot project automatically updates px4_msgs
with new message definitions whenever they are changed (in the master
branch).
PX4 firmware contains the microRTPS client based on its build-time message definitions.
You cannot use an agent generated as part of a "normal" PX4 build with ROS 2 (e.g. if the user uses BUILD_MICRORTPS_AGENT=1 make px4_sitl_rtps
). While microRTPS client is the same, the IDL files used by ROS 2 are slightly different from the custom ones with generate in PX4. The other detail is that the "normal" PX4 build doesn't use fastddsgen
with typesupport for ROS 2 networks - and that's also one of the main reasons we have a separate microRTPS agent in px4_ros_com
, which is completely compatible with ROS 2 networks. We use the px4_msg
to generate appropriate IDL files for the micrortps_agent
in px4_ros_com
.
Installation & Setup
To setup ROS 2 for use with PX4 you will need to:
Sanity Check the Installation (Optional)
Install Fast DDS
Follow the Fast DDS Installation Guide to install Fast RTPS(DDS) 2.0.2 (or later) and Fast-RTPS-Gen 1.0.4 (not later!) and their dependencies.
Check the guide to confirm the latest dependencies! You won't be able to continue with this guide until the correct versions of Fast RTPS(DDS) and Fast-RTPS-Gen have been installed.
Install ROS 2
To install ROS 2 and its dependencies:
The install process should also install the
colcon
build tools, but in case that doesn't happen, you can install the tools manually:eigen3_cmake_module
is also required, since Eigen3 is used on the transforms library:Some Python dependencies must also be installed (using
pip
orapt
):
Build ROS 2 Workspace
This section shows how create a ROS 2 workspace hosted in your home directory (modify the commands as needed to put the source code elsewhere). The px4_ros_com
and px4_msg
packages are cloned to a workspace folder, and then a script is used to build the workspace.
To create and build the workspace:
Create a workspace directory using:
Clone the ROS 2 bridge packages
px4_ros_com
andpx4_msgs
to the/src
directory (themaster
branch is cloned by default):Use the
build_ros2_workspace.bash
script to build the ROS 2 workspace (includingpx4_ros_com
andpx4_msgs
).
All script options can be listed by calling it with the --help
argument. In particular the --verbose
argument shows the full colcon build output.
Sanity Check the Installation
One way to check that the installation/setup succeeded is to test that the bridge can communicate with PX4. We can do this by running the bridge against PX4 running in the simulator.
Setup your PX4 Ubuntu Linux development environment - the default instructions get the latest version of PX4 source and install all the needed tools.
Open a new terminal in the root of the PX4 Autopilot project, and then start a PX4 Gazebo simulation using:
Once PX4 has fully started the terminal will display the NuttShell/System Console. Note also that PX4 SITL will automatically start the
micrortps_client
connected to UDP ports 2019 and 2020.On a new terminal,
source
the ROS 2 workspace and then start themicrortps_agent
daemon with UDP as the transport protocol:Open a new terminal and start a "listener" using the provided launch file:
If the bridge is working correctly you will be able to see the data being printed on the terminal/console where you launched the ROS listener:
You can also verify the rate of the message using ros2 topic hz
. E.g. in the case of sensor_combined
use ros2 topic hz /fmu/sensor_combined/out
:
ROS 2 Example Applications
Creating a ROS 2 listener
With the px4_ros_com
built successfully, one can now take advantage of the generated microRTPS agent app and also from the generated sources and headers of the ROS 2 msgs from px4_msgs
, which represent a one-to-one matching with the uORB counterparts.
To create a listener node on ROS 2, lets take as an example the sensor_combined_listener.cpp
node under px4_ros_com/src/examples/listeners
.
The code first imports the C++ libraries needed to interface with the ROS 2 middleware and the required message header file:
Then it creates a SensorCombinedListener
class that subclasses the generic rclcpp::Node
base class.
This creates a callback function for when the sensor_combined
uORB messages are received (now as RTPS/DDS messages), and outputs the content of the message fields each time the message is received.
The lines below create a publisher to the sensor_combined
uORB topic, which can be matched with one or more compatible ROS2 subscribers to the fmu/sensor_combined/out
ROS2 topic.
The instantiation of the SensorCombinedListener
class as a ROS node is done on the main
function.
Creating a ROS 2 advertiser
A ROS 2 advertiser node publishes data into the DDS/RTPS network (and hence to the PX4 Autopilot).
Taking as an example the debug_vect_advertiser.cpp
under px4_ros_com/src/advertisers
, first we import required headers, including the debug_vect
msg header.
Then the code creates a DebugVectAdvertiser
class that subclasses the generic rclcpp::Node
base class.
The code below creates a function for when messages are to be sent. The messages are sent based on a timed callback, which sends two messages per second based on a timer.
The instantiation of the DebugVectAdvertiser
class as a ROS node is done on the main
function.
Offboard Control
For a complete reference example on how to use Offboard control with PX4, see: ROS 2 Offboard control example.
Manual Workspace Setup with a ROS1 compatible workspace (FYI Only)
This section describes the process to manually setup your workspace and build the px4_ros_com
, px4_msgs
, and ros1_bridge
package. The topic effectively explains the operation of the build_ros2_workspace.bash
script in the installation instructions).
To build the ROS 2 workspace only:
cd
intopx4_ros_com_ros2
dir and source the ROS 2 environment. Don't mind if it tells you that a previous workspace was set before:Build the workspace:
To build both ROS 2 and ROS (1) workspaces (replacing the previous steps):
cd
intopx4_ros_com_ros2
dir and source the ROS 2 environment. Don't mind if it tells you that a previous workspace was set before:Clone the
ros1_bridge
package so it can be built on the ROS 2 workspace:Build the
px4_ros_com
andpx4_msgs
packages, excluding theros1_bridge
package:Then build the ROS(1) packages side. First open a new terminal window and source the ROS(1) environment that was installed on the system:
Build the
px4_ros_com
andpx4_msgs
packages on the ROS end (using the terminal opened in the previous step):Open another new terminal and then source the environments and workspaces in the order listed below:
Finally, build the
ros1_bridge
:
Cleaning the workspaces
After building the workspaces there are many files that must be deleted before you can do a clean/fresh build (for example, after you have changed some code and want to rebuild).
Unfortunately colcon does not currently have a way of cleaning the generated build, install and log directories, so these directories must be deleted manually.
The clean_all.bash script (in px4_ros_com/scripts) is provided to ease this cleaning process, this script can be used to clean all of the workspace options listed above (ROS 2, ROS 1, and Both)
The most common way of using it is by passing it the ROS (1) workspace directory path (since it's usually not on the default path):
Like the build scripts, the clean_all.bash
script also has a --help
guide.
Additional information
Last updated