Hello. This is Aiden from the Marketing Team.

Today, I would like to introduce setting up the PX4 development environment, specifically focusing on using the Gazebo simulator. Please note that this content is copyrighted by QUAD Drone Lab, and we kindly ask that you refrain from unauthorized distribution.

Using the Gazebo Simulator

Please proceed with the following steps in order, along with the YouTube video provided below.

Gazebo is an open-source robotics simulator. It replaces the previous Gazebo Classic simulator and is the only version of Gazebo supported on Ubuntu 22.04 and above.

Supported Vehicles: Quadrotors, Airplanes, VTOL

Installation (Ubuntu Linux)

Gazebo is installed by default on Ubuntu 22.04 as part of the development environment setup.
To use Gazebo on Ubuntu 20.04, you can install it manually after following the general setup process (Note: Installing gz-garden will remove Gazebo-Classic!).

sudo wget https://packages.osrfoundation.org/gazebo.gpg -O /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gazebo-stable.list > /dev/null
sudo apt-get update
sudo apt-get install gz-garden

sudo wget https://packages.osrfoundation.org/gazebo.gpg -O /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gazebo-stable.list > /dev/null
sudo apt-get update
sudo apt-get install gz-garden

Running the Simulation

The Gazebo SITL simulation can be conveniently executed using the make command as shown below.

cd /path/to/PX4-Autopilot
make px4_sitl gz_x500

cd /path/to/PX4-Autopilot
make px4_sitl gz_x500

This runs both the PX4 SITL instance and the Gazebo client.

The supported vehicles and commands are as follows. All Gazebo make options use the gz_ prefix.

Headless Mode

Gazebo can be run in “headless mode” (without the Gazebo GUI), which consumes fewer resources and does not rely on systems with graphics cards that properly support OpenGL rendering. This results in faster loading and execution, and may be all that is needed for many simple use cases.

You can run the simulation in headless mode by prefixing the command with the HEADLESS=1 environment variable.

HEADLESS=1 make px4_sitl gz_x500

HEADLESS=1 make px4_sitl gz_x500

World Specification

You can run a simulation within a specific world by connecting the desired world to the name of the desired vehicle.

make px4_sitl gz_x500_windy

make px4_sitl gz_x500_windy

You can also specify the world using the PX4_GZ_WORLD environment variable.

PX4_GZ_WORLD=windy make px4_sitl gz_x500

PX4_GZ_WORLD=windy make px4_sitl gz_x500

The following worlds are supported:

Usage/Configuration Options

The startup pipeline allows for highly flexible configuration. In particular, it enables:

• Start a new simulation in an arbitrary world or connect to a simulation that is already running.
• Add a new vehicle to the simulation or connect a new PX4 instance to an existing vehicle.

These scenarios are managed by setting the appropriate environment variables.

Syntax

The startup syntax takes the following form:

ARGS ./build/px4_sitl_default/bin/px4

ARGS ./build/px4_sitl_default/bin/px4

Where can I find the list of environment variables, including ARGS?

• PX4_SYS_AUTOSTART (Required): Sets the airframe autostart ID for the PX4 vehicle to be started.
• PX4_GZ_MODEL_NAME: Sets the name of a model already existing in the Gazebo simulation. If provided, the startup script will attempt to bind the new PX4 instance to a Gazebo resource exactly matching that name.
• This setting is mutually exclusive with PX4_SIM_MODEL.
• PX4_SIM_MODEL: Sets the name of a new Gazebo model to be spawned in the simulator. If provided, the startup script will look for a model matching the given variable in the Gazebo resource path, spawn it, and bind the new PX4 instance.
• This setting is mutually exclusive with PX4_GZ_MODEL_NAME.
• PX4_GZ_MODEL_POSE: Sets the spawn position and orientation of the model. If provided, the startup script will spawn the model at a pose following the syntax “x,y,z,roll,pitch,yaw”, where positions are in meters and angles are in radians.
• If omitted, a zero pose [0,0,0,0,0,0] is used.
• If fewer than six values are provided, the missing values are fixed at 0.
• This can only be used with PX4_SIM_MODEL (not PX4_GZ_MODEL_NAME).
• PX4_GZ_WORLD: Sets the Gazebo world file for a new simulation.
• If an existing simulation is already running, this variable is ignored.
• This value should be specified for the selected airframe but can be overridden using this argument.
• PX4_SIMULATOR=GZ: Sets the simulator to Gazebo.
• This value should be set for the selected airframe, in which case it does not need to be set as an argument.
• PX4_GZ_STANDALONE: Indicates that PX4 should not start a Gazebo instance. Gazebo must be run separately as described in standalone mode.

