Aurora: Automated ROS2 Integration and Reliability Assessment Testbed Framework for PX4 UAVs

This is a project for automatically testing PX4 software stack using ROS2. The project contains autotest_px4_ros2 package with a ROS2 action server and ROS2 action client. The ROS2 action server can execute variety of micro/macroactions by sending commands to the drone (with PX4) using the offboard mode over XRCE-DDS. The action client is capable of requesting these actions to the action server. The client reads this set of test actions from a json file and then sends the action requests to action server sequencially while tracking the progress of each test action.

Architecture of the Aurora Testbed

The ROS2 action server can execute the following test actions using the offboard control mode:

• set_offboard_mode (Initiates the offboard mode and starts sending offboard mode command to the vehicle)
• arm (Arms the vehicle)
• disarm (Disarms the vehicle)
• takeoff (Takes off to a specified altitude at the current location)
• land (Lands at a current location)
• hover (Hover at a given position)
• return_to_home (Returns to home location and lands)
• track_traj (Tracks a given trajectory or a set of waypoints with specified wait times)

The ROS2 test server supports following base classes that support importing plugins for testing controllers and tarjectory planning algorithms.

• BaseTrajectoryPlanner

  Click to expand/collapse details

  The BaseTrajectoryPlanner class allows importing trajectory planner classes derived from this base class to be directly used inside the ros2 test server to support testing various trajectory planner algorithms. The plugin class should be derived from BaseTrajectoryPlanner and should define the following method for the plugin to be properly loaded.

  - CustomTrajectoryPlanner::getTrajectory(int num_sample_points, double sampling_time, tester_msgs::msg::Trajectory& traj)
  

• BaseController

  Click to expand/collapse details

  The BaseController class allows importing low level trakcing controllers classes derived from this base class to be directly used inside the ros2 test server to support testing various low level controller algorithms. The plugin class should be derived from BaseController and should define the following method for the plugin to be properly loaded.

  CustomController::calculateForcesAndMoments(px4_msgs::msg::TrajectorySetpoint& des_state)
  
  CustomController::calculateActuatorCommands(px4_msgs::msg::TrajectorySetpoint& des_state)
  

The ROS2 test server also supports subscribing to ROS2 topics for providing input trajectory or tracking controller or any ROS2 node.

• ROS Topic

Directory structure

src/
┣ autotest_px4_ros2/
┣ controller/
┣ px4_msgs/
┣ ros2_tests/
┣ tester_msgs/
┣ trajectory_planner/
┣ trajectory_publisher/
┣ user_interface/
┣ utils/

NOTE: This project is currently tested on Ubuntu 22.04.03 LTS, with ROS2=humble and GAZEBO HARMONIC and GAZEBO CLASSIC Simulators.

Docker Container Setup

Docker Container

1. Clone the workspace in ws_aurora directory.

   git clone git@github.com:tiiuae/Aurora.git ws_aurora
   

   This command clones the workspace in ws_aurora directory. The same directory name is also used inside the container as well.

2. Directly clone a prebuilt docker image

   docker pull ghcr.io/tiiuae/aurora:gz-harmonic
   

   This downloads a prebuilt docker image that supports gazebo-harmonic simulator.

   For gazebo-classic simulator, run

   docker pull ghcr.io/tiiuae/aurora:gz-classic
   

   OR

3. Build image locally

   ./build_docker_image.sh
   

   This script builds a docker image ghcr.io/tiiuae/aurora:gz-harmonic that supports gazebo-harmonic simulator.

   For gazebo-classic simulator, either set SIMULATOR env variable in the .env file in the root of the workspace or run the build script with --simulator gz-classic flag.

   ./build_docker_image.sh --simulator gz-classic
   

   Click to see the details about the supported additional input arguments

   Argument	Type	Default	Description
   --image	string	ghcr.io/tiiuae/aurora	Name of the Docker image to build.
   --tag	string	Same as --simulator	Docker image tag to apply. If not set explicitly, defaults to simulator name.
   --simulator	string	gz-harmonic	Simulator type. Used to resolve the appropriate Dockerfile.
   --no-cache	flag	false	If set, builds the Docker image without using the cache.
   --context	string	.	Build context directory (passed to docker build).

Setup Instructions

1. Run the docker container

   ./run_docker_container.sh
   

   This script runs the docker container using docker-compose.yml file and opens a bash terminal in the root of the workspace /ws_aurora. You can edit this docker-compose.yml file for any configuration changes.

