Simulator Quickstart: First Race in Under an Hour

This ladder gets you driving a simulated Racerbot as fast as possible, then shows you the higher-fidelity simulator the team uses when the lightweight one is not enough. Two rungs:

1. f1tenth_gym_ros - a lightweight 2D-top-down simulator that runs inside the workspace container you already have. This page gets you to a moving car in under an hour.
2. AutoDRIVE - a 3D, physics-heavy digital-twin simulator for realistic testing. More setup, more hardware demands; install it when a project needs it.

Prerequisite: a working development environment from the dev environment setup guide - the commands below all run inside the racerbot container unless they say otherwise.

Rung 1: f1tenth_gym_ros

Adapted from the team’s F1TENTH_GYM_ROS setup doc, which tracks the upstream f1tenth_gym_ros repo (dev-humble branch).

1. Create the workspace virtual environment (once)

Inside the container:

sudo apt install python3.10-venv
python3 -m venv --system-site-packages /racerbot_ws/.venv
source /racerbot_ws/.venv/bin/activate
python3 -m pip install -U pip

--system-site-packages matters: it lets the venv see the ROS 2 Python packages. Every later terminal that touches the simulator must activate this venv.

2. Clone the simulator packages

cd /racerbot_ws/src
git clone -b dev-humble https://github.com/f1tenth/f1tenth_gym_ros.git
cd f1tenth_gym_ros
rm -rf f1tenth_gym
git clone -b dev-humble https://github.com/f1tenth/f1tenth_gym.git

3. Install and build

cd /racerbot_ws/src/f1tenth_gym_ros/f1tenth_gym
source /racerbot_ws/.venv/bin/activate
pip install -e .
cd /racerbot_ws
rosdep update
rosdep install -i --from-path src --rosdistro humble -y
colcon build

Checkpoint: colcon build finishes with no failed packages. The troubleshooting section covers the pip errors you are most likely to hit here.

4. Launch the simulator

Every new terminal needs all three sources:

source /racerbot_ws/.venv/bin/activate
source /opt/ros/humble/setup.bash
source /racerbot_ws/install/local_setup.bash
ros2 launch f1tenth_gym_ros gym_bridge_launch.py

Checkpoint: the terminal prints the Foxglove WebSocket line in blue, [INFO] [launch.user]: Foxglove WebSocket: ws://localhost:8765, and ros2 topic list in a second terminal shows /scan, /map and /ego_racecar/odom.

5. Watch and drive it in Foxglove

1. Open Foxglove in your browser (free account).
2. “Open connection” → “Foxglove WebSocket” → address ws://localhost:8765. Topics appearing in the left panel means the connection works.
3. Import the simulator’s layout: layout menu (top right) → import from file → gym_bridge_foxglove.json in racerbot_ws/src/f1tenth_gym_ros/config/foxglove.
4. Drive it: set kb_teleop to True in f1tenth_gym_ros/config/sim.yaml, rebuild, relaunch, then in another sourced terminal run ros2 run teleop_twist_keyboard teleop_twist_keyboard. i drives forward, , reverses, u/o turn, k stops.

Checkpoint - you have completed rung 1 when: you can see the car and its laser scan in Foxglove and drive it around the map from the keyboard.

Useful things to know:

• Change the map with map_path in config/sim.yaml - a package-relative path like maps/levine, or a built-in gym track name like Spielberg. Rebuild after config changes.
• Two-car racing: num_agent: 2 adds an opponent with its own /opp_scan, /opp_drive and odometry topics. More than two agents is not supported.
• Your own controller publishes AckermannDriveStamped commands on /drive; the simulator gives you /scan and odometry back. That one-topic contract is what every Stage 2 lab builds against.
• RViz works too (gym_bridge.rviz in the launch folder), but Foxglove is the team’s default.

Rung 2: AutoDRIVE (higher fidelity)

AutoDRIVE is a 3D digital-twin simulator with realistic vehicle physics, sensor models and rendering. Use it when you are validating something the 2D gym cannot show: camera-based perception, suspension behaviour, realistic dynamics before a testing day.

Where rung 1 was Python-light, AutoDRIVE is heavier:

• It is tested on Ubuntu only, assumes Docker, and realistically wants an NVIDIA GPU with the NVIDIA Container Toolkit for usable framerates.
• The current competition framework lives in AutoDRIVE-Ecosystem/AutoDRIVE-RoboRacer-Sim-Racing; the older AutoDRIVE-F1TENTH-Sim-Racing repo is deprecated. Prebuilt images are on Docker Hub.
• It runs its own simulator container plus a devkit (API) container that bridges into ROS 2, instead of living inside your workspace.

Checkpoint for rung 2: the simulator window renders the track, and the devkit container’s topics are visible from your workspace container. Follow the README in the RoboRacer Sim-Racing repo for the exact build and run commands.

Which simulator when

The team’s position: standardize on these two. A third simulator adds maintenance without adding capability.

Troubleshooting

This package is managed externally / PEP 668 error on pip install -e . You are installing into the system Python. Activate the venv first: source /racerbot_ws/.venv/bin/activate.

PyQt6 fails to install, or the gym install hangs on PyQt6 Pin the supported version first: pip3 install pyqt6==6.7.1, then pip install -e . again. On an ARM Ubuntu server image (VMware Fusion on Mac), use pip3 install pyqt6==6.7.1 --config-settings --config-license= --verbose to accept its GPL license non-interactively.

AttributeError: module 'coverage' has no attribute 'types' pip3 install --upgrade coverage (needs 7.6.1+).

ImportError: cannot import name 'Transpose' from 'PIL.Image' pip3 install --upgrade pillow (needs 9.1.0+).

ValueError: numpy.dtype size changed, may indicate binary incompatibility pip3 install --upgrade scipy (needs 1.13.0+).

"opencv>=3. invalid" while pip-installing python3 -m pip install --upgrade pip wheel setuptools, then retry.

The launch starts but Foxglove shows no topics Check the WebSocket address is exactly ws://localhost:8765, that the container was started with -p 127.0.0.1:8765:8765, and that the launch terminal still shows the simulator running.

ros2 launch f1tenth_gym_ros ... says the package does not exist You have not sourced the workspace overlay in this terminal: source /racerbot_ws/install/local_setup.bash.

Sources

• sfu-racerbot/racerbot-docs: F1TENTH_GYM_ROS.md and WORKFLOW.md - the team docs this page follows.
• f1tenth/f1tenth_gym_ros - upstream simulator bridge (dev-humble branch).
• AutoDRIVE-Ecosystem/AutoDRIVE-RoboRacer-Sim-Racing - the current AutoDRIVE competition framework.
• Foxglove and the Foxglove docs.

Next: the hands-on ROS 2 primer, which builds your first nodes against this simulator.