Skip to content

Quick start: test a driving policy

From an empty directory to a scenario result, with no ROS 2 and no Autoware. The framework downloads CARLA, launches it, serves the driving policy in its own process and runs the scenario: after the setup it is one command.

You need Linux x86_64, uv, git, an NVIDIA GPU that runs CARLA UE5, and about 30 GB of free disk for the simulator. (The framework also runs on Linux aarch64, but CARLA's server does not: there, run CARLA on an x86_64 host and add server.host=<address> to the commands below; see installation.)

1. Add the framework to your project

The framework is a Python library on PyPI. Depend on it from your project's pyproject.toml:

[project]
name = "my-policy-tests"
version = "0.1.0"
requires-python = ">=3.10,<3.15"
dependencies = ["autoware-carla-scenario>=28"]
uv sync

This also installs carla-driver-interface 2.x, the policy side of the gRPC contract (versioned on its own; the framework requires carla-driver-interface>=2.4.2,<3, so a policy accepting 2.4.2 or a later 2.x shares the environment), and the CARLA client, typesafe_carla. Its wheel carries a prebuilt CPython package. Where that package does not match the installed toolchain, the first run that imports the client builds it once instead (15-50 min, ~14 GB of memory, needs cc) into ~/.cache/typesafe_carla. uv run typesafe-codon pycarla does that ahead of time, and says "nothing to build" when the prebuilt package applies.

2. Download CARLA

uv run scenario-setup

This downloads CARLA's nightly Linux build (about 16 GB, with a progress bar) and unpacks it, while it downloads, into ~/.autoware_carla_scenario/bin/carla. That is where the scenario runner looks for CARLA when CARLA_EXECUTABLE is not set. Run it again at any time: an install that is still the current nightly is kept, a newer one replaces it. If the connection drops partway, the download picks up where it stopped (with an HTTP range request) instead of starting over; it gives up after several reconnections in a row that deliver nothing, and stops (the next run fetches it whole) if the nightly was replaced in the meantime. A new install is unpacked next to the old one (carla.partial) and swapped in by renames once it is complete, so stopping scenario-setup (Ctrl-C) at any point leaves either the previous install or none, never a half-deleted one; the next run deletes whatever the interrupted one left beside it. Only one scenario-setup at a time installs into a directory: a second one started meanwhile says it is waiting for the first (a lock on carla.lock, which stays beside the install), then usually finds the first one's install up to date; Ctrl-C stops it while it waits. A user who cannot write carla.lock (a shared install of another user's) can still check the install, and is told so rather than downloading if it is missing or out of date.

Option Meaning
--force Download again even if the install is current
--url URL Install another CARLA Linux package (.tar.gz), e.g. a release: a URL, or a local path (~/Downloads/CARLA.tar.gz, ./CARLA.tar.gz) to install an archive already downloaded
--dir DIR Unpack into DIR (new or empty) instead; then point CARLA_EXECUTABLE at the launcher it prints

AUTOWARE_CARLA_SCENARIO_HOME moves ~/.autoware_carla_scenario as a whole.

3. Run a scenario against a policy

uv run scenario scenario=cut_in/left map=town10hd_opt \
  ego.spawn_lanelet_id=324 scenario.npc_lanelet_id=446 \
  ego.entity=carla_driver driver.policy=route_follower

The single command does everything:

  1. It launches CARLA (CarlaUnreal.sh, on server.port). The first boot takes a minute or two. A CARLA already listening on that port is used instead.
  2. It fetches the Town10HD_Opt Lanelet2 map into ~/autoware_data/maps, the first time only.
  3. It serves route_follower, a reference policy, inside the scenario's own process.
  4. It runs the scenario, prints the pass/fail result, writes it under outputs/, and stops CARLA again. It does so even when the run is stopped with SIGTERM (it then exits 143) or killed: a CARLA the run launched does not outlive it. A CARLA that was already running is left running.

ego.entity=carla_driver hands the ego to a policy over alpasim's egodriver.EgodriverService contract. driver.policy names the policy the scenario serves itself.

The example scenarios name lanelets of the NishishinjukuMap by default, so on Town10HD_Opt a run gives its own. The two above are one of the cases the scenario's sweep matches. scenario-expand lists every case, each as the overrides to add to the command above, without running anything:

uv run scenario-expand scenario=cut_in/left map=town10hd_opt

4. Test your own policy

A policy implements BaseDriver.drive(). It gets the session's observations and returns a trajectory in the rig frame (x forward, y left):

# src/my_policy_tests/__init__.py
from carla_driver_interface.driver import BaseDriver, DriveContext, DriveResult
from carla_driver_interface.geometry import Pose, Trajectory


class MyPolicy(BaseDriver):
    name = "my_policy"

    def drive(self, ctx: DriveContext) -> DriveResult:
        plan = Trajectory.empty()
        for i in range(1, 41):  # 4 s ahead at 5 m/s
            plan.append(ctx.time_now_us + i * 100_000, Pose.from_xyz_yaw(0.5 * i, 0.0, 0.0, 0.0))
        return DriveResult(trajectory_in_rig=plan)

So that uv sync installs the module, give the project a build backend:

[build-system]
requires = ["uv_build>=0.9.7,<0.10.0"]
build-backend = "uv_build"

Then name the policy by its import path:

uv run scenario scenario=cut_in/left map=town10hd_opt \
  ego.spawn_lanelet_id=324 scenario.npc_lanelet_id=446 \
  ego.entity=carla_driver driver.policy=my_policy_tests:MyPolicy

See External Driver Interface for what a policy receives (cameras, LiDAR, the map, traffic lights). Other scenarios are listed in Example Scenarios.

Running the policy as a separate process

A policy can also live in a process of its own, for example an alpasim driver or a model in another environment. Leave driver.policy unset and point driver.address at it:

# Terminal 1 -- the policy
uv run carla-driver-interface serve --policy my_policy_tests:MyPolicy --port 50051

# Terminal 2 -- the scenario
uv run scenario scenario=cut_in/left map=town10hd_opt \
  ego.spawn_lanelet_id=324 scenario.npc_lanelet_id=446 \
  ego.entity=carla_driver driver.address=localhost:50051

Both modes use the same gRPC contract and the same policy class. The only difference is which process serves the policy.