2. Adjust ENV variables in the .env file of the root of the workspace Make sure you're in the root of the workspace (e.g., ws_aurora), then open the .env file:

   nano .env

   📄 Example .env File

   PX4_PATH=/ws_aurora/px4
   PX4_VERSION=v1.15.4
   SIMULATOR=gz-harmonic
   ENABLE_GPU=false
   #HITL only
   PX4_IP=192.168.0.3
   PX4_PORT=14543
   HOST_IP=192.168.0.50
   HOST_PORT=14542
   

   Click to see the details about the env variables

   Variable	Type	Description
   PX4_PATH	str	Absolute path to the PX4 source directory inside the container.
   PX4_VERSION	str	PX4 firmware version to use (e.g., a tag like v1.15.4 or a branch like main).
   SIMULATOR	str	Simulator backend to use. Supported values:
   		• gz-harmonic – Ignition Gazebo (Harmonic version)
   		• gz-classic – Gazebo Classic (v11, legacy version)
   ENABLE_GPU	str	Enable GPU usage when running the Docker container
   PX4_IP	str	IP address of the PX4 instance
   PX4_PORT	str	UDP port opened by the MAVLink instance on PX4
   HOST_IP	str	IP address of the host system
   HOST_PORT	str	UDP port on the host system allowed to connect to PX4

3. Clone and Build PX4

   ./setup_and_build_px4.sh
   

   This command clones the px4 repo at the path specified by PX4_PATH env variable and checkouts the version specified by PX4_VERSION env variable and then builds the px4_sitl for the simulator given by SIMULATOR env variable.

   If you want to overwrite the simulator in .env file and specify from terminal, then run:

   ./setup_and_build_px4.sh --simulator gz-classic
   

4. Build the workspace

   ./build_workspace.sh
   

   Make the script executable if not already by running chmod +x build_workspace.sh.

   For the first time you will need to copy the px4-msgs from the px4 repo for proper building of the workspace. Run the build script with --copy-px4-msgs flag.

   ./build_workspace.sh --copy-px4-msgs
   

5. Create python virtual environment

   ./create_venv.sh
   

   Make the script executable if not already by running chmod +x create_venv.sh

   To avoid any linking issues, it is better to run this script with --recreate that forces recreation of the virtual envrionment.

   ./create_venv.sh --recreate
   

6. (Optional) Patch PX4 source to support HITL Run the following command:

   python3 tools/patch_px4.py
   

Running automatic testing framework

Run tests using the user interface

1. Launch the UI by running the following command in the root of the workspace

   cd autotest_px4_ros
   ./run_ui.sh
   

   Make the script executable if not already by running chmod +x run_ui.sh

2. You will need to first generate a config file for filtering tests and this will show you list of tests available for running.

OR

Run tests using terminal

1. Run automated tests by running the following command in the root of the workspace

   ./run_ros2_tests.sh --config ./config/sitl.json --gui
   

   This runs all the tests specified by the configuration in the src/ros_test2/config/sitl.json file.

   To run tests with the HITL configuration, provide the appropriate config file:

   ./run_ros2_tests.sh --config ./config/hitl_gazebo_classic.json --gui
   

   To run a single test

   ./run_ros2_tests.sh --config ./config/sitl.json --case "test case name" --gui
   

   Click to see the details about supported command line arguments

   Argument	Type	Default	Description
   --config	str	./config/sitl.json	Path to the test configuration JSON file.
   --skip-dirs	str	""	Comma-separated directories to skip.
   --test	str	""	Specific test case name to run.
   --log-dir	str	log	Directory to save log files.
   --speed-factor	float	1	Simulation speed multiplier (e.g. 0.5 for half speed).
   --iterations	int	1	Number of test repetitions.
   --abort-early	flag	false	If set, aborts on the first failed test.
   --gui	flag	false	If set, enables simulation GUI.
   --model	str	all	PX4 model to test (e.g., iris, x500, or all).
   --case	str	all	Case name to filter (used when --test is not set).
   --run-test-client-separate	flag	false	Run test client in a separate process.
   --use-ros2-launch	flag	false	Use ros2 launch instead of direct script.
   --debugger	str	""	Debugger command prefix (e.g., gdb --args).
   --upload	flag	false	If set, uploads results after test execution.
   --verbose	flag	false	Enables verbose output in the test runner.
   --verbose-action-server	flag	false	Enables verbose logs for the action server.
   --px4-dir	str	$PX4_PATH from .env	Path to the PX4 firmware directory.
   --px4-build-dir	str	build/px4_sitl_default/	Path to PX4 build output directory.
   --tests-build-dir	str	build/	Path to build directory for test binaries.
   --gz-models-dir	str	None	Path to Gazebo models directory.
   --gz-worlds-dir	str	None	Path to Gazebo worlds directory.

Local Setup

Prerequisites

Click to see the details about prerequisites

Please make sure the following things are setup before running the ROS2 tests in SITL using this package. Refer to the Dockerfiles in docker directory for more details.

1. Gazebo Harmonic or Gazebo Classic

   If not installed already, follow Install Gazebo Harmonic or Install Gazebo Classic

2. PX4-autopilot

   cd
   git clone https://github.com/PX4/PX4-Autopilot.git --recursive
   bash ./PX4-Autopilot/Tools/setup/ubuntu.sh
   cd PX4-Autopilot/
   make px4_sitl
   

   Detailed instructions found at: Install PX4

