Gazebo Simulation
WARNING
Gazebo was previously known as "Gazebo Ignition" (while Gazebo Classic was previously known as Gazebo). See the official blog post for more information.
Gazebo is an open source robotics simulator. It supersedes the older Gazebo Classic simulator, and is the only supported version of Gazebo for Ubuntu 22.04 and onwards.
Supported Vehicles: Quadrotor, Plane, VTOL, Rover
INFO
See Simulation for general information about simulators, the simulation environment, and simulation configuration (e.g. supported vehicles).
Installation (Ubuntu Linux)
Gazebo Harmonic is installed by default on Ubuntu 22.04 as part of the normal development environment setup.
INFO
The PX4 installation scripts are based on the instructions: Binary Installation on Ubuntu (gazebosim.org).
WARNING
Gazebo Harmonic cannot be installed on Ubuntu 20.04 and earlier.
On Ubuntu 20.04 we recommend use Gazebo Classic. If you really must use Gazebo then you should update to Ubuntu 22.04.
Until November 2024 it is possible to install Gazebo Garden on Ubuntu 20.04. After that date Garden will reach end-of-life and should not be used.
Running the Simulation
Gazebo SITL simulation can be conveniently run using a make
command as shown below:
sh
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 make
commands are listed below. Note that all gazebo make targets have the prefix gz_
.
Vehicle | Command | PX4_SYS_AUTOSTART |
---|---|---|
Quadrotor(x500) | make px4_sitl gz_x500 | 4001 |
Quadrotor(x500) with Depth Camera | make px4_sitl gz_x500_depth | 4002 |
Quadrotor(x500) with Vision Odometry | make px4_sitl gz_x500_vision | 4005 |
Quadrotor(x500) with 2D LIDAR | make px4_sitl gz_x500_lidar | 4013 |
VTOL | make px4_sitl gz_standard_vtol | 4004 |
Plane | make px4_sitl gz_rc_cessna | 4003 |
Advanced Plane | make px4_sitl gz_advanced_plane | 4008 |
Differential Rover | make px4_sitl gz_r1_rover | 4009 |
Ackermann Rover | make px4_sitl gz_rover_ackermann | 4012 |
All vehicle models (and worlds) are included as a submodule from the Gazebo Models Repository repository.
WARNING
The Advanced Lift Drag Plugin that is required to run the Advanced Plane is not yet part of the Gazebo distribution, so the Advanced Plane will not yet fly: PX4-Autopilot#22337.
As a workaround to enable Advanced Plane, you can compile the gz-sim library from Gazebo source code, go into the build/lib
directory, copy out the advanced lift drag plugin .so
file (depending on the exact Gazebo Version this is called something along the lines of libgz-sim7-advanced-lift-drag-system.so
), and paste this into the ~/.gz/sim/plugins
folder.
The commands above launch a single vehicle with the full UI. QGroundControl should be able to automatically connect to the simulated vehicle.
Standalone Mode
Another way that Gazebo SITL can be connected is in standalone mode. In this mode PX4 SITL and Gazebo are started separately in their own terminals. By default these terminals are on the same host, but you can also connect SITL and Gazebo instances running on any two devices on the network (or even different networks if you use a VPN to connect them).
You start PX4 in standalone mode by prefixing the make
command with PX4_GZ_STANDALONE=1
:
sh
cd /path/to/PX4-Autopilot
PX4_GZ_STANDALONE=1 make px4_sitl gz_x500
PX4 SITL will then wait until it detects an instance of gz-server, and then connect to it.
INFO
If you have not yet started gz-server when you run the make
command, you will see the following warning until gazebo has been started and an instance of gz-server is detected by PX4:
sh
WARN [gz bridge] Service call timed out as Gazebo has not been detected
The simplest way to start the simulation is to use the Python script simulation-gazebo, which can be found in the Gazebo Models Repository repository. This can be used to launch a gz-server instance with any supported world and vehicle.
The script can be used without installing any additional dependencies, and will fetch the supported PX4 models and worlds on first use (by default) and save them to ~/.simulation-gazebo
. If called again the script will use this directory to get models and worlds. Therefore if you want to use your own model and run it in standalone mode, you will have to place its source code in ~/.simulation-gazebo
.
You can fetch the script locally using any method you like, such as wget
:
sh
wget https://raw.githubusercontent.com/PX4/PX4-gazebo-models/main/simulation-gazebo
The script can be started with:
sh
cd /path/to/script/
python3 simulation-gazebo
For more information and arguments, see Gazebo Models.
INFO
If make px4_sitl gz_x500
gives the error ninja: error: unknown target 'gz_x500'
then run make distclean
to start from a clean slate, and try running make px4_sitl gz_x500
again.
Headless Mode
You might want to run Gazebo in "headless mode" (without the Gazebo GUI) as it uses fewer resources, and does not rely on your system having a graphics card that properly supports OpenGL rendering. This makes it faster to load and run, and for many simple use cases may be all you need.
The simulation can be run in headless mode by prefixing the command with the HEADLESS=1
environment variable:
sh
HEADLESS=1 make px4_sitl gz_x500
Specify World
The simulation can be run inside a particular world by concatenating the desired world to the name of the desired vehicle. For example, to run the windy world with the x500
vehicle you can specify:
sh
make px4_sitl gz_x500_windy
You can also specify the world using the PX4_GZ_WORLD
environment variable:
sh
PX4_GZ_WORLD=windy make px4_sitl gz_x500
The supported worlds are listed below.
World | Command | Description |
---|---|---|
default | make px4_sitl * | Empty world (a grey plane) |
aruco | make px4_sitl *_aruco | Empty world with aruco marker for testing precision landing |
baylands | make px4_sitl *_baylands | Baylands world surrounded by water |
lawn | make px4_sitl *_lawn | Lawn world for testing rovers |
rover | make px4_sitl *_rover | Rover world (optimised/preferred) |
walls | make px4_sitl *_walls | Wall world for testing collision prevention |
windy | make px4_sitl *_windy | Empty world with wind enabled |
WARNING
Note that if no world is specified, PX4 will use the default
world. However you must not explicitly specify _default
on the model as this will prevent PX4 from launching. In other words, use make px4_sitl gz_x500
instead of make px4_sitl gz_x500_default
for the default.
INFO
Baylands world throws a warning in Gazebo Harmonic because there are so many meshes. This can be ignored:
sh
[Wrn] [SDFFeatures.cc:843] The geometry element of collision [collision] couldn't be created
Usage/Configuration Options
The startup pipeline allows for highly flexible configuration. In particular, it is possible to:
- Start a new simulation with an arbitrary world or attach to an already running simulation.
- Add a new vehicle to the simulation or link a new PX4 instance to an existing one.
These scenarios are managed by setting the appropriate environment variables.
Syntax
The startup syntax takes the form:
sh
ARGS ./build/px4_sitl_default/bin/px4
where ARGS
is a list of environment variables including:
PX4_SYS_AUTOSTART
(Mandatory): Sets the airframe autostart id of the PX4 airframe to start.PX4_GZ_MODEL_NAME
: Sets the name of an existing model in the gazebo simulation. If provided, the startup script tries to bind a new PX4 instance to the Gazebo resource matching exactly that name.- The setting is mutually exclusive with
PX4_SIM_MODEL
.
- The setting is mutually exclusive with
PX4_SIM_MODEL
: Sets the name of a new Gazebo model to be spawned in the simulator. If provided, the startup script looks for a model in the Gazebo resource path that matches the given variable, spawns it and binds a new PX4 instance to it.- The setting is mutually exclusive with
PX4_GZ_MODEL_NAME
.
INFO
The environmental variable
PX4_GZ_MODEL
has been deprecated and its functionality merged intoPX4_SIM_MODEL
.- The setting is mutually exclusive with
PX4_GZ_MODEL_POSE
: Sets the spawning position and orientation of the model whenPX4_SIM_MODEL
is adopted. If provided, the startup script spawns the model at a pose following the syntax"x,y,z,roll,pitch,yaw"
, where the positions are given in metres and the angles are in radians.- If omitted, the zero pose
[0,0,0,0,0,0]
is used. - If less then 6 values are provided, the missing ones are fixed to zero.
- This can only be used with
PX4_SIM_MODEL
(notPX4_GZ_MODEL_NAME
).
- If omitted, the zero pose
PX4_GZ_WORLD
: Sets the Gazebo world file for a new simulation. If it is not given, then default is used.- This variable is ignored if an existing simulation is already running.
- This value should be specified for the selected airframe but may be overridden using this argument.
PX4_SIMULATOR=GZ
: Sets the simulator, which for Gazebo must begz
.- 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
: Lets PX4 know that it should not launch an instance of Gazebo. Gazebo will need to be launched separately, as described in Standalone Mode.PX4_GZ_SIM_RENDER_ENGINE
: Sets the render engine to be used by gazebo.The default rendering engine (OGRE 2) is not well supported on some platforms/environments. Specify
PX4_GZ_SIM_RENDER_ENGINE=ogre
to set the rendering engine to OGRE 1 if you have rendering issues when running PX4 on a virtual machine.
The PX4 Gazebo worlds and and models databases can be found on Github here.
INFO
gz_env.sh.in
is compiled and made available in $PX4_DIR/build/px4_sitl_default/rootfs/gz_env.sh
Examples
Here are some examples of the different scenarios covered above.
Start simulator + default world + spawn vehicle at default pose
shPX4_SYS_AUTOSTART=4001 PX4_SIM_MODEL=gz_x500 ./build/px4_sitl_default/bin/px4
Start simulator + default world + spawn vehicle at custom pose (y=2m)
shPX4_SYS_AUTOSTART=4001 PX4_GZ_MODEL_POSE="0,2" PX4_SIM_MODEL=gz_x500 ./build/px4_sitl_default/bin/px4
Start simulator + default world + link to existing vehicle
shPX4_SYS_AUTOSTART=4001 PX4_GZ_MODEL_NAME=x500 ./build/px4_sitl_default/bin/px4
Start simulator in standalone mode + connect to Gazebo instance running default world
shPX4_GZ_STANDALONE=1 PX4_SYS_AUTOSTART=4001 PX4_SIM_MODEL=gz_x500 ./build/px4_sitl_default/bin/px4
In a separate terminal run:
shpython /path/to/simulation-gazebo
Adding New Worlds and Models
SDF files, mesh files, textures and anything else to do with the functionality and appearance in Gazebo for worlds and models can be placed in the appropriate /worlds
and /models
directories in PX4-gazebo-models.
Within PX4 follow the below steps to add models and worlds.
Adding a Model
To add a new model:
Define an airframe configuration file.
Define the default parameters for Gazebo in the airframe configuration file (this example is from x500 quadcopter):
iniPX4_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 that specific airframe.PX4_GZ_WORLD=${PX4_GZ_WORLD:=default}
sets the default world for that specific airframe.Setting the default value of
PX4_SIM_MODEL
lets you start the simulation with just:shPX4_SYS_AUTOSTART=<your new airframe id> ./build/px4_sitl_default/bin/px4
Add CMake Target for the airframe.
- If you plan to use "regular" mode, add your model SDF to
Tools/simulation/gz/models/
. - If you plan to use standalone mode, add your model SDF to
~/.simulation-gazebo/models/
You can of course also use both.
- If you plan to use "regular" mode, add your model SDF to
Adding a World
To add a new world:
Add your world to the list of worlds found in the
CMakeLists.txt
here. This is required in order to allowCMake
to generate correct targets.- If you plan to use "normal" mode, add your world sdf to
Tools/simulation/gz/worlds/
. - If you plan to use standalone mode, add your world SDF to
~/.simulation-gazebo/worlds/
- If you plan to use "normal" mode, add your world sdf to
INFO
As long as the world file and the model file are in the Gazebo search path (GZ_SIM_RESOURCE_PATH
) it is not necessary to add them to the PX4 world and model directories. However, make px4_sitl gz_<model>_<world>
won't work with them.
PX4-Gazebo Time Synchronization
Unlike the Gazebo Classic and jMAVSim simulators, PX4 and Gazebo do not implement a lockstep mechanism.
During Gazebo simulations PX4 subscribes to the Gazebo \clock
topic and uses it as clock source. This guarantees that PX4 will always wait for Gazebo before moving forward in time, even if Gazebo is running with real time factors different from 1.
Note, however, that as the lockstep is missing, Gazebo will never wait for PX4 to finish its computations. In the worst case scenario, PX4 can completely go offline and Gazebo will keep running, with obvious crashes of the simulated drone.
Multi-Vehicle Simulation
Multi-Vehicle simulation is supported on Linux hosts.
For more information see: Multi-Vehicle Simulation with Gazebo