Domain: sensors¶
1. Scope and release¶
Lidar, camera, radar, IMU, GNSS, magnetometer, joint encoders, with timing models (rate, latency, jitter). Sensors read the world state and the environment signals and write measurements that the bridges publish.
Sensor |
Release |
Notes |
|---|---|---|
IMU, joint encoders, 2D/3D lidar (Tier 0 and Tier 1) |
v0.2 |
needed for Nav2 |
RGB and depth camera |
v0.3 |
arms |
GNSS, magnetometer, barometer |
v0.4 |
drones |
Weather effects in lidar and camera |
v0.5 |
|
Radar, hardware-RT lidar (Tier 2), rolling shutter, lens model |
v0.6 |
cars |
2. Models per fidelity level¶
Each sensor has ground_truth (the substitute) and one or more physical levels.
Lidar
Level |
Content |
|---|---|
|
One ray per beam sample; range to the first hit; intensity from |
|
Adds per-ray timestamps within the scan so that sensor motion distorts the cloud (rotating and solid-state patterns) |
|
Adds beam divergence (several sub-rays per beam), multiple returns (strongest, last, dual), retro-reflector saturation, weather attenuation and backscatter from |
Camera
Level |
Content |
|---|---|
|
Rasterised colour, depth, instance segmentation through the shared renderer ( |
|
Adds exposure (scene radiance → electrons with exposure time and gain), photon shot noise and read noise, quantisation to bit depth, lens distortion (plumb-bob or equidistant), vignetting, motion blur from per-pixel velocity, rolling shutter by rendering row bands at different times |
|
Ray-traced shadows and reflections for the above |
Colour look. On a GPU a camera’s colour comes from the viewport’s realistic renderer: sun shadows,
sky, materials, photo textures, water, and the season (--camera-look realistic|simple,
--camera-season). A software device keeps the simple shading. Depth and instance ids are the same
either way (RasterLook test in test_raster). It is drawn by eye, not calibrated: exposure and
colour response are not those of any real camera, and rain and snow are in the picture only when the
season says so, separately from the --weather fog veil. With the sedan and the full town on an Iris
Xe the run went at about 1.3× real time, against 1.4× with the simple look.
Status of sensor_model in v0.6 (modules/sensors/include/lagrange/sensors/CameraModel.hpp, CPU
after the raster render, every tier with a Vulkan device): each part runs when
CameraSensorAPI_1 asks for it. Lens distortion (plumb_bob, equidistant) by remapping a wider
pinhole render (at most twice the size); vignetting as a fraction of cos⁴θ; a rotational
rolling shutter (each row from the camera’s orientation at its exposure, the angular velocity
held over the frame; translation left out); exposure as e = L·electronRate·t from the render’s
linear value, Poisson shot and Gaussian read noise, full well, gain and bit depth (EMVA 1288’s
linear model), then display encoding again; auto exposure aims the mean at 18 % of full scale
(sensor/<n>/exposure_time). camera_info carries the distortion. Checked in
test_camera_model: OpenCV’s lens formulas and their inverse, the photon-transfer variance
within 3 %, cos⁴θ, the skew of a vertical line under a pan, exposure and auto exposure. The sample
sedan’s front camera uses all of it. Owed: motion blur, a light model (absolute radiance),
colour filter array and demosaicing, translation in the rolling shutter, importing SDFormat
<distortion> and <noise>.
Since 1.2.x the per-pixel work runs on the GPU right after the render
(gpu/kernels/camera/camera_model.slang, in the same submission, so only the output’s size is
read back): the same rays, vignetting and tables as CameraModel::apply, which stays the CPU
reference (LAGRANGE_CAMERA_MODEL=cpu keeps it in a run). The noise draws the reference’s
Philox bits, six blocks per pixel as the per-row CPU stream takes them; Box-Muller is in float on
the GPU, double on the CPU, so a code differs only where the electrons sit on a rounding edge.
test_camera (GpuCameraModel) checks all but 0.1 % of the channels within 2 codes (on the RTX
4060 all but about 10 of 307 200 are the same code), the same ids, depth within 10⁻⁴ and the same
auto exposure. A thermal camera draws no colour (RasterCamera::setColour): it paints its own
from the ids.
The render does not hold up the run (since 1.2.x): the camera is a split step (architecture.md
§6): its step() submits the render (RasterCamera::begin), the scheduler runs the tick’s
other modules (the lidar, the radar, …) while the GPU draws, and the camera waits for it
(RasterCamera::finish) right before the first module that reads its images, or at the end of
the tick. The images are those of the step’s state, as before (test_raster,
FramesInFlightGiveWhatRenderGives: two frames in flight give what render() gives, byte for
byte). With the model on the GPU the render’s images stay in device memory for it; only the
model’s output crosses to the host. A fisheye camera, and a camera with faults, still draw in
step().
Thermal camera (after v1.0, ThermalCameraAPI_1 on a camera,
modules/sensors/include/lagrange/sensors/ThermalCamera.hpp). A camera with it draws the same
raster frame, and then reads each pixel’s instance id as a surface of known temperature and
emissivity:
a prim under a
ThermalAPI_1node (the longest path that holds it), else a node on the same body, is at that node’sthermal/<n>/temperature, with itsthermal:emissivity;a person (
HumanAPI_1) is at Fanger’s mean skin temperature in comfort while walking slowly, t_sk = 35.7 − 0.0275·M °C at M = 116 W/m² (Thermal Comfort, 1970): 32.5 °C, emissivity 0.98 (Steketee 1973). Clothing, cooler than skin, is not told apart;everything else is at the site’s ambient temperature, and so reads it whatever its emissivity;
where nothing is hit, the clear sky: T_sky = 0.0552·T_air^1.5 (Swinbank 1963), 16 K below 20 °C air.
What a surface sends is ε·B(T) + (1 − ε)·B(T_amb), with B Planck’s radiance over the camera’s band
(sensor:thermal:bandMin/bandMax, 8–14 µm by default; the exact series of Widger and Woodall
1976), and the camera reports the temperature a black body would need for it, as radiometric
cameras do. Each pixel then gets Gaussian noise of sensor:thermal:netd (1 σ, Philox). Outputs:
sensor/<n>/temperature (r32f, K) and image, the temperatures in a palette
(sensor:thermal:palette white_hot, black_hot or ironbow, over displayMin/displayMax or each
frame’s range, at least 4 K); depth and instance are as for any camera. ROS: /<name>/temperature/image_raw
(32FC1, K) beside /<name>/image_raw. URDF <sensor type="thermal"> or "thermal_camera", and
SDFormat’s thermal_camera, give a thermal camera with the defaults. It needs the site’s
temperature (--ambient-temperature, --weather temperature= or the profile’s
thermal.ambient_temperature) and refuses to start without it. Sample:
assets/robots/amr_diffdrive/amr_diffdrive_thermal.usda.
Checked in test_thermal_camera: the black-body fractions of Incropera et al. (Fundamentals of
Heat and Mass Transfer, Table 12.1) at four λT within 1·10⁻⁵ (the table’s C₂ is 14 388 µm·K,
CODATA’s 14 387.77), the band radiance against a direct integration of Planck’s law within 10⁻⁹
and Stefan–Boltzmann over all wavelengths within 10⁻⁶, the apparent temperature of a grey
surface, Swinbank’s sky, and a run that sees a 350 K node with ε 0.95 at its apparent temperature
(about 2.6 K low), the air and the sky, with the noise at its NETD. Not modelled: the atmosphere’s
own absorption and emission (small over tens of metres in clear air, not in fog; the visible fog
veil is left off for thermal cameras), the sun’s heating of surfaces and the ground, the sky
reflected in upward faces (surfaces reflect the ambient air), clouds, the optics’ blur and the
detector’s fixed-pattern noise and drift. There is no measured thermal image to compare with.
Since 1.2.x the per-pixel part runs on the GPU right after the render
(gpu/kernels/camera/thermal_camera.slang): each pixel’s surface temperature from a table of the
frame’s apparent temperatures by prim (worked out on the CPU, a few per frame), the noise from the
reference’s Philox bits (pixel u of a row takes block u of the row’s stream), the frame’s range
by atomics, then the palette. Camera::stepThermal stays the CPU reference
(LAGRANGE_THERMAL_CAMERA=cpu) and is used with a sensor model or a fisheye. The sums are in float
on the GPU: test_thermal_camera (TheGpuImageAgreesWithTheCpuReference, every palette, each
frame’s range and a fixed one) checks the temperatures within 10⁻³ K (3·10⁻⁵ K on the RTX 4060 and
on llvmpipe), the same ids and every colour within one code (all the same there).

Radar: ray-launched returns with radar cross-section from sensmat:radarCrossSectionDensity,
radial velocity from relative motion, a range–Doppler–azimuth detection list after a
constant-false-alarm threshold; rain attenuation from weather. Raw ADC cubes are not produced.
Status in v0.6 (modules/sensors/include/lagrange/sensors/Radar.hpp, RadarAPI_1): rays at
half the azimuth resolution over the field of view, each echo σ = ρ·r²·ΔΩ·cos θ (Lambertian
back-scatter of the body’s sensmat:radarCrossSectionDensity, 0.1 without one); echoes of one
object in one range cell are one detection (power-weighted range, angles, radial velocity from
the bodies’ twists); SNR by the radar equation against the effective noise floor, a fixed
threshold standing in for CFAR, noise of resolution/√(2·SNR); at most 64 detections, strongest
first. Ground-plane hits are dropped as clutter. Checked in test_radar: a plate’s σ = ρ·A
within 3 %, a 10 m/s Doppler, the detection range from the radar equation. ROS:
/<name>/detections PointCloud2 (x, y, z, velocity, rcs, snr). The sample sedan has a front
radar. Owed: rain attenuation, multipath and ghosts, a published RCS reference.
Viewer: a viewer that subscribes to a radar’s prim (SubscribeSensor; a RadarAPI_1 radar or an
imaging_radar) gets each new scan as a SensorFrame of points with fields x, y, z (sensor frame),
velocity, rcs and snr (no protocol change: PointCloudData names its fields). The viewport draws
them under Overlays → Radar detections (--overlays radar): boxes sized by RCS (−20 to +20 dBsm),
coloured by radial velocity on the design’s diverging map (viewer/client RadarScale.hpp), a
Doppler tick along the line of sight, and the field of view as a faint wedge to its range from the
prim’s attributes; the Sensors workspace has a Radar view (fan and range–azimuth).
Placement: on the CPU the rays and their echoes run in parallel (TBB) and are summed in ray order,
so the deterministic reference keeps its numbers bit for bit; with --lidar gpu the rays go to the
lidar’s kernel (bvh_traverse.slang, float ranges, Tier 1, not deterministic) and the echoes stay
on the CPU. test_radar checks the GPU finds the CPU’s detections within 5 mm, 1 mrad, 1 cm/s and
1 % of cross-section.
4D imaging radar (as built)¶
Kind imaging_radar (a built-in custom kind, §9; URDF <sensor type="imaging_radar"> with its
settings as leaf elements, USD CustomSensorAPI_1 with sensor:custom:kind = "imaging_radar"
and sensor:custom:param:<name>; RadarAPI_1 is unchanged) is a cascaded-MIMO automotive radar
of the kind that reports range, azimuth, elevation and Doppler per detection. It shares the
radar’s rays and echoes (Radar.cpp, sensors::createImagingRadar): the same settings as
RadarAPI_1 (max_range, azimuth_fov, elevation_fov, tx_power, antenna_gain,
noise_floor, detection_threshold, carrier_frequency, range_resolution,
velocity_resolution) plus:
Setting |
Meaning |
Default |
|---|---|---|
|
virtual channels (N_TX × N_RX) along each axis |
none: |
|
angle cells at boresight (rad) without elements |
0.035, |
|
d, in wavelengths |
0.5 |
|
sweep B (Hz): |
none |
|
T_c (s) and N_c: unambiguous velocity ±λ/(4·T_c), |
none |
|
the unambiguous velocity (m/s), directly |
λ/(4·T_c), else no folding |
|
ranges beyond it fold back, r mod R_u (m) |
no folding |
|
the ground’s power reflection |Γ|² for multipath ghosts |
0: none |
|
1: cells merge into their local peak; 0: every cell over the threshold is a detection |
1 |
|
detections per scan (1..4096) |
256 |
|
rad between rays |
half the finer angle cell at boresight |
The radar’s resolution cells: range cells of range_resolution, Doppler cells of
velocity_resolution after folding into [−v_max, v_max), and angle cells uniform in direction
sine (u = cos el · sin az, w = sin el) of width 1/(N·d) for N channels d wavelengths apart, the
Rayleigh limit λ/(N·d) at boresight that widens as 1/cos θ off it (S. Rao,
“Introduction to mmWave Sensing: FMCW Radars”, Texas Instruments mmWave training, 2017
(TODO(verify): its TI literature number): angle resolution θ_res = λ/(N·d·cos θ); range
resolution c/2B, v_max = λ/4T_c and v_res = λ/2T_f there too). Every echo (σ as the radar’s,
sensmat:radarCrossSectionDensity) falls in its cell; with peak grouping each cell climbs to its
strongest neighbour (±1 cell in each of the four dimensions) and a local peak takes in every
cell that climbs to it, so one target spread over neighbouring cells by the grid is one
detection, and two targets nearer than about a cell merge (two with an emptier cell between them
stay two). A peak whose summed signal Σσ/R⁴ (at the true ranges) beats the threshold by the
radar equation is a detection: range, angles, folded velocity as signal-weighted means, σ the
sum. Unlike the RadarAPI_1 radar, which makes one detection per object and range cell, an
object larger than a cell gives several, and objects in one cell share one. Ghosts: each echo
also returns by the fixed ground plane both ways, from the target’s mirror image below the
ground (range to the image, its Doppler with the mirrored velocity, power × |Γ|⁴), which is what
puts imaging radars’ ghost points under the road; the two one-bounce paths, which add coherently
to the direct return, and occlusion of the bounce are not modelled. Noise: range, velocity and
the angle cells over √(2·SNR), as the radar’s. Writes sensor/<n>/detections
(max_detections × 6: range, azimuth, elevation, velocity, rcs, snr; NaN beyond the count) and
sensor/<n>/count; ROS /<name>/detections is the radar’s PointCloud2 (x, y, z from range and
both angles, velocity, rcs, snr). CPU (deterministic) and GPU (--lidar gpu) rays as the radar’s.
Sample: assets/robots/sedan/sedan_4d_radar.usda (64 × 16 channels, 1 GHz, 256 chirps of 20 µs;
illustrative, not a product’s datasheet).
Checked in test_kinds_imaging_radar: a plate’s σ = ρ·A and its SNR by the radar equation, the
detection range the equation gives; the angle cell λ/(N·d); two targets 0.08 apart in sine merge
with 16 channels (cells of 0.125) and part with 64, two 0.3 apart part with 16; two targets
0.23 rad apart in elevation part with 16 elevation channels at their heights and merge with one;
a plate receding at 10 m/s reads −2 m/s at v_max = 6 m/s (from T_c = λ/24 or given); Doppler
alone parts two targets in one range and angle cell; a 20 m plate at 5 m with R_u = 15 m; the
ghost below the ground at |Γ|⁴ of the plate’s σ and at its mirror range; the CPU reference
repeats bit for bit; GPU against CPU (counts within 10 %, σ totals within 1 %, the strongest
detections within 5 cm, 5 mrad, 0.1 m/s). test_radar pins the RadarAPI_1 radar’s CPU
numbers bit for bit. Owed: speckle (a coherent sum per cell, which makes real point clouds of
walls dense), sidelobes and the array’s grating lobes, the one-bounce multipath paths, guard-rail
ghosts, CA/OS-CFAR against the clutter around a cell (the threshold is fixed over the noise
floor), rain attenuation, a published 4D-radar dataset to check against.
IMU: specific force and angular rate from body/*/acceleration and body/*/twist at the
sensor frame, plus white noise (noise density), bias instability (first-order Gauss–Markov),
rate random walk, scale-factor and misalignment errors, saturation at the range limits,
quantisation. Parameters map directly to Allan-variance datasheet values.
Status in v0.2 (modules/sensors/include/lagrange/sensors/ImuNoise.hpp): white noise (per
sample, or as a density N), turn-on bias, Gauss-Markov bias instability, rate random walk K,
saturation and quantisation, per channel; the names follow SDFormat’s <noise> elements, which
the URDF loader reads. Scale-factor and misalignment errors are not modelled yet. The bias is
saved with the module state and draws from its own Philox streams, so it leaves the white noise
of a run unchanged. test_imu_noise checks the Allan deviation of a 4-hour static record
against N²/τ + K²τ/3 (IEEE Std 952): within 1 % up to τ = 100 s and 4.3 % at 1000 s.
<dynamic_bias_stddev> σ_b is the deviation of the noise that drives the Gauss-Markov bias
(“the standard deviation of the noise used to drive a process to model slow variations in a sensor
bias”, SDFormat 1.12 noise.sdf), as Gazebo integrates it (gz-sensors GaussianNoiseModel.cc:
b ← e^(−dt/τ)·b + N(0, σ_b²·τ/2·(1 − e^(−2dt/τ)))), so the bias’s stationary deviation is
σ_b·√(τ/2): 1e-3 with τ = 3600 s gives 0.042. Until 2026-11-12 Lagrange took σ_b as the
stationary deviation itself.
GNSS: position from the body pose converted through the local frame to WGS84
(core/world/coords/), Gaussian horizontal and vertical error with first-order time
correlation, velocity error, fix-loss when sky view is blocked (ray casts to a fixed set of
sky directions as a stand-in for satellites), optional urban multipath bias.
Magnetometer: Earth field (constant vector given by the scene, or a world magnetic model
evaluated at the geo-origin; the model coefficients are a data file with an epoch), rotated into
the body frame, soft- and hard-iron distortion, noise, plus emi/{p}/b_field.
Timing (all sensors, from SensorAPI), as built: a sample is taken on the scheduler at
k / rate, and its ROS message goes out latency plus jitter later (Gaussian, cut at 3σ, never
out of order, on the simulation’s clock), still stamped with the sampling time. Set it with
sensor:latency and sensor:jitter, <latency> and <jitter> in a URDF’s <gazebo> sensor,
--sensor-timing NAME=LATENCY[,JITTER] or the run file’s sensor_timing:. The sensor’s own
sensor/<n>/<q> stay on time as the ground truth, as do /ground_truth and /tf; every other
consumer can have what the robot gets: lagrange_sensors’ delay line (sensors::DelayLine, only
for sensors with a delay) writes sensor/<n>/delayed/<q> for each of its numbers and images, and
sensor/<n>/delayed/stamp (s), the sampling time of what is there now, -1 before the first
arrives. Plugins read those like any signal, recordings and Python get them, and the viewer’s
lidar points and camera image are the delayed ones. The delay line ticks at 1 kHz, so a delay
rounds up to the next millisecond, and a signal commits only when a value arrives (SignalBus::hold).
Each sample’s delay is a function of the run seed, the sensor and
the sampling time, so runs and restored checkpoints repeat; the ROS bridge draws its own jitter
(same latency and spread, other numbers) and goes out on its publish tick. Sampling instants do
not jitter.
3. Signals¶
// modules/sensors — declare()
for (auto& s : world.instancesOf("SensorAPI_1")) {
auto n = name(s); auto b = bodyOf(s);
d.input({.name = fmt("body/{}/pose", b), .type = SignalType::Pose, .unit = units::m});
d.input({.name = fmt("body/{}/twist", b), .type = SignalType::Wrench, .unit = units::m_per_s});
d.input({.name = fmt("sensor/{}/contamination", n), .type = SignalType::Scalar, .unit = units::one,
.optional = true, .defaultValue = 0.0}); // weather
if (auto load = powerLoadOf(s))
d.input({.name = fmt("load/{}/powered", *load), .type = SignalType::Bool, .unit = units::one,
.optional = true, .defaultValue = 1.0}); // electrical: brownout turns sensors off
d.output({.name = fmt("sensor/{}/meta", n), .type = SignalType::Bytes, .unit = units::one}); // stamp, sequence, status
if (has(s, "LidarAPI_1")) {
d.input ({.name = "env/extinction/nir_905", .type = SignalType::Scalar, .unit = units::per_m,
.optional = true, .defaultValue = 0.0});
d.input ({.name = "env/rain_rate", .type = SignalType::Scalar, .unit = units::m_per_s,
.optional = true, .defaultValue = 0.0});
d.output({.name = fmt("sensor/{}/points", n), .type = SignalType::PointCloud, .unit = units::m});
}
if (has(s, "CameraSensorAPI_1")) {
d.input ({.name = "env/extinction/visible", .type = SignalType::Scalar, .unit = units::per_m,
.optional = true, .defaultValue = 0.0});
d.input ({.name = "env/solar_irradiance", .type = SignalType::Scalar, .unit = units::W_per_m2, .optional = true});
d.input ({.name = "env/sun_direction", .type = SignalType::Vec3, .unit = units::one, .optional = true});
d.output({.name = fmt("sensor/{}/image", n), .type = SignalType::Image, .unit = units::one});
d.output({.name = fmt("sensor/{}/depth", n), .type = SignalType::Image, .unit = units::m});
}
if (has(s, "RadarAPI_1")) {
d.input ({.name = "env/radar_attenuation_77ghz", .type = SignalType::Scalar, .unit = units::per_m,
.optional = true, .defaultValue = 0.0});
d.output({.name = fmt("sensor/{}/detections", n), .type = SignalType::PointCloud, .unit = units::m});
}
if (has(s, "ImuAPI_1")) {
d.input ({.name = fmt("body/{}/acceleration", b), .type = SignalType::Wrench, .unit = units::m_per_s2});
d.input ({.name = fmt("emi/{}/e_field_rms", n), .type = SignalType::Scalar, .unit = units::V_per_m,
.optional = true, .defaultValue = 0.0});
d.output({.name = fmt("sensor/{}/specific_force", n), .type = SignalType::Vec3, .unit = units::m_per_s2, .frame = "sensor"});
d.output({.name = fmt("sensor/{}/angular_rate", n), .type = SignalType::Vec3, .unit = units::rad_per_s, .frame = "sensor"});
}
if (has(s, "GnssAPI_1")) {
d.output({.name = fmt("sensor/{}/geodetic", n), .type = SignalType::ScalarArray, .unit = units::one,
.arrayLength = 3}); // latitude (rad), longitude (rad), height (m): see note
d.output({.name = fmt("sensor/{}/velocity_enu", n), .type = SignalType::Vec3, .unit = units::m_per_s});
d.output({.name = fmt("sensor/{}/fix", n), .type = SignalType::Int, .unit = units::one});
}
if (has(s, "MagnetometerAPI_1")) {
d.input ({.name = fmt("emi/{}/b_field", n), .type = SignalType::Vec3, .unit = units::T,
.optional = true, .frame = "body"});
d.output({.name = fmt("sensor/{}/magnetic_field", n), .type = SignalType::Vec3, .unit = units::T, .frame = "sensor"});
}
}
Implementation note (v0.2): a lidar writes sensor/{n}/ranges (ScalarArray, one range per
beam, m) instead of a PointCloud handle, because the bus’s buffer table for handle types does not
exist yet. Beams are rings of columns (LidarLayout in core/world: SDFormat’s horizontal and
vertical samples and angles, ring after ring from the lowest); a single ring is a 2D scanner. The
server turns ranges into the viewer’s point frames, and the ROS bridge into sensor_msgs/LaserScan
for 2D lidars or an organised sensor_msgs/PointCloud2 (x, y, z, intensity, ring) for 3D ones.
On Tier 0, rays are cast on the CPU with the exact closed-form tests in double, and Embree’s
bounding-volume hierarchy (user geometry: a padded bounding sphere per shape; the shapes that
have never moved in a hierarchy built once, the ones that have in a second one rebuilt when they
move) only skips the shapes a ray cannot reach; planes are tested directly. The result
is bit-identical to testing every shape (ShapeCaster, test_shape_caster), beams run in
parallel with TBB, and the run stays deterministic. --lidar auto uses it: it outruns the GPU
round trip for scans of this size (docs/design/benchmarks.md). On Tier 1 (--lidar gpu), rays
are cast by gpu/kernels/lidar/bvh_traverse.slang: the same closed-form tests in float, one
thread per beam, through a bounding-volume hierarchy built on the CPU (median split, uploaded)
and refitted to each scan’s shapes, rebuilt when refitting has grown its inner boxes’ area by a
quarter or after 30 scans. Shapes are taken relative to the sensor and combined with its orientation in double
before the conversion to float, and spheres and cylinders use the distance-to-line form of the
discriminant (Ray Tracing Gems, ch. 7), so grazing rays keep their precision. Range limits and
Philox noise are applied on the CPU after the cast, keyed by the same module name, so both tiers
add the same noise. The GPU lidar declares itself not deterministic; the server uses it only when
the run takes ROS input, or with --lidar gpu (acceptance criterion 6 is
modules/sensors/test/test_lidar_tiers.cpp: 100 000 random beams in 400 random shapes give the
same shape for every beam and a worst range error of 0.16 mm on an Intel Iris Xe and 0.31 mm on
llvmpipe, within 300 m). The IMU also writes sensor/{n}/orientation (ground truth) for
sensor_msgs/Imu. Sensors come from Gazebo <sensor> blocks of a URDF until SensorAPI_1 exists.
Note on GNSS: a three-element array with mixed units (rad, rad, m) cannot carry one Unit. The
design options are three scalar signals (latitude, longitude, height) or a dedicated
Geodetic signal type. The listing shows the problem on purpose; RFC 0001 unresolved question 2
recommends three scalar signals.
4. Step size¶
The sensors module is scheduled at the smallest period any sensor needs (default 1 ms when an
IMU is present, otherwise 1 / max(rate)), and each sensor fires on its own schedule within it.
Rendering sensors (camera, lidar, radar) submit GPU work and collect results one or more ticks
later; the latency model absorbs this, and a sensor whose configured latency is shorter than the
measured pipeline delay raises a warning in real-time mode. In deterministic mode the scheduler
waits for the result so that delivery ticks do not depend on GPU timing.
5. Substitutes and contract¶
Contract: every sensor/{s}/* output above.
Profile token |
Kind |
Behaviour |
|---|---|---|
|
ideal |
No rendering. IMU, GNSS, magnetometer and encoders publish exact values with correct timing. Lidar and camera outputs are published as empty buffers with valid metadata, and |
|
replay |
Sensor outputs from MCAP |
The profile key sensors.only enables physical simulation for the named sensors and ground
truth for the rest, which is the common case of “simulate the lidar, skip the cameras”.
6. Placement¶
Sensor |
Tier 0 |
Tier 1 |
Tier 2 |
|---|---|---|---|
Lidar |
Embree |
|
|
Camera |
shared raster renderer on a software Vulkan device; documented as slow |
GPU raster |
GPU raster + optional RT |
Radar |
Embree (shapes) with TBB |
compute BVH ( |
ray query |
IMU, GNSS, magnetometer, encoders |
CPU |
CPU |
CPU |
Output buffers stay on the GPU when a consumer can take them: the viewer through shared memory
after one readback, ROS 2 through rosidl::Buffer with the CUDA backend
(ros-lyrical-cuda-buffer) when bridges.ros2.gpu_buffers is on. A Vulkan-to-CUDA hand-off
needs external-memory interop in gpu/hal/; that is planned for v0.6 and tracked as a risk (R11).
The same kernels serve all three lidar tiers at the level of “one ray → one hit record”; only the traversal differs. Tests compare tier outputs on the same scene (section 7).
7. Validation¶
Test |
Reference |
Tolerance |
|---|---|---|
Lidar geometry |
analytic scenes (plane, sphere, corner) |
range error < 1 mm before noise |
Tier agreement |
same scene on Tier 0, 1, 2 |
identical hit prim for > 99.9 % of rays; range within 1 mm |
Lidar intensity |
Lambertian target at known range and angle |
2 % |
Camera projection and distortion |
synthetic checkerboard; calibrate with OpenCV and recover the intrinsics |
reprojection error < 0.1 px |
Camera noise |
photon-transfer curve (variance vs mean) |
slope within 3 % of the configured gain |
Rolling shutter |
skew of a vertical edge at known speed |
1 px |
IMU noise |
Allan deviation of a 4-hour simulated static record vs configured parameters |
within the estimator’s confidence band |
GNSS |
error statistics and correlation time |
5 % |
Timing |
measured rate, latency and jitter histograms |
1 base tick |
Sim-vs-real (per release) |
public datasets with ground truth and sensor specifications (candidates: an indoor 2D-lidar AMR dataset for v0.2; an automotive dataset for v0.6; choose and check licenses) |
reported per metric; thresholds set from the dataset |
8. GNSS, magnetometer and barometer (v0.4)¶
GeoSensors.cpp in lagrange_sensors, from GnssAPI_1, MagnetometerAPI_1 and
BarometerAPI_1 prims. They place the sensor on the Earth through the world’s geo origin
(world.geo_origin in a profile, --geo-origin), a site parameter with no default: without one
they are left out and the server logs why.
Sensor |
Signals |
Model |
Check |
|---|---|---|---|
GNSS |
|
The antenna’s pose through the geo origin, velocity with the lever arm; white noise per fix |
exact against |
Magnetometer |
|
World Magnetic Model 2025 main field ( |
within 0.001 nT of NOAA’s 100 test points ( |
Barometer |
|
ICAO standard atmosphere at the sensor’s ellipsoidal height (troposphere); white noise |
ICAO table values ( |
Not yet: GNSS outages, multipath and latency; crustal field, hard- and soft-iron effects; the
geoid (ellipsoidal height stands for altitude above mean sea level); the site’s weather instead of
the standard day (v0.5); URDF and SDFormat <sensor type="gps|magnetometer|altimeter"> import.
Lidar intensity from materials (as built)¶
sensor/<name>/intensities holds each beam’s intensity next to ranges; it reaches /scan’s
intensities, /points’ intensity and the viewer. It is the reflected power relative to a white
wall head-on at 1 m, capped at 1: ρ·((1−s)·cos θ + s·lobe(θ))·(1 m / r)², with ρ the reflectivity at the
lidar’s wavelength (905 or 1550 nm), θ the incidence angle from the true surface normal, s the
specular fraction and lobe a mirror’s, 2° wide (illustrative). A retroreflector gives 100·ρ·(1 m / r)² at any angle.
A beam passes a surface with transmission by chance (seeded per step and beam; CPU only: the GPU tier gets the first hit).
A surface with a material gives no return when its power is under what the lidar needs at its
range limit for a target of max_range_reflectivity (default 0.1), so water and dark surfaces drop
out at a slant or from far. Surfaces with no material keep ρ = 0.5 and always return.
Give a surface a material with SensorMaterialAPI_1 on a collider prim, an ancestor or its bound
material (sensmat:preset, then any authored attribute), or in URDF:
<gazebo reference="deck">
<sensor_material preset="asphalt" reflectivity_905="0.12"/>
</gazebo>
Presets (default, water, glass, mirror, asphalt, concrete, white_paint, black_rubber,
retroreflector) are illustrative orders of magnitude, not measurements. The formula is tested against
its closed form; a real lidar’s intensity channel has not been compared with it.
Lidar motion distortion (as built)¶
A rotating lidar’s columns fire one after another through the scan, so a moving robot’s scan skews.
Column c of n fires at the fraction (c + 1) / n of the scan, from the sensor’s pose at that moment,
interpolated between the last scan’s end and this one’s (linear position, slerp). So a motion that
changes within one scan is smoothed over it. On by default on both lidar tiers
(sensor:lidar:motionDistortion, or <ray><motion_distortion>0</motion_distortion></ray> in a URDF’s
<gazebo> sensor; an SDFormat file cannot turn it off yet). Only the sensor’s motion counts: other bodies stay where they are at the scan’s end, and
every lidar sweeps once per output, whatever sensor:lidar:rotationRate says. The first scan of a run has
no motion to use.
So that the scan can be undone, /scan is stamped when its first column fired, with time_increment
and scan_time, and /points the same with a time field (float32, s after the stamp). With distortion off,
the stamp is the scan’s end and those are zero (scan_time stays).
Lidar scan patterns (as built)¶
A lidar’s beams are a grid by default: samples columns evenly spaced in azimuth from min_angle to
max_angle, vertical_samples rings evenly spaced in elevation (lagrange/world/LidarLayout.hpp), at most 2²² beams
in a scan (a count below 1 or over that is refused).
Three opt-in patterns change where the beams go; without their settings every beam stays exactly
where it was (tested bit for bit). All three reach /points (sensor_msgs/PointCloud2) and the
viewer; /scan stays for 2D grids only.
Channel table (Velodyne style). Real multi-beam lidars space their channels unevenly (denser near
the horizon). List one elevation per channel, in radians, in any order; the rings are these sorted
from the lowest up (the ring field of /points), and vertical_samples and the vertical angles are
then ignored:
<ray>
<scan>
<horizontal><samples>1800</samples><min_angle>-3.14159</min_angle><max_angle>3.14159</max_angle></horizontal>
<vertical><angles>-0.4363 -0.0175 0.0262 -0.1396 0.2618 -0.0087</angles></vertical>
</scan>
</ray>
Settings vertical_angle_0, vertical_angle_1, … (rad).
Flash lidar (solid state). A focal-plane array fires every beam at once, so its scan has no motion
distortion (motion_distortion is set to 0 and /points’ time is 0). Its beams are a pinhole’s pixels:
evenly spaced on the image plane, so the tangent of a beam’s angle, not the angle, is linear in its
column and ring; min_angle/max_angle and the vertical angles are the outer beams’ angles and must lie
within ±π/2 (the run refuses to start otherwise). /points is organised as rings × columns.
<ray>
<pattern>flash</pattern>
<scan>
<horizontal><samples>320</samples><min_angle>-0.5236</min_angle><max_angle>0.5236</max_angle></horizontal>
<vertical><samples>240</samples><min_angle>-0.3927</min_angle><max_angle>0.3927</max_angle></vertical>
</scan>
</ray>
Setting pattern 1.
Rosette (Livox Mid-40/Mid-70 style non-repetitive scan). The beam passes two wedge (Risley) prisms turning at different, incommensurate speeds; to first order each deflects it by a fixed angle δᵢ in the direction its wedge points, and the deflections add as vectors (Marshall, “Risley prism scan patterns”, Proc. SPIE 3787, 1999; Livox’s own account: Liu, Zhang and Hong, “Low-cost retina-like robotic lidars based on incommensurable scanning”, IEEE/ASME Trans. Mechatronics 27(1), 2022):
δ(t) = δ₁ (cos ω₁t, sin ω₁t) + δ₂ (cos ω₂t, sin ω₂t)
|δ| is the beam’s angle off the sensor’s x axis, its direction the way round it. With equal prisms the
beam traces petals through the centre (|δ| = 2δ|cos((ω₁ − ω₂)t / 2)|); since the speeds are
incommensurate the petals never repeat, so each scan goes on where the last stopped and the field fills
up with integration time. Each scan holds the last samples points fired, one after another at
rosette_point_rate, the last at the moment the scan is taken: point i fires (samples − 1 − i) /
point_rate before it, which is the time of /points after its stamp (the first point’s firing),
and the pose motion distortion casts it from. The prisms’ angles follow the points: scan k’s point i
is at the pattern’s t = (k·samples + i) / point_rate. Both are the real picture only when
samples = point_rate / update_rate (the defaults: 10000 = 100 000 / 10 Hz), and the run warns
otherwise: with fewer, each scan covers only the end of its period (2000 points at 100 000/s and
10 Hz span 20 ms of the 100 ms) and the pattern runs slower than the clock; with more, scans overlap
and their first points take the last scan’s pose. The beams change every scan, so the module also
writes sensor/<name>/directions (ScalarArray, 3 × samples, unit vectors x y z in the sensor frame, per
beam) and /points and the viewer take each scan’s beams from it. /points is one row of samples
points; each point’s time is when it fired (with motion distortion on, the default, each point is cast
from the sensor’s pose at that moment).
<ray>
<pattern>rosette</pattern>
<scan><horizontal><samples>10000</samples></horizontal></scan>
<rosette>
<fov>0.6702</fov> <!-- full cone angle, rad: 38.4°, Mid-40 -->
<point_rate>100000</point_rate> <!-- points/s -->
<speed_1>763.83</speed_1> <!-- rad/s, prism 1 -->
<speed_2>-488.42</speed_2> <!-- rad/s, prism 2; opposite sign: counter-rotating -->
<prism_ratio>1</prism_ratio> <!-- δ₂/δ₁; ≠ 1 leaves a hole of |δ₁ − δ₂| at the centre -->
</rosette>
</ray>
Setting |
Unit |
Default |
|---|---|---|
|
— |
2 for the rosette |
|
points per scan |
10000 (when the rosette’s URDF gives none) |
|
rad, full cone (δ₁ + δ₂ = fov / 2) |
0.670206 (38.4°: Livox Mid Series User Manual v1.2, 2019.08, table 1.2.1) |
|
1/s |
100000 (same table) |
|
rad/s |
2π·7294/60, −2π·4664/60 (7294 and −4664 rpm: the prototype in Livox’s paper, Liu, Zhang and Hong, arXiv:2006.11034, appendix B; Livox does not publish the Mid-40’s own, so a recorded Mid-40 pattern may differ) |
|
δ₂/δ₁ |
1 |
With the defaults one 0.1 s scan hits under half of the disc’s 0.5° cells and a second about all of
them; the shape is checked against the closed forms (reach δ₁ ± δ₂, the radial distribution
P(|δ| ≤ R) = 1 − (2/π) arccos(R / 2δ) for equal prisms, coverage growing every scan, scans not
repeating, the same scan and beam always the same direction) and both lidar tiers cast it
(test_lidar_patterns). Not a measured Livox pattern: the first-order model leaves out the prisms’
refraction nonlinearity (third-order Risley theory) and the Mid-40’s actual speeds; the Avia’s own
non-repetitive pattern (70.4° × 77.2°, six beams) is not modelled.
These patterns come from all three formats (RFC 0015): URDF (<gazebo reference=L><sensor type="ray|lidar">, as above); SDFormat, whose <lidar> has no place for them, from Lagrange’s custom
elements <lagrange:pattern>, <scan><vertical><lagrange:angles> and <lagrange:rosette> (or the
plain names, as in URDF; formats.md §9.3); and USD, LidarAPI_1’s scanPattern flash or rosette,
channelElevations and rosette:fov, pointRate, speed1, speed2, prismRatio (formats.md §3.8).
The rosette’s USD attributes have no fallback: unauthored, the values above are assumed and the
loader says so. lagrange_import writes all of it, and the round trip URDF → USD → run gives the same
beams bit for bit (OpticsImport.PatternsAndLensesSurviveTheTripThroughUsd).
Fisheye cameras (as built)¶
A camera can be a fisheye up to all round (lagrange/world/FisheyeLens.hpp,
modules/sensors/src/Fisheye.cpp), for surround-view rigs and wide-angle navigation cameras. The
projection is Kannala–Brandt as OpenCV’s fisheye module and ROS write it: a ray θ off the optical axis
lands f·θ_d from the principal point, θ_d = θ(1 + k₁θ² + k₂θ⁴ + k₃θ⁶ + k₄θ⁸) (Kannala and Brandt,
“A generic camera model and calibration method for conventional, wide-angle, and fish-eye lenses”,
IEEE TPAMI 28(8), 2006); all k = 0 is the ideal equidistant lens, r = fθ. horizontal_fov is then the
lens’s angle across the image’s width (f = (width/2) / θ_d(fov/2), as Gazebo’s wide-angle camera with
scale_to_hfov); the lens sees nothing beyond cutoff_angle (half-angle, default the larger of fov/2
and 90°, as Gazebo), where pixels are black, at infinite range, with no instance. Up to 2π. A cutoff
below fov/2 is taken the same way from URDF, SDFormat and USD: the angle across the width stays the
lens’s and the pixels beyond the cutoff are black (the example below cuts off 0.05 mrad inside its
100°).
<sensor name="fisheye" type="camera">
<camera>
<horizontal_fov>3.4907</horizontal_fov> <!-- 200° across the width -->
<image><width>1024</width><height>1024</height></image>
<lens>
<type>equidistant</type> <!-- or kannala_brandt; gnomonical is the pinhole -->
<cutoff_angle>1.7453</cutoff_angle> <!-- rad -->
<k1>-0.013</k1><k2>0.0042</k2><k3>-0.0011</k3><k4>0.0001</k4> <!-- Lagrange's: OpenCV fisheye -->
</lens>
</camera>
</sensor>
Settings projection 1, distortion_model 2, distortion_k1..distortion_k4, fisheye_cutoff (rad).
A lens whose θ_d turns back before the cutoff is refused.
How it is drawn: a pinhole render cannot reach 180°, so the camera renders the faces of a cube around
itself (front, right, left, down, up, back: only those some pixel looks through, and of each only the
window those pixels need, at the fisheye’s focal length so the centre keeps its resolution), then each
output pixel takes the face its ray crosses: colour bilinear in linear light, depth and instance id from
the nearest render pixel. Depth is the range along the pixel’s ray (m), not along the optical axis,
which means nothing at 90° and beyond. /<name>/camera_info is distortion_model: equidistant,
D = [k1, k2, k3, k4], K with that f (the ROS camera_calibration fisheye convention), so
cv::fisheye::undistortImage takes it as is. A 200° fisheye costs five renders instead of one.
Tested: projection and its inverse round trip within 1 µrad up to 150° for realistic k
(test_fisheye), the face choice and the range from synthetic renders, and a 240° camera drawn on the
Vulkan device (llvmpipe in CI) sees a cube beside it at 90° and one behind it at 112° where the formula
puts them, at their ranges.
Not yet: vignetting, rolling shutter and exposure together with a fisheye (refused at start); a fog
field’s veil and the detections/stereo_camera/event_camera kinds, which still take the camera as a
pinhole; other lens types (stereographic, equisolid, orthographic).
From SDFormat (RFC 0015): <lens><type>equidistant</type> and <cutoff_angle> as SDFormat defines
them, k1..k4 from <lens><lagrange:k1>..<lagrange:k4> (or plain <k1>.., as in URDF; formats.md
§9.3). From USD: CameraSensorAPI_1’s lensType = "equidistant" selects this fisheye, with k1..k4 from
distortionModel = "equidistant" and distortionCoeffs and the cutoff from cutoffAngle; the angle
across the width comes from UsdGeomCamera’s focal length f and horizontal aperture w through the lens,
2 θ_d⁻¹(w / 2f), so a 200° lens has a positive focal length (formats.md §3.8). Without lensType, an
equidistant distortionModel stays what it was: the same distortion on the pinhole render, below
about 160°. lagrange_import writes the lens, and the round trip gives the same k and cutoff exactly
and the same angle to the float precision of focalLength.
Sensor faults (as built)¶
To test how a robot stack copes with a failing sensor, any sensor can be given faults: the built-in
types, the built-in custom kinds of §9 and a plugin’s custom sensors alike. They are off unless asked
for, and change what every consumer gets: ROS, plugins, the delay line, recordings, Python and the
viewer all read the faulted sensor/<n>/<q>. Ground truth stays where it always is, in the bodies’
and joints’ signals (/ground_truth/odom, /tf).
Mode |
What the sensor delivers |
Keys (besides |
|---|---|---|
|
nothing for each lost sample (no new value: its stamp stays, so no ROS message goes out), or NaN with |
|
|
the last value it delivered before the window, again at every sample |
|
|
its value plus |
|
|
its value plus |
|
|
its value plus Gaussian noise of standard deviation |
|
|
nothing (or NaN) from |
|
at (s, default 0) and for (s, default for good) set the window, compared with each sample’s time
(the end of the step that takes it), in whole nanoseconds. value, rate and sigma are in the
quantity’s own unit (rad/s for an IMU’s angular_rate, m for a lidar’s ranges); they apply to every
component, or to one with component (0 = x). A fault names one quantity, or all of the sensor’s
(*, or no quantity): dropout, stuck and disconnect can, bias, drift and noise need one.
Images and point buffers take dropout, stuck and disconnect only; for them nan means nothing.
So do Bool and Int quantities (a valid flag, a count): bias, drift or noise on one stops the
start, and with nan their dropped samples are held instead (no new value), so a Bool still reads 0
or 1 and a count a whole number.
Faults act on samples: a sensor that samples slower than the run (a Wi-Fi scan every 2 s, a 1 Hz
GNSS) shows dropout, stuck, bias, drift and noise from its first sample inside the window,
while fault/active turns 1 at at itself; a window that opens and closes between two samples
changes nothing. disconnect is the exception with nan=1: its numbers read NaN from at (a new
value at that step), not from the next sample; without nan nothing new comes from at either way.
A sensor’s quantities in one fault go together: with imu=dropout the whole IMU message is lost,
while imu:angular_rate=dropout keeps the message, which then carries the last angular rate (the ROS
bridge sends an IMU message when specific_force is new).
Set them with --sensor-fault NAME[:QUANTITY]=MODE[,key=value...] (repeatable), the run file’s
sensor_faults:, a profile’s sensor_faults: (which replaces the command line’s when given), or
Python’s Simulation(..., sensor_faults=[...]):
lagrange_server --sensor-fault imu:angular_rate=bias,value=0.02,at=5,component=2 \
--sensor-fault front_lidar=dropout,at=10,for=2,probability=0.3
sensor_faults: # profile or run file
- {sensor: imu, quantity: angular_rate, mode: drift, rate: 0.001, at: 30}
- {sensor: gps, mode: disconnect, at: 60}
Each faulted sensor also writes sensor/<n>/fault/active (Bool: a fault’s window is open) and
sensor/<n>/fault/dropped (Int: samples lost so far), which --ros-topics can publish, e.g.
{signal: sensor/imu/fault/active, topic: /imu/fault, type: std_msgs/Bool}. A fault that names
no sensor, or a quantity the sensor does not have, stops the start and lists what it has.
How: sensors::withFaults (modules/sensors/src/Faults.cpp) wraps each sensor module the server
adds, the built-in ones and plugins’ own-domain modules, and applies the faults to its outputs after
its step and before they commit: a dropped sample is held (SignalBus::hold, so readers and its
stamp stay as they were), the others are written into the pending value. The wrapper keeps what the
sensor wrote last without the faults and puts it back before each step, so a module that does not
write every step never gets a fault twice. With no faults, nothing is wrapped and nothing costs; with
faults, every sensor module goes through one more call per step, and each faulted number is copied
twice per step. The wrapped module keeps its name, seed and order, so its own noise is unchanged.
Random draws (which samples a probability loses, a noise burst) come from
random::Stream(seed, step, 0xFA170000 + 2f [+ 1]) of the sensor module’s own seed and step index
for fault f: a run and a restored checkpoint repeat them, and another run seed draws others. The
wrapper’s state (the stuck values, the clean values, the counts) is saved with the module’s.
The ground-truth substitute (sensors: {enabled: false, substitute: ground_truth}) is faulted too.
A fault is in the hardware between the sensor and the robot (a cable, a supply, a mount), not in the
sensor’s model, which is what the substitute replaces: a run that tests a planner at ground truth
speed against a lost GPS still loses it. To have clean ground truth, give no faults; the bodies’
signals are never faulted. A replay (--replay) shows what was recorded, faults included, and adds
none. A plugin that substitutes the sensors domain itself is not wrapped.
Faults are set when the run starts; at and for schedule them within it. Applying a profile with
other sensor_faults changes them, restarting the run at t = 0 as any profile does. Tests:
modules/sensors/test/test_faults.cpp (every mode on a lidar, an IMU and a buffer, determinism,
saved states, the substitute), server/test/test_sensor_faults.cpp, Plugins.APluginSensorCanBeFaulted.
9. Built-in custom sensor kinds¶
A custom sensor (SensorType::Custom: a URDF/SDFormat <sensor type="KIND"> Lagrange has no
type for, or USD CustomSensorAPI_1 with sensor:custom:kind) whose kind is listed here is
simulated by lagrange_sensors itself, with no plugin (sensors::isBuiltinKind,
modules/sensors/src/kinds/). Its numbers are World::Sensors::settings (SI units) and its text
World::Sensors::text, by the parameter’s path (<range><max> is range/max). Every kind runs at
the sensor’s update rate (above 0 Hz: Gazebo’s 0, as fast as possible, is refused; a period of
whole nanoseconds is kept, 400 Hz runs every 2.5 ms, and any other goes to whole milliseconds,
or whole 10 µs below 1 ms, as the cameras’ do: 30 Hz runs every 33 ms, so that its steps line up
with the other modules’; the built-in lidar, IMU, radar, GNSS, magnetometer and barometer
likewise), writes sensor/<name>/..., draws its noise from the run’s seed (the
CPU reference stays bit-reproducible), and under the sensors domain’s ground_truth substitute
reads exactly. On a robot added to a run (spawned, --add-robot), whose bodies, joints,
sensors and components are renamed <robot>_<name>, the names a kind’s text gives (joints,
bodies, batteries, tethers, cameras, signals) are its own robot’s: left_wheel_joint on a copy
added as copy is copy_left_wheel_joint; a kind that takes the stage’s only battery or
tether takes its own robot’s when the run has several. No schema changes: these are additions
under RFC 0007. The sample plugins’ kinds
(tof, ultrasonic, thermistor, ir_thermometer) stay plugins; a plugin that implements one
of the kinds below as well would write the same signals, and the run refuses to start.
Ranges. A number parameter outside the range the sensor catalog gives it
(modules/sensors/catalog/sensor_catalog.yaml, the min/max of the tables below) refuses the
run, naming it: battery_monitor batt: voltage/resolution = -0.5: must be at least 0 V. None is
clamped or read as “not given” any more (wheel_radius 0 was “from the colliders”, a negative
resolution turned quantisation off, samples 0 became 1): leave a parameter out for its
default. The code’s table (src/kinds/ParamRanges.cpp) is the catalog’s row for row
(test_sensor_catalog, which also starts every kind with each value just outside).
Defaults. A default taken from a part’s data sheet cites the document (part number, document
number and revision, where it says so); the checks of 2026-11-12 against the documents are listed
in docs/plan/sensor-defaults-verification-2026-11-12.md. A default marked illustrative has no
primary source because it is a property of the installation or the scene, not of a part (a
shunt’s resistance, a tag’s size, a mast’s height, a threshold the integrator picks), or because
the maker publishes no figure for it (the noise of an optical flow chip, the prisms’ speeds of a
Livox lidar): give your part’s or your log’s figure.
ROS topics of the built-in kinds¶
Every custom sensor’s numbers are on ROS 2 from the first run, with no mapping file, as the
cameras, lidars and IMU are (bridges/ros2/src/KindTopics.cpp, ros2::kindTopics): each on
/<sensor>/<quantity>, stamped when it was sampled, through the sensor’s sensor:latency and
jitter like any sensor topic, faulted as the signals are (sensor faults), and built only while
someone subscribes. A kind whose device has a standard ROS message publishes that message; every
other number the sensor writes goes out by its signal type and unit:
Kind |
Topic |
Message |
Notes |
|---|---|---|---|
|
|
|
INFRARED (light), |
|
|
|
INFRARED, |
|
|
|
|
|
|
|
ULTRASOUND, |
|
|
|
|
|
|
|
from −fov/2, |
|
|
|
|
|
|
|
ROS’s signs and units: current negative discharging, |
|
|
|
the joint’s name and its |
|
|
|
in the signal’s frame; |
|
|
|
x, y the integrated flow (rad) about |
|
|
|
in the camera’s |
|
|
|
“Images of kinds” above |
Every other number, any kind (plugins’ kinds too):
Signal |
Message |
|---|---|
Bool |
|
Int |
|
Scalar in K |
|
Scalar in Pa |
|
Scalar |
|
Scalar |
|
any other Scalar |
|
ScalarArray |
|
Vec3 |
|
Pose |
|
Wrench in m/s |
|
So a humidity_sensor publishes /<n>/relative_humidity and /<n>/temperature, an airspeed
/<n>/differential_pressure (FluidPressure), /<n>/airspeed, /<n>/indicated_airspeed,
/<n>/temperature, an anemometer /<n>/wind_velocity (Vector3Stamped in <n>),
/<n>/wind_speed, /<n>/wind_direction, a uwb /<n>/ranges (no standard ROS message
carries UWB ranges), a sensor with faults /<n>/fault/active and /<n>/fault/dropped, and every
kind its /<n>/valid as a std_msgs/Bool (the power kinds, battery_monitor, current_sensor,
voltage_sensor, esc_telemetry and tension_sensor, keep valid a Scalar 0/1 on the bus for
the readers they had, and publish it as a Bool like the others; it was a Float64 before). Not
published:
sensor/<n>/delayed/... (the topics are delayed themselves), an image’s intrinsics and
position (its camera_info), and sensor/<n>/contamination, the weather’s lens contamination
the sensor reads (an input, not a reading). /<n>/battery_state’s power_supply_status is
DISCHARGING while the pack gives current and CHARGING while it takes it, FULL only at rest with
SOC 1, NOT_CHARGING at rest below; its design_capacity is the parameter capacity, else the
battery’s elec:battery:capacity.
A map wins. A --ros-topics publish entry replaces a default topic when it uses the same
topic name, or when it publishes a signal the default topic carries (the whole default goes:
publishing sensor/alt/range as Float64 on /alt leaves no /alt/range). The sensor’s other
defaults stay. kind_topics: false at the top of the map file turns every default off. With
--no-ros there is no bridge and nothing is published. Tests: test_kind_topics (bridges/ros2:
each message family from fake signals, laziness, a map’s precedence; lagrange_server: the safety
AMR’s topics end to end).
optical_flow¶
A downward optical flow sensor such as the PixArt PMW3901 or PX4Flow, computed from geometry
rather than by matching images: the sensor’s own velocity and angular velocity (its body’s
twist, with the lever arm to the mount) and the depth to what it sees, from a 3 × 3 grid of
rays over its field of view cast against every collider except its own body’s (CPU
ShapeCaster, deterministic; no GPU). Each ray that hits within range contributes the
Longuet-Higgins and Prazdny (1980) motion field at its image point; the flow is their mean. On
the optical axis that is ω + (ẑ × v)/Z; over a plane parallel to the image at height h, a
sensor moving at v reads exactly v/h.
The sensor looks along its x like a camera, so a downward sensor is mounted pitched by +90°
(rpy="0 1.5708 0"). Its flow is about the optical frame’s x and y (z along the view, x right,
y down in the image), in the sign of PX4’s SensorOpticalFlow.pixel_flow: a right-handed
rotation of the sensor about an axis reads positive about it, so a pure rotation reads as the
gyro’s delta angle and flow − delta_angle is the translational part (PX4-Autopilot
msg/SensorOpticalFlow.msg; ekf2 negates both, EKF2.cpp). With a wide field of view a pure
rotation reads slightly more than the gyro (the 1 + y² term of the motion field: about 4 % at
42°), as a real perspective sensor does.
<gazebo reference="base_link">
<sensor name="flow" type="optical_flow">
<pose>0 0 -0.05 0 1.5708 0</pose>
<update_rate>100</update_rate>
<optical_flow><fov>0.733</fov><min_range>0.08</min_range><max_range>30</max_range>
<max_flow_rate>7.4</max_flow_rate><noise>0.05</noise></optical_flow>
</sensor>
</gazebo>
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
rad |
0.733 (42°, PMW3901MB-TXQT datasheet v1.00, table 3) |
field of view the rays span |
|
m |
0.08 (PMW3901 datasheet) |
nearer ground: quality 0 |
|
m |
30 (illustrative: PixArt gives no limit, “80 mm to infinity”) |
farther ground: quality 0 |
|
rad/s |
7.4 (PMW3901 datasheet) |
faster flow: quality 0, it loses the texture |
|
rad/s |
0.05 (illustrative: the datasheet gives no noise figure) |
white noise on each axis’s rate, 1σ |
The period is rounded to whole milliseconds. Signals: sensor/<n>/flow (ScalarArray of 2, rad,
integrated over the sample: rate × period), quality (0–255 as PX4: the share of rays in range
times the contrast through fog exp(−σ d) with σ the optional env/extinction/visible, 0 when
nothing is in range or the flow exceeds max_flow_rate; flow then reads 0), distance (m, the
optical axis’s ray, +inf out of range) and integration_time (s). Under ground_truth there is
no noise. Not modelled: the surface’s texture and the light level (owed: a low-texture or dark
floor does not lower the quality yet). Tests: test_kinds_optical_flow (v/h over a plane,
rotation = gyro, noise σ, range and rate limits).
event_camera¶
A dynamic vision sensor (iniVation DAVIS346, Prophesee) from successive rendered frames, as ESIM
(Rebecq, Gehrig and Scaramuzza, “ESIM: an Open Event Camera Simulator”, CoRL 2018) and v2e (Hu,
Liu and Delbruck, “v2e: From Video Frames to Realistic DVS Events”, CVPR Workshops 2021) make
events. Each step renders the camera scene (as the camera does, on the GPU or the software
device) and turns each pixel into log intensity (linear luminance in digital numbers, ln above
20 DN and linear below, v2e’s lin-log). Between two frames a pixel’s log intensity is linear in
time; each time it crosses the pixel’s memorised level by its threshold an event fires at the
crossing time and the level moves by the threshold. A crossing within the refractory period of
the pixel’s last event is held to the next frame. Thresholds differ per pixel by
threshold_sigma (drawn once per run from its seed), and background activity fires at
noise_rate per pixel with random polarity. The render rate is the sensor’s update rate: events
between frames are interpolated, so a faster rate follows faster motion.
<sensor name="dvs" type="event_camera">
<update_rate>200</update_rate>
<event_camera><width>346</width><height>260</height><horizontal_fov>1.2357</horizontal_fov>
<threshold_on>0.2</threshold_on><threshold_off>0.2</threshold_off>
<threshold_sigma>0.03</threshold_sigma><refractory_period>0.0005</refractory_period>
<noise_rate>0.1</noise_rate><max_events>20000</max_events></event_camera>
</sensor>
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
px |
346, 260 (DAVIS346) |
the pixel array (also |
|
rad |
1.2357 (70.8°: the DAVIS346 sheet’s, 4.5 mm lens) |
(also |
|
m |
0.05 |
|
|
ln |
0.2 (v2e’s default; its paper calls 0.3 typical) |
contrast thresholds |
|
ln |
0.03 (v2e) |
per-pixel mismatch, 1σ |
|
s |
5e-4 (v2e’s default; iniVation publishes none) |
|
|
Hz |
0.1 (the v2e paper’s typical leak rate; v2e’s own default is 0.01) |
background activity per pixel |
|
20000 |
events per step kept in |
Signals: sensor/<n>/events (ScalarArray of 4 × max_events: x, y, t in s of sim time,
polarity ±1, sorted by time, NaN after the last), count (Int, events in this step’s packet),
dropped (Int, events over max_events), and image (Image rgba8: this step’s events per
pixel, grey 128 plus 64 per ON and minus 64 per OFF) with image/intrinsics and
image/position. Rendering makes it a GPU path, not
deterministic (invariant 7); under ground_truth it renders nothing and fires nothing. Without a
Vulkan device the run refuses to start, as with a camera. Tests: test_kinds_event_camera (a
ramp fires one event per threshold at the crossing times, the refractory hold, threshold and
noise statistics, lin-log; rendered: a still scene is silent, a moving one fires).
stereo_camera¶
An active stereo depth camera like the Intel RealSense D435: left and right infrared imagers a
baseline apart and the left imager’s depth. It renders the camera scene from both imagers (the
right one baseline to the right in the image) and gives the left’s rendered depth the error a
stereo matcher makes, without matching: Gaussian noise of σ_z = z² σ_d / (f b) with σ_d the
sub-pixel disparity error, f the focal length in pixels and b the baseline (Grunnet-Jepsen et al.,
“Tuning depth cameras for best performance”, Intel RealSense white paper), quantised to
depth_unit. Invalid pixels follow from the geometry: a point the right imager does not see
(outside its image, the left band whose width is the disparity f b / z, or behind something
nearer in its depth, an occlusion shadow) is NaN; nearer than min-Z = f b / max_disparity is
−inf; beyond max_range or nothing is +inf (ROS REP 118). As the lidar’s, the gate is on the true
depth and the noisy reading is then held inside [min-Z, max_range], so no finite depth is ever past
max_range.
<sensor name="d435" type="stereo_camera">
<update_rate>30</update_rate>
<stereo_camera><width>848</width><height>480</height><horizontal_fov>1.518</horizontal_fov>
<baseline>0.05</baseline><subpixel>0.08</subpixel><max_disparity>126</max_disparity>
<max_range>10</max_range><depth_unit>0.001</depth_unit></stereo_camera>
</sensor>
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
px |
848, 480 (D435 depth) |
|
|
rad |
1.518 (87°, D435 depth field of view, D400 datasheet 337029 table 3-49) |
|
|
m |
0.05 |
|
|
m |
0.050 (D435) |
|
|
px |
0.08 (Intel white paper) |
σ_d |
|
px |
126 (D400 search range, the white paper’s min-Z formula) |
sets min-Z |
|
m |
10 (illustrative: the D400 datasheet gives “0.2 m to over 3 m (varies with lighting conditions)”, the white paper up to about 10 m on a white wall) |
|
|
m |
0.001 (D400) |
output quantum; 0 for none |
Signals: sensor/<n>/depth (Image r32f, m along the optical axis, NaN/±inf as above), left
and right (Image rgba8, the rendered luminance as grey: the IR imagers without their emitter’s
dot pattern), each with its intrinsics and position (the right imager at +baseline; see
“Images of kinds”). Rendering makes it a GPU path, not deterministic; under ground_truth it
publishes empty images that keep their size. Tests: test_kinds_stereo_camera (σ_z of a noisy wall at 1,
2 and 4 m, the left band, REP 118 limits, occlusion, the 1 mm quantum; rendered: a wall ahead).
Getting these signals out¶
The scalar and array signals are on ROS by default (“ROS topics of the built-in kinds” above:
/flow/flow Vector3Stamped, /flow/quality, /flow/distance, /dvs/count, …); a
--ros-topics map can put them elsewhere or on other messages:
publish:
- {signal: sensor/flow/flow, topic: /flow/flow, type: std_msgs/msg/Float64MultiArray}
and Python reads them with sim.read("sensor/flow/flow"). Images and events need no mapping:
see the next section.
Images of kinds¶
Any Image signal a custom sensor writes (a built-in kind’s or a plugin’s) reaches every user by
its name, with nothing written per kind; a new kind that writes sensor/<n>/<q> as an Image gets
all of this for free.
Calibration on the bus. A kind whose image is a pinhole writes beside it
sensor/<n>/<q>/intrinsics(ScalarArray of 4, px: fx, fy, cx, cy, OpenCV convention, origin at the first pixel’s centre) andsensor/<n>/<q>/position(Vec3, m, frameoptical: where that image’s camera centre is in the sensor’s optical frame).stereo_camerawrites them forleft,right(at +baselinealong x) anddepth;event_cameraforimage.ROS 2 (
Bridge::attach, anySensorType::Custom): each Image signal assensor_msgs/Imageon/<n>/<q>/image_raw, encoding from the buffer (rgba8 →rgba8, rgb8 →rgb8, r8 →mono8, r16u →mono16, r32f →32FC1, r32u →32SC1;ros2::rosImageEncoding), stamped when it was sampled, in<n>_opticalfor an image in the optical frame (the bridge then publishes the static<n>→<n>_opticaltransform) and<n>otherwise; with the calibration,sensor_msgs/CameraInfoon/<n>/<q>/camera_info(no distortion, K from the intrinsics, P withTx = −fx·xandTy = −fy·yfrom the position: a stereo pair’s right image hasTx = −fx·b, as REP 104 and CameraInfo.msg give it for the second camera of a horizontal pair; both images in the left’s optical frame). Packed events (sensor/<n>/events, 4 numbers per event, withcount) go assensor_msgs/PointCloud2on/<n>/events:x,y(uint16, px),polarity(int8, ±1),t(float64, s of sim time), one point per event, in<n>_optical. No new message package:event_camera_msgsis not a Lyrical rosdep key, and Image, CameraInfo and PointCloud2 are insensor_msgs. Sensor timing (<latency>,<jitter>) delays them as it does a camera’s topics; radio links (--link-topics) gate them by topic. For the D435 example:/d435/left/,/d435/right/and/d435/depth/image_rawwith theircamera_info, ready forstereo_image_procordepth_image_proc. Test:test_bridge(KindImageBridgeTest.PublishesACustomSensorsImagesWithTheirCalibration).Python:
sim.image("sensor/d435/depth")returns the latest frame as a numpy array: rgba8(height, width, 4)uint8, rgb8(h, w, 3), r8(h, w)uint8, r16u uint16, r32f(h, w)float32 (m for a depth, K for a temperature), r32u uint32; None before the first frame (theground_truthsubstitute renders nothing). It reads a camera’simage,depthandinstancetoo.sim.readof an image raises TypeError andimageof a number signal likewise; the events read as numbers,numpy.asarray(sim.read("sensor/dvs/events")) .reshape(-1, 4)(Server::readImage; testpython/test/test_images.py).Viewer: the existing
SubscribeSensorcommand andSensorFramemessage carry an image by signal name as well as a sensor by prim path: a viewer that subscribes tosensor/<n>/<q>gets that image’s frames asSensorFrame{sensor: "sensor/<n>/<q>", image}(the delayed image when the sensor has sensor timing), with its own encoding. No protocol change: the field was a string already, and an older server ignores a name it does not know. The viewer keeps image signals in its catalog (they have no samples) and lists custom sensors with images in the Sensors workspace; the Camera panel’s modes are then the sensor’s images (left,right,depth;imagefor an event camera), and for a cameradepthandlabelsnow show its depth and instance images. r32f draws as grey from its nearest (white) to its farthest, r32u as a colour per id. Tests:test_viewer_client(AnImageSignalDoesNotEndTheCatalog,AnImageSignalIsWatchedByNameAndDrawnAsRgba,ImageToRgba.*),test_server(ArmServerTest.AnImageSignalIsSentByItsName).
The power kinds below (battery_monitor, current_sensor, voltage_sensor, esc_telemetry,
tension_sensor) share one measuring chain (kinds/Converter.hpp): the truth times
(1 + gain_error), plus offset, plus white noise of noise (1 σ) per conversion, each
conversion rounded to the step and clamped to the range, samples conversions averaged and the
mean rounded again. They read other domains’ signals as optional inputs: while the domain that
writes one is off (or the stage has nothing that writes it), that reading is NaN and
sensor/<name>/valid is 0 when the main one is missing. Under ground_truth every reading is
the input itself, unrounded.
battery_monitor¶
A smart battery’s fuel gauge (a TI BQ40Z50 class part) or a power module, on one battery of the electrical domain. Its default steps are the Smart Battery Data Specification Rev 1.1 (SBS-IF, 1998) §5.1 registers: Voltage in mV, Current in mA, Temperature in 0.1 K, RelativeStateOfCharge in %, RemainingCapacity in mAh.
<sensor name="fuel_gauge" type="battery_monitor">
<update_rate>10</update_rate>
<battery_monitor>
<battery>battery</battery>
<voltage><noise>0.002</noise></voltage>
<current><bits>16</bits><full_scale>60</full_scale></current>
</battery_monitor>
</sensor>
Parameter |
Default |
Meaning |
|---|---|---|
|
the stage’s only |
which battery (its prim name); the run refuses to start when there are none or several and none is named |
|
|
the pack’s rated charge in A·h (5 for a 5000 mAh pack), only when the stage has no such battery. The one parameter of §9 not in SI units: it is kept in A·h as written on packs and in ROS’s |
|
SBS steps: 1 mV, 1 mA, 0.1 K, 0.01, 3.6 C |
the step of quantity |
|
none |
an ADC instead: step = full_scale / 2^bits over [0, full_scale] (current: ±full_scale, step full_scale / 2^(bits−1)) |
|
0, 0, 0, 1 |
the chain above, in |
Signal |
Unit |
|
|---|---|---|
|
V |
from |
|
A |
|
|
1 |
|
|
K |
|
|
C |
SOC × capacity (1 mAh = 3.6 C) |
|
1 |
0 while the electrical domain is off |
Test: test_kinds_battery_monitor (register steps, step = full scale / 2^bits, noise σ and
reproducibility, NaN with electrical off, battery naming, ground truth).
current_sensor and voltage_sensor¶
One current (A) or voltage (V) signal of the run, named by signal: a bus voltage
(bus/<b>/voltage), a motor’s motor/<m>/bus_current, a branch’s branch/<b>/current, a
battery’s battery/<b>/terminal_voltage, or a plugin’s. A signal of the other unit is refused at
wiring (invariant 2).
<sensor name="motor1_current" type="current_sensor">
<current_sensor>
<signal>motor/rotor_1_motor/bus_current</signal>
<model>ina226</model>
<shunt_resistance>0.0005</shunt_resistance>
<averages>16</averages>
<conversion_time>0.000588</conversion_time>
</current_sensor>
</sensor>
Models:
ina226(default, both kinds): TI INA226, datasheet SBOS547C §5.5 and Tables 7-3 to 7-5. Shunt voltage step 2.5 µV over ±81.92 mV; bus voltage step 1.25 mV over 0 to 40.96 V (inputs only up to 36 V);conversion_timeone of 140, 204, 332, 588, 1100 (default), 2116, 4156 or 8244 µs;averagesone of 1 (default), 4, 16, 64, 128, 256, 512, 1024;channels2 (default: shunt and bus, continuous, the power-on mode) or 1. The INA226 integrates, so it reads the signal’s mean over its window (Hold::WindowAverage), and a new reading comes every conversion_time × channels × averages: that is the module’s step, whateverupdate_ratesays, on the kinds’ whole milliseconds (2.2 ms by default runs every 2 ms: the exact 2.2 ms beside a 1 Hz sensor would repeat only after 11 s, and the scheduler would refuse the run). For currentsshunt_resistance(Ω, default 2 mΩ, illustrative);noiseandoffsetare in volts at the ADC’s input (shunt or bus). The datasheet bounds them: shunt offset ±2.5 µV typical, ±10 µV maximum; bus offset ±1.25 mV typical, ±7.5 mV maximum; gain error 0.02% typical, 0.1% maximum. The defaults are 0, so give the part’s figures. Each step averagesaveragesnoisy conversions, so noise falls as 1/√N.hall(current only): an Allegro ACS712 read by a microcontroller’s ADC. Its output iszero_output(defaultsupply/ 2,supply5 V) +sensitivity× I. The defaults are the ACS712ELCTR-05B (ACS712-DS Rev. 22, 2024): 0.185 V/A, and noise 21 mV peak to peak taken as 6 σ (3.5 mV rms; the 20 A part is 0.100 V/A and 11 mV, the 30 A part 0.066 V/A and 7 mV). Thenadc/bits(12) over 0 toadc/reference(defaultsupply), andaverages.divider(voltage only): a divider ofratio(output over input, default 1/11, illustrative) intoadc/bits(12) over 0 toadc/reference(3.3 V), as a flight controller’s power module reads its pack.
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
none: required |
the current (A) or voltage (V) signal it measures |
|
|
|
|
|
|
Ω |
0.002 (illustrative) |
|
|
s |
0.0011 |
|
|
1 |
conversions averaged ( |
|
|
2 |
|
|
|
V |
0, 0 |
at the ADC’s input, 1σ and fixed ( |
|
0 |
reads (1 + gain_error) × the truth |
|
|
V |
5 |
|
|
V/A |
0.185 |
|
|
V |
|
|
|
1/11 (illustrative) |
|
|
|
12 |
|
|
|
V |
|
the ADC’s range is 0 to it |
Signal |
Unit |
|
|---|---|---|
|
A or V |
the reading |
|
1 |
0 while nothing writes |
Tests: test_kinds_current_sensor (2.5 µV steps and the ±81.92 mV range, σ ratio 4 from 1 to
16 averages, the window mean, an ACS712 through 12 bits with its default noise, NaN and unit
checks, ground truth); test_kinds_voltage_sensor (1.25 mV steps, 40.96 V full scale, the
divider and its range).
esc_telemetry¶
What a drone’s ESC reports of the motor on joint (BLHeli_32, AM32). The motor is the
ElectricalMotorAPI_1 whose elec:joint is that joint: its pole pairs (elec:polePairs), its
gear (elec:gearRatio, motor turns per joint turn), its bus (found through its ports, as the
electrical network finds it) and its thermal node (thermal/<motor>/temperature). eRPM =
mechanical RPM × pole pairs. speed is decoded back to the motor shaft, so RPM = speed × 60/2π.
<sensor name="esc_1" type="esc_telemetry">
<update_rate>50</update_rate>
<esc_telemetry><joint>rotor_1_joint</joint><protocol>kiss</protocol><escs>4</escs></esc_telemetry>
</sensor>
kiss(default): KISS serial telemetry, a 10-byte frame at 115200 baud per request, the flight controller asking each ESC in turn on a shared wire (Betaflightsrc/main/sensors/esc_sensor.c). Temperature in °C, voltage in 0.01 V, current in 0.01 A, consumption in mAh, speed in 100 eRPM, all unsigned. The rate isupdate_ratebut at mostbaud/ (100 bits ×escs) (default 115200 baud and 4 ESCs: 288 Hz).consumptioncounts the motor’sbus_currentfrom the start.dshot: bidirectional DShot. Each reply carries the eRPM as its period in whole µs, a 9-bit mantissa shifted by a 3-bit exponent (period = m << e). Below 60·10⁶ / (511 << 7) ≈ 917 eRPM it reads 0. Extended DShot Telemetry v2.1.1 (github.com/bird-sanctuary/extended-dshot-telemetry) sends temperature in 1 °C (0 to 255), voltage in 0.25 V (0 to 63.75) and current in 1 A (0 to 255) atextended_rate(default 1 Hz, the spec’s example schedule). It has no consumption (NaN).
Other parameters: pole_pairs and gear_ratio (needed when no motor prim drives the joint),
bus, temperature_node, and current/…, voltage/…, temperature/… noise, offset and
gain_error (temperature/ in °C). Telemetry periods are rounded up to whole milliseconds, as every kind’s.
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
none: required |
the motor’s joint |
|
|
|
|
|
|
4 |
|
|
|
bit/s |
115200 |
|
|
Hz |
1 |
|
|
the motor’s |
needed when no motor prim drives the joint |
|
|
the motor’s bus and thermal node |
||
|
A, V |
0.01, 0.01 ( |
the frame’s steps |
|
°C |
1 |
|
|
none |
an ADC instead, as the battery monitor’s |
|
|
0, 0, 0, 1 |
the chain above, in |
Signal |
Unit |
|
|---|---|---|
|
rad/s |
motor shaft, from the protocol’s eRPM |
|
A |
|
|
V |
|
|
K |
|
|
C |
kiss only (1 mAh = 3.6 C) |
|
1 |
0 while physics writes no joint velocity |
Test: test_kinds_esc_telemetry (KISS steps, whole-mAh consumption, the wire’s rate limit,
DShot’s 898 µs = 449 << 1 and the extended frames once a second, the stop threshold, missing
domains, ground truth).
tension_sensor¶
A strain-gauge load cell where a tether meets its body (end attach, default:
tether/<t>/tension_attach) or its station (anchor: tension_anchor), read by a bridge ADC.
The cell gives sensitivity × excitation × F / capacity volts. Its error is a bow of
nonlinearity × capacity × 4x(1 − x) (x = |F| / capacity: largest at half load, none at 0 and
full load), and hysteresis × capacity between loading and unloading at half load. The loading
branch reads low and the unloading branch high, by half each. The ADC defaults to an Avia HX711
channel A: 24-bit two’s complement over ±0.5 × excitation / adc/gain (gain 128: ±19.5 mV at
5 V), input noise 50 nV rms (gain 128, 10 SPS), all from its datasheet. Run it at 10 or 80 Hz
update_rate, the HX711’s two rates.
<sensor name="tether_load" type="tension_sensor">
<update_rate>80</update_rate>
<tension_sensor>
<tether>tether</tether><end>attach</end>
<capacity>200</capacity><sensitivity>0.002</sensitivity><excitation>5</excitation>
<nonlinearity>0.0002</nonlinearity><hysteresis>0.0002</hysteresis>
</tension_sensor>
</sensor>
Parameter |
Default |
Meaning |
|---|---|---|
|
the stage’s only |
which tether |
|
|
|
|
500 N |
rated load (illustrative: give your cell’s) |
|
0.002 V/V |
rated output at capacity (2 mV/V, a common figure) |
|
5 V |
also the ADC’s AVDD |
|
0 |
fractions of capacity |
|
0 |
at the cell, in N (offset: zero balance) |
|
24, 128, ±0.5·excitation/gain, 50 nV, 1 |
the converter, in V at the bridge |
|
0.001 |
strain at the gauges at capacity, for |
Signal |
Unit |
|
|---|---|---|
|
N |
the reading |
|
1 |
force / capacity × rated_strain |
|
1 |
0 while the tether domain is off |
Test: test_kinds_tension_sensor (the ADC’s step, HX711 noise in newtons, the bow and the
hysteresis loop at half load, the anchor end, tether off, ground truth).
On ROS by default: the fuel gauge as /<n>/battery_state (sensor_msgs/BatteryState), the
others’ numbers on /<n>/<quantity> (“ROS topics of the built-in kinds” above). A
--ros-topics FILE.yaml map (bridges/ros2/src/SignalTopics.cpp) renames or retypes them:
publish:
- {signal: sensor/fuel_gauge/voltage, topic: /battery/voltage, type: std_msgs/msg/Float64}
- {signal: sensor/fuel_gauge/temperature, topic: /battery/temperature, type: sensor_msgs/msg/Temperature, frame: base_link}
- {signal: sensor/esc_1/speed, topic: /esc_1/speed, type: std_msgs/msg/Float64}
- {signal: sensor/tether_load/force, topic: /tether/force, type: std_msgs/msg/Float64}
A sample: assets/robots/quad_x500/quad_x500_telemetry.usda adds to the sample quadcopter
KISS telemetry from its first rotor’s ESC, the pack’s fuel gauge and an INA226 on its bus
(CustomSensorAPI_1, sensor:custom:param:<path>).
The environment kinds below read other domains’ signals as optional inputs: while the domain
that writes one is off (no weather, no aerodynamics), the outputs that need it are NaN and
sensor/<name>/valid is 0. Their closed forms are in lagrange/sensors/EnvironmentSensors.hpp;
the shared code (the body’s motion, a collider scene for a ray or two, the sun) in
src/kinds/EnvCommon.hpp and SunCommon.hpp. Datasheet “±” accuracies are taken as 2σ. Noise,
offsets and lags are off under ground_truth, which reads the environment exactly.
anemometer¶
Ultrasonic (2D or 3D, after the Gill WindSonic) or cup and vane (after the R. M. Young 05103).
<gazebo reference="mast">
<sensor name="wind" type="anemometer">
<update_rate>4</update_rate>
<anemometer><type>ultrasonic</type><axes>2</axes></anemometer>
</sensor>
</gazebo>
Parameter |
Default |
Meaning |
|---|---|---|
|
|
or |
|
2 |
2 or 3 (ultrasonic) |
|
0.02 (cup 0) |
speed noise, 1σ, of the speed (the WindSonic’s 2 % RMSE) |
|
0.01 m/s (cup 0) |
speed noise, 1σ, the least |
|
1° (cup 0) |
rad, 1σ (the WindSonic’s ±2° as 2σ) |
|
0.01 m/s, 1° |
|
|
0.01 m/s (cup 1.0 m/s) |
below it the speed reads 0 |
|
0.01 m/s (cup 1.1 m/s) |
below it the vane holds |
|
0 (cup 2.7 m) |
cup lag: first order, τ = L / V |
|
read |
Signals: wind_velocity (Vec3, m/s, sensor frame: where the air goes, relative to the sensor),
wind_speed (m/s), wind_direction (rad, [0, 2π): where it blows from, clockwise from the
sensor’s +x seen from above, the meteorological convention when +x points north), valid.
Model: the air is the aerodynamics domain’s env/wind/velocity (mean wind and gust at the first
link’s height; or with air_rotor a rotor’s air, the wind plus other robots’ downwash at its hub;
a robot’s own downwash at the sensor is not included), less the sensor’s own velocity
(v + ω × r of its body), in the sensor frame; 2D drops the vertical part. The noise is a gain
error on the speed and an angle error on the direction. Without the aerodynamics domain (no
AeroAPI_1 link or rotors, or no site air density) it is not valid. Check: test_kinds_anemometer
(relative air and heading exact, the direction convention, WindSonic accuracy, the cup’s threshold
and its lag against y = V·(1 − e^(−t·V/L))). References: Gill WindSonic User Manual 1405-PS-0019
Issue 30 (2022), appendix A (speed “± 2% RMSE (at 12m/s)”, 0.01 m/s resolution; direction ±2° at
12 m/s, ±3° in the 2009 datasheet, 1°; threshold 0.01 m/s in the datasheets), R. M. Young 05103
Wind Monitor manual 05103-90 rev. N062819 (propeller threshold 1.0 m/s, vane 1.1 m/s at 10°
displacement, distance constant 2.7 m for 63 % recovery).
airspeed¶
A pitot-static probe along the sensor’s +x on a differential pressure sensor (after the TE MS4525DO-DS5AI001DP that PX4 and ArduPilot use).
<sensor name="pitot" type="airspeed">
<update_rate>50</update_rate>
<airspeed><noise><stddev>2.0</stddev></noise></airspeed>
</sensor>
Parameter |
Default |
Meaning |
|---|---|---|
|
0 Pa |
1σ |
|
0 Pa |
zero offset |
|
6894.757 Pa (±1 psi) |
the reading clips there |
|
1.052 Pa |
one count: 2·1 psi / (0.8·16383) |
|
0.098 K |
11 bits over −50 … 150 °C |
|
kg/m³, only when neither the weather nor the site gives one |
|
|
as the anemometer’s |
Signals: differential_pressure (Pa), airspeed (m/s, true: from the measured pressure at the
air’s density), indicated_airspeed (m/s, at the ICAO sea-level 1.225 kg/m³), temperature (K:
the weather’s env/air_temperature, else the site’s ambient temperature, else NaN), valid.
Model: q = ½·ρ·V·|V|, V the air relative to the probe along its axis (the wind as the anemometer;
without the aerodynamics domain, still air, so the probe still sees its own motion). ρ is the
weather’s env/air_density when it runs, else the site’s (--air-density, the profile’s
rotor_aero.air_density or aerodynamics.air_density, handed to the sensors domain as config
air_density), else the parameter; with none it is not valid. Incompressible: under 1 % low below
Mach 0.3. Check: test_kinds_airspeed (½ρV², a headwind, the weather’s density first, the count
grid). The MS4525DO’s total error band, ±1 % of span (datasheet MS4525DO 04/2019, p. 4: about
±138 Pa on ±1 psi, over −10 to 85 °C), is not modelled by default: give it as offset.
rangefinder¶
One laser beam along the sensor’s +x (after the Benewake TFmini-S; set the range for a LightWare
SF11/C, 0.2 to 100 m). Kind tof, the sample plugin, is a different sensor (a cone of rays).
<sensor name="altimeter" type="rangefinder">
<pose>0 0 -0.05 0 1.5708 0</pose>
<update_rate>100</update_rate>
<rangefinder><range><min>0.1</min><max>12</max></range></rangefinder>
</sensor>
Parameter |
Default |
Meaning |
|---|---|---|
|
0.1 m, 12 m |
|
|
0.03 m |
1σ, the least |
|
0.005 |
1σ of the range |
|
0.01 m |
Signals: range (m; +inf when nothing is within reach, −inf when something is closer than
range/min, REP 117), valid.
Model: the exact CPU ray cast against every collider at its body’s pose (ShapeCaster, on every
tier), its own body’s colliders skipped. Noise σ = max(stddev, fraction·r) (TFmini-S: ±6 cm to
6 m, ±1 % to 12 m). With the weather its reach shrinks as a lidar’s does
(lidarDetectionRange: env/extinction/nir_905 and its sensor/<name>/contamination); the
target’s reflectivity is not used. Check: test_kinds_rangefinder.
ROS: /altimeter/range (sensor_msgs/Range, INFRARED, the kind’s limits) and /altimeter/valid
by default; the same by hand: {signal: sensor/altimeter/range, topic: /altimeter/range, type: sensor_msgs/msg/Range, frame: altimeter, params: {radiation_type: 1, min_range: 0.1, max_range: 12.0}}.
light_sensor¶
An ambient light sensor whose face looks along the sensor’s +x (after the ROHM BH1750FVI).
<sensor name="lux" type="light_sensor">
<pose>0 0 0.2 0 -1.5708 0</pose> <!-- +x up -->
<update_rate>8</update_rate>
<light_sensor><start_utc>2026-06-21T03:00:00Z</start_utc></light_sensor>
</sensor>
Parameter |
Default |
Meaning |
|---|---|---|
|
UTC date and time at t = 0, |
|
|
|
or |
|
100 m |
illustrative depth of fog the beam crosses per air mass |
|
1 |
the BH1750’s part-to-part ratio, 0.8 to 1.2 |
|
0 |
1σ, of the reading |
|
1/1.2 lx |
one count in H-resolution mode (BH1750FVI datasheet Rev.D, p. 7: lx = counts / 1.2) |
|
54 612 lx |
65535 counts / 1.2 |
|
0 |
light from the ground |
Signals: illuminance (lx, as cd·sr/m² with no quantity kind: lagrange::units has no lux),
valid. ROS: sensor_msgs/msg/Illuminance.
Model: the sun (below) and the daylight model of Gillette, Pierpoint and Treado (NBS, 1982), as
the IES daylight availability practice (J. IES 13(4), 1984; not read) took it up: direct normal
E_dn = 127.5 klx·(1 + 0.033·cos(2π·day/365))·exp(−0.21·m), m the Kasten–Young air mass (the
source has 1/sin α), and diffuse horizontal (0.8 + 15.5·√sin α) klx on a clear sky,
(0.3 + 21·sin α) klx and no beam on an overcast one (Robbins and Hunter, SERI/TR-254-1703, 1983,
eqs. 2-16, 2-17 and 3-6, which quote it). The clear-sky extinction 0.21 per air mass is the
rural design value of LBL-17727 (“Analysis of atmospheric turbidity for daylight calculations”,
Lawrence Berkeley Laboratory, 1984: 0.21, 0.32 and 0.53 for rural, urban and industrial air). On the face: the beam ×
cos of incidence, zero when one ray toward the sun meets a collider (its own body skipped), plus
the sky by the isotropic model (1 + n_z)/2 and the ground’s ρ_g·E_gh·(1 − n_z)/2. The weather:
rain or snow (env/rain_rate, env/snow_rate) make the sky overcast; fog (env/extinction/visible)
dims the beam by exp(−σ·fog_depth·m). Night is zero (no twilight, moon or lamps; cloud cover is
not a weather signal yet). The cosine and spectral response are ideal. Full sun saturates the
BH1750 (65535 counts, 54 612 lx); set max_illuminance for another part. Check: test_kinds_light_sensor
(Meeus’ Julian day example, the NREL SPA example within 0.02°, Kasten–Young at the horizon, the IES
closed forms, shade and overcast).
sun_sensor¶
A two-axis sun sensor looking along +x (after the Solar MEMS nanoSSOC-A60, product sheet nanoSSOC-A60, solar-mems.com, 2024: field of view ±60°, accuracy < 0.5° (3σ), precision < 0.1°). The noise is the accuracy over 3, which holds its bias too; for the noise alone give the precision.
Parameter |
Default |
Meaning |
|---|---|---|
|
as the light sensor’s |
|
|
120° |
full cone angle |
|
0.167° |
rad, 1σ per axis |
|
1000 lx |
illustrative (Solar MEMS gives no threshold): the least direct beam it finds the sun in |
Signals: sun_direction (Vec3, unit, sensor frame; NaN when the sun is not seen), sun_visible
(the sun is in the field of view, not shaded and its beam is strong enough), valid.
The sun, for both kinds: the NOAA solar position algorithm (NOAA GML Solar Calculator, after
Meeus 1998; about 0.01°, with NOAA’s refraction) at the sensor’s geodetic position (the site’s geo
origin, --geo-origin) and the time start_utc + t, in world ENU. Without a geo origin or
start_utc it is the weather’s env/sun_direction (the WeatherAPI_1 prim’s, day 80); without
that, not valid. Check: test_kinds_sun_sensor and the solar checks above (Reda and Andreas,
NREL/TP-560-34302, example: zenith 50.11162°, azimuth 194.34024°).
rain_sensor¶
An optical rain gauge (after the Hydreon RG-15: Rain Gauge Model RG-15 Instructions, SW rev 1.000, 2022.07.18: ±10 % “under controlled conditions, accuracy may vary near/below freezing”, 0.2 or 0.02 mm).
Parameter |
Default |
Meaning |
|---|---|---|
|
0.2 mm (0.2e-3 m) |
the accumulation’s step (high resolution 0.02 mm) |
|
0.05 |
1σ of a gain error drawn once per run (RG-15 ±10 %) |
|
0.1 mm/h |
illustrative: |
|
0 s |
first-order lag of the rate |
|
0 |
1: count snow too (melted water) |
Signals: rain_rate (m/s of water), accumulation (m, since the start, in whole steps),
raining, valid. ROS: std_msgs/msg/Float64 and Bool. From the weather’s env/rain_rate
(and env/snow_rate). Check: test_kinds_rain_sensor (∫R dt).
humidity_sensor¶
Relative humidity and temperature (after the Sensirion SHT40).
Parameter |
Default |
Meaning |
|---|---|---|
|
4 s, 2 s |
τ63 |
|
0.000267, 0.0133 K |
1σ: the SHT4x’s high-precision repeatability, 0.08 %RH and 0.04 °C, is 3σ (datasheet V7.3, tables 1–2) |
|
0 |
its accuracy (SHT40: ±0.018, ±0.2 K typical) |
|
0.0001, 0.01 K |
Signals: relative_humidity (0 to 1; ROS sensor_msgs/msg/RelativeHumidity takes 0 to 1 too),
temperature (K), valid. From the weather’s env/relative_humidity and env/air_temperature
through a first-order lag, y += (1 − e^(−Δt/τ))·(u − y), exact for an input held over a step.
Without the weather the humidity is NaN (valid 0) and the temperature the site’s ambient one,
if given. Check: test_kinds_humidity_sensor (the lag’s closed form, a step through τ).
visibility_sensor¶
A forward-scatter visibility sensor (after the Vaisala PWD22, datasheet B210385EN-F: 10 to 20 000 m, ±10 % to 10 km, ±15 % from 10 to 20 km).
Parameter |
Default |
Meaning |
|---|---|---|
|
10 m, 20 000 m |
|
|
0.05 |
1σ, of the MOR (±10 % as 2σ) |
|
1.5 × |
1σ beyond 10 km (±15 %) |
|
60 s |
first-order lag of the extinction: PWD22 User’s Guide M210543EN-B, table 24, “Time constant 60 seconds” (its 1 min output is a running mean of 15 s values) |
Signals: visibility (m: the meteorological optical range), extinction (1/m, what it measured),
valid. Model: MOR = −ln 0.05 / σ ≈ 3/σ (Koschmieder with WMO’s 5 % threshold, WMO-No. 8 Vol. I
ch. 9), σ the weather’s env/extinction/visible (fog, rain, snow and dust). The weather’s
visibility is at a 2 % threshold (σ = 3.912/V), so a fog of V reads an MOR of 0.766·V, as a
real sensor would. Check: test_kinds_visibility_sensor.
They are on ROS by default (“ROS topics of the built-in kinds” above); a --ros-topics map
puts them elsewhere, which replaces the defaults it covers:
publish:
- {signal: sensor/wind/wind_velocity, topic: /wind, type: geometry_msgs/msg/Vector3Stamped,
frame: wind}
- {signal: sensor/pitot/differential_pressure, topic: /pitot/pressure,
type: sensor_msgs/msg/FluidPressure, frame: pitot}
- {signal: sensor/lux/illuminance, topic: /lux, type: sensor_msgs/msg/Illuminance, frame: lux}
- {signal: sensor/sht/relative_humidity, topic: /sht/humidity,
type: sensor_msgs/msg/RelativeHumidity, frame: sht}
- {signal: sensor/sht/temperature, topic: /sht/temperature, type: sensor_msgs/msg/Temperature,
frame: sht}
- {signal: sensor/pwd/visibility, topic: /visibility, type: std_msgs/msg/Float64}
The contact, ray and joint kinds below (bumper, cliff, wheel_odometry, safety_scanner,
force_torque, joint_torque) read only declared inputs (body/<b>/pose, body/<b>/twist,
body/<b>/contact_force, joint/<j>/position, joint/<j>/reaction); cliff and
safety_scanner cast against every collider at its body’s pose on the CPU (ShapeCaster, the
Tier 0 lidar’s exact tests; kinds/KindScene.hpp), skipping their own body’s colliders, so they
run the same on every tier. They publish by default (“ROS topics of the built-in kinds” above);
a --ros-topics map renames them (example at the end).
bumper¶
A contact switch: pressed when what touches the sensor’s body pushes it hard enough from the
side it watches. It reads body/<b>/contact_force (the sum of every contact on the body, world
frame, rigid_body.md “Contact force”), averaged over the sensor’s period, turns it into the
sensor frame and takes its xy part (the floor’s support is vertical). The contact sits opposite
the push, at angle atan2(−F_y, −F_x) (0 straight ahead); the bumper is pressed when the push is
at least threshold and that angle is in [sector_min, sector_max]. It needs physics; on a body
that never moves the run refuses to start.
<gazebo reference="base_link">
<sensor name="front_bumper" type="bumper">
<pose>0.3 0 0.05 0 0 0</pose><update_rate>100</update_rate>
<bumper><threshold>5</threshold><sector_min>-1.05</sector_min><sector_max>1.05</sector_max></bumper>
</sensor>
</gazebo>
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
N |
5 (illustrative) |
push that closes the switch |
|
rad |
−π, π |
angles of the contact it reports, sensor frame |
|
0/1 |
0 |
1: the whole force counts, the vertical part too |
Signals: sensor/<n>/pressed (Bool), force (N, the push’s size), direction (rad, where the
contact is). The body is all one switch: two bumpers on one body see the same contact sum, told
apart by their sectors. A floor that drags the body sideways (a sliding caster) pushes it too;
the threshold is set above that. Test test_kinds_bumper: a 10 kg box pushed by 30 N into a
wall reads 30 N ±2 % straight ahead and closes the front bumper, not the rear one; standing alone
it closes neither (the vertical one reads m·g ±1 %).
cliff¶
A robot vacuum’s cliff sensor: an infrared range finder looking down the sensor’s −z. One ray, or
rays rays (one straight down and the others on a ring at beam_angle) whose nearest return
wins, as an IR spot’s strongest return does. The range is clamped up to min_range (the floor is
there), +inf beyond max_range; cliff is 1 when the range is +inf or above threshold.
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
m |
0.005, 0.15 (illustrative) |
what it can measure |
|
m |
0.06 (illustrative) |
farther than this is a drop |
|
1 |
1 |
rays, 1 to 64 |
|
rad |
0 |
half angle of the ring |
|
m |
0 |
1 sigma, per reading |
|
0/1 |
1 |
rays pass the sensor’s own body’s colliders |
Signals: sensor/<n>/range (m, +inf for none), cliff (Bool). Floor material and colour do not
change the reading (an IR cliff sensor’s real weakness on black carpet is not modelled). Test
test_kinds_cliff: over a table it reads its height to 1e-12 m, past the edge (floor 0.5 m down,
out of range) and held 9 cm high (threshold 6 cm) it reports a cliff; a cone 1 cm past the edge
still finds the table at 0.04/cos(0.3) m; the noise has its sigma within 5 % over 2000 readings;
ground truth reads exactly.
wheel_odometry¶
Dead reckoning of a differential drive, as its base controller computes it. Each step it reads
the wheels’ joint/<j>/position, quantised to whole counts when encoder_resolution (counts per
revolution) is given, turns the count change into distance with the radius it believes, and
integrates the unicycle model exactly over the step (an arc of ds = (s_l + s_r)/2,
dψ = (s_r − s_l)/b). Nothing models slip: when the physics lets a wheel spin or skid, the wheel
turns no longer match the body’s motion, and the odometry drifts as a real robot’s does. The
odometry frame is the body’s pose at its first step, flattened to x, y, yaw. Without
left_joint/right_joint it finds the two driven hinges hanging off its body that carry a
cylinder or sphere (the one at +y is left; on a passive robot, one spawned or added to a run,
whose joints nothing drives, the two such hinges); without wheel_radius/wheel_separation it takes
the wheel collider’s radius and the wheels’ distance apart, as the server’s diff-drive controller
does. Each wheel’s forward sense comes from its axis in the body frame.
<gazebo reference="base_link">
<sensor name="wheel_odom" type="wheel_odometry">
<update_rate>50</update_rate>
<wheel_odometry>
<left_joint>left_wheel_joint</left_joint><right_joint>right_wheel_joint</right_joint>
<encoder_resolution>4096</encoder_resolution><radius_error>0.01</radius_error>
</wheel_odometry>
</sensor>
</gazebo>
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
detected |
the wheel joints |
|
|
m |
the wheel collider’s |
radius it believes |
|
m |
the wheels’ distance apart |
track it believes |
|
1 |
0 |
relative error of both radii (0.01: 1 % large) |
|
1 |
|
per wheel |
|
1 |
0 |
relative error of the track |
|
counts/rev |
0 (exact angle) |
encoder counts per wheel turn |
Signals: sensor/<n>/pose (Pose, frame odom, z = 0), yaw (rad), twist (Wrench of m/s:
forward speed, 0, 0, then 0, 0, turn rate, body frame). Ground truth: the body’s own pose in the
odometry frame and its speeds, exactly. Test test_kinds_wheel_odometry (MuJoCo, two wheels and
two caster balls): driving straight 3 s on μ = 1 it is 0.13 % long against the ground truth
(2.0376 m for 2.0351 m), turning on the spot 2 s 1.2 % (0.3033 rad for 0.2997 rad); a radius 5 %
large reads 5 % long; a 1024-count encoder stays within a count of the exact angle; on μ = 0.05
with 40 N of wheel force asked for, the spinning wheels read 70.9 m while the body moved 0.74 m.
safety_scanner¶
A safety laser scanner in the manner of SICK’s nanoScan3 and microScan3: a scan in the sensor’s
xy plane over fov, each return checked against a protective field and a warning field in the
sensor frame. A field is a polygon (<field>/polygon, text "x,y x,y x,y ...", even-odd rule), a
sector (<field>/radius, within the aperture) or a rectangle (<field>/x_min (default 0),
x_max, y_min, y_max). The outputs switch response_time after the scan that saw the
change, rounded up to whole scans of the sensor’s period (a ring of scan states): protective is
what turns the OSSDs off. Defaults are the nanoScan3 Core I/O’s, SICK data sheet NANS3-AAAZ30AN1
(part 1100333): scanning angle 275°, angular resolution 0.17°, response time 70 ms, distance
measuring range 40 m (protective fields up to 3 m and warning fields up to 10 m on that part; the
fields themselves are the user’s, with no default, and a protective field is required). The data
sheet gives no scan cycle time; the operating instructions do: 30 ms (nanoScan3 I/O operating
instructions 8024602/1W27/2026-05-26, Japanese edition, §14.2 table 33 “scan cycle time 30 ms”;
§14.3: response time t_R = n × 30 ms + 10 ms, n the multiple sampling, 2 by default, hence the
70 ms). The sensor’s update rate is its scan cycle: give <update_rate> 33.333 (a 30 ms period)
for a nanoScan3. Not modelled: the 65 mm protective field supplement (add it to the field), object
resolution (20–200 mm), remission limits (1.8 % up), contour detection, monitoring cases switched
by inputs. Two speed-dependent monitoring cases are: with switch_speed (m/s), at or above that
speed along the sensor’s x (from body/<b>/twist) the protective_fast and warning_fast fields
watch (warning_fast defaults to warning), and sensor/<n>/case reads 1.
<gazebo reference="base_link">
<sensor name="safety" type="safety_scanner">
<pose>0.3 0 0.15 0 0 0</pose><update_rate>33.333</update_rate>
<safety_scanner>
<protective><x_max>0.6</x_max><y_min>-0.35</y_min><y_max>0.35</y_max></protective>
<warning><polygon>0,-0.6 1.5,-0.6 1.5,0.6 0,0.6</polygon></warning>
</safety_scanner>
</sensor>
</gazebo>
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
rad |
4.7997 (275°) |
aperture, centred on +x |
|
rad |
0.002967 (0.17°) |
between beams |
|
m |
0, 40 |
returns kept |
|
m |
0 |
1 sigma, per beam |
|
s |
0.070 |
delay of the outputs, 0 to 60 s |
|
m |
none |
the fields, above |
|
m/s |
0 (off) |
forward speed of the fast case |
|
m |
none, |
the fast case’s fields |
Signals: sensor/<n>/protective, warning (Bool, delayed), min_distance (m, nearest return
of the latest scan, +inf for none), ranges (ScalarArray, m, +inf for none; a LaserScan with
angle_min = −fov/2). Ground truth: no noise and no delay. Test test_kinds_safety_scanner: a
plate driving at 1 m/s enters the 2 m warning polygon at 1 s and the 1 m protective rectangle at
2 s; at 25 Hz each output is still off one scan after and on by the third scan (70 ms → 2 scans),
at once under ground truth; min_distance is the plate’s face; driving at 1 m/s at a wall, a
scanner fast above 0.5 m/s with a 1.5 m fast field trips a metre before one with a fixed 0.5 m
field; no protective field refuses to start.
force_torque¶
A six-axis force-torque sensor (a wrist sensor) from joint/<j>/reaction: what the parent does
to the child at the child’s origin, world frame, including the motor’s torque (rigid_body.md
“Contact force and force-torque”). The joint is joint (text), else the one whose child is the
sensor’s body. The wrench is moved to the sensor’s origin (τ_s = τ_j + (p_j − p_s) × F) and
turned into the sensor frame; measure_direction child_to_parent reverses it. Then per axis:
offset, noise, a first-order low-pass at cutoff_frequency (α = 1 − exp(−2π·f_c·dt)), range
(clipped, saturated = 1), resolution (rounded to whole steps). Preset mini45_si_580_20 is ATI’s
Mini45 with calibration SI-580-20 (ati-ia.com, F/T sensor models, Mini45, table “Metric
Calibrations (SI)” for a 16-bit DAQ, ECAT, Net, TWE or WNet F/T system): ranges Fx, Fy 580 N, Fz 1160 N, Tx, Ty, Tz 20 N·m; resolutions Fx, Fy, Fz 1/4 N, Tx, Ty
1/188 N·m, Tz 1/376 N·m. ATI quotes those resolutions after dropping four counts of noise; the
preset’s noise of one resolution step (1 sigma) per axis is our assumption. Temperature drift is
not modelled.
<gazebo reference="tool0">
<sensor name="wrist_ft" type="force_torque">
<update_rate>1000</update_rate>
<force_torque><joint>wrist_3_joint</joint><preset>mini45_si_580_20</preset>
<cutoff_frequency>200</cutoff_frequency></force_torque>
</sensor>
</gazebo>
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
the body’s joint, |
above |
|
|
N, N·m |
∞ (or the preset’s) |
clipping |
|
N, N·m |
0 (or the preset’s) |
step |
|
N, N·m |
0 (or a step) |
1 sigma |
|
N, N·m |
0 |
bias |
|
Hz |
0 (none) |
first-order low-pass |
Signals (frame sensor:<n>): sensor/<n>/wrench (Wrench, N then N·m), force (Vec3, N),
torque (Vec3, N·m), saturated (Bool). Ground truth: the moved and turned wrench exactly (no
offset, noise, filter, range or step).
joint_torque¶
A link-side joint torque sensor, as in each joint of a Franka Panda or a KUKA LBR iiwa: the
reaction’s moment about the joint axis (its force along the axis for a slide), so at rest it reads
what the motor holds. Parameters joint (text, default the body’s joint), range, resolution,
noise (1 sigma), offset (N·m or N) and cutoff_frequency (Hz), all ideal by default: give the
part’s figures. Franka publishes none for the FR3 (datasheet R02212 2.6, July 2026: “link-side
torque sensor in all 7 axes”); KUKA gives “axis-specific torque accuracy ±2 % of maximum torque”
for the LBR iiwa 7 R800 and 14 R820 (spec sheet), no resolution or noise. Signals:
sensor/<n>/torque (N·m; force, N, on a slide), saturated (Bool).
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
the joint whose child is the sensor’s body |
||
|
N·m (N) |
∞ |
clipping; |
|
N·m (N) |
0: none |
step |
|
N·m (N) |
0, 0 |
1σ, bias |
|
Hz |
0: none |
first-order low-pass |
Test test_kinds_force_torque (both kinds): a 2 kg arm on a hinge held horizontal by its motor
(m·g·d = 9.80665 N·m): at the joint F = (0, 0, m·g) and τ = (0, −m·g·d, 0) within 0.5 %; at its
centre of mass no moment; child_to_parent the opposite; turned 90° about z the moment is about
the sensor’s x; the joint torque sensor reads −m·g·d; the Mini45 clips Fz at a 10 N range and its
readings are whole 1/4 N and 1/188 N·m steps; the 5 Hz low-pass follows 1 − exp(−2π·5·t) within
2 % of the weight at 20, 50 and 100 ms; ground truth is exact.
ROS topics for these kinds¶
By default /front_bumper/pressed (Bool), /cliff_fl/range (Range), /wheel_odom/odom
(Odometry), /safety/scan (LaserScan), /safety/protective, /wrist_ft/wrench
(WrenchStamped), /<joint torque sensor>/joint_state (JointState). A map that wants other names:
publish:
- {signal: sensor/front_bumper/pressed, topic: /bumper/front, type: std_msgs/msg/Bool}
- {signal: sensor/cliff_fl/range, topic: /cliff/front_left, type: sensor_msgs/msg/Range,
frame: cliff_fl, params: {min_range: 0.005, max_range: 0.15, field_of_view: 0.1}}
- {signal: sensor/wheel_odom/pose, topic: /wheel_odom/pose, type: geometry_msgs/msg/PoseStamped,
frame: odom}
- {signal: sensor/wheel_odom/twist, topic: /wheel_odom/twist, type: geometry_msgs/msg/TwistStamped,
frame: base_link}
- {signal: sensor/safety/protective, topic: /safety/protective, type: std_msgs/msg/Bool}
- {signal: sensor/safety/ranges, topic: /safety/scan, type: sensor_msgs/msg/LaserScan,
frame: safety, params: {angle_min: -2.39983, angle_max: 2.39983, range_min: 0.0,
range_max: 40.0}}
- {signal: sensor/wrist_ft/wrench, topic: /wrist_ft, type: geometry_msgs/msg/WrenchStamped,
frame: wrist_ft}
Kinds that find things by name (detections, landing_target, line_sensor, tag_reader)
search the model’s scene prims (Model::scene, every prim of the robot and the world, with the
box of its meshes and its children’s meshes on the same body); run without a scene (an old
caller of createSensorModules(const World&)) they see only World::prims. Names match a whole
prim name, a whole path or the end of a path (landing_pad, /open_field/landing_pad), or, where
said, whole words of a name split at _ - . / and spaces. The URDF examples below go inside a
<gazebo reference="LINK"> block, as every URDF sensor does. Their ray checks (occlusion, the floor
under a sensor) are exact casts against every collider at its body’s pose (ShapeCaster, the
CPU reference) that look through the colliders of the sensor’s own body: a camera looks out of
its housing, an array out of its chassis.
detections¶
Ground-truth annotations for machine-learning datasets, attached to a camera of the same robot:
from that camera’s instance image (sensor/<camera>/instance, the scene prim index per pixel)
and the scene, every visible object’s 2D box, visible pixels, occlusion and truncation, class and
3D box, and a semantic segmentation image. It runs in step with the camera, at the camera’s
rate (its own update_rate is not used), and reads the frame the camera drew in the same tick.
<sensor name="front_labels" type="detections">
<camera>front_camera</camera>
<semantic>crate,pallet=1;forklift=2;human,person=3</semantic>
<max_objects>32</max_objects>
</sensor>
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
required |
the camera sensor whose images it labels |
|
|
the table below |
|
|
|
64 |
rows of |
|
|
px |
1 |
fewer visible pixels: not listed (still in the semantic image) |
|
1 |
0: no occlusion renders (field 7 NaN) |
Objects. A robot is one object (every body below one root body, drawn parts and all), a
walking human (RFC 0009, one robot per person) is one object, and every static scene prim with a
mesh is one. The object’s id (field 0) is the lowest scene prim index of its parts, the number
its pixels carry in sensor/<camera>/instance.
Classes. The class comes from the words of the root body’s name, then the body’s, then each
part’s prim path; a moving body nothing names is 9 (robot); anything else is 0 (unlabelled).
Without semantic:
Id |
Words |
|---|---|
1 ground |
ground, floor, terrain |
2 road |
road, lane, sidewalk, crossing, marking |
3 building |
building, wall, house, shed, roof |
4 vehicle |
car, sedan, vehicle, truck, bus, van |
5 person |
human, person, pedestrian, walker, actor |
6 vegetation |
tree, bush, hedge, plant, vegetation |
7 pole, sign |
pole, sign, light, signal |
8 goods |
box, crate, pallet, rack, shelf, barrel, cone |
9 robot |
any other moving body |
Signals.
Signal |
Type |
Unit |
Meaning |
|---|---|---|---|
|
ScalarArray, |
mixed (below) |
one row per object, NaN rows after the last |
|
Int |
1 |
rows filled |
|
Image |
the class id per pixel, 0 for nothing or unlabelled, the camera’s size |
The 16 fields of a row:
# |
Field |
Unit |
|---|---|---|
0 |
object id (scene prim index) |
|
1 |
class id |
|
2–5 |
2D box |
px |
6 |
visible pixels |
px |
7 |
occlusion: 1 − visible / pixels it covers drawn alone (NaN without a GPU device, with |
1 |
8 |
truncation: the share of its projected 3D box outside the image (NaN when the box is partly behind the camera, and on a fisheye camera) |
1 |
9–11 |
3D box centre in the camera’s optical frame (x right, y down, z forward) |
m |
12–14 |
3D box length, width, height: along the object’s own x, y, z (the root body’s frame; a static prim’s own frame) |
m |
15 |
yaw: KITTI’s |
rad |
Model. The 2D boxes, pixel counts and the semantic image come straight from the instance
image, so they are exact for what the camera drew, lens distortion and rolling shutter included.
The occlusion draws each listed object alone with the same pinhole (no lens model) on the
camera’s device: exact without lens distortion, approximate with it. That is one more render
per listed object and frame (max_objects, occlusion 0 to skip them in a busy scene). The 3D box is the
axis-aligned box of the object’s meshes in its frame, at this step’s body poses (the box of the
mesh vertices, not the tightest box). The conventions follow the KITTI object benchmark (Geiger,
Lenz, Urtasun 2012, “Are we ready for autonomous driving?”, CVPR; its devkit_object readme
defines the box, truncated, occluded and rotation_y); KITTI’s occlusion is a level
(0–3) and its 3D box centre is the bottom face’s, while here occlusion is a fraction and the
centre is the box’s middle. A GPU path (invariant 7): not deterministic, like the camera. With
the cameras as ground truth (empty images) it lists nothing. test_kinds_detections: three boxes
at known poses give their projected 2D boxes within a pixel, the occlusion of the one behind
within 0.02 of the closed form, their 3D boxes and classes (llvmpipe or a GPU).
The rows are on ROS by default as vision_msgs/Detection2DArray on /<n>/detections and
Detection3DArray on /<n>/detections_3d, the semantic image as /<n>/semantic/image_raw
(“ROS topics of the built-in kinds”, “Images of kinds”). The raw rows as a
std_msgs/msg/Float64MultiArray take a --ros-topics map (which replaces both defaults):
publish:
- {signal: sensor/front_labels/detections, topic: /front_labels/detections,
type: std_msgs/msg/Float64MultiArray}
- {signal: sensor/front_labels/count, topic: /front_labels/count, type: std_msgs/msg/Int64}
landing_target¶
A vision landing-target detector (an AprilTag or ArUco pad seen by a downward camera, IR-LOCK
style beacons) at the detector level, with PX4’s meaning of MAVLink LANDING_TARGET
(common.xml: angle_x, angle_y, distance, size_x, size_y, position). No fiducial texture
is drawn or decoded: the target is a scene prim, seen when it is wholly in the field of view, in
range, facing the camera, not behind a collider, and large enough in pixels to decode.
<sensor name="pad_finder" type="landing_target">
<pose>0 0 -0.05 0 1.5708 0</pose> <!-- pitched 90°: x down, a downward camera -->
<update_rate>20</update_rate>
<target>landing_pad</target>
<horizontal_fov>1.047</horizontal_fov>
<max_range>20</max_range>
</sensor>
The open field’s pad (assets/worlds/open_field, prim landing_pad, 2 m × 2 m) is the default
target.
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
|
the prim (name or path); its box’s top face centre is the target point, its +z its normal |
|
|
m |
its box’s x and y extents, else 1 |
side of the marker |
|
rad |
1.047; from |
the camera’s view (sensor x forward) |
|
px |
640, 480 |
the image, for pixels across the marker |
|
m |
0.05, 30 |
|
|
px |
12 (illustrative) |
pixels across the marker’s smaller side under which it is never decoded |
|
rad |
1.2217 (70°, illustrative) |
the most the line of sight may be off the marker’s normal |
|
px |
0.5 (illustrative) |
1 sigma of the corners’ position |
|
m |
0.05 |
a collider this close in front of the target does not hide it |
Signals: sensor/<n>/detected (Bool), angle_x, angle_y (rad: the target’s direction in
the optical frame, atan2(x, z) and atan2(y, z), x right, y down), distance (m),
position (Vec3, m, in the sensor frame: x forward, y left, z up), size_x, size_y (rad, the
angular size of the marker’s sides). Not detected: NaN in all but detected.
Model. With f = width / 2 / tan(horizontal_fov / 2) and the marker pixels = f · s ·
√cos θ / d across (s its smaller side, θ the angle between the line of sight and its normal, d the
distance), the chance of a detection per frame is (pixels − min_pixels) / min_pixels, clamped
to 0..1: none below min_pixels, always from twice that. Each angle gets Gaussian noise of
pixel_noise / f, and the distance, taken from the apparent size, of d · pixel_noise / pixels:
it grows with d² as a fiducial’s range does. Occlusion is one exact ray (ShapeCaster) from the
target point towards the sensor; a collider within occlusion_margin of either end, or on the
sensor’s own body, does not hide it. Deterministic (CPU, Philox). Under ground_truth: exact, detected
whenever the chance is above 0. test_kinds_landing_target: a pad at a known offset gives the
angles and distance of the geometry, the noise has the spread above within 5 %, the detection rate
the chance above, and a collider, the field of view and the range hide it.
On ROS by default as /<n>/<quantity> (“ROS topics of the built-in kinds”); a map for other
names:
publish:
- {signal: sensor/pad_finder/angle_x, topic: /landing_target/angle_x, type: std_msgs/msg/Float64}
- {signal: sensor/pad_finder/position, topic: /landing_target/position,
type: geometry_msgs/msg/Vector3Stamped, frame: pad_finder}
line_sensor¶
An AGV guide sensor, a row of channels across the sensor’s y that look down (the sensor’s −z) for tape on the floor: a reflective line-follower array or a magnetic tape sensor, at the detector level (no light or magnetic field is modelled, only where tape is). Channel 0 is the leftmost (+y).
<sensor name="guide" type="line_sensor">
<pose>0.3 0 0.04 0 0 0</pose>
<update_rate>100</update_rate>
<channels>16</channels>
<spacing>0.01</spacing>
</sensor>
Tape is either a scene prim with the word tape or line in its name (parameter pattern; its
mesh box: a thin box or quad on the floor; e.g. a URDF link tape_aisle_1 with a
<box size="10 0.05 0.001"/> visual fixed to the world, or a USD Xform "guide_tape" with a
mesh), or a collider whose surface material (SensorMaterialAPI_1, URDF <sensor_material>) has
a 905 nm reflectivity of at least tape_reflectivity (at most, with dark_tape).
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
16 |
||
|
m |
0.01 (illustrative) |
between channel centres; each channel is that wide |
|
5 |
rays across a channel |
|
|
m |
0.1 |
tape further below is not seen |
|
1 |
0.02 (illustrative) |
1 sigma on each channel’s activation |
|
1 |
0.2 |
activation a channel counts from in |
|
|
words that make a prim tape |
|
|
1 |
0.8 |
the collider route |
|
0 |
1: tape darker than |
Signals: sensor/<n>/channels (ScalarArray of channels, 1: the share of each channel over
tape, 0..1), offset (m, the line’s centre to the sensor’s left, the activation-weighted mean of
the channels at or over threshold; NaN without tape), width (m, the tape under the array,
Σ activation × spacing: wider at a junction or a marker), detected (Bool).
Model. Each of a channel’s rays counts when the first thing below it within max_range
(its own body’s colliders aside) is tape (a tape prim’s box no further than 1 mm past the floor, or a tape-bright collider). The
offset resolves a fraction of a channel: within one ray spacing (spacing /
samples_per_channel) of the tape’s centre without noise (test_kinds_line_sensor, named tape
and bright collider). Deterministic (CPU, Philox); ground_truth drops the noise. Real arrays
reach about 1 mm: the Roboteq MGS1600GY magnetic guide sensor (datasheet v1.3, 2018, table 11)
gives 160 mm of capture width, 1 mm resolution (2 mm at most) from 16 sensors, at 100 Hz.
tag_reader¶
A warehouse localisation reader for tags on the floor at the detector level: mode rfid reads
the nearest tag within a radius of the antenna; mode qr (QR or Data Matrix under a downward
camera) reads the tag nearest the optical axis in the camera’s footprint (along the sensor’s −z),
facing it and not hidden, with its offset and yaw.
<sensor name="floor_reader" type="tag_reader">
<pose>0 0 0.05 0 0 0</pose>
<update_rate>30</update_rate>
<mode>qr</mode>
<max_range>0.3</max_range>
</sensor>
Tags are scene prims whose name starts with rfid_ or qr_ (parameter prefix); a tag’s point
is its box’s top face centre (its origin without a mesh), its +z must face the reader, its x axis
gives the yaw. The number a name ends with is its code (qr_0042 → 42). Tags on the floor of a
USD world:
def Xform "qr_0001" {
double3 xformOp:translate = (2.0, 0.5, 0.0005)
uniform token[] xformOpOrder = ["xformOp:translate"]
def Cube "visual" { double size = 1 float3 xformOp:scale = (0.05, 0.05, 0.001)
uniform token[] xformOpOrder = ["xformOp:scale"] }
}
def Xform "rfid_17" { double3 xformOp:translate = (4.0, 0.5, 0.0)
uniform token[] xformOpOrder = ["xformOp:translate"] }
or a URDF link qr_0001 with a <box size="0.05 0.05 0.001"/> visual fixed to the world. The
sample floor assets/worlds/tag_floor/tag_floor.urdf has an 8 m guide tape along x with QR tags
qr_0001..qr_0004 on it every 2 m from x = 1.5 m and RFID tags rfid_1..rfid_4 between
them: lagrange my_agv.urdf assets/worlds/tag_floor/tag_floor.urdf.
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
|
|
|
|
|
||
|
m |
0.1 (illustrative, an HF floor tag) |
from the sensor’s origin to the tag point |
|
m |
0.01, 0.5 |
depth below the reader |
|
rad |
0.8, as horizontal |
the footprint across the sensor’s x and y |
|
rad |
0.79 (45°) |
|
|
m |
5e-4 (illustrative) |
1 sigma on the offset’s x and y |
|
rad |
0.005 (illustrative) |
1 sigma |
Signals: sensor/<n>/detected (Bool), tag (Int: the index in the tags of this mode sorted
by path, −1 for none), code (Int, −1 without a number), tag_position (Vec3, m, world_local:
the tag’s surveyed position, for a localisation filter), offset (Vec3, m, the tag point in the
sensor frame), yaw (rad: the tag’s x axis in the sensor’s xy plane; NaN for RFID).
Model. RFID: the nearest tag in range, read every step (no anti-collision protocol or
missed reads; radio passes through colliders). QR: the footprint, the facing test and one
occlusion ray (as landing_target’s, 1 cm margin); Gaussian noise on the
offset and yaw. Deterministic (CPU, Philox); ground_truth drops the noise.
test_kinds_tag_reader: a QR tag at a known pose gives its offset and yaw exactly, its noise the
spread set, RFID reads within and not beyond its range, and a reader in its own housing reads while another
body’s plate hides the tag.
On ROS by default as /<n>/<quantity> (“ROS topics of the built-in kinds”); a map for other
names:
publish:
- {signal: sensor/floor_reader/code, topic: /floor_reader/code, type: std_msgs/msg/Int64}
- {signal: sensor/floor_reader/offset, topic: /floor_reader/offset,
type: geometry_msgs/msg/Vector3Stamped, frame: floor_reader}
wifi_scanner¶
What a Wi-Fi scan reports: the received signal strength (RSSI) of every access point the robot
hears (modules/sensors/src/kinds/WifiScanner.cpp, test_kinds_wifi_scanner).
<gazebo reference="base_link">
<sensor name="wifi" type="wifi_scanner">
<pose>0 0 0.4 0 0 0</pose>
<update_rate>10</update_rate>
<wifi_scanner>
<access_points>0 0 2.5; 30 12 2.5</access_points>
<scan_time>2</scan_time>
<sensitivity>-82</sensitivity>
</wifi_scanner>
</sensor>
</gazebo>
Access points, in the order of the outputs:
every
RadioLinkAPI_1whose receiver prim is on the sensor’s body (its transmitter is the access point). It readslink/<rx>/rx_powerfrom the comms domain, so walls and shadowing are the link’s (comms.md). With the comms domain off (the input unconnected, or the ideal substitute’s 1 W sentinel) the link’s own attributes go through the model below;the points of
access_points(x y z; x y z; ..., m, in the region frame the run started in; they move with a floating-origin rebase as the scenery does);every world prim or body whose name starts with
wifi_ap, in load order.
The model for 2 and 3 (and 1 without comms) is comms.md’s log-distance budget: Friis free space
to reference_distance, then (d/d0)^path_loss_exponent, and wall_loss_db per wall the
straight line crosses (colliders of bodies that never move; the ground, the scanner’s body and
the access points’ bodies left out).
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
m |
none |
|
|
s |
2 |
a new scan every so often; between scans the outputs hold. Illustrative: a scan dwells some 60 ms on each channel when active and 111 ms when passive (Linux mac80211 |
|
dBm |
−82 |
weaker access points are not listed: the OFDM PHY’s minimum input sensitivity at 6 Mb/s, 20 MHz (IEEE 802.11-2020 Table 17-18) |
|
dB |
0 |
1σ per reading, before rounding (the comms domain adds its own shadowing) |
|
W |
0.1 |
20 dBm |
|
Hz |
2.437e9 |
channel 6 |
|
1 |
3 |
as the sample link |
|
m |
1 |
|
|
dB |
10 |
per wall, illustrative (as the sample link) |
Signal |
Type |
Unit |
Meaning |
|---|---|---|---|
|
ScalarArray(N) |
dBm (unit |
per access point, rounded to whole dBm as scans report it; NaN when not heard |
|
ScalarArray(N) |
W |
the same as power, |
|
Int |
1 |
access points heard |
|
Bool |
1 |
at least one heard |
N is the number of access points (at least 1). Ground truth: the model’s exact level, no noise,
no rounding, no sensitivity cut. Checked against the closed form at 10 m (−50 dBm), with a wall,
the sensitivity cut, a link’s −40 dBm and the scan interval. On ROS by default as /<n>/<quantity> (“ROS topics of the
built-in kinds”); a map for other names:
publish:
- {signal: sensor/wifi/rssi, topic: /wifi/rssi, type: std_msgs/msg/Float64MultiArray}
uwb¶
Ultra-wideband two-way ranging from a tag on the robot to fixed anchors, as a Qorvo (Decawave)
DW1000 or DW3000 gives it (modules/sensors/src/kinds/Uwb.cpp, test_kinds_uwb).
<gazebo reference="base_link">
<sensor name="tag" type="uwb">
<pose>0 0 0.3 0 0 0</pose>
<update_rate>10</update_rate>
<uwb>
<anchors>0 0 2.5; 20 0 2.5; 20 15 2.5; 0 15 2.5</anchors>
<range_noise>0.1</range_noise>
</uwb>
</sensor>
</gazebo>
Anchors, in the order of the outputs: the points of anchors (x y z; ..., m, in the region frame
the run started in; they move with a floating-origin rebase as the scenery does),
then every world prim or body whose name starts with uwb_anchor (in prim order, then body
order; a body is taken at its origin). A run with no anchor is refused.
Each range is the straight distance from the tag (the sensor’s mount) to the anchor. When that
line passes through colliders (all of them but the tag’s body and the anchors’ own bodies), the
first path is slower inside them: the range grows by (√εr − 1) times the length inside, the
excess delay of a pulse through a dielectric slab, and the flag los is 0; such a range also gets
nlos_noise. Material shorter than 1 cm along the line (an anchor on a wall) does not count.
Beyond max_range the anchor drops out.
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
m |
none |
|
|
m |
0.1 |
1σ with line of sight: “a precision of 10 cm” (DW1000 Datasheet Version 2.10, p. 1; DW3000 Datasheet Version 1.1: “an accuracy of 10 cm”), on the safe side: the DW1000’s figure 11 spreads about ±8 cm |
|
1 |
5.24 |
εr of what blocks the line: concrete, 1–100 GHz (ITU-R P.2040-1 Table 3; UWB channels 5 and 9 are 6.5 and 8 GHz) |
|
m |
0.3 |
extra 1σ without line of sight, illustrative |
|
m |
50 |
illustrative for indoor anchors at 6.8 Mb/s (DW1000 datasheet figure 31: some 50–110 m in open line of sight) |
Signal |
Type |
Unit |
Meaning |
|---|---|---|---|
|
ScalarArray(N) |
m |
per anchor; NaN beyond range |
|
ScalarArray(N) |
1 |
1 line of sight, 0 through material, NaN beyond range |
|
Int |
1 |
anchors in range |
|
Bool |
1 |
at least one |
Ground truth: the straight distance, no delay, no noise (los still tells whether the line is
clear). Checked: exact distances, σ = 0.1 m over 2000 samples, 0.2 m of concrete adding
(√5.24 − 1)·0.2 m, dropouts and anchors named in the world. On ROS by default as /<n>/<quantity> (“ROS topics of the
built-in kinds”); a map for other names:
publish:
- {signal: sensor/tag/ranges, topic: /uwb/ranges, type: std_msgs/msg/Float64MultiArray}
particle_sensor¶
An optical particulate-matter sensor such as the Sensirion SPS30, reading the dust the weather
domain puts in the air (modules/sensors/src/kinds/ParticleSensor.cpp,
test_kinds_particle_sensor). A gas sensor has no counterpart yet: no domain carries gas
concentrations.
<gazebo reference="base_link">
<sensor name="pm" type="particle_sensor">
<update_rate>1</update_rate>
</sensor>
</gazebo>
The air holds two populations of grains, each of one size: the weather’s own dust
(env/dust/concentration and env/dust/median_diameter, written by the weather domain from its
dust_concentration and dust_median_diameter) and the dust rotor outwash lifts off loose ground
(env/dust/downwash, of downwash_diameter). PMx counts the grains between 0.3 µm and x. The
reading follows the air with a first-order lag, y += (u − y)(1 − e^(−dt/τ)) (the first sample reads the air as it is), then gets the
datasheet’s precision as Gaussian noise and is held within 0–1000 µg/m³. Without the weather
domain (its inputs unconnected) every class is NaN and valid 0; without lifted dust that part
is 0.
Sensirion SPS30 datasheet (Version 2.0 – D1 – June 2023, table 1): sizes 0.3–10 µm, range 0–1000 µg/m³, sampling interval 1 s; precision PM1 and PM2.5 ±(5 µg/m³ + 5 % of the reading) up to 100 µg/m³ (±10 µg/m³ in v1.0 of March 2020) and ±10 % above, PM4 and PM10 ±25 µg/m³ and ±25 %, taken here as 1σ of each reading. Sensirion’s precision is the variation between devices on averages of at least 150 s, so this is a stand-in: a real part’s error is more an offset that stays than noise.
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
s |
8 |
the lag: the SPS30’s typical start-up time at 200–3000 particles/cm³ (table 1); illustrative as a lag, since Sensirion gives no step response |
|
1 |
1 |
times the datasheet precision (0: no noise) |
|
m |
1e-4 |
grains lifted by outwash (the weather’s |
Signal |
Type |
Unit |
Meaning |
|---|---|---|---|
|
Scalar |
kg/m³ |
mass concentration; µg/m³ = kg/m³ × 1e9 |
|
Bool |
1 |
the weather domain is there |
Ground truth: the air’s PMx exactly, no lag, no noise, no limit. Checked: the classes a grain
size falls in, a step against 1 − e^(−t/τ), the precision at 50 µg/m³ over 3000 samples, the
1000 µg/m³ limit, NaN without weather. Run with --weather ...,dust_concentration=2e-7 (200
µg/m³). On ROS by default as /<n>/<quantity> (“ROS topics of the
built-in kinds”); a map for other names:
publish:
- {signal: sensor/pm/pm2_5, topic: /pm/pm2_5, type: std_msgs/msg/Float64}
proximity¶
A proximity skin of a collaborative robot: an array of short-range time-of-flight elements over
a field of view (modules/sensors/src/kinds/Proximity.cpp, test_kinds_proximity). Each element
casts one ray along its direction against every collider except the sensor’s own body and reads
the distance to the first. A different kind from the tof and ultrasonic plugins: many
elements, and the nearest of them as one signal for a speed-and-separation monitor.
<gazebo reference="forearm_link">
<sensor name="skin" type="proximity">
<pose>0.1 0 0.05 0 0 0</pose>
<update_rate>50</update_rate>
<proximity>
<rows>2</rows><columns>4</columns>
<fov>1.2</fov><vertical_fov>0.4</vertical_fov>
<max_range>0.3</max_range>
</proximity>
</sensor>
</gazebo>
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
1 |
1, 1 |
elements, at most 4096 |
|
rad |
0.44 |
spread of the columns about the sensor’s +x (25°: ST VL53L0X DocID029104 Rev 2, §5.1) |
|
rad |
|
spread of the rows |
|
m |
0, 0.3 |
outside them an element reads +inf |
|
m |
0.012 |
1σ per element: the VL53L0X’s 4 % standard deviation (table 12, 33 ms, white target indoors) at the 0.3 m reach |
Element (row r, column c) looks at azimuth −fov/2 + (c + ½)·fov/columns (columns from the
sensor’s right to its left) and elevation −vertical_fov/2 + (r + ½)·vertical_fov/rows (rows from
bottom to top), row-major in the outputs.
Signal |
Type |
Unit |
Meaning |
|---|---|---|---|
|
ScalarArray(rows·columns) |
m |
per element; +inf when nothing in range |
|
Scalar |
m |
the nearest; +inf for none |
|
Bool |
1 |
something in range |
Ground truth: the ray distances exactly. Checked against d / (cos el · cos az) to a wall, the
range cut and σ = 1 mm. On ROS by default as /<n>/<quantity> (“ROS topics of the
built-in kinds”); a map for other names:
publish:
- {signal: sensor/skin/min_distance, topic: /skin/min_distance, type: std_msgs/msg/Float64}
gripper_sensor¶
What a gripper’s controller knows about its grasp: the opening, the motor current, whether it
holds something and whether that slips (modules/sensors/src/kinds/GripperSensor.cpp,
test_kinds_gripper_sensor). Mount it on the hand; the fingers are joints.
<gazebo reference="hand">
<sensor name="grip" type="gripper_sensor">
<update_rate>100</update_rate>
<gripper_sensor>
<fingers>finger_l_joint finger_r_joint</fingers>
<width_scale>1</width_scale>
<torque_constant>10</torque_constant>
</gripper_sensor>
</sensor>
</gazebo>
The model:
Opening:
width_offset + width_scale · Σ joint/<f>/positionover the finger joints (two prismatic fingers moving apart from 0: scale 1, offset 0; revolute fingers: scale ≈ finger length).Current: Σ |
motor/<m>/current_q| over the motorsmotorsnames (the electrical domain’s torque current); withoutmotors, or with the electrical domain off, the proxy Σ |joint/<f>/torque| /torque_constant(0 for a joint nothing drives).Contact: a finger touches when |
body/<finger>/contact_force| (its joint’s child body) exceedscontact_threshold. An object is held when every finger touches and the opening is aboveclosed_width(fingers pressing on each other are not an object).grip_forceis the smallest finger’s contact force while all touch, else 0.Slip: the object is the body
objectnames, else a moving body outside the gripper’s body tree within a finger’s colliders’ reach pluscontact_margin. Its velocity at the finger less the finger’s, with the part along the contact force removed, is the slip speed;slipis 1 while an object is held and that exceedsslip_threshold.
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
text |
required |
finger joint names |
|
text |
none |
motor names for |
|
m per joint unit, m |
1, 0 |
|
|
N·m/A or N/A |
1 |
for the current proxy |
|
N |
0.5 |
illustrative |
|
m |
0.001 |
|
|
m/s |
0.005 |
illustrative |
|
m |
0.005 |
|
|
text |
none |
the held body by name |
|
m, A |
0, 0 |
1σ |
Signal |
Type |
Unit |
Meaning |
|---|---|---|---|
|
Scalar |
m |
opening |
|
Scalar |
A |
motor current, or its proxy |
|
Scalar |
N |
|
|
Bool |
1 |
|
|
Bool |
1 |
|
|
Scalar |
m/s |
0 when nothing is held |
Ground truth: no noise. Checked: a held 4 cm cube (opening, current, grip), slip across the force
and none along it, closed or open fingers holding nothing, the motors’ currents. On ROS by default as /<n>/<quantity> (“ROS topics of the
built-in kinds”); a map for other names:
publish:
- {signal: sensor/grip/object_detected, topic: /gripper/object_detected, type: std_msgs/msg/Bool}
tpms¶
A tyre-pressure monitoring system: a pressure and temperature sensor in every tyre of a vehicle
(modules/sensors/src/kinds/Tpms.cpp, test_kinds_tpms). Its wheels are the WheelAPI_1
joints in the sensor’s body tree (or those wheels names), in load order.
<gazebo reference="base_link">
<sensor name="tpms" type="tpms">
<update_rate>1</update_rate>
<tpms><fill_pressure>230000</fill_pressure></tpms>
</sensor>
</gazebo>
The tyre’s air is an ideal gas at nearly constant volume (Gay-Lussac): its absolute pressure is
the cold fill’s, fill_pressure + 101325 Pa at fill_temperature, times T / T_fill, with T
the ambient air’s (env/air_temperature from the weather domain, else the parameter
temperature; with neither every reading is NaN and valid 0). The vehicle_dynamics domain has
no tyre temperature, so the heating of a running tyre is not modelled: the readings follow
the weather only (a cold morning’s drop, a leak). A leak lowers the fill by leak_rate. The
reading is gauge pressure (absolute less env/pressure, else 101325 Pa), and warning comes on
as FMVSS No. 138 (49 CFR 571.138 S4.2) asks, when a tyre is 25 % or more below the placard.
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
Pa (gauge) |
230000 |
the placard cold pressure, a typical car |
|
K |
293.15 |
where it was filled |
|
K |
none |
the air’s when the weather domain is off |
|
Pa/s |
0 |
every tyre |
|
Pa |
0 |
1σ |
|
text |
all |
wheel joint names |
Signal |
Type |
Unit |
Meaning |
|---|---|---|---|
|
ScalarArray(N) |
Pa |
gauge, per wheel |
|
ScalarArray(N) |
K |
per wheel |
|
Bool |
1 |
FMVSS No. 138 low pressure |
|
Bool |
1 |
an air temperature is known |
Ground truth: no noise. Checked: 230 kPa filled at 20 °C reads 207.4 kPa at 0 °C, a 1 kPa/s leak
warns after 57.5 s, NaN without a temperature. On ROS by default as /<n>/<quantity> (“ROS topics of the
built-in kinds”); a map for other names:
publish:
- {signal: sensor/tpms/pressure, topic: /tpms/pressure, type: std_msgs/msg/Float64MultiArray}
sonar¶
An underwater sonar: by default a multibeam imaging sonar’s fan, after the Blueprint Subsea
Oculus M750d in its 750 kHz mode (Blueprint Subsea, Oculus M-series specifications page,
blueprintsubsea.com/oculus/oculus-m-series, read 2026-11-12: 0.1 to 120 m, 130° × 20°, 512
beams, 4 mm range resolution, up to 40 Hz); with beams 1 a single-beam echosounder or altimeter
such as the Blue Robotics Ping2 (store page “Ping Sonar Altimeter and Echosounder”, technical
details, read 2026-11-12: 115 kHz, a 25° beam at −3 dB, 0.3 m to 100 m typical, range resolution
0.5 % of range). The defaults are the Oculus’s: for a Ping2 give beams 1, frequency 115000
and range 0.3 to 100 m, as the example does. It hears only under the surface of a body of water
(WaterAPI_1, as the hydrodynamics domain and the lidars read it).
<sensor name="fls" type="sonar"> <!-- forward-looking, +x ahead, z up -->
<pose>0.3 0 -0.1 0 0.35 0</pose>
<update_rate>15</update_rate>
<sonar><beams>256</beams><image_bins>200</image_bins><water_temperature>12</water_temperature></sonar>
</sensor>
<sensor name="altimeter" type="sonar"> <!-- Ping2 looking down -->
<pose>0 0 -0.15 0 1.5708 0</pose>
<update_rate>10</update_rate>
<sonar><beams>1</beams><beam_width>0.436</beam_width><frequency>115000</frequency><range><min>0.3</min><max>100</max></range></sonar>
</sensor>
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
512 |
across |
|
|
rad |
2.269 (130°), 0.349 (20°) |
the fan |
|
rad |
0.436 (25°) |
full cone of a single beam |
|
5 |
rays across |
|
|
m |
0.1, 120 |
|
|
m |
0.004 |
range quantisation |
|
m |
|
1σ on the range |
|
m/s |
1500 |
what the device converts time of flight with (Urick, Principles of Underwater Sound, 1983: the conventional round value) |
|
°C, PSU, 1 |
10, 35, 8 (illustrative) |
the water: absorption, and with a temperature its own sound speed; −2 to 40 °C (not K) and 0 to 45 PSU, else refused |
|
Hz |
750e3 |
for the absorption |
|
dB |
−27 |
Lambert’s 10·log10 μ (Mackenzie, JASA 33(11), 1961), every surface |
|
dB |
1 (illustrative) |
1σ on the echo level |
|
dB |
−180 (illustrative) |
weaker echoes are not detected |
|
0 |
range bins of the polar image; 0: no image |
Signals: ranges (ScalarArray[beams], m; +inf without an echo), intensities (ScalarArray[beams],
dB re a perfect reflector at 1 m; NaN without an echo), image (ScalarArray[beams × image_bins],
row per beam, dB above min_level at each echo’s bin, 0 elsewhere; only with image_bins),
depth (m below the surface; NaN in air), sound_speed (m/s, the water’s), ping_interval (s),
valid (Bool: under water).
Model: each beam’s first echo among its rays: the colliders at their bodies’ poses (the CPU
ShapeCaster, the sensor’s own body skipped), the water’s flat surface (its mean level: waves
are not seen) and the box’s bottom; sound leaving through a side of the box is lost. The water’s
sound speed is Mackenzie’s nine-term equation (JASA 70(3), 1981) when water_temperature is
given, else sound_speed; the device reads range = true range × sound_speed / c, so a sonar set
to 1500 m/s in 1490 m/s water reads 0.7 % long, as real ones do. A ping waits for the farthest
echo: the kind steps no faster than 1 / (2·range/max / sound_speed) (0.16 s at 120 m). Echo
level −40·log10 R − 2·α·R + 10·log10(μ·cos²θ): two-way spherical spreading, absorption α by
Ainslie and McColm (JASA 103(3), 1998; ≈ 0.24 dB/m at 750 kHz, 10 °C) and Lambert backscatter at
incidence θ (from two more rays 1 mrad apart on a collider). No beam pattern, side lobes,
multipath, speckle or acoustic shadow texture; the insonified area is not in the level. Above water
everything reads nothing and valid 0. Check: test_kinds_sonar (Mackenzie’s value, ≈ 1 dB/km at
10 kHz, the bottom and the surface at their depths, the sound speed’s bias, a fan on a wall at
45°: √2 in range and 12.04 + 3.01 dB weaker, the image bin, the noise and 4 mm steps).
ROS by default: a fan as /fls/scan (sensor_msgs/LaserScan with the intensities, beam 0 the
left one, so the angles run from +65° to −65°), one beam as /<n>/range (sensor_msgs/Range,
ULTRASOUND), and the rest on /<n>/<quantity>. By hand: {signal: sensor/fls/ranges, topic: /fls/scan, type: sensor_msgs/msg/LaserScan, frame: fls, params: {angle_min: 1.1345, angle_max: -1.1345, range_min: 0.1, range_max: 120.0}}.
adsb_receiver¶
A 1090 MHz ADS-B receiver (1090ES, RTCA DO-260B) that hears the other aircraft of the run: a
detect-and-avoid input for a drone, or a ground station’s traffic display. An aircraft is another
robot with RotorAPI_1 rotors (Lagrange has no fixed-wing aircraft yet), or with aircraft: all
every other robot whose root body is not kinematic (traffic agents and lamps never count). It reads
their root bodies’ body/<b>/pose and twist from the bus, nothing else.
<sensor name="adsb" type="adsb_receiver">
<update_rate>10</update_rate>
<adsb_receiver><range><max>50000</max></range></adsb_receiver>
</sensor>
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
|
or |
|
|
m |
100e3 (illustrative) |
|
|
1 |
0: no radio horizon |
|
|
m |
2 (illustrative) |
the receiver’s antenna above its mount, for the horizon |
|
m |
3 (illustrative) |
1σ per axis of the sender’s GNSS position |
Signals: aircraft (ScalarArray, 10 per aircraft in robot order: robot index (the ICAO address
stands in), heard (1/0), latitude (rad), longitude (rad), height (m, ellipsoidal) when the site’s
geo origin is known (geodetic 1), else x, y, z in world ENU (m); east, north, up velocity (m/s);
age of the last message (s); distance (m)); count (Int, aircraft heard); geodetic (Bool).
Model: each aircraft squitters its airborne position and velocity every 0.4 to 0.6 s at random
(ICAO Annex 10 Vol. IV §3.1.2.8.6.4.2 and .5, which DO-260B implements; about 2 Hz; the receiver should run at 10 Hz or more to see them); a message
is heard while the aircraft is within range/max and the straight line is above the radio horizon
√(2kR·h₁) + √(2kR·h₂), k = 4/3 (Bean and Dutton, Radio Meteorology, 1966), heights the ENU up
coordinates (h₁ plus antenna_height). The message carries the sender’s noisy position, height
in 25 ft steps, east and north velocity in 1 kt steps and vertical rate in 64 ft/min steps (the Q-bit
altitude of Annex 10 Vol. IV §3.1.2.6.5.4 and the subtype 1 velocity, as J. Sun’s The 1090
Megahertz Riddle, 2nd ed., gives it); latitude and longitude are not CPR-encoded (their
≈ 5 m step is below the noise). Out of reach the row reads NaN and heard 0. No garbling, Mode S
interference, barometric altitude, identification or NIC/NACp fields. ground_truth: every step,
exact. Check: test_kinds_adsb_receiver (which robots are aircraft, exact local and geodetic
positions, range and horizon at 30 and 50 km, 17 to 25 messages in 10 s, the quantisation).
ROS by default: /adsb/aircraft (std_msgs/Float64MultiArray, dimensions rows × columns of
10; no standard ROS message carries ADS-B), /adsb/count, /adsb/geodetic.
v2x¶
A V2X on-board unit (DSRC IEEE 802.11p or C-V2X PC5) receiving the SAE J2735 messages of the traffic domain’s world: each traffic agent’s Basic Safety Message and each signalised approach’s Signal Phase and Timing, sent at 10 Hz (SAE J2945/1) by a roadside unit at its signal head.
<sensor name="obu" type="v2x">
<update_rate>10</update_rate>
<v2x><loss_distance>300</loss_distance></v2x>
</sensor>
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
m |
300 (illustrative) |
where half the messages are lost |
|
m |
50 (illustrative) |
how fast the loss grows |
|
m |
1000 |
nothing beyond |
|
s |
0.5 |
a sender counts as heard while its last message is this recent |
Signals: bsm (ScalarArray, 10 per traffic agent in traffic/agents order: index, valid, class
(0 car, 1 pedestrian), x, y (m, world_local), yaw (rad), speed (m/s), length, width (m), age (s)),
spat (ScalarArray, 7 per light in traffic/lights order: index, valid, road id, state (0 red,
1 yellow, 2 green), x, y of the signal head (m), age (s)), bsm_count, spat_count (Int: valid
rows), valid (Bool: the traffic domain’s signals are there).
Model: inputs traffic/agents and traffic/lights only (optional: without the traffic domain
everything reads NaN and valid 0). Their lengths are found from the world as the traffic domain
finds them (one agent per kinematic body traffic_vehicle_<i>/traffic_pedestrian_<i>, one light
per signal head, the kinematic lamp bodies traffic_lamp_<lane>_red in lane order), so a
different traffic layout would stop the run at wiring, not misread. Each step every sender in range
is received with probability 1/(1 + exp((d − loss_distance)/loss_width)): illustrative, of the shape
of measured DSRC packet delivery ratios, not fitted (Meireles et al., IEEE VNC 2010: over 80 %
at 400 m with line of sight in their suburban run, to zero at 500 m with vehicles in the way; the
defaults, 12 % at 400 m, sit near the obstructed case);
no walls, no channel congestion, no latency. A row keeps its last message; age grows until the
next. Run it at 10 Hz (one draw per step). ground_truth: every message in range. Check:
test_kinds_v2x (exact copies and the heads’ positions, ½ received at loss_distance over 2000
steps, range, no traffic).
ROS by default: /<n>/spat and /<n>/bsm (std_msgs/Float64MultiArray, rows of 7 and 10),
the counts and valid; a map renames them, e.g. {signal: sensor/obu/spat, topic: /v2x/spat, type: std_msgs/msg/Float64MultiArray}.
vehicle_can¶
What a production car’s own sensors put on its CAN bus, for a VehicleAPI_1 robot (the sensor’s
robot must have a VehicleAPI_1 chassis, or the run refuses to start): ABS wheel speeds, the
steering wheel angle, the ESP cluster’s yaw rate and accelerations, and the gear.
<gazebo reference="base_link">
<sensor name="can" type="vehicle_can">
<update_rate>100</update_rate>
<vehicle_can><teeth>48</teeth><steering_ratio>15.5</steering_ratio></vehicle_can>
</sensor>
</gazebo>
Parameter |
Unit |
Default |
Meaning |
|---|---|---|---|
|
48 (illustrative; 43 to 100 are common) |
teeth of each ABS tone ring |
|
|
15.5 (illustrative) |
steering wheel to road wheel |
|
|
rad |
0.00175 (0.1°, illustrative) |
|
|
rad/s |
0.00175 (0.1°/s, illustrative) |
1σ |
|
m/s² |
0.03 (illustrative) |
1σ |
Signals: wheel_speeds (ScalarArray, m/s, unsigned, one per WheelAPI_1 wheel in schema order),
speed (m/s, their mean), steering_wheel_angle (rad, positive left), yaw_rate (rad/s),
longitudinal_acceleration, lateral_acceleration (m/s², the specific force in the sensor’s
frame: gravity shows when the car pitches or rolls, as it does on a real ESP sensor), gear
(vehicle/<v>/gear; NaN without the vehicle dynamics domain), valid.
Model: wheel speed from each wheel joint’s joint/<j>/position as an ABS controller measures
it, by the time between tooth edges: the edges passed in a step (each edge’s moment interpolated
within the step) × (2π/teeth)·r over the time since the edge before them; with no edge in a step
the estimate falls as one tooth over the time since the last, so a stopped wheel reads a speed
that decays toward zero (no direction, as passive sensors give none). ground_truth uses
|ω|·r. Steering: each steered wheel’s angle (its wheel:steerJoint
position with its sign, else wheel/<j>/steer_angle) turned back through Ackermann’s
tan δ = L·tan δw / (L + y·tan δw) (the inverse of vehicle_dynamics’ ackermannAngle), averaged,
times the ratio, quantised. Yaw rate: the chassis’s angular velocity about the sensor’s z.
Accelerations: the sensor point’s velocity differenced over the step, less gravity, in the
sensor’s frame (the first step reads as at rest). No CAN timing, message counters or checksums.
Check: test_kinds_vehicle_can (10 m/s straight, v·ω = 5 m/s² on a circle, the steering wheel
angle of a 0.1 rad bicycle angle, edge timing exact at a steady 33 rad/s and under one tooth per
second a second after the wheel stops, the gear, refused without VehicleAPI_1).
ROS by default: /can/yaw_rate, /can/speed, … (std_msgs/Float64) and /can/wheel_speeds
(std_msgs/Float64MultiArray), with the sensor named can.