Skip to content

HILS: ECUs in the Loop

scenario-hils is a hardware-in-the-loop bridge. It is a resident process on the HILS PC wired to the ECUs under test, independent of the scenario runner. It follows the ego of a scenario run in CARLA and sends the ECUs what their real sensors and buses would deliver: CAN frames, a GNSS receiver's output, a LiDAR's UDP packets, camera frames. It initializes and finalizes the ECUs around each scenario, and hands what they command back to the run, which drives the ego with it. The ECU traffic goes through hilspy (a Rust core with a thin Python layer).

flowchart LR
    subgraph sim["Simulation host"]
        runner["scenario runner<br/>ego.entity=hils<br/>(ticks the world)"]
        carla[("CARLA server")]
        runner -- typesafe_carla --> carla
    end
    subgraph hils["HILS PC: scenario-hils (resident)"]
        bridge["HilsBridge<br/>(a second CARLA client, never ticks)"]
        canvas["carla_canvas renderer<br/>(optional)"]
        hilspy["hilspy channels"]
        bridge -- "sensors (listen)" --> canvas
        bridge <--> hilspy
    end
    carla -- "ticks, ego state, sensor data" --> bridge
    runner <-- "TCP :7700<br/>start / ready / command / disconnect / reconnect / end / ended" --> bridge
    hilspy <-- "can:// dbc<br/>(inputs: ECU commands)" --> ecu1["ECU: vehicle CAN"]
    hilspy -- "tcp:// sbf, serial:// nmea" --> ecu2["ECU: GNSS input"]
    hilspy -- "udp:// lidar:MODEL" --> ecu3["ECU: LiDAR driver"]
    hilspy -- "v4l2://" --> ecu4["ECU: camera input"]

The bridge is a CARLA client of its own: it waits for the runner's ticks (World.wait_for_tick), so it works with the runner's synchronous mode, and it never ticks the world itself. One scenario-hils serves scenario after scenario, a whole batch, for as long as it runs.

A scenario's life, with ego.entity=hils:

  1. The runner spawns the ego and connects to the bridge (hils.host, hils.port): start, with the ego's actor id.
  2. The bridge starts the devices' periodic messages, runs the scenario_start steps (wake the ECUs, wait until they say they are ready) and then attaches its sensors to the ego, so the ECUs get no sensor data measured before the scenario is live. Then it runs the warmup steps with the sensors streaming (wait until the ECUs are ready to drive: an automated driving stack localized, routed and engaged). The runner ticks the world meanwhile, holding every vehicle still, until the bridge answers ready -- or fails the run when a step fails or nothing comes within hils.ready_timeout_s. The scenario's clock starts then: this wait is the run's warm-up, as for an ego whose stack comes up over ROS 2.
  3. Every tick the ego's state goes to the ECUs; whenever an ECU sends a command message (inputs), the bridge forwards the command and the runner applies it to the ego.
  4. When the scenario ends the runner sends end; the bridge removes its sensors, runs the scenario_end steps, stops the periodic messages and answers ended. A run that goes away mid-scenario ends it as well.

A message that cannot be sent on the link ends the link: either side gives a peer that does not read 10 s to take it, and a send that fails or times out may have written part of its line, so nothing is sent after it. The bridge then shuts the connection down and counts the run as gone (ending its scenario, as above), and the run fails with "The HILS bridge's link failed". Waiting for what the peer sends never shortens or lengthens that 10 s.

Without a run connected (any other ego.entity), the bridge streams the ego to the ECUs all the same, and the ego appearing and disappearing start and end the scenario; the ECUs' commands then go nowhere. The ego of a run that went away -- it failed, or ended -- can stay in the world a while; it does not start a scenario, but an ego spawned after it does.

Running it

The bridge is the hils extra. With uv, one command installs it in a cached environment and runs it:

# Write a commented example configuration and edit it.
uvx --from 'autoware-carla-scenario[hils]' scenario-hils --example > hils.yaml

# Check it: what each device sends, nothing opened.
uvx --from 'autoware-carla-scenario[hils]' scenario-hils hils.yaml --check