The PX4 Gazebo world and model database can be found here on GitHub.

Examples:

Here are some examples of the various scenarios covered above:

1. Start simulator + Default world + Spawn vehicle at default pose

   PX4_SYS_AUTOSTART=4001 PX4_SIM_MODEL=gz_x500 ./build/px4_sitl_default/bin/px4

   PX4_SYS_AUTOSTART=4001 PX4_SIM_MODEL=gz_x500 ./build/px4_sitl_default/bin/px4

2. Start simulator + Default world + Spawn vehicle at custom pose (y=2m)

   PX4_SYS_AUTOSTART=4001 PX4_GZ_MODEL_POSE="0,2" PX4_SIM_MODEL=gz_x500 ./build/px4_sitl_default/bin/px4

   PX4_SYS_AUTOSTART=4001 PX4_GZ_MODEL_POSE="0,2" PX4_SIM_MODEL=gz_x500 ./build/px4_sitl_default/bin/px4

3. Start simulator + Default world + Connect to an existing vehicle

   PX4_SYS_AUTOSTART=4001 PX4_GZ_MODEL_NAME=x500 ./build/px4_sitl_default/bin/px4

   PX4_SYS_AUTOSTART=4001 PX4_GZ_MODEL_NAME=x500 ./build/px4_sitl_default/bin/px4

4. Start simulator in standalone mode + Connect to a Gazebo instance running the default world

   PX4_GZ_STANDALONE=1 PX4_SYS_AUTOSTART=4001 PX4_SIM_MODEL=gz_x500 ./build/px4_sitl_default/bin/px4

   PX4_GZ_STANDALONE=1 PX4_SYS_AUTOSTART=4001 PX4_SIM_MODEL=gz_x500 ./build/px4_sitl_default/bin/px4

Run the following in a separate terminal:

   python /path/to/simulation-gazebo

   python /path/to/simulation-gazebo

Adding New Worlds and Models

You can place SDF files, mesh files, textures, and everything related to the functionality and appearance of Gazebo worlds and models into the corresponding /models or /worlds directories within PX4-gazebo-models.

To add models and worlds within PX4, follow the steps below.

Adding a Model

To add a new model:

1. Define the airframe configuration file.
2. Define the default parameters for Gazebo in the airframe configuration file.

   PX4_SIMULATOR=${PX4_SIMULATOR:=gz}
   PX4_GZ_WORLD=${PX4_GZ_WORLD:=default}
   PX4_SIM_MODEL=${PX4_SIM_MODEL:=<your model name>}

   PX4_SIMULATOR=${PX4_SIMULATOR:=gz}
   PX4_GZ_WORLD=${PX4_GZ_WORLD:=default}
   PX4_SIM_MODEL=${PX4_SIM_MODEL:=<your model name>}

• PX4_SIMULATOR=${PX4_SIMULATOR:=gz}: Sets the default simulator(Gz) for a specific airframe.
• PX4_GZ_WORLD=${PX4_GZ_WORLD:=default}: Sets the default world.
• By setting these default values, you can start the simulation using only the airframe ID as follows: PX4_SYS_AUTOSTART=<your new airframe id> ./build/px4_sitl_default/bin/px4

1. Add the CMake Target for the Airframe

• If you want to use “General” mode, add the model SDF to: Tools/simulation/gz/models/
• If you want to use “Standalone” mode, add the model SDF to: ~/.simulation-gazebo/models/
• Of course, you can use both locations.

PX4-Gazebo Time Synchronization

Unlike the Gazebo Classic and jMAVSim simulators, PX4 and Gazebo (New/Harmonic/Garden) do not implement a lock-step mechanism.

During a Gazebo simulation, PX4 subscribes to the Gazebo /clock topic and uses it as its primary clock source. This ensures that PX4 always waits for Gazebo to advance time, even if Gazebo is running at a different real-time factor (RTF).
However, because there is no lock-step synchronization: This can lead to the simulated drone crashing or behaving erratically while the simulation environment remains active. Gazebo does not wait for PX4 to finish its internal calculations. In the worst-case scenario, if PX4 hangs or becomes completely offline, Gazebo will continue to run the physics engine.

Multi-Vehicle Simulation

Multi-vehicle simulation is supported on Linux hosts.

For more detailed information, please refer to the Multi-Vehicle Simulation with Gazebo documentation.

That concludes our look at how to use the Gazebo simulator, the final step in configuring the PX4 development environment. In the next post, I will return with a guide on PX4 development environment training. Thank you all for your hard work throughout this process!

Author: Aiden, Marketing Team at QUAD Drone Lab

Date: February 21, 2026