XTDrone UAV Simulation Platform Setup Tutorial

Preface#

XTDrone is a general-purpose UAV simulation platform jointly built on PX4, ROS, and Gazebo. It allows us to run complex single-UAV or multi-UAV flight simulations in the Gazebo physics environment, and uses MAVROS to seamlessly connect the underlying PX4 Software-In-The-Loop (SITL) flight-control logic with the higher-level ROS ecosystem. With this complete technical chain, developers can implement path planning, flight control, multi-sensor perception, and even validate complex visual SLAM algorithms at the upper level, without bearing the crash risk and high cost of real-world test flights.

Because it couples multiple underlying frameworks, the biggest challenge in setting up this simulation environment is often not compiling/installing a particular piece of software, but clarifying the version-dependency combinations across the system. For example: the Ubuntu version, the ROS distribution, the Gazebo version, the stable release of PX4 source, MAVROS compatibility, and conflicts between OpenCV and cv_bridge when integrating vision algorithms. If versions are mismatched, it is easy to fall into an endless dependency hell. Therefore, this post is written from my own hands-on experience as a reproducible, pitfall-reducing tutorial.

Environment Preparation and System Configuration#

Stable operation of the simulation platform depends heavily on the underlying environment. For developers deploying via virtual machines such as VMware, resolving three basic issues first (network connectivity, input method configuration, and disk capacity) can greatly improve the efficiency of subsequent setup. If you are on dual-boot or a native Linux install, you can skip this step. Network stability directly determines whether open-source dependencies can be downloaded smoothly via APT and GitHub. Since later steps involve pulling large Gazebo model libraries and the full PX4 source repository, as well as generating a large amount of C++ build artifacts, increasing the VM disk capacity appropriately (recommend allocating 60GB or more as dynamic space) can effectively avoid build failures or system crashes caused by insufficient disk space.

Reference Index#

Below are some resources you may need, as well as solutions and illustrated tutorials for issues you may encounter.

• XTDrone project (Gitee search): Search XTDrone on Gitee ↗
• XTDrone basic configuration docs (Yuque search): Search on Yuque: simulation platform basic config PX4 1.13 XTDrone ↗
• VMware Ubuntu networking (Zhihu search): Search VMware Ubuntu networking on Zhihu ↗
• Ubuntu Chinese input method (Zhihu search): Search Ubuntu 20.04 Chinese input method on Zhihu ↗
• VMware Ubuntu disk expansion (Jianshu search): Search VMware Ubuntu 20.04 disk expansion on Jianshu ↗

Install the Core Software Infrastructure#

In essence, setting up XTDrone is building a bottom-up data and control pipeline. In this pipeline, the basic toolchain is the foundation, ROS provides the middleware layer for inter-component communication, and subsequent independent simulation nodes depend on the entire software/hardware stack. This section covers the core installation steps for the whole tech stack.

Build Dependencies and ROS Noetic Deployment#

The prerequisite for any build work is a complete C++ and Python development toolkit. First, install a bundle of basic dependencies including build-essential, cmake, and ninja-build, and also tools like git, wget, and python3-pip for code fetching and package management. After the base toolchain is in place, you can proceed to installing ROS Noetic.

sudo apt update
sudo apt install -y \
	build-essential cmake ninja-build \
	git curl wget unzip \
	python3-pip python3-venv \
	pkg-config \
	software-properties-common \
	lsb-release

ROS Noetic is the official recommended ROS version for Ubuntu 20.04 and the last long-term supported release in the ROS 1 ecosystem. During configuration, you need to add the official packages.ros.org repository to the system sources.list, and import a trusted key via apt-key, so that you can install the full desktop variant ros-noetic-desktop-full. The full version includes common communication libraries and also integrates visualization tools needed by foundational simulation environments. Also remember to append the corresponding setup.bash sourcing command to the user’s ~/.bashrc initialization script.

sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
sudo apt-key adv --keyserver 'hkp://keyserver.ubuntu.com:80' --recv-key C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654
sudo apt update
sudo apt install -y ros-noetic-desktop-full
echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc
source ~/.bashrc

Use the command below to verify that ROS is installed successfully:

roscore

After creating a ROS workspace named catkin_ws, run catkin_make for the first build. This workspace will later host all your control-algorithm packages and cloned custom dependencies. If you have not created a workspace before, you can create one with the commands below; it will also serve as an isolated area for your later projects.

mkdir -p ~/catkin_ws/src
cd ~/catkin_ws
catkin_make
echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc
source ~/.bashrc

Gazebo Simulation Node, ROS Bridging, and MAVROS#

Some ROS installations may include an older or custom Gazebo version by default. To avoid compatibility issues, it is more recommended to remove unneeded versions and install Gazebo 9 specifically, which has been widely verified as a robust combination with ROS Noetic. To synchronize physics feedback from Gazebo into the ROS network, you must install a series of gazebo_ros_pkgs plugins and additional dependencies such as moveit-msgs, octomap-msgs, and controller interface libraries.