3. ROS2 (humble in this case)

   sudo apt update && sudo apt install locales
   sudo locale-gen en_US en_US.UTF-8
   sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
   export LANG=en_US.UTF-8
   sudo apt install software-properties-common
   sudo add-apt-repository universe
   sudo apt update && sudo apt install curl -y
   sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
   echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
   sudo apt update && sudo apt upgrade -y
   sudo apt install ros-humble-desktop
   sudo apt install ros-dev-tools
   source /opt/ros/humble/setup.bash && echo "source /opt/ros/humble/setup.bash" >> .bashrc
   

   The instructions above are reproduced from the official installation guide: Install ROS 2 Humble.

   Some Python dependencies must also be installed (using pip or apt):

   pip install --user -U empy==3.3.4 pyros-genmsg setuptools
   

   Required ROS2 packages and dependencies

   sudo apt-get update && apt-get install -y --no-install-recommends \
   python3-pip \
    python3-colcon-common-extensions \
    python3-rosdep \
    python3-vcstool \
    ros-humble-ros-base \
    ros-humble-rclcpp \
    python3-ament-package \
    ros-humble-ament-cmake \
    ros-humble-rosidl-default-generators \
    ros-humble-rosidl-default-runtime \
    ros-humble-rosidl-typesupport-cpp \
    ros-humble-rosidl-typesupport-c \
    ros-humble-rosidl-typesupport-interface \
    ros-humble-std-msgs \
    ros-humble-sensor-msgs \
    ros-humble-angles \
    ros-humble-rclpy \
    ros-humble-rclcpp-action \
    ros-humble-rclcpp-components \
    ros-humble-std-srvs \
    ros-humble-nav-msgs \
    ros-humble-geometry-msgs \
    ros-humble-trajectory-msgs \
    ros-humble-tf2-ros \
    ros-humble-tf2-geometry-msgs \
    ros-humble-tf2-eigen \
    ros-humble-builtin-interfaces \
    ros-humble-pluginlib \
   

4. MicroXRCE-DDS agent

   git clone https://github.com/eProsima/Micro-XRCE-DDS-Agent.git
   cd Micro-XRCE-DDS-Agent
   mkdir build
   cd build
   cmake ..
   make
   sudo make install
   sudo ldconfig /usr/local/lib/
   

5. nlohmann-json (if not installed already)

   sudo apt install nlohmann-json3-dev
   

6. catch_ros2 (package to use catch2 framework efficiently with ROS2 nodes) To install Debian packages of catch_ros2 simply run the following command (assuming your environment is properly set up for installing Debian packages):

   apt install ros-${ROS_DISTRO}-catch-ros2
   

   If required follow the installation instructions at https://github.com/ngmor/catch_ros2

7. (Optional) Install Catch2 (Install this separately only if catch_ros2 installed previously does not work)

   git clone https://github.com/catchorg/Catch2.git
   cd Catch2
   cmake -B build -S . -DBUILD_TESTING=OFF
   sudo cmake --build build/ --target install
   

   These instructions can be found at https://github.com/catchorg/Catch2/blob/devel/docs/cmake-integration.md#installing-catch2-from-git-repository

   Ideally, just including catch2 using the header file "catch2/catch.hpp" should be sufficient to be able to use catch2 in this package but if you ran into issues with linking the catch2 with the package then try building catch with cmake -B build -S . -DBUILD_TESTING=OFF -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DCMAKE_CXX_STANDARD=17 and explicitly link it with the package in CMakeLists.txt file.

8. Python3

   Ideally, the Ubuntu 22.04 should have python3 already installed. But, if for some reason it is not installed, then you can follow:

   https://docs.python.org/3.11/using/unix.html#getting-and-installing-the-latest-version-of-python

9. Code-generator python package

   python3 -m pip install code-generation==2.3.0
   

   This package is used to create test_cases.cpp files automatically.

10. (Optional) MAVSDK v1.3.1 from Source

1. Navigate to the desired installation directory (e.g., /opt):

   cd /opt

2. Clone the MAVSDK repository with all submodules:

   git clone --recurse-submodules https://github.com/mavlink/MAVSDK.git
   

3. Navigate into the MAVSDK directory and check out version v1.3.1:

   cd MAVSDK
   git checkout v1.3.1
   git submodule update --init --recursive
   

4. Create a build directory and configure the build using CMake:

   mkdir build
   cd build
   cmake .. -DCMAKE_BUILD_TYPE=Release
   

5. Compile and install MAVSDK:

   make -j$(nproc)
   sudo make install
   

6. (Optional) Clean up source directory: After installation, you can remove the source to save space:

   cd /
   sudo rm -rf /opt/MAVSDK
   

Setup Instructions

For setup instructions refer to setup instructions as in the Docker Container Setup

Run Tests

For running tests refer to the run instructions in the Docker Container Setup