# Run it, until Ctrl-C or SIGTERM.
uvx --from 'autoware-carla-scenario[hils]' scenario-hils hils.yaml

# Sensors rendered by carla_canvas (`canvas:` in hils.yaml).
uvx --from 'autoware-carla-scenario[hils]' --with 'carla-canvas[client]>=0.2' \
    scenario-hils hils.yaml

--host, --port, --role-name and --listen override the file's CARLA address, ego and run link; a --port outside 1-65535 is a usage error (exit 2), as is an empty --host, --role-name or --listen (the run link is turned off only by runner.listen: null in the file). In a checkout, uv sync --dev installs hilspy and uv run scenario-hils hils.yaml runs it.

Then run scenarios with the ego driven by the ECUs, on the same CARLA server:

uv run scenario ego.entity=hils hils.host=hils-pc
hils. setting Default
host, port localhost, 7700 the bridge's runner.listen; an IPv6 host without brackets (hils.host=::1); with brackets, quote it ('hils.host="[::1]"'), or Hydra reads [::1] as a list; the port is a whole number from 1 to 65535
connect_timeout_s 10.0 reaching the bridge
ready_timeout_s 60.0 its scenario_start and warmup steps together (wall clock): raise it to cover the steps' timeouts when they add up to more
end_timeout_s 30.0 its scenario_end steps (wall clock)
stale_s 0.5 a command older than this (wall clock) is stale
on_stale brake brake, or hold the last command, once stale; before any command the ego brakes

A null hils. setting is its default; an empty host is refused, and so is a timeout that is not a number (true, "10").

Setting up the HILS PC

The virtual devices the bridge writes to must exist before it opens them: a can://vcan0 device needs the interface vcan0, a v4l2:///dev/video10 camera the v4l2loopback device /dev/video10. --setup creates them from the configuration: it derives the variables of hilspy's ansible playbooks (shipped in the hilspy wheel, hilspy/ansible/, from hilspy 0.17) from the devices, and runs them on this PC through ansible-runner. They need a Debian or Ubuntu host and sudo (its password is asked for once, when needed), and are idempotent: run --setup again after editing the devices.

# What --setup would run, as JSON: each playbook and its variables.
uvx --from 'autoware-carla-scenario[hils-setup]' scenario-hils hils.yaml --setup-vars

# Show what would change (ansible --check --diff), change nothing.
uvx --from 'autoware-carla-scenario[hils-setup]' scenario-hils hils.yaml --setup --check

# Create the devices, now and at every boot.
uvx --from 'autoware-carla-scenario[hils-setup]' scenario-hils hils.yaml --setup
Device url Playbook Variables
can://vcanN (?fd: CAN FD) vcan.yml vcan_interfaces: [{name: vcanN, fd: ...}]: the vcan module, the interface with the CAN FD MTU (72) or the classic one (16), kept by the systemd unit hilspy-vcan.service; an interface that two devices share is FD if one of them is; one no longer named is deleted
v4l2:///dev/videoN v4l2loopback.yml v4l2loopback_numbers: [N, ...], v4l2loopback_labels: [<device name>, ...] (cut to 31 bytes, " and , made _): GStreamer, v4l2loopback (DKMS) and its devices with exclusive_caps, and the user who ran it (SUDO_USER) in the video group
anything else -- left alone, and listed as such: a CAN adapter (can://can0: its bitrate is the adapter's), the network of udp:// and tcp:// devices, a serial port

For the example configuration:

$ scenario-hils hils.yaml --setup-vars
{
  "vcan.yml": {
    "vcan_interfaces": [{"name": "vcan0", "fd": false}]
  },
  "v4l2loopback.yml": {
    "v4l2loopback_numbers": [10],
    "v4l2loopback_labels": ["front_camera"],
    "v4l2loopback_exclusive_caps": true,
    "hilspy_user": "hils",
    "hilspy_build": false
  }
}

A v4l2:// path that is not /dev/videoN, two cameras on one device, or a vcan name Linux does not take (at most 15 letters, digits, _, . or -) stops --setup with status 1 before anything runs. The cameras also need hilspy built with its v4l2 feature, which the published wheels are not (hilspy's README, "Cameras"); --setup prepares the devices and GStreamer, not that build. With ansible of your own (another inventory, a fleet of HILS PCs), run the playbooks with the variables --setup-vars prints.

Keeping it resident

The bridge waits for a CARLA server that is not up yet, and for runs, for as long as it runs; Ctrl-C or SIGTERM end a running scenario (its scenario_end steps), run the shutdown steps and close the devices. A step that waits (a wait or a sleep) in any phase but shutdown ends at once on SIGTERM rather than wait out its timeout: a stop during startup ends the startup steps (the bridge does not reach CARLA), one during scenario_start or warmup fails the run's start, and in scenario_end the waits left are skipped while its sends still go. The shutdown steps always run whole. The bridge takes the runner.listen address before the startup steps: one it cannot listen at (a port in use) ends scenario-hils with status 1 and a one-line error before anything reaches the ECUs, and no shutdown step is sent either. A systemd unit keeps it up across reboots:

# /etc/systemd/system/scenario-hils.service
[Unit]
Description=scenario-hils (HILS bridge)
After=network-online.target

[Service]
User=hils
ExecStart=/home/hils/.local/bin/uvx --from 'autoware-carla-scenario[hils]' scenario-hils /etc/scenario-hils/hils.yaml
Restart=on-failure
KillSignal=SIGTERM
TimeoutStopSec=60

[Install]
WantedBy=multi-user.target

A failing startup step stops the bridge with status 1 (systemd restarts it).

Exposure

The run link has no authentication: anyone who can reach runner.listen can start and end runs on the ECUs and read the commands they send. Its default, 0.0.0.0:7700, is every interface, so bind it to the interface that faces the scenario runner (or to 127.0.0.1 when the runner is on the same machine), or firewall the port so only the runner reaches it. Listening on an address that is not a loopback one, scenario-hils says so on stderr when it starts, as the viewer and the scenario editor do.

Configuration

One YAML file describes everything. Relative paths in it (the canvas file, a codec's file, a profiles option) are relative to the file. Unknown keys are refused, so a typo fails at start-up instead of being ignored.

carla: {host: sim-host, port: 2000, timeout: 10.0}
ego: {role_name: Ego, wait: 120.0}
canvas: canvas.yaml        # optional
clock: simulation          # or wall
devices:
  vehicle_can: {...}
  lidar_top: {...}
Key Default
carla.host, carla.port localhost, 2000 the CARLA server the scenario runs on; the port is a whole number from 1 to 65535
carla.timeout 10.0 seconds (positive), for RPCs and for each tick
ego.role_name Ego the runner's ego
ego.wait 120.0 seconds (not negative; wall clock) without an ego -- since the bridge reached CARLA, or since the last scenario ended -- before a warning, logged once a wait (it keeps waiting)
canvas none a carla_canvas configuration: see carla_canvas
clock simulation the devices' time: see Time
runner.listen 0.0.0.0:7700 where runs with ego.entity=hils reach the bridge, with no authentication (Exposure): host:port or host (port 7700); an IPv6 address in brackets, "[::1]:7700" or "[::]" (quoted: unquoted, YAML reads [...] as a list). "[::]" also takes IPv4 where the OS supports dual-stack sockets (Linux, by default); elsewhere it is IPv6 only and 0.0.0.0 is for IPv4. An IPv6 address without brackets, such as ::1, is all host, on port 7700: fe80::1:7700 is not port 7700 of fe80::1. The port is a whole number from 0 to 65535 (0 picks a free one), checked when the file loads; null: no run link (an empty "" is refused)
commands.mode control how the ECUs' command drives the ego: see ECU to simulation
devices one entry per device, by name
lifecycle none steps around the bridge and each scenario: see Lifecycle

A null setting is its default, as a missing one is (carla: {port: null} is port 2000), but for runner.listen, whose null turns the run link off. carla.host, ego.role_name and runner.listen refuse empty text, as --host, --role-name and --listen do.

Names, addresses and raw bytes are text. YAML 1.1, which the bridge reads, turns some unquoted values into something else: 0102 is the octal number 66, 1:30 is 90, and on, off, yes and no are booleans. What was written is then lost, so the bridge refuses these forms anywhere in the file, field values and codec options included, naming the line and the key (write true/false, a decimal or 0x number, or quote the text). 0x7DF, 1.5 and true mean what they say and are taken.

Where text is expected, a value YAML reads as a number or a boolean is also refused (carla.host: 10.0 is the number 10.0) and must be quoted. This covers device names, url, codec, field names (a DBC signal called On is written "On": 1), signal: and field:, carla.host, ego.role_name, runner.listen, canvas, clock, commands.mode and a raw frame's data. Message, input and step names also take a whole number, as its decimal text (RTCM's name: 1005). Field values and id are numbers and stay unquoted (id: 0x7DF).

The numbers the bridge itself uses are checked as well, naming the key: carla.port is a whole number from 1 to 65535 (2000.7 is refused, not truncated); every duration -- carla.timeout, ego.wait, a message's period, a step's sleep and a wait's timeout -- is finite (YAML's .inf and .nan are refused), ego.wait and sleep are not negative and the others are positive; and a field's scale and offset, a sensor's transform and its intensity_scale are finite.

A device is one hilspy channel: url (the transport), codec (raw when omitted) and options (codec options), exactly what hilspy.open(url, codec, **options) takes. The url is non-blank text, and the codec a name (raw, nmea, ...) or a name and its argument (dbc:vehicle.dbc, lidar:vlp16): an empty or blank url, an empty codec and a dbc: with nothing after the colon are refused when the file loads, naming the key and the value (devices.vehicle_can.codec: expected an argument after the colon ..., got 'dbc:'), not passed on to hilspy. It has messages (periodic messages filled from the ego's signals, sent while a scenario runs) and inputs (messages the ECU sends that carry its command), or a sensor (a CARLA sensor on the ego whose measurements it is sent). A device with neither still serves the lifecycle steps (a power supply on a serial port, say).

Message devices

Each message is sent periodically through the codec, and its fields are updated from the ego on every tick:

vehicle_can:
  url: can://vcan0
  codec: dbc:vehicle.dbc
  options: {ecu: VCU}          # send only what the VCU transmits
  messages:
    - name: VehicleSpeed
      period: 0.01             # seconds; omitted: the DBC's GenMsgCycleTime
      fields:
        Speed: $speed_kmh
        YawRate: {signal: yaw_rate, scale: 1.0, offset: 0.0}
        Gear: D

A field is

  • a constant (D, 4, true),
  • $name: a signal (below), or
  • {signal: name, scale: k, offset: c}: signal * k + c.

$$ starts a constant that begins with $. scenario-hils --signals lists the signals:

Signal Unit
time, frame s, - the world's elapsed seconds and frame
x, y, z m world position (CARLA's frame)
roll, pitch, yaw deg CARLA rotation
heading deg clockwise from north, [0, 360)
latitude, longitude, altitude deg, deg, m from the map's geo-reference
latitude_rad, longitude_rad rad as SBF's PVTGeodetic takes them
velocity_north, velocity_east, velocity_up m/s
course deg course over ground, clockwise from north
speed, speed_kmh m/s, km/h magnitude of the velocity
longitudinal_velocity, lateral_velocity, vertical_velocity m/s vehicle frame: x forward, y left, z up
longitudinal_acceleration, lateral_acceleration, vertical_acceleration m/s² vehicle frame
roll_rate, pitch_rate, yaw_rate deg/s right-handed: yaw_rate positive turning left
yaw_rate_rad rad/s
throttle, brake, steer - the control last applied (steer positive right, as CARLA)
hand_brake, reverse, gear - 0 or 1, 0 or 1, CARLA's gear

Any codec hilspy encodes with works. A GNSS receiver over TCP, as a Septentrio receiver streams SBF:

gnss:
  url: tcp://0.0.0.0:28784?listen
  codec: sbf
  messages:
    - name: PVTGeodetic
      period: 0.1
      fields: {mode: 4, latitude: $latitude_rad, longitude: $longitude_rad,
               height: $altitude, vn: $velocity_north, ve: $velocity_east,
               vu: $velocity_up}
    - name: AttEuler
      period: 0.1
      fields: {heading: $heading, pitch: $pitch, roll: $roll}

or NMEA on a serial port:

gps:
  url: serial:///dev/ttyUSB0?baud=115200
  codec: nmea
  options: {talker: GN}
  messages:
    - name: GGA
      period: 0.1
      fields: {latitude: $latitude, longitude: $longitude, altitude: $altitude,
               fix_type: Rtk, fix_satellites: 14}
    - name: RMC
      period: 0.1
      fields: {lat: $latitude, lon: $longitude, speed_over_ground: {signal: speed, scale: 1.943844},
               true_course: $course, status_of_fix: Autonomous}

hilspy's README lists the codecs and their message fields (DBC and FIBEX networks, SOME/IP, SBF, NMEA, UBX, RTCM).

Sensor devices

The bridge spawns the sensor on the ego (its role_name is the device's name, so it cannot be Ego, ego or hero in any case, which the framework reads as the ego), listens to it, and sends each measurement. A blueprint attribute is text, a number or a bool; an empty value (YAML's null), a list or a mapping is refused. A sensor that fails to attach is destroyed, not left on the ego:

lidar_top:
  url: udp://192.168.1.201:2368          # the ECU's LiDAR driver
  codec: lidar:pandar_xt32
  sensor:
    blueprint: sensor.lidar.ray_cast
    transform: {x: 0.0, y: 0.0, z: 2.0, roll: 0.0, pitch: 0.0, yaw: 0.0}
    attributes: {channels: 32, range: 120, points_per_second: 640000,
                 rotation_frequency: 10, upper_fov: 15, lower_fov: -16}
    intensity_scale: 255                  # CARLA's 0-1 intensity -> a byte

front_camera:
  url: v4l2:///dev/video10?format=BGRA&width=1280&height=720&fps=20
  sensor:
    blueprint: sensor.camera.rgb
    transform: {x: 1.5, z: 1.6}
    attributes: {image_size_x: 1280, image_size_y: 720, fov: 90}
    encoding: bgra
  • LiDAR (sensor.lidar.ray_cast, with a lidar:MODEL codec: Hesai Pandar and Velodyne models). CARLA measures the arc a LiDAR sweeps in one tick; the bridge gathers the arcs into whole revolutions (by rotation_frequency and the time between measurements, splitting the arc that completes one by each point's azimuth, so each covers the field of view once) and hilspy encodes each revolution into the model's UDP packets, paced over the revolution as the sensor streams them. A revolution is one sweep of horizontal_fov (360 degrees by default; CARLA turns the rays through azimuths [-fov/2, fov/2)), which may be anything in (0, 360], at rotation_frequency revolutions a second, which must be a finite positive number. A sensor_tick other than 0 is refused: CARLA sweeps only one world tick per measurement, so a LiDAR measured less often turns slower than its rotation_frequency. dropoff_general_rate (the proportion of points CARLA drops at random) and dropoff_zero_intensity (the probability a point of zero intensity is dropped) must be in [0, 1]: CARLA clamps neither, so 45 would empty every sweep without a word. dropoff_intensity_limit, an intensity threshold rather than a proportion, is passed as it is. Points go from CARLA's sensor frame (y right) to the sensor's (y left). Match channels, the field of view and rotation_frequency to the model.
  • Cameras (sensor.camera.*, codec raw). Each image is one frame, in encoding: bgra (CARLA's raw image), bgr, rgb, jpeg or png. v4l2:// makes it a V4L2 camera any client on the PC sees (hilspy built with its v4l2 feature, and v4l2loopback: hilspy's README, "Cameras"); udp:// or tcp:// send the bytes.

ECU to simulation

A device's inputs name the messages an ECU sends that carry the command driving the ego, and which message field fills which command field:

commands:
  mode: control                  # or ackermann
devices:
  vehicle_can:
    url: can://can0
    codec: dbc:vehicle.dbc
    inputs:
      - name: ControlCmd         # as the codec decodes it
        command:
          throttle: {field: AccelPedal, scale: 0.01}   # % -> [0, 1]
          brake: {field: BrakePedal, scale: 0.01}
          steer: {field: SteeringCmd, scale: -1.0}     # left-positive -> CARLA's right
      - name: GearCmd
        command: {reverse: {field: Reverse}}

A command field is a message field (AccelPedal), a scaled one ({field: ..., scale: k, offset: c}), or a constant. Several messages can each fill part of the command; the bridge merges the newest values into one command and forwards it to the run whenever an input arrives. The fields:

commands.mode Fields CARLA
control throttle, brake (0-1), steer (-1-1, positive right), hand_brake, reverse, manual_gear_shift (0/1), gear VehicleControl
ackermann steer (rad, positive right), steer_speed (rad/s), speed (m/s; negative reverses), acceleration (m/s²), jerk (m/s³) VehicleAckermannControl

An ackermann speed is signed: CARLA's Ackermann controller engages reverse for a negative target speed, once the vehicle is (nearly) standing still, and brakes to a stop first when the vehicle is moving the other way. Any negative speed, however small, asks for reverse: there is no deadband, so an ECU that means "stop" sends 0.

A value that is not finite (NaN or an infinity: a decoded IEEE-float signal, a scale that overflows), or larger in magnitude than a 32-bit float holds (CARLA's controls would make it an infinity), is dropped with a warning, as a missing field is: the command keeps the field's previous value. The run drops one it receives too, and the field takes its default. A constant, scale or offset must be finite. The run clamps gear to a 32-bit integer.

The run applies the newest command every tick. One older than hils.stale_s (the ECUs stopped sending) is stale: the ego brakes, or with hils.on_stale=hold keeps the last command.

Lifecycle

lifecycle lists steps for five moments:

Phase When If a step fails
startup once, when the bridge starts (devices just opened, before CARLA is reached) the bridge stops (status 1)
scenario_start a scenario starts (the run's start, or the ego appearing); the periodic messages are already running, and the run waits for the steps; the sensors are attached after them (even when one fails), so no sensor data measured during the steps is sent the run fails, with the step's error
warmup right after scenario_start, with the sensors attached and the world followed (the ego's state and the sensor data reach the ECUs as in the scenario; their commands are not applied yet, and the run holds every vehicle still); the run waits for these steps too, and its clock starts after them the run fails, with the step's error
scenario_end the scenario ends (the run's end, the run going away, or the ego disappearing); the sensors go before the steps (nothing they measure meanwhile is queued or sent), and the periodic messages stop after them logged; the other steps still run
shutdown once, when the bridge stops (Ctrl-C, SIGTERM) logged; the other steps still run
lifecycle:
  startup:
    - send: vehicle_can                    # a message through the codec
      name: PowerMode
      fields: {Ignition: 0}
  scenario_start:
    - send: vehicle_can
      name: PowerMode
      fields: {Ignition: 1, Odometer: $x}  # signals are the ego's, at the start
    - wait: vehicle_can                    # for an ECU's message with these fields
      name: EcuStatus
      fields: {Ready: 1}
      timeout: 10.0
  warmup:                                  # the sensors stream meanwhile
    - wait: vehicle_can
      name: EcuStatus
      fields: {Engaged: 1}
      timeout: 60.0
  scenario_end:
    - send: diag_can                       # a raw frame: id and hex bytes
      id: 0x7DF
      data: "02 11 01"
    - sleep: 0.5
  shutdown:
    - send: power
      data: "4F 55 54 30 0A"

A raw frame's data is a quoted string of hex bytes, with or without spaces (data: "0102" or data: "01 02"), or a list of byte values (data: [0x01, 0x02]). Unquoted, YAML reads a hex string as a number (0102 is octal 66, 0x10 is 16), so the bridge refuses it rather than send other bytes. A send has either a name (and fields) or raw data (and id), never keys of both: only a missing or null key counts as absent.

A wait is satisfied by a matching message received since its phase began, so an ECU that answers a send at once is not missed, nor is a matching message that later ones of its name do not match (a one-frame Ready: 1 pulse among periodic Ready: 0 status frames). While steps run the bridge does not follow the world, and with clock: simulation its clock follows the wall clock instead, so periodic messages keep flowing to an ECU that is being waited on. startup and shutdown steps have no ego, so their fields are constants.

Communication loss

CommunicationLossAction reproduces a break in the communication path to an ECU: the data it names -- a CAN frame, a LiDAR's or a camera's packets, a GNSS receiver's stream -- stops, for as long as the action runs. The run asks the bridge (disconnect on the link) when the action fires and asks it to carry the data again (reconnect) when the action ends; the bridge stops it in the device's hilspy channel (Channel.disconnect). The bus or socket stays open and the device's other traffic carries on.

from autoware_carla_scenario import CommunicationLossAction, ElapsedTimeCondition

# VehicleSpeed stops reaching the ECU for 2 s, 10 s into the scenario.
self.register_pre_tick(
    CommunicationLossAction(
        "vehicle_can",
        messages=["VehicleSpeed"],
        direction="to_ecu",
        duration=2.0,
        condition=ElapsedTimeCondition(10.0, label="at_10s"),
    )
)
# The top LiDAR's packets stop from 20 s until 25 s.
self.register_pre_tick(
    CommunicationLossAction(
        "lidar_top",
        condition=ElapsedTimeCondition(20.0, label="at_20s"),
        until=ElapsedTimeCondition(25.0, label="at_25s"),
    )
)
Argument Default
device None the configuration's device; None for every device
messages None the messages to stop, by the names the device's codec gives them (VehicleSpeed of a DBC, scan of a LiDAR); a list or one comma-separated string. None stops everything the device carries (camera frames, which have no name, included)
direction both to_ecu (what the bridge sends the ECU), from_ecu (what the ECU sends back), or both
duration None scenario seconds the action runs
until None a condition that ends the action
entity_name Ego the HILS ego

The action runs from its trigger until until fires or duration has passed, whichever comes first; with neither, until the scenario ends. Several actions add up: a device stops what any running action names. While data is stopped, the periodic messages are still encoded and only their frames are dropped, so an E2E counter or a sequence number moves on as an ECU's would on a cut bus. Stopping an ECU's command messages (from_ecu) makes the run's command go stale after hils.stale_s, and the ego brakes or holds it (hils.on_stale). The bridge carries everything again when the scenario ends, before its scenario_end steps, so they reach the ECUs. A device the bridge does not have ends the run with an error; on any ego but ego.entity=hils the action only logs a warning, so one scenario serves HILS and simulation runs alike.

Time

With clock: simulation (the default) every device runs on simulated time: a hilspy.Clock that the world's ticks advance by the simulated time that passed. Periodic messages go out as the clock passes their periods and a LiDAR revolution's packets as it reaches their times, so the ECU sees the traffic the simulation implies even when CARLA runs slower or faster than real time; the clock starts at the wall-clock time the bridge starts, so GNSS time stamps are plausible.

With clock: wall the devices run on real time: periodic messages from hilspy's threads, sensor data sent from a thread per device as it arrives (the newest data wins when a device falls behind). Use it when the simulation runs in real time and the ECUs check timing against their own clocks.

Sensors rendered by carla_canvas

canvas: canvas.yaml has carla_canvas render the bridge's cameras and LiDARs (3D Gaussian splatting, or any renderer behind its gRPC protocol) instead of the CARLA server. The bridge points typesafe_carla's sensor plugin at carla_canvas before anything listens, as canvas.config does for a run (autoware_carla_scenario.canvas.use_canvas). Its sensors rules can select the bridge's sensors by role_name, which is the device's name. Keep carla_canvas's asynchronous rendering (renderer.async, its default): the bridge does not tick the world, and the asynchronous path renders each frame the runner ticks. carla_canvas's client is installed with --with 'carla-canvas[client]>=0.2'.

Limitations

  • One run at a time: a second run that connects while one is served waits for it (and fails its own hils.connect_timeout_s meanwhile).
  • One ego. Run one scenario-hils per ego role (and runner.listen port) for more.
  • Sensors are the ray-cast LiDAR and the cameras; GNSS and IMU are signals of the ego's state, without CARLA's sensor noise.
  • A sensor's data reaches the devices on the tick after the one it was measured on when it arrives after that tick; an ECU command reaches the ego on the run's next tick after it arrives.