sudo apt-get install -y \
	ros-noetic-moveit-msgs \
	ros-noetic-object-recognition-msgs \
	ros-noetic-octomap-msgs \
	ros-noetic-camera-info-manager \
	ros-noetic-control-toolbox \
	ros-noetic-polled-camera \
	ros-noetic-controller-manager \
	ros-noetic-transmission-interface \
	ros-noetic-joint-limits-interface

Next, configure MAVROS. You can think of it as an important bridge that lets the ROS topic ecosystem interface directly with the MAVLink protocol used by various hardware flight controllers. Since UAV simulation involves a lot of geo-spatial computation, while installing the MAVROS package via APT, be sure to also run the included geographic dataset download script. This script can take a long time and often fails due to network issues; rerun it until it completes downloading the global coordinate compensation datasets.

sudo apt-get install -y ros-noetic-mavros
cd /opt/ros/noetic/lib/mavros
sudo ./install_geographiclib_datasets.sh

PX4 SITL and XTDrone Source Build#

After configuring external support libraries, the next step is to handle the PX4 core firmware and the XTDrone distribution source. Here we use PX4 based on version 1.13 (or a higher compatible version) as the main control-strategy provider. Setting up SITL (Software In The Loop) essentially means running, in a virtual environment via internal network addresses, the embedded code that would otherwise be flashed onto the flight controller chip.

After the XTDrone repository is cloned into the established workspace, you often need to clean old intermediate caches and rerun specific build commands to generate the required PX4 platform packages and properly set up control topics and multi-UAV coordination scripts. By running the corresponding build scripts, you can ultimately drive the virtual UAV in Gazebo to take off and execute predefined 3D motions using keyboard commands in the terminal.

./build.sh
./build_ros.sh

If you try to connect via QGroundControl (QGC), a common issue is that offline maps fail to load. This is usually because QGC’s built-in map source is blocked under certain networks; you can resolve it by switching to another map source or adjusting your network/proxy settings.

Visual SLAM (ORB-SLAM2) Integration#

Getting the UAV to take off and accept keyboard control is not the final goal of simulation. Many research and industrial applications need to mount a virtual camera on the UAV and run SLAM algorithms such as the classic ORB-SLAM2. To integrate such algorithms, you typically need to introduce three crucial external dependencies: Eigen (for feature/matrix computation), Pangolin (for UI rendering and interaction), and OpenCV (the foundational building blocks for computer-vision computation).

OpenCV and cv_bridge Version Conflicts#

When integrating vision-processing nodes, the most common and devastating engineering disaster is OpenCV version conflicts. When installing ROS Noetic, the precompiled dependency chain pulled from official repositories often includes a default OpenCV (e.g., 4.2.x), and cv_bridge is built against it to connect ROS image messages. However, many independent projects like ORB-SLAM2 often strictly pin an older OpenCV such as 3.2.0 in their CMake configurations. This divergence causes many missing-symbol errors at final linking or runtime, because the system cannot decide whether to link against the system’s 4.2 libraries or the manually compiled 3.2 source libraries.

There are multiple ways to fully resolve this: Some developers prefer to unify OpenCV include conventions at the very front of the workspace, download OpenCV source (4.2 or the required version) and rebuild/replace the cv_bridge package that came with ROS APT installation. If you want a quick reproduction and to “stop the bleeding” to get a working build, a temporary but commonly used approach is to directly overwrite the ROS system path /opt/ros/noetic/share/ with the cv_bridge library you just compiled under the high-privilege system directory /usr/local/share/. This is rough and not friendly for cross-platform migration, but it can be surprisingly effective for emergency validation of the pipeline where the UAV camera frames are passed to downstream modules like object detection and tracking.

# Emergency workaround, use with caution in production environments
sudo cp -rf /usr/local/share/cv_bridge /opt/ros/noetic/share/

Core Methodology for Tracing Build Errors#

If compilation keeps failing at this stage, the underlying logic can usually be reduced to two categories: (1) missing headers and macros, which requires patiently tracing the C++ compiler error logs and installing the missing upstream dependency packages; and (2) mismatched linked libraries. The key tool for investigating the latter is the ldd command. It helps inspect the actual dependency paths of generated shared libraries or executables. Once you find that the loaded paths do not match expectations, or multiple references lead to ABI crashes, you should decisively intervene and adjust the CMake find-order priorities.

Closing#

After a large and complex development lifecycle covering environment setup, loading low-level dependencies, wiring ROS middleware, and finally integrating high-level algorithms, successfully lighting up an XTDrone UAV in Gazebo is an extremely memorable full-stack industrial simulation experience. I hope this long technical post, based on real deployment pitfalls and fixes, can serve as a clear reference path and greatly reduce confusion and wasted effort for beginners attempting to build a collaborative flight simulation system for the first time.