Autonomous Roboracer Rust - an autonomous driving stack for RoboRacer (formerly F1TENTH) cars, written in Rust.
philly and its trophy for second place in the Master Cup of the 27th RoboRacer Autonomous Racing Competition, ICRA 2026, Vienna
The Frenet overtaking racing in simulation on the Vienna 2026 qualifying map
The Frenet overtaking against the MPC in simulation on the same map
It covers the whole pipeline in one crate (aurorus): a vehicle and LIDAR
simulator with a random track generator, SLAM mapping, localization by scan
matching or a particle filter, race-line planning, opponent detection, a set
of autonomous driving algorithms, and the drivers for the real car (VESC,
Hokuyo LIDAR, joystick).
Everything is driven from a browser GUI, and the same code runs in simulation
on a laptop and on the car.
-
Install Rust with rustup (see the official install page for other platforms and options):
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
The crate needs Rust 1.95 or newer -
rustup updatebrings an older install up to date. No other system library is required. -
Build everything from the repository root:
cargo build --release
The executables are placed in
target/release/. The release profile trades compile time for speed (LTO, a single codegen unit), so the first build takes a few minutes. -
Run the main application and open http://localhost:1999:
./target/release/web_gui
On a machine that isn't set up as a car this runs the simulation. Run the executables from the repository root: they look for
config/,maps/and the other folders below relative to the current directory.
cargo build --release builds every binary below into target/release/.
Each one prints its full list of options with --help.
| Executable | What it does | Web page |
|---|---|---|
web_gui |
The main application: drive the simulation or the real car | http://localhost:1999 |
replay_web_gui |
Play back a recorded debug session | http://localhost:1998 |
benchmark_viewer |
Compare and replay recorded benchmark runs | http://localhost:1997 |
car_calibration |
Guided calibration of a car's hardware | http://localhost:1996 |
mapping_lab |
Build maps from a recorded mapping session with other SLAM parameters, and compare them | http://localhost:1995 |
localization_lab |
Localize a recorded drive again with every localization algorithm and odometry, and compare their error and cost lap by lap | http://localhost:1994 |
probe |
Test one piece of the car's hardware on its own | - |
benchmark_communication_time |
Measure topic read/write latency | - |
benchmark_data_freshness |
Measure how stale the data readers see is | - |
The web pages are served on every network interface, so they can also be
opened from another device, e.g. a phone or laptop next to the car, at
http://<address of the machine>:<port>.
The main application. It starts every part of the stack - sensors, localization, planning, perception, the driving algorithms - and serves the GUI to control them: pick or generate a map, plan a race line, map a track with SLAM, select and tune a driving algorithm live, race against simulated opponents, run benchmarks and record debug sessions.
It simulates the car unless the machine is set up as one: with a CAR_NAME
file naming a calibrated car (see Car calibration)
it drives the real hardware instead.
./target/release/web_gui # simulation, or the car CAR_NAME names
./target/release/web_gui --sim # simulate, even on a car
./target/release/web_gui --car tom # run as the car "tom"
./target/release/web_gui --debug # record a debug session from the startSee Web GUI for every part of the page.
Read-only playback of a .debug session file recorded by web_gui (from its
Debug panel, or with --debug): the same map view, drawing whatever the
recorded executors drew, with a timeline to scrub through. It only needs the
file itself. See Replay web GUI.
./target/release/replay_web_gui --file debugs/<session>.debugRead-only web UI over the benchmark runs recorded from web_gui's Benchmark
panel: filter them, compare their lap times, parameters and telemetry, and
replay several of them together on the map. See
Benchmark viewer.
./target/release/benchmark_viewerBuilds maps offline from the mapping sessions web_gui records (the Mapping
panel's Record session toggle), each with its own SLAM parameters, and
compares them on the map, over the true map in simulation, by their scores.
Sweeps run every combination of up to three parameters' ranges at once. The
chosen map is saved under maps/, and its parameters into
config/localization/slam.toml.
See Mapping lab.
./target/release/mapping_lab # pick a session on the page
./target/release/mapping_lab --file mapping_sessions/lap.mappingLocalizes the drives web_gui records (the Localization panel's Record
session) again, with every localization algorithm and odometry - scan
matching, the particle filter, odometry alone, each with its own parameters
- and compares them on the very same drive: their trajectories on the map
over the ground truth, their error and time per scan along each lap, and a
table of scores per lap. On the car, any run can be the reference instead of
the ground truth. The chosen parameters are saved into
config/localization/. See Localization lab.
./target/release/localization_lab # pick a session on the page
./target/release/localization_lab --file localization_sessions/laps.localizationA guided calibration of a real car, served as a web page: its size and
weight, how its IMU and LIDAR are mounted, its steering range and its motor's
speed gain. Saving writes config/calibration/<car>.toml, which every other
executable then uses. It needs the car's VESC and can't run at the same time
as web_gui. See Car calibration.
./target/release/car_calibration --car tomTwo terminal benchmarks of the executor/topic framework everything is built on, with one writer and several readers at different rates. The first measures how long the read and write calls take, the second how old the data is when a reader sees it. Both are explained in Core framework.
./target/release/benchmark_communication_time --duration 30Small bring-up tools for the real car, each testing one piece of hardware on
its own, without the rest of the stack: useful when web_gui or
car_calibration misbehave and it isn't clear which part is at fault. Like
car_calibration, the VESC probes can't run at the same time as web_gui.
probe alone lists them.
| Subcommand | What it does |
|---|---|
probe vesc [SECONDS] [PORT] |
Read-only: prints the VESC's firmware, then its state and IMU ten times a second |
probe hokuyo [SECONDS] |
Prints the LIDAR's scan rate and what it sees ahead, left, right and closest, e.g. to check the mounting |
probe servo POSITION|center [PORT] |
Moves the steering servo to one position (0.15..=0.85) and exits. Never spins the motor |
probe motor ERPM SECONDS [PORT] |
Wheels off the ground: spins the motor at a low ERPM (at most 3000, for at most 15 s), then brakes. Never moves the servo. Ctrl+C brakes early |
./target/release/probe vesc
./target/release/probe servo centerMaps live in maps/, one folder per map. The repository ships the tracks
of the RoboRacer races the UniBo team took part in (see Credits):
| Map | Track |
|---|---|
Atlanta_2025 |
ICRA 2025, Atlanta |
Vienna_2026_Quali |
ICRA 2026, Vienna: the qualifying track |
Vienna_2026_Final_Ground |
ICRA 2026, Vienna: the final track, at ground level |
Vienna_2026_Final_Bridge |
ICRA 2026, Vienna: the same final track, on the bridge level |
The Vienna final track crossed over itself on a bridge, so it comes as two maps of the same area, one per level.
Only each map's image and info.json are tracked. Race lines are not: plan
one from web_gui's Planning panel (see Planning).
Any other map you create from web_gui - generate a random track, import an
image, or map a real track with SLAM - stays local.
These files and folders are listed in .gitignore: they are created locally
as the executables run and are specific to one machine.
| Path | What it holds |
|---|---|
target/ |
Cargo's build output, including the executables in target/release/ |
maps/ |
Every map but the race tracks above, and every map's race lines (see Maps) |
debugs/ |
.debug session files recorded by web_gui, played back by replay_web_gui |
benchmarks/ |
Benchmark runs recorded by web_gui, read by benchmark_viewer |
mapping_sessions/ |
.mapping session files recorded by web_gui, read by mapping_lab |
localization_sessions/ |
.localization session files recorded by web_gui, read by localization_lab |
CAR_NAME |
One line naming the car this machine drives; without it, web_gui simulates |
config/calibration/history/ |
Each car's older calibrations, kept when car_calibration saves a new one |
other_repos/ |
Local clones of third-party projects kept for reference |
Everything else under config/ is tracked: one TOML file per component,
loaded at startup.
| Document | What it covers |
|---|---|
| Core framework | The executor/topic framework, its design decisions, and the two communication benchmarks |
| Web GUI | Every part of web_gui's page, with screenshots, and how it works underneath |
| Replay web GUI | Playing back a recorded debug session: the map, the timeline, and how it works |
| Benchmark viewer | Filtering, comparing and replaying benchmark runs |
| Autonomous algorithms | How driving algorithms are structured, selected and tuned live, and how to add one |
| Tutorials | Writing an autonomous algorithm from an empty file, step by step: a gap follower and a pure pursuit |
| Planning | How the race line is planned for a map |
| SLAM | Mapping a track and localizing on a known map, by scan matching or with a particle filter |
| Mapping lab | Recording mapping sessions and building their maps again offline with other parameters |
| Localization lab | Recording localization sessions and comparing localization algorithms on the same drive |
| Detector | Finding and tracking an opponent by comparing the LIDAR scan with the map |
| Vehicle models | The simulator's vehicle dynamics models |
| Car calibration | Calibrating a real car and the car file it produces |
| Joystick | Driving the car with a gamepad |
The API documentation is generated from the code:
cargo doc --no-deps --openThe whole project was written by me (@Noce99) with AI-assisted development, using as a reference the (non-public) ROS2 repository of the University of Bologna's 1:10 scale autonomous driving team. I have led the team since 2024: at the RoboRacer Autonomous Racing Competition at IEEE ICRA 2025 in Atlanta it took first place with one car, philly, running the Frenet overtaking (watch the final), and at ICRA 2026 in Vienna it took second and third place in the Master Cup with two cars: philly with the Frenet overtaking and tom with the MPC.
| Atlanta, ICRA 2025: first place in the RoboRacer competition | Vienna, ICRA 2026: second and third place in the Master Cup |
I would like to thank @SamueleCrimi and @Scheggetta for their amazing work in the UniBo autonomous driving team, especially for the first implementations of the Frenet overtaking and the Path Follower. Both algorithms have been ported to this repository.
Special thanks also to @AlbYoda, who implemented the detector (ported to this repository) and is now working on a faster, Acados-based MPC (not yet ported), and to @FelixFrog, who implemented the map switch that let us use the bridge at Vienna 2026 (not yet ported) and is now working on a new MPPI implementation.
Many thanks to everyone else who has been part of the UniBo driverless team, especially @TorioCrema, @FedericoCalzoni, @beatricebottari, @LucaTedeschini, @ncridlig and @StefanoColamonaco.
A final special thanks goes to @gerkone. In the second half of 2020, we worked together with @EnricoTrombetti and @AldoCanfora on a project for a Complex Systems course shared between physicists and computer scientists (all of us were physicists except @gerkone). Shortly afterwards, @gerkone founded the UniBo autonomous driving team, which I have enjoyed being part of ever since.
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.