diff --git a/assets/middleware/microdds/simulation.png b/assets/middleware/microdds/simulation.png new file mode 100644 index 000000000000..d84a03343f6a Binary files /dev/null and b/assets/middleware/microdds/simulation.png differ diff --git a/assets/middleware/microdds/topic.png b/assets/middleware/microdds/topic.png new file mode 100644 index 000000000000..3fa3b2e6d522 Binary files /dev/null and b/assets/middleware/microdds/topic.png differ diff --git a/en/SUMMARY.md b/en/SUMMARY.md index bec64594e60b..5f9e1ce29d04 100644 --- a/en/SUMMARY.md +++ b/en/SUMMARY.md @@ -313,7 +313,6 @@ * [Ubuntu Setup](dev_setup/dev_env_linux_ubuntu.md) * [Windows Setup](dev_setup/dev_env_windows_wsl.md) * [Visual Studio Code IDE](dev_setup/vscode.md) - * [Fast DDS installation](dev_setup/fast-dds-installation.md) * [Building the Code](dev_setup/building_px4.md) * [Writing your First Application](modules/hello_sky.md) * [Application/Module Template](modules/module_template.md) @@ -538,8 +537,7 @@ * [wind](msg_docs/wind.md) * [yaw_estimator_status](msg_docs/yaw_estimator_status.md) * [MAVLink Messaging](middleware/mavlink.md) - * [RTPS/DDS Interface: PX4-Fast RTPS(DDS) Bridge](middleware/micrortps.md) - * [Manually Generate Client/Agent](middleware/micrortps_manual_code_generation.md) + * [MicroDDS PX4-Bridge](middleware/microdds.md) * [Modules & Commands](modules/modules_main.md) * [Commands](modules/modules_command.md) * [Communication](modules/modules_communication.md) @@ -611,7 +609,7 @@ * [ROS](ros/README.md) * [ROS 2](ros/ros2.md) * [ROS 2 User Guide](ros/ros2_comm.md) - * [ROS 2 microRTPS Offboard Control Example](ros/ros2_offboard_control.md) + * [ROS 2 microRTPS Offboard Control Example](ros/ros2_offboard_control.md) * [ROS (1) via ROS 2 Bridge](ros/ros1_via_ros2.md) * [ROS (1) with MAVROS](ros/ros1.md) * [ROS/MAVROS Installation Guide](ros/mavros_installation.md) diff --git a/en/advanced_config/ethernet_setup.md b/en/advanced_config/ethernet_setup.md index 1702a361d64a..36ccd59d5dc2 100644 --- a/en/advanced_config/ethernet_setup.md +++ b/en/advanced_config/ethernet_setup.md @@ -203,10 +203,10 @@ However this is not recommended because the default configuration is optimised f ## ROS2 Setup Example - -Prerequisites: - -- You have a supported autopilot hardware with RTPS feature enabled firmware on it by using [this guide](../middleware/micrortps.md#client-px4-px4-autopilot). + +Prerequisites: + +- You have a supported autopilot hardware with RTPS feature enabled firmware on it by using [this guide](../middleware/micrortps.md#client-px4-px4-autopilot). - [ROS2](../ros/ros2_comm.md#sanity-check-the-installation) has been set up correctly and [sanity check](../ros/ros2_comm.md#sanity-check-the-installation) has been confirmed. - You have followed the Ethernet network and port setup as discussed at the top of this page. diff --git a/en/dev_setup/building_px4.md b/en/dev_setup/building_px4.md index 856f18e6ee68..ae19541fce80 100644 --- a/en/dev_setup/building_px4.md +++ b/en/dev_setup/building_px4.md @@ -256,7 +256,7 @@ make [VENDOR_][MODEL][_VARIANT] [VIEWER_MODEL_DEBUGGER_WORLD] - **VENDOR:** The manufacturer of the board: `px4`, `aerotenna`, `airmind`, `atlflight`, `auav`, `beaglebone`, `intel`, `nxp`, etc. The vendor name for Pixhawk series boards is `px4`. - **MODEL:** The *board model* "model": `sitl`, `fmu-v2`, `fmu-v3`, `fmu-v4`, `fmu-v5`, `navio2`, etc. -- **VARIANT:** Indicates particular configurations: e.g. `rtps`, `lpe`, which contain components that are not present in the `default` configuration. Most commonly this is `default`, and may be omitted. +- **VARIANT:** Indicates particular configurations: e.g. `rtps`, `lpe`, which contain components that are not present in the `default` configuration. Most commonly this is `default`, and may be omitted. :::tip You can get a list of *all* available `CONFIGURATION_TARGET` options using the command below: diff --git a/en/dev_setup/dev_env_linux_arch.md b/en/dev_setup/dev_env_linux_arch.md index 564a315d66b1..c37dd602790c 100644 --- a/en/dev_setup/dev_env_linux_arch.md +++ b/en/dev_setup/dev_env_linux_arch.md @@ -7,7 +7,7 @@ See [Toolchain Installation](../dev_setup/dev_env.md) for information about the The PX4-Autopilot repository provides a convenient script to set your Arch installation up for PX4 development: [Tools/setup/arch.sh](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/setup/arch.sh). -The script installs (by default) all tools to build PX4 (without RTPS) for NuttX targets and run simulation with *jMAVsim*. +The script installs (by default) all tools to build PX4 for NuttX targets and run simulation with *jMAVsim*. You can additionally install the *Gazebo* simulator by specifying the command line argument: `--gazebo`. ![Gazebo on Arch](../../assets/simulation/gazebo/arch-gazebo.png) diff --git a/en/dev_setup/dev_env_linux_ubuntu.md b/en/dev_setup/dev_env_linux_ubuntu.md index c4462f8c2bd5..4608ce78ec83 100644 --- a/en/dev_setup/dev_env_linux_ubuntu.md +++ b/en/dev_setup/dev_env_linux_ubuntu.md @@ -7,7 +7,6 @@ This environment can be used to build PX4 for [most PX4 targets](../dev_setup/de * [Gazebo Simulation](../simulation/gazebo.md) * [Raspberry Pi](#raspberry-pi) * [ROS (1)](#ros-gazebo) (Robotics Operating System) -* [Fast DDS](../dev_setup/fast-dds-installation.md) - Required for ROS2 :::tip This setup is supported by the PX4 dev team. @@ -207,15 +206,6 @@ To install the development toolchain: ::: - - -## Fast DDS installation - -[eProsima Fast DDS](https://github.com/eProsima/Fast-DDS) is required if you're using PX4 with ROS2 (or some other RTPS/DDS system). - -Follow the instructions in [Fast DDS Installation](../dev_setup/fast-dds-installation.md) to install it. - - ## Next Steps Once you have finished setting up the command-line toolchain: diff --git a/en/dev_setup/fast-dds-installation.md b/en/dev_setup/fast-dds-installation.md deleted file mode 100644 index 62f266e285c7..000000000000 --- a/en/dev_setup/fast-dds-installation.md +++ /dev/null @@ -1,148 +0,0 @@ -# Fast DDS Installation - -logo [eProsima Fast DDS](https://github.com/eProsima/Fast-DDS) is a C++ implementation of the Object Management Group's (OMG) Data Distribution Service (DDS) specification and the Real Time Publish Subscribe (RTPS) protocol. - -Fast DDS enables an RTPS/DDS interface that allows PX4 uORB topics to be shared with offboard components that participate in same DDS domain, including robotics and simulator tools. -In particular, Fast DDS is the default middleware implementation for Robot Operating System 2 (ROS 2), and is essential for integrating PX4 with ROS2. - -This topic explains how to install Fast DDS and *Fast-RTPS-Gen* to use in the PX4 build system and with the microRTPS bridge. - -:::note -You do not have to install Fast DDS if you have ROS 2 Dashing (Ubuntu 18.04) or ROS 2 Foxy (Ubuntu 20.04) installed, as it comes included with the default `base` or `desktop` installations through the `ros--rmw-fastrtps` package. -This means you just need to install *Fast-RTPS-Gen* and have your ROS 2 environment sourced (`source /opt/ros//setup.bash`) in order to be able to compile the `rtps` targets in the PX4-Autopilot repo. - -For *ROS2 Galactic and above*, one has to install the `rmw` implementation through `apt` using `apt install ros-galactic-rmw-fastrtps`, since the default middleware for Galactic and above is CycloneDDS and the FastDDS middleware doesn't come installed by default. -::: - -:::tip -Fast DDS is not an essential component of the PX4 Autopilot and should only be installed if you plan to interface the PX4 Autopilot with Fast RTPS/DDS participants. -ROS 2 nodes are an example of these, though Fast DDS middleware and C++ implementations are installed by default on ROS 2 Foxy and below, as mentioned above. -::: - -:::note -Fast DDS was previously named FastRTPS (the name was changed in version 2.0.0 as it now includes a full DDS implementation, rather than just the RTPS wire protocol). -::: - - -## Prerequisites - -*eProsima Fast DDS* requires the following packages to work. - -:::note -At time of writing you will need to install *from source* for: -- **Ubuntu 18.04:** Fast RTPS 1.8.4 (or later) and Fast-RTPS-Gen 1.0.4 (not later!). -- **Ubuntu 20.04:** Fast DDS 2.0.2 (or later) and Fast-RTPS-Gen 1.0.4 (not later!). -::: - -:::tip -Remember (again) you only need to install Fast DDS if you are not using ROS 2 and just want to leverage non-ROS2 DDS networks and applications. -If you have ROS 2 installed (and `rmw-fasrtps` as its default middleware), you can skip to [Fast-RTPS-Gen build and install](#fast-rtps-gen). -::: - -### Java - -Java is required to build and use eProsima's RTPS/DDS from IDL code generation tool - *Fast-RTPS-Gen*. -[Java JDK 11](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html) is recommended, and it is installed through the setup scripts made available in [Ubuntu Development Environment](../dev_setup/dev_env_linux.md). - -### Foonathan memory - -In order to build Fast DDS you need to install the Foonathan Memory dependency. - -```sh -git clone https://github.com/eProsima/foonathan_memory_vendor.git -cd foonathan_memory_vendor -mkdir build && cd build -cmake .. -cmake --build . --target install -``` - -:::note -If the last step fails, try running the command with the proper user privileges (`sudo`). -::: - - -## Installation from Sources - -### Fast DDS - -Clone the project from Github: - -```sh -$ git clone --recursive https://github.com/eProsima/Fast-DDS.git -b v2.0.2 ~/FastDDS-2.0.2 -$ cd ~/FastDDS-2.0.2 -$ mkdir build && cd build -``` - -If you are on Linux, execute: - -```sh -$ cmake -DTHIRDPARTY=ON -DSECURITY=ON .. -$ make -j$(nproc --all) -$ sudo make install -``` - -This will install Fast DDS to `/usr/local`, with secure communications support. -If you need to install to a custom location you can use: `-DCMAKE_INSTALL_PREFIX=`. - -#### Compile Options - -The following additional arguments can be used when calling *CMake*: - -- `-DCOMPILE_EXAMPLES=ON`: Compile the examples -- `-DPERFORMANCE_TESTS=ON`: Compile the performance tests - - -### Fast-RTPS-Gen - -*Fast-RTPS-Gen* is the Fast RTPS (DDS) IDL code generator tool. -It should be installed after Fast RTPS (DDS) and made sure the `fastrtpsgen` application is in your `PATH`. -You can check with `which fastrtpsgen`. - -Then clone Fast-RTPS-Gen 1.0.4: -``` -git clone --recursive https://github.com/eProsima/Fast-DDS-Gen.git -b v1.0.4 ~/Fast-RTPS-Gen \ - -&& cd ~/Fast-RTPS-Gen/gradle/wrapper -``` - -After that, modify the distribution version of gradle inside the gradle-wrapper.properties file to gradle-6.8.3 such that the distributionUrl file becomes as follows: - -``` -distributionUrl=https\://services.gradle.org/distributions/gradle-6.8.3-bin.zip -``` -Now you should run the following commands: - -``` - cd ~/Fast-RTPS-Gen - ./gradlew assemble && sudo env "PATH=$PATH" ./gradlew install -``` - -## Installation from Binaries - -:::note -Although the binaries are available, we recommend to build and install the code from source, given that the binaries may not come with required components and dependencies in place. -::: - -The latest binary release of *eProsima Fast DDS* can be downloaded from the [company website](http://www.eprosima.com/). - -Documentation on how to do this can be found here: [Installation from Binaries on Linux](https://fast-dds.docs.eprosima.com/en/latest/installation/binaries/binaries_linux.html) and [Installation from Binaries on Windows](https://fast-dds.docs.eprosima.com/en/latest/installation/binaries/binaries_windows.html) (*eProsima Fast DDS* official documentation) - -#### Environmental Variables - -* `FASTRTPSGEN_DIR`: Root folder where *eProsima Fast-RTPS-Gen* is installed, usually set to `/usr/local`, which is the default installation directory. - If the user sets a different install directory in the `gradle install` step, it must set this variable to that same directory as well. - Otherwise, the code generation step, and consequently, the build of the `rtps` targets in PX4 will fail. - - -## Further Information - -- [RTPS/DDS Interface: PX4-Fast RTPS(DDS) Bridge](../middleware/micrortps.md) -- [PX4-ROS 2 bridge](../ros/ros2_comm.md) - -- Additional installation information can be found in the official [*eProsima Fast DDS* documentation](https://fast-dds.docs.eprosima.com/en/latest/) (from which this topic is derived): - - Installation from Sources - - [Linux](https://fast-dds.docs.eprosima.com/en/latest/installation/sources/sources_linux.html) - - [Windows](https://fast-dds.docs.eprosima.com/en/latest/installation/sources/sources_windows.html) - - Installation from Binaries - - [Linux](https://fast-dds.docs.eprosima.com/en/latest/installation/binaries/binaries_linux.html) - - [Windows](https://fast-dds.docs.eprosima.com/en/latest/installation/binaries/binaries_windows.html) diff --git a/en/hardware/porting_guide_config.md b/en/hardware/porting_guide_config.md index 6bc3fd8ed3de..bf20d817e00a 100644 --- a/en/hardware/porting_guide_config.md +++ b/en/hardware/porting_guide_config.md @@ -39,7 +39,7 @@ Builds will silently ignore any missing or miss-spelled modules in the `*.px4bo Each PX4 board must have a `default.px4board` configuration and can have an optional `bootloader.px4board configuration`. However you can add also separate configurations under a different label e.g. `rtps.px4board`. Note that by default the configuration of `rtps.px4board` inherits all settings set in `default.px4board`. -When changing the `rtps.px4board` it only stores the delta of the Kconfig keys that are different compared to `default.px4board`, this is useful to simplify configurations management +When changing the `rtps.px4board` it only stores the delta of the Kconfig keys that are different compared to `default.px4board`, this is useful to simplify configurations management. :::note When modifying a Kconfig key in `default.px4board` it will be modified in all derivative configurations of the same board that had the same config as well. diff --git a/en/middleware/microdds.md b/en/middleware/microdds.md new file mode 100644 index 000000000000..f4264ea406f2 --- /dev/null +++ b/en/middleware/microdds.md @@ -0,0 +1,74 @@ +# MicroDDS + +Micro XRCE-DDS is a software solution that enables communication with an existing DDS network. + +The new approach provides a faster and simpler method of integrating applictaions running and linked in DDS domains (including ROS nodes), making it easy to share sensor data, commands, and other vehicle information. + +The following guide describes the new PX4 bridge architecture, and shows the reader how to write a simple *Micro DDS* application to subscribe * publish telemetry updates from the PX4 Autopilot. + +:::note +MicroDDS has replaced the PX4 FastRTPS (DDS) Bridge. +If you're working PX4 v1.13 (or earlier) FastRTPS documentation can be found here: + +- [RTPS/DDS Interface: PX4-Fast RTPS(DDS) Bridge](https://docs.px4.io/v1.13/en/middleware/micrortps.html) + - [Manually Generate Client and Agent Code](https://docs.px4.io/v1.13/en/middleware/micrortps_manual_code_generation.html) +- [Fast DDS Installation](https://docs.px4.io/v1.13/en/dev_setup/fast-dds-installation.html) +::: + + +## Why this approach is of interest? + +Initially, micro-RTPS served as the middleware and its consistent improvement evolved into what's known as the microDDS that provides the user a native interface between the flight controller and the mission computer DDS/ROS2 data space. +The notable difference between the two is what kind of transport protocol each supports. The newest version supports UDP/TCP/Serial/Custom transport protocol. + +The Micro-XRCE-DDS-Gen has 2 major advantages, i.e. it can be used to generate client code and build px4_msgs along with microdds_client together creating a single library. + +:::tip + +::: + +## Architectural overview + +### microDDS Bridge + +[*micro XRCE-DDS*](https://micro-xrce-dds.docs.eprosima.com/en/stable/introduction.html) provides a DDS publisher/subscriber middleware wherein the client is on a low-resource consumption device and the agent is connected to with the DDS global data space. + +#### The microdds Client +The *Client* is the PX4 Autopilot middleware daemon process that runs on the flight controller. The client can either publish or subcribe directly to data topics because the agent itself acts on behalf of the [client](https://micro-xrce-dds.docs.eprosima.com/en/stable/client.html) + +#### The microdds Agent +The *Agent* runs as a daemon process that's defined by what the clients defines it to be and hence it's dynamic. It's a server that acts an an intermediary between the client and the DDS Global Data Space. + +#### microdds Communication +microDDS has APIs that allow writing time-critical applications and can be used over many transport protocols supporting TCP,UDP over Ethernet Wi-Fi & 6LoWPAN and Bluetooth. The user can also customise this making microDDS transport-agnostic. + +## Test + +Let’s test! +You can check the microdds running using a grep command (ps aux | grep micro) + +TERMINAL 1 + +Start your favorite simulation model, we’re gonna go with the default. + +```sh +cd ~/PX4_Autopilot #Into your Autopilot folder +make px4_sitl gazebo +``` +Gazebo must open and you can check the micro-dds client running with the following command + +```sh +microdds_client status #Checks client status +``` +![Simulation](../../assets/middleware/microdds/simulation.png) + +TERMINAL 2 + +```sh +cd ~/px4_ros2_ws #Intro your ROS2 directory +source /opt/ros/humble/setup.bash +source install/setup.bash +ros2 topic list -v #Displays available topic +ros2 topic echo fmu/out/vehicle_status #You can check any available topic +``` +![ROS2 Topic](../../assets/middleware/microdds/topic.png) \ No newline at end of file diff --git a/en/middleware/micrortps.md b/en/middleware/micrortps.md index c42b9313b03c..c225f6610d2e 100644 --- a/en/middleware/micrortps.md +++ b/en/middleware/micrortps.md @@ -1,384 +1,3 @@ -# RTPS/DDS Interface: PX4-Fast RTPS(DDS) Bridge + -The *PX4-Fast RTPS(DDS) Bridge*, which is also referred to as as the *microRTPS Bridge*, adds a Real Time Publish Subscribe (RTPS) interface to the PX4 Autopilot, enabling the exchange of [uORB messages](../middleware/uorb.md) between the various PX4 Autopilot internal components and (offboard) *Fast DDS* applications in realtime. - -This allows us to better integrate with applications running and linked in DDS domains (including ROS nodes), making it easy to share sensor data, commands, and other vehicle information. - -The following guide describes the RTPS/DDS bridge architecture, and shows the reader how to write a simple *Fast DDS* application to subscribe to telemetry updates from the PX4 Autopilot. - -:::note -RTPS is the underlying protocol of the Object Management Group's (OMG) Data Distribution Service (DDS) standard. -It aims to enable scalable, real-time, dependable, high-performance and inter-operable data communication using the publish/subscribe pattern. - -*Fast DDS* is a very lightweight cross-platform implementation of the latest version of the RTPS protocol / DDS middleware. It was previously named *Fast RTPS*. -::: - -## When should RTPS be used? - -RTPS should be used when you need to reliably share time-critical/real-time information between the flight controller and offboard components. It is instrumental in cases where offboard software needs to become a *peer* of software components running in PX4 (sending and receiving uORB topics). - -Possible use cases include communicating with robotics libraries for computer vision and other use cases where real-time data to/from actuators and sensors is essential for vehicle control. - -*Fast DDS* is not intended as a replacement for MAVLink. [MAVLink](../middleware/mavlink.md) remains the most appropriate protocol for communicating with ground stations, gimbals, cameras, and other offboard components (although *Fast DDS* may open other opportunities for working with some peripherals at higher frequencies). - -:::tip -It is possible to use Fast RTPS(DDS) over slower links (e.g., radio telemetry) by being mindful of your link's extra constraints. Keep in mind you can easily overload your telemetry channel. -::: - -## Architectural overview - -### microRTPS Bridge - -The *microRTPS* bridge exchanges messages between PX4 and DDS-participant applications, seamlessly converting between the [uORB](../middleware/uorb.md) and RTPS/DDS messages used by each system. - -![basic example flow](../../assets/middleware/micrortps/architecture.png) - -The main elements of the architecture are the client and agent processes shown in the diagram above. - -#### The microRTPS Client -The *Client* is the PX4 Autopilot middleware daemon process that runs on the flight controller. This client subscribes to uORB topics published by other PX4 Autopilot components and sends any updates to the *Agent* (via a UART or UDP port), and also receives messages from the *Agent* and publishes them as uORB messages to the PX4 Autopilot. - -#### The microRTPS Agent -The *Agent* runs as a daemon process on an offboard computer (outside the flight controller). This agent watches for uORB update messages from the *Client* and (re)publishes them over RTPS, and also subscribes to "uORB" RTPS/DDS messages from other DDS-participant applications and forwards them to the *Client*. - -#### microRTPS Agent/Client Communication -The *Agent* and *Client* are connected via a serial link (UART) or UDP network, and the uORB information is [CDR serialized](https://en.wikipedia.org/wiki/Common_Data_Representation) before being sent (*CDR serialization* provides a common format for exchanging serial data between different platforms). - -The *Agent* and any *Fast DDS* applications are connected via UDP and may be on the same or another device. In a typical configuration, they will be on the same system (e.g., a development computer, Linux companion computer, or compute board), connected to the *Client*. This can be through a Wifi link or USB. - -## Code generation - -### Dependencies -Fast DDS 2.0.0 or later and Fast-RTPS-Gen 1.0.4 (not later!) must be installed in order to generate the required code, and continue to the next steps. [Follow the installation guide.](../dev_setup/fast-dds-installation.md) - -:::note -RTPS has been adopted as the middleware for the ROS 2 (Robot Operating System). - -For information about how to use this interface within the ROS 2 applications and development workflows, see [PX4-ROS 2 bridge](../ros/ros2_comm.md). -::: - -### Fast RTPS(DDS) Applications (ROS Independent) - -All the code needed to create, build and use the bridge is automatically generated when PX4-Autopilot is compiled. - -The *Client* application is also compiled and built into the firmware as part of the normal build process. -The *Agent* must be separately/manually compiled for the target computer. - -:::tip -Most users will not need to do so. Still, the bridge can be [manually generated](micrortps_manual_code_generation.md), providing a more detailed overview of the build process and useful for troubleshooting. -::: - -## Supported uORB messages - -The generated bridge code will enable a specified subset of uORB topics to be published/subscribed via RTPS, regardless if you are deploying a ROS application or not. - -For *automatic code generation* there's a *yaml* definition file in the PX4 **PX4-Autopilot/msg/tools/** directory called **uorb_rtps_message_ids.yaml**. This file defines the set of uORB messages to be used with RTPS, whether the messages are to be sent, received or both, and the RTPS ID for the message to be used in DDS/RTPS middleware. - -:::note -It's essential to note that every RTPS message **needs** an ID to be set in this file. -::: - -```yaml -rtps: - - msg: actuator_armed - id: 0 - - msg: actuator_control - id: 1 - - ... - - msg: airspeed - id: 5 - send: true - - msg: battery_status - id: 6 - send: true - - msg: camera_capture - id: 7 - - msg: camera_trigger - id: 8 - receive: true - - ... - - msg: sensor_baro - id: 63 - receive: true - send: true -``` - - -## Client (PX4/PX4-Autopilot) - -The *Client* source code is generated, compiled and built into the PX4 Autopilot firmware as part of the normal build process. - -To build the PX4 Autopilot firmware for NuttX/Pixhawk flight controllers use the `_rtps` feature in the configuration target. - -For example, to build RTPS for px4_fmu-v4: -```sh -make px4_fmu-v4_rtps -``` - -To build the firmware for a SITL target: -```sh -make px4_sitl_rtps -``` - -The *Client* application can be launched from [NuttShell/System Console](../debug/system_console.md). -The command syntax is shown below (you can specify a variable number of arguments): - -```sh -> micrortps_client start|stop|status [options] - -t [UART|UDP] Default UART - -d UART device. Default /dev/ttyACM0 - -l How many iterations will this program have. -1 for infinite. Default -1. - -w Time in ms for which each iteration sleep. Default 1ms - -b UART device baudrate. Default 460800 - -p Time in ms to poll over UART. Default 1ms - -r UDP port for receiving. Default 2019 - -s UDP port for sending. Default 2020 - -i Select IP address (remote) values: . Default: 127.0.0.1 -``` - -:::note -By default the *Client* runs as a daemon, but it does not automatically start, and must be manually launched. - -The PX4 Autopilot firmware initialization code may in future automatically start the *Client* as a permanent daemon process. -::: - -For example, in order to run the *Client* daemon with SITL connecting to the Agent via UDP: - -```sh -micrortps_client start -t UDP -``` - -## Agent in an Offboard Fast DDS interface (ROS-independent) - -The *Agent* code is automatically *generated* when you build the associated PX4 Autopilot firmware, and you can find the source here: `build//src/modules/micrortps_bridge/micrortps_client/micrortps_agent/`. - -To build the *Agent* application, compile the code: - -```sh -cd build//src/modules/micrortps_bridge/micrortps_client/micrortps_agent -mkdir build && cd build -cmake .. -make -``` - -The command syntax for the *Agent* is listed below: - -```sh -$ ./micrortps_agent [options] - -t [UART|UDP] Default UART. - -d UART device. Default /dev/ttyACM0. - -w Time in us for which each iteration sleep. Default 1ms. - -b UART device baudrate. Default 460800. - -p Time in ms to poll over UART. Default 1ms. - -r UDP port for receiving. Default 2019. - -s UDP port for sending. Default 2020. - -n Set a namespace for the micrortps_agent. -``` - -To launch the *Agent*, run `micrortps_agent` with appropriate options for specifying the connection to the *Client* (the default options connect from a Linux device to the *Client* over a UART port). - -As an example, to start the *micrortps_agent* with connection through UDP, issue: - -```sh -./micrortps_agent -t UDP -``` - -## Creating a Fast DDS Listener application - -Once the *Client* (on the flight controller) and the *Agent* (on an offboard computer) are running and connected, *Fast DDS* applications can publish and subscribe to uORB topics on the PX4 Autopilot using RTPS. - -This example shows how to create a *Fast DDS* "listener" application that subscribes to the `sensor_combined` topic and prints out updates published from the PX4 Autopilot. A connected RTPS application can run on any computer on the same network as the *Agent*. For this example the *Agent* and *Listener application* will be on the same computer. - -The *fastrtpsgen* script can be used to generate a simple RTPS application from an IDL message file. - -:::note -RTPS messages are defined in IDL files and compiled to C++ using *fastrtpsgen*. - -When building the bridge code, IDL files are generated for the uORB messages that may be sent/received, these IDL files are needed when you create a Fast DDS application to communicate with the PX4 Autopilot. - -You can find them in following path per build target: -**build/BUILDPLATFORM/src/modules/micrortps_bridge/micrortps_agent/idl/*.idl**. -::: - -Enter the following commands to create the application: - -```sh -cd /path/to/PX4/PX4-Autopilot -cd build/px4_sitl_rtps/src/modules/micrortps_bridge -mkdir micrortps_listener -cd micrortps_listener -fastrtpsgen -example x64Linux2.6gcc ../micrortps_agent/idl/sensor_combined.idl -``` - -This creates a basic subscriber and publisher, and a main-application that you can run. - -In order to print the data from the sensor combined topic, modify the following methods in **sensor_combined_Subscriber.cxx**: -- `init()`: To change the subscription topic name (by default, the micrortps agent publishes the data on the named topic: `fmu/sensor_combined/out`), -- `onNewDataMessage()`: To print the received sensor combined data. - -```cpp -bool sensor_combinedSubscriber::init(Subscriber* sub) -{ - // Create RTPSParticipant - - ParticipantAttributes PParam; - PParam.rtps.setName("Participant_subscriber"); //You can put the name you want - mp_participant = Domain::createParticipant(PParam); - if(mp_participant == nullptr) - { - return false; - } - - //Register the type - - Domain::registerType(mp_participant, static_cast(&myType)); - - // Create Subscriber - - SubscriberAttributes Rparam; - Rparam.topic.topicKind = NO_KEY; - Rparam.topic.topicDataType = myType.getName(); //Must be registered before the creation of the subscriber - Rparam.topic.topicName = "fmu/sensor_combined/out"; - mp_subscriber = Domain::createSubscriber(mp_participant,Rparam, static_cast(&m_listener)); - if(mp_subscriber == nullptr) - { - return false; - } - return true; -} -``` - -```cpp -void sensor_combinedSubscriber::SubListener::onNewDataMessage(Subscriber* sub) -{ - // Take data - sensor_combined_ st; - - if(sub->takeNextData(&st, &m_info)) - { - if(m_info.sampleKind == ALIVE) - { - // Print your structure data here. - ++n_msg; - std::cout << "\n\n\n\n\n\n\n\n\n\n"; - std::cout << "Sample received, count=" << n_msg << std::endl; - std::cout << "=============================" << std::endl; - std::cout << "gyro_rad: " << st.gyro_rad().at(0); - std::cout << ", " << st.gyro_rad().at(1); - std::cout << ", " << st.gyro_rad().at(2) << std::endl; - std::cout << "gyro_integral_dt: " << st.gyro_integral_dt() << std::endl; - std::cout << "accelerometer_timestamp_relative: " << st.accelerometer_timestamp_relative() << std::endl; - std::cout << "accelerometer_m_s2: " << st.accelerometer_m_s2().at(0); - std::cout << ", " << st.accelerometer_m_s2().at(1); - std::cout << ", " << st.accelerometer_m_s2().at(2) << std::endl; - std::cout << "accelerometer_integral_dt: " << st.accelerometer_integral_dt() << std::endl; - std::cout << "magnetometer_timestamp_relative: " << st.magnetometer_timestamp_relative() << std::endl; - std::cout << "magnetometer_ga: " << st.magnetometer_ga().at(0); - std::cout << ", " << st.magnetometer_ga().at(1); - std::cout << ", " << st.magnetometer_ga().at(2) << std::endl; - std::cout << "baro_timestamp_relative: " << st.baro_timestamp_relative() << std::endl; - std::cout << "baro_alt_meter: " << st.baro_alt_meter() << std::endl; - std::cout << "baro_temp_celcius: " << st.baro_temp_celcius() << std::endl; - - } - } -} -``` - -To build and run the application on Linux: - -```sh -make -f makefile_x64Linux2.6gcc -bin/*/sensor_combined_PublisherSubscriber subscriber -``` - -Now you should see the sensor information being printed out: - -```sh -Sample received, count=10119 -Received sensor_combined data -============================= -gyro_rad: -0.0103228, 0.0140477, 0.000319406 -gyro_integral_dt: 0.004 -accelerometer_timestamp_relative: 0 -accelerometer_m_s2: -2.82708, -6.34799, -7.41101 -accelerometer_integral_dt: 0.004 -magnetometer_timestamp_relative: -10210 -magnetometer_ga: 0.60171, 0.0405879, -0.040995 -baro_timestamp_relative: -17469 -baro_alt_meter: 368.647 -baro_temp_celcius: 43.93 -``` - -:::note -Make sure the *Client* is running, if the *Listener application* does not print anything. -::: - -## Setting up the bridge with real hardware - -This section is work-in-progress. - -## Troubleshooting - -### Client reports that selected UART port is busy - -If the selected UART port is busy, it's possible that the MAVLink application is already being used. -If both MAVLink and RTPS connections are required you will have to either move the connection to use another port or using the available protocol splitter for PX4 and companion computers. - -:::tip -A quick/temporary fix to allow bridge testing during development is to stop MAVLink from *NuttShell*: -```sh -mavlink stop-all -``` -::: - -### Agent not built/fastrtpsgen is not found - -The *Agent* code is generated using a *Fast DDS* tool called *fastrtpsgen*. - -If you haven't installed Fast DDS in the default path then you must specify its installation directory by setting the `FASTRTPSGEN_DIR` environment variable before executing *make*. - -On Linux/Mac this is done as shown below: - -```sh -export FASTRTPSGEN_DIR=/path/to/fastrtps/install/folder/bin -``` - -:::note -This should not be a problem if [Fast DDS is installed in the default location](../dev_setup/fast-dds-installation.md). -::: - -### Enable UART on a companion computer - -For UART transport on a Raspberry Pi or any other companion computer you will have to enable the serial port: - -1. Make sure the `userid` (default is pi on a Raspberry Pi) is a member of the `dialout` group: - - ```sh - groups pi - sudo usermod -a -G dialout pi - ``` -1. For the Raspberry Pi in particular, you need to stop the GPIO serial console that is using the port: - - ```sh - sudo raspi-config - ``` - - In the menu showed go to **Interfacing options > Serial**. - Select **NO** for *Would you like a login shell to be accessible over serial?*. Valid and reboot. -1. Check UART in kernel: - - ```sh - sudo vi /boot/config.txt - ``` - - And make sure that the `enable_uart` value is set to 1: - ``` - enable_uart=1 - ``` - - -## Helpful Resources - -* [Fast DDS Installation](../dev_setup/fast-dds-installation.md) -* [Manually Generate Client and Agent Code](micrortps_manual_code_generation.md) + diff --git a/en/middleware/micrortps_manual_code_generation.md b/en/middleware/micrortps_manual_code_generation.md deleted file mode 100644 index 771f90122a06..000000000000 --- a/en/middleware/micrortps_manual_code_generation.md +++ /dev/null @@ -1,187 +0,0 @@ -# Manually Generate Client and Agent Code - -This topic shows how to manually generate the code for the client and the agent (instead of [automatically generating](../middleware/micrortps.md) it when the PX4 firmware is compiled). - -The code is generated using the python script: **/Tools/generate_microRTPS_bridge.py**. - -:::note -This method should only be used for debugging purposes when creating new messages or if you just want to consume the generated code outside of the PX4 domain. Otherwise please use the *normal* method explained in [PX4-Fast RTPS(DDS) Bridge](../middleware/micrortps.md), which uses the PX4-Autopilot build system. -::: - -## Disable automatic bridge code generation - -First disable automatic generation of bridge code. Set the variable `GENERATE_RTPS_BRIDGE` to *off* in the **.cmake** file for the target platform: - -```sh -set(GENERATE_RTPS_BRIDGE off) -``` - -## Using generate_microRTPS_bridge.py - -The *generate_microRTPS_bridge* tool's command syntax is shown below: - -```sh -$ cd /path/to/PX4/PX4-Autopilot/msg/tools -$ python generate_microRTPS_bridge.py -h -usage: generate_microRTPS_bridge.py [-h] [-a] [-c] [-i] [-j IDL_DIR] [-m] [-l] - [-t MSGDIR] [-b UORB_TEMPLATES] - [-q URTPS_TEMPLATES] [-y YAML_FILE] - [-p PACKAGE] [-o AGENTDIR] [-u CLIENTDIR] - [-f [FASTRTPSGEN]] - [-g FASTRTPSGEN_INCLUDE] - [-r [ROS2_DISTRO]] [--delete-tree] - -optional arguments: - -h, --help show this help message and exit - -a, --agent Flag for generate the agent, by default is true if -c - is not specified - -c, --client Flag for generate the client, by default is true if -a - is not specified - -i, --generate-idl Flag for generate idl files for each msg - -j IDL_DIR, --idl-dir IDL_DIR - IDL files dir - -m, --mkdir-build Flag to create 'build' dir - -l, --generate-cmakelists - Flag to generate a CMakeLists.txt file for the micro- - RTPS agent - -t MSGDIR, --topic-msg-dir MSGDIR - Topics message, by default using relative path 'msg/' - -b UORB_TEMPLATES, --uorb-templates-dir UORB_TEMPLATES - uORB templates, by default using relative path to - msgdir 'templates/uorb_microcdr' - -q URTPS_TEMPLATES, --urtps-templates-dir URTPS_TEMPLATES - uRTPS templates, by default using relative path to - msgdir 'templates/urtps' - -y YAML_FILE, --rtps-ids-file YAML_FILE - RTPS msg IDs definition path, by default using - relative path to msgdir - 'tools/uorb_rtps_message_ids.yaml' - -p PACKAGE, --package PACKAGE - Msg package naming, by default px4 - -o AGENTDIR, --agent-outdir AGENTDIR - Agent output dir, by default using relative path - 'src/modules/micrortps_bridge/micrortps_agent' - -u CLIENTDIR, --client-outdir CLIENTDIR - Client output dir, by default using relative path - 'src/modules/micrortps_bridge/micrortps_client' - -f [FASTRTPSGEN], --fastrtpsgen-dir [FASTRTPSGEN] - fastrtpsgen installation dir, only needed if - fastrtpsgen is not in PATH, by default empty - -g FASTRTPSGEN_INCLUDE, --fastrtpsgen-include FASTRTPSGEN_INCLUDE - directory(ies) to add to preprocessor include paths of - fastrtpsgen, by default empty - -r [ROS2_DISTRO], --ros2-distro [ROS2_DISTRO] - ROS 2 distro, only required if generating the agent for - usage with ROS 2 nodes, by default empty - --delete-tree Delete dir tree output dir(s) -``` - -:::caution -Using with `--delete-tree` option erases the content of the `CLIENTDIR` and the `AGENTDIR` before creating new files and folders. -::: - -- The arguments `--send/-s` and `--receive/-r` specify the uORB topics that can be sent/received from PX4. Code will only be generated for specified messages. -- The output appears in `CLIENTDIR` (`-o src/modules/micrortps_bridge/micrortps_client`, by default) and in the `AGENTDIR` (`-u src/modules/micrortps_bridge/micrortps_agent`, by default). -- If no flag `-a` or `-c` is specified, both the client and the agent will be generated and installed. -- The `-f` option may be needed if *Fast DDS* was not installed in the default location (`-f /path/to/fastdds/installation/bin`). - -The example below shows how you can generate bridge code to publish/subscribe just the `sensor_baro` single uORB topic. - -```sh -$ cd /path/to/PX4/PX4-Autopilot -$ python Tools/generate_microRTPS_bridge.py -s msg/sensor_baro.msg -r msg/sensor_combined.msg -``` - -## Generated code - -Code is generated for the *Client*, *Agent*, *CDR serialization/deserialization* of uORB messages, and the definition of the associated RTPS messages (IDL files). - -Manually generated code for the bridge can be found here (by default): - -- *Client*: **src/modules/micrortps_bridge/micrortps_client/** -- *Agent*: **src/modules/micrortps_bridge/micrortps_agent/** - - -### uORB serialization code - -Serialization functions are generated for all the uORB topics as part of the normal PX4 compilation process (and also for manual generation). For example, the following functions would be generated for the *sensor_combined.msg*: - -```sh -void serialize_sensor_combined(const struct sensor_combined_s *input, char *output, uint32_t *length, struct microCDR *microCDRWriter); -void deserialize_sensor_combined(struct sensor_combined_s *output, char *input, struct microCDR *microCDRReader); -``` - -### RTPS message IDL files - -IDL files are generated from the uORB **.msg** files ([for selected uORB topics](../middleware/micrortps.md#supported-uorb-messages)) in the generation of the bridge. These can be found in: **src/modules/micrortps_bridge/micrortps_agent/idl/** - -*Fast DDS* uses IDL files to define the structure of RTPS/DDS messages (in this case, RTPS/DDS messages that map to uORB topics). They are used to generate code for the *Agent*, and *Fast DDS* applications that need to publish/subscribe to uORB topics. - -:::note -IDL files are compiled to C++ by the *fastrtpsgen* tool. -::: - -## Verify code generation - -You can verify successful code generation by checking that the output directories match the listing shown below (On Linux, the `tree` command can be used for listing the file structure). - -Agent directory: -```sh -$ tree src/modules/micrortps_bridge/micrortps_agent -src/modules/micrortps_bridge/micrortps_agent -├── build -├── CMakeLists.txt -├── idl -│   ├── sensor_baro_.idl -│   └── sensor_combined_.idl -├── microRTPS_agent.cpp -├── microRTPS_timesync.cpp -├── microRTPS_timesync.h -├── microRTPS_transport.cpp -├── microRTPS_transport.h -├── RtpsTopics.cpp -├── RtpsTopics.h -├── sensor_baro_.cpp -├── sensor_baro_.h -├── sensor_baro_Publisher.cpp -├── sensor_baro_Publisher.h -├── sensor_baro_PubSubTypes.cpp -├── sensor_baro_PubSubTypes.h -├── sensor_combined_.cpp -├── sensor_combined_.h -├── sensor_combined_PubSubTypes.cpp -├── sensor_combined_PubSubTypes.h -├── sensor_combined_Subscriber.cpp -└── sensor_combined_Subscriber.h - 2 directories, 20 files -``` - -Client directory: -```sh -$ tree src/modules/micrortps_bridge/micrortps_client -src/modules/micrortps_bridge/micrortps_client -├── CMakeLists.txt -├── microRTPS_client.cpp -├── microRTPS_client_dummy.cpp -├── microRTPS_client_main.cpp -├── microRTPS_transport.cpp -└── microRTPS_transport.h - 0 directories, 4 files -``` - -## Build and use the code - -The manually generated *Client* code is built and used in *exactly* the same way as [automatically generated Client code](../middleware/micrortps.md#client_firmware). - -Specifically, once manually generated, the *Client* source code is compiled and built into the PX4 Firmware as part of the normal build process. For example, to compile the code and include it in Firmware for NuttX/Pixhawk targets: - -```sh -make px4_fmu-v4_rtps upload -``` - -:::note -You must first [disable automatic bridge code generation](#disable-automatic-bridge-code-generation) so that the toolchain uses the manually generated source code (and does not attempt to regenerate it). -::: - -The manually generated *Agent* code is also compiled and used in the same way as the [automatically generated code](../middleware/micrortps.md#agent-in-an-offboard-fast-dds-interface-ros-independent). -The only difference is that the manually source code is created in **src/modules/micrortps_bridge/micrortps_agent** instead of build/BUILDPLATFORM**/src/modules/micrortps_bridge/micrortps_agent/**. diff --git a/en/ros/README.md b/en/ros/README.md index 3fb8c2aa055f..d5d51311823f 100644 --- a/en/ros/README.md +++ b/en/ros/README.md @@ -26,7 +26,7 @@ PX4 supports both the "original" ROS and ROS 2, with the following configuration Unveiled at the [PX4 Developer Summit 2020](https://www.youtube.com/watch?v=lZ8crGI16qA) (and [ROS World 2020](https://www.youtube.com/watch?v=8XRkzHqQSf0)), the PX4 Development team, announced the plans to support microROS. -* microRTPS: microRTPS bridge with Fast DDS (The current stable ROS 2 interface) -* micro XRCE-DDS: DDS on PX4 (Next step!) -* micro ROS: ROS 2 on the PX4 (Our Target!) +* microRTPS: microRTPS bridge with Fast DDS (The current stable ROS 2 interface) +* micro XRCE-DDS: DDS on PX4 (Next step!) +* micro ROS: ROS 2 on the PX4 (Our Target!) diff --git a/en/ros/ros1_via_ros2.md b/en/ros/ros1_via_ros2.md index 286c7f4ee16c..cec310472453 100644 --- a/en/ros/ros1_via_ros2.md +++ b/en/ros/ros1_via_ros2.md @@ -20,14 +20,14 @@ The PX4 development team recommend that all users [upgrade to ROS 2](../ros/ros2 ## Overview -The application pipeline for ROS (1) bridged over ROS 2 is shown below. +The application pipeline for ROS (1) bridged over ROS 2 is shown below. -![Architecture with ROS](../../assets/middleware/micrortps/architecture_ros.png) +![Architecture with ROS](../../assets/middleware/micrortps/architecture_ros.png) Essentially it is the same as for ROS 2, except that there is an additional [`ros1_bridge`](https://github.com/ros2/ros1_bridge) package (by Open Robotics) that translates messages between the two versions. This is needed because the original version of ROS does not support RTPS. -The other main difference is that the `px4_ros_com` and `px4_msgs` packages a separate `ros1` branch that generates the ROS message headers and source files for using **with** the `ros1_bridge`. +The other main difference is that the `px4_ros_com` and `px4_msgs` packages a separate `ros1` branch that generates the ROS message headers and source files for using **with** the `ros1_bridge`. This branch also includes example listener and advertiser nodes. @@ -100,7 +100,7 @@ To use ROS (1) **and** ROS 2 (you need both for this!): $ micrortps_agent -t UDP ``` -1. On the [NuttShell/System Console](../debug/system_console.md), start the `micrortps_client` daemon also in UDP: +1. On the [NuttShell/System Console](../debug/system_console.md), start the `micrortps_client` daemon also in UDP: ```sh > micrortps_client start -t UDP ``` diff --git a/en/ros/ros2_comm.md b/en/ros/ros2_comm.md index b14f4076d7f2..842fc4f678d5 100644 --- a/en/ros/ros2_comm.md +++ b/en/ros/ros2_comm.md @@ -11,7 +11,7 @@ For information about using the *microRTPS bridge* **without ROS 2**, see the [R ::: :::note -For a more detailed and visual explanation on how to use PX4 with ROS 2 see these presentations from the PX4 maintainers: +For a more detailed and visual explanation on how to use PX4 with ROS 2 see these presentations from the PX4 maintainers: 1. [ROS World 2020 - Getting started with ROS 2 and PX4](https://www.youtube.com/watch?v=qhLATrkA_Gw) 1. [PX4 Dev Summit 2019 - "ROS 2 Powered PX4"](https://www.youtube.com/watch?v=2Szw8Pk3Z0Q) ::: @@ -65,14 +65,9 @@ To setup ROS 2 for use with PX4 you will need to: - [Build ROS 2 Workspace](#build-ros-2-workspace) - [Sanity Check the Installation](#sanity-check-the-installation) (Optional) + ### Install ROS 2 diff --git a/en/ros/ros2_offboard_control.md b/en/ros/ros2_offboard_control.md index 86271a6e9112..254f24ab1880 100644 --- a/en/ros/ros2_offboard_control.md +++ b/en/ros/ros2_offboard_control.md @@ -6,7 +6,7 @@ If you are operating on a real vehicle be sure to have a way of gaining back man ::: :::warning -ROS 2 interaction with PX4, done through the [*microRTPS* bridge](../ros/ros2_comm.md), requires that the user understands how the PX4 internals work! +ROS 2 interaction with PX4, done through the [*microRTPS* bridge](../ros/ros2_comm.md), requires that the user understands how the PX4 internals work! The same understanding is required for PX4 offboard control via ROS 2, where the user publishes directly to the required uORB topics (without any level of abstraction between ROS and PX4 data formats/conventions). If you are unsure of PX4 internals work, we recommend that you instead use a workflow that depends on the MAVLink microservices and abstraction layer to execute offboard control or any other kind of interaction through the *microRTPS* bridge. diff --git a/en/simulation/README.md b/en/simulation/README.md index 555e6a27b631..bd2e737f21e4 100644 --- a/en/simulation/README.md +++ b/en/simulation/README.md @@ -100,7 +100,7 @@ The different parts of the system connect via UDP, and can be run on either the Simulators then exchange information with PX4 using the [Simulator MAVLink API](#simulator-mavlink-api) described above. PX4 on SITL and the simulator can run on either the same computer or different computers on the same network. :::note - Simulators can also use the *microRTPS bridge* ([PX4-FastRTPS Bridge](../middleware/micrortps.md)) to directly interact with PX4 (i.e. via [UORB topics](../middleware/uorb.md) rather than MAVLink). + Simulators can also use the *microRTPS bridge* ([PX4-FastRTPS Bridge](../middleware/micrortps.md)) to directly interact with PX4 (i.e. via [UORB topics](../middleware/uorb.md) rather than MAVLink). This approach *may* used by [Gazebo multi-vehicle simulation](../simulation/multi_vehicle_simulation_gazebo.md#build-and-test-rtps-dds). ::: * PX4 uses the normal MAVLink module to connect to ground stations and external developer APIs like MAVSDK or ROS