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:
- The runner spawns the ego and connects to the bridge (
hils.host,hils.port):start, with the ego's actor id. - The bridge starts the devices' periodic messages, runs the
scenario_startsteps (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 thewarmupsteps 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 answersready-- or fails the run when a step fails or nothing comes withinhils.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. - 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. - When the scenario ends the runner sends
end; the bridge removes its sensors, runs thescenario_endsteps, stops the periodic messages and answersended. 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:
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 alidar:MODELcodec: Hesai Pandar and Velodyne models). CARLA measures the arc a LiDAR sweeps in one tick; the bridge gathers the arcs into whole revolutions (byrotation_frequencyand 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 ofhorizontal_fov(360 degrees by default; CARLA turns the rays through azimuths [-fov/2, fov/2)), which may be anything in (0, 360], atrotation_frequencyrevolutions a second, which must be a finite positive number. Asensor_tickother than 0 is refused: CARLA sweeps only one world tick per measurement, so a LiDAR measured less often turns slower than itsrotation_frequency.dropoff_general_rate(the proportion of points CARLA drops at random) anddropoff_zero_intensity(the probability a point of zero intensity is dropped) must be in [0, 1]: CARLA clamps neither, so45would 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). Matchchannels, the field of view androtation_frequencyto the model. - Cameras (
sensor.camera.*, codecraw). Each image is one frame, inencoding:bgra(CARLA's raw image),bgr,rgb,jpegorpng.v4l2://makes it a V4L2 camera any client on the PC sees (hilspy built with itsv4l2feature, and v4l2loopback: hilspy's README, "Cameras");udp://ortcp://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_smeanwhile). - One ego. Run one
scenario-hilsper ego role (andrunner.listenport) 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.