Skip to content

About

A ready-to-use Ultra-Wideband simulator for relative localization of multi-robot teams integrated with ROS 2, Gazebo Harmonic and PX4 SITL.

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

UWBPX4Sim

📌 This work has been presented at the 1st Workshop on Robot Meets GNSS and Ranging for Seamless Autonomy during ICRA 2026!

📌 This work has been featured in the ROSCon Spain 2026 official program!

A ready-to-use Ultra-Wideband simulator for relative localization of multi-robot teams integrated with ROS 2, Gazebo Harmonic and PX4 SITL. This is a standalone repo that is complementary to the work Radio-based Multi-Robot Odometry and Relative Localization, containing all simulation-based tools used in the main work.

Features

  • UWB measurement plugin for Gazebo: two-way ranging (TWR) or time difference of arrival (TDOA), with noise, dropout and bias driven by distance and by the obstacles in the way, including their material. See Measurement model.
  • Calibrated presets, one per system and mode: eliko_twr (Eliko, TWR), lps_tdoa (Bitcraze Loco Positioning, TDOA) and lps_twr (Bitcraze Loco Positioning, TWR). Tune one and save your own from the setup GUI.
  • Multi-robot layouts from one YAML file: UAVs and UGVs carrying any mix of tags and anchors, plus anchors fixed in the world. Vehicle models and the ROS 2 bridge are generated from it.
  • Guided setup with a browser GUI, a one-command launcher, and RViz showing the robots, transceivers and live UWB links for any layout.
  • ROS 2 offboard nodes that fly the UAVs and drive the UGVs along CSV trajectories.

Calibration datasets

Each preset is calibrated from a real UWB dataset (details and validation in Measurement model: Calibration):

Preset Dataset UWB system Mode Conditions
eliko_twr Eliko identification [1] Eliko KIO RTLS TWR LOS
lps_tdoa UTIL identification dataset [2] Bitcraze Loco Positioning (DWM1000) TDOA LOS and NLOS
lps_twr Pfeiffer et al. UWB dataset [3] Bitcraze Loco Positioning (DWM1000) TWR LOS

Pfeiffer et al.'s TDoA flights [3] were also used to test the Loco Positioning TDOA preset on a second installation.

  1. A. Martínez-Silva, D. Alejo, L. Merino, F. Caballero, "Radio-based Multi-Robot Odometry and Relative Localization", IEEE ICRA, 2026, pp. 17557–17564. Paper, preprint, data.
  2. W. Zhao, A. Goudar, X. Qiao, A. P. Schoellig, "UTIL: An Ultra-wideband Time-difference-of-arrival Indoor Localization Dataset", IJRR, 2024. Paper, data.
  3. S. Pfeiffer, C. de Wagter, G. C. H. E. de Croon, "A Computationally Efficient Moving Horizon Estimator for Ultra-Wideband Localization on Small Quadrotors", IEEE RA-L, 2021. Paper, data.

Getting started

A docker/ folder is provided with a ready-to-use image (Ubuntu 24.04, ROS 2 Jazzy, Gazebo Harmonic, PX4, and this repo's plugin/bridge pre-built) as an alternative to setting everything up natively. It requires Docker and the Docker Compose plugin.

cd <ros_ws>/src
git clone --recurse-submodules https://github.com/amartinezsilva/UWBPX4Sim.git
cd UWBPX4Sim/docker
./setup.sh

The first build compiles the PX4 toolchain and the full ROS 2 workspace, so it can take a while (15-30 minutes depending on your machine); subsequent runs reuse the cached image and start instantly. setup.sh then starts a persistent container in the background and drops you into its guided menu:

  1. Run UWBPX4Sim setup (setup_simulator.sh): configure the PX4/Gazebo plugin, models, and layout inside the container. Opens a browser-based GUI (prints the URL, default http://localhost:5050) to build the robot layout and tune plugin parameters, then shows setup's progress there, including the optional PX4 re-compile; falls back to terminal prompts if the GUI isn't available.
  2. Launch simulation (ticks once setup has been run): launches PX4 SITL, Gazebo, and the UWB bridge/offboard nodes via simulator_launcher.sh.
  3. Open a shell: skip the menu and get a plain shell in the container.
  4. Exit: stops the container, and asks whether to remove it completely instead (default just stops it) -- everything else, including closing your terminal, leaves it running with your configuration intact. Run ./setup.sh again any time to get back to this same menu.
The setup GUI: loading a demo layout, editing its robots and transceivers, and browsing the plugin parameters The setup GUI: loading demo_util_nlos, selecting the lps_tdoa preset and running setup with the PX4 build until it finishes
Building a layout and tuning the plugin parameters (3x speed). Loading demo_util_nlos, selecting the lps_tdoa preset and running setup with the PX4 build (sped up).

docker-compose.yml bind-mounts the whole repository (plus ROS2/px4_sim_offboard/trajectories/ onto its installed path) from the host into the container, so editing a layout, a plugin-parameter preset, a custom world, a trajectory CSV, or the plugin source on the host takes effect the next time setup (or the simulation) runs -- no image rebuild needed.

This image is also the base of mr-radio-localization's SITL Docker image (./setup.sh --sim in that repo's docker/), which builds FROM it and adds the radar/localization stack on top, building this image first if it's missing. mr-radio-localization also has a standalone image that runs the localization on recorded bags without this simulator.

To run without Docker, see Running without Docker.

Configuring an experiment

A layout YAML in config/ defines the robots, their spawn poses, the UWB sensors they carry and their trajectories:

world: walls_nlos          # optional: a file from worlds/, or a world PX4 ships
uavs:
  - id: 0
    spawn_pose: [3.0, 0.0, 0.0, 0.0, 0.0, 1.57079632679]   # x, y, z, roll, pitch, yaw
    offboard:
      trajectory_csv_file: trajectory_lemniscate_uav.csv
    tags:
      - id: 1
        position: [-0.24, -0.24, -0.06]                    # relative to the robot
ugvs:
  - id: 0
    spawn_pose: [0.0, 0.0, 0.0, 0.0, 0.0, 1.57079632679]
    offboard:
      trajectory_csv_file: trajectory_lemniscate_agv.csv
    anchors:
      - id: 1
        position: [-0.32, 0.3, 0.875]
static_anchors:                                            # optional, not on a robot
  - id: 5
    position: [4.0, 2.0, 2.5]                              # in world coordinates

Any robot can carry tags, anchors or both. Tag ids must be unique across the layout, and so must anchor ids. uavs and ugvs are optional, as long as there is at least one tag and one anchor. See config/ for complete examples. Build layouts from the setup GUI or edit the files directly, then run setup again.

Demos

Four ready-made experiments ship in config/. The first two are the LOS and NLOS experiments of the UWBPX4Sim paper (Robot Meets Ranging workshop, ICRA 2026), with a UGV-UAV team carrying anchors and tags; the last two reproduce real flights with the Loco Positioning presets:

Layout Scenario Preset
demo_los.yaml A UGV with four anchors and a UAV with two tags, in open space. The UAV flies 80 m away and back, so noise and dropout grow with distance until the link closes. eliko_twr
demo_nlos.yaml The same team side by side past walls of increasing thickness (worlds/walls_nlos.sdf): a 25 cm wall (soft NLOS), a 75 cm corner (hard NLOS) and a 120 cm section (blackout). eliko_twr
demo_util_nlos.yaml One of the UTIL dataset's real NLOS flights [2]: its eight surveyed anchors, a metal and three wooden cabinets blocking four of them (worlds/util_nlos.sdf), and the recorded path flown by an x500. lps_tdoa
demo_lps_twr.yaml One of Pfeiffer et al.'s real TWR flights [3]: the eight surveyed Loco Positioning anchors of the TU Delft Cyberzoo, and the recorded star-shaped path flown by an x500, in line of sight. lps_twr
The UTIL NLOS demo in RViz: the drone flies its recorded loops among the eight anchors, with links fading when a measurement drops and the cabinets blocking four anchors The NLOS demo in RViz: the UGV drives along the wall and stops at its corner while the UAV flies around the corner, so their links cross the wall
demo_util_nlos (6x speed): the recorded path, the eight anchors and the live links, with the metal (grey) and wooden (brown) cabinets. demo_nlos (8x speed, camera following the UAV): the UGV and the UAV, each carrying its own transceivers, move along the wall until the corner puts it between them.

Run one with its preset, for example:

./setup_simulator.sh --layout config/demo_util_nlos.yaml --params lps_tdoa

To mark an obstacle's material, add a <uwb:material> element to its model (or to one of its collisions), and declare the uwb prefix on the world's <sdf> root:

<sdf version="1.9" xmlns:uwb="https://github.com/amartinezsilva/UWBPX4Sim">
  ...
  <model name="wall_1">
    <uwb:material>concrete</uwb:material>

A __material_<name> suffix on the model name, e.g. wall_1__material_concrete, also still works. See the measurement model for details.

Output topics

Mode Measurements Ground truth
TWR /uwb_gz_simulator/distances/aItJ /uwb_gz_simulator/distances_ground_truth/aItJ
TDOA /uwb_gz_simulator/tdoa/aIaKtJ /uwb_gz_simulator/tdoa_ground_truth/aIaKtJ

I and K are anchor ids (I is the TDOA reference, the lowest anchor id) and J is the tag id. All of these topics are bridged to ROS 2, but only the active mode publishes. Each robot also publishes /<prefix>/odom and /<prefix>/gt, with prefix uav_<id> or ugv_<id>.

Using the plugin on its own

The Gazebo plugin also works without PX4 or ROS 2, in your own Gazebo Harmonic world with your own robots. See examples/barebones/.

Documentation

  • UWB basics: a short introduction to UWB ranging, TWR and TDoA, and common setups, for readers new to UWB.
  • Measurement model: equations, materials, all plugin parameters and calibration results.
  • Advanced setup: running without Docker, full layout reference, adding vehicle types, manual installation and ROS 2 interfaces.

Cite this work

UWBPX4Sim is the simulation environment of the following work. If you use it in your research, please cite:

A. Martínez-Silva, D. Alejo, L. Merino and F. Caballero, "Radio-based Multi-Robot Odometry and Relative Localization," 2026 IEEE International Conference on Robotics and Automation (ICRA), Vienna, Austria, 2026, pp. 17557–17564, doi: 10.1109/ICRA57385.2026.11696767.

@inproceedings{martinezsilva2026radio,
  author    = {Mart{\'i}nez-Silva, Andr{\'e}s and Alejo, David and Merino, Luis and Caballero, Fernando},
  title     = {Radio-based Multi-Robot Odometry and Relative Localization},
  booktitle = {2026 IEEE International Conference on Robotics and Automation (ICRA)},
  address   = {Vienna, Austria},
  year      = {2026},
  pages     = {17557--17564},
  doi       = {10.1109/ICRA57385.2026.11696767}
}

About

A ready-to-use Ultra-Wideband simulator for relative localization of multi-robot teams integrated with ROS 2, Gazebo Harmonic and PX4 SITL.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages