Robot classes¶
Status: draft for review. For each class: required modules, integrations, sample assets, and the
release in which it becomes usable. Package versions are those found on Ubuntu 26.04 with ROS 2
Lyrical on 2026-10-13 (docs/plan/verification.md §4).
1. Summary¶
Class |
Release |
Required domains |
Key integrations |
Status of integrations on Lyrical |
|---|---|---|---|---|
Mobile robot / AMR |
v0.2 |
rigid_body, sensors (lidar, IMU, encoders) |
ros2_control, Nav2, simulation_interfaces, Open-RMF (demo) |
ros2_control 6.10.1, Nav2 1.5.1 available; RMF partly (no |
Robot arm |
v0.3 |
rigid_body, electrical, thermal, sensors (camera) |
ros2_control, MoveIt 2 |
MoveIt 2.15.2 available |
Drone |
v0.4 |
rigid_body, rotor_aero, aerodynamics, electrical, sensors (IMU, GNSS, mag, baro) |
PX4 and ArduPilot SITL over MAVLink; MAVROS |
MAVROS 2.15.1 available; PX4 and ArduPilot ROS 2 guides target Jazzy/Humble (V8) |
Car |
v0.6 |
rigid_body, vehicle_dynamics, aerodynamics |
ros2_control (Ackermann), OpenDRIVE |
available |
Autonomous car |
v0.6 |
car + sensors (lidar, camera, radar, GNSS/IMU), traffic, weather |
Autoware, OpenSCENARIO, SUMO |
Autoware not released into Lyrical (V7); SUMO 1.25.0 in apt |
Huge-world operations (any class) |
v0.7 |
+ streaming, geospatial |
3D Tiles, GeoTIFF, OSM |
GDAL 3.12.2, PROJ 9.7.1 in apt |
Legged, marine, climbing |
post-1.0 |
— |
— |
— |
2. Common integration layer (all classes, from v0.2)¶
2.1 ROS 2 bridge (bridges/ros2/, package lagrange_ros2)¶
An rclcpp component inside the server process.
Interface |
Detail |
|---|---|
|
|
TF |
|
Joint states |
|
Sensors |
|
GPU transport |
With |
Standard simulator API |
|
Signals |
Any bus signal can be exposed as a |
QoS |
Sensor data: best effort, keep last 5. State: reliable. Configurable per topic |
RMW |
Tested with |
Lockstep: with time.real_time_factor: 0 or when a controller must not miss a cycle, the server
can wait for a named set of subscribers to acknowledge each control period. This is implemented
through ros2_control’s own cycle (section 2.2), not through a custom ROS protocol.
2.2 ros2_control (bridges/ros2_control/, package lagrange_ros2_control)¶
Top-priority integration. A hardware_interface::SystemInterface plugin loaded by the user’s
controller_manager, as with gz_ros2_control (3.0.9 on Lyrical) and mujoco_ros2_control
(0.1.2 on Lyrical). Those two packages are the behavioural references.
Item |
Design |
|---|---|
Where the controller manager runs |
Inside the server process, stepped by the scheduler at the controller update rate. This gives exact lockstep: read state → update controllers → write commands, once per control period, with no dependence on wall-clock timing |
State interfaces |
|
Command interfaces |
|
URDF |
|
Encoders |
|
Encoder effects |
When EMI is enabled, |
2.3 Scripting and RL¶
Python bindings (nanobind) for Scheduler, SignalBus and world queries. A gRPC control API is
planned for v0.2 at the level of start/stop/step/get/set, mirroring simulation_interfaces.
Batched environments (batch: N) expose signals as arrays; a Gymnasium-style wrapper is a v0.3+
item and is not required for any acceptance criterion before 1.0.
3. AMR / mobile robot (v0.2)¶
Need |
Provided by |
|---|---|
Differential, Ackermann, mecanum, omni bases |
rigid_body + ros2_control controllers ( |
2D and 3D lidar, IMU, wheel encoders |
sensors (Tier 0 Embree, Tier 1 compute BVH) |
Navigation |
Nav2 1.5.1 against |
Fleet demo |
Open-RMF with a small warehouse; depends on RMF package availability (R8) |
Battery behaviour |
electrical (v0.3; thin slice proposed for v0.2, Q3): state of charge, sag under load, brownout |
Docking, lifts, doors |
scripted kinematic bodies in the world; RMF door/lift adapters later |
Sample assets: assets/robots/amr_diffdrive/ (the file in docs/design/formats.md §4),
assets/robots/amr_mecanum/ (v0.3), assets/worlds/warehouse_small/ (20 m × 30 m, shelves,
a ramp, a narrow aisle), assets/worlds/empty_flat/.
Acceptance scenario for v0.2: the sample AMR navigates between four waypoints in the warehouse
with Nav2, using diff_drive_controller through lagrange_ros2_control, with lidar on Tier 0 and
Tier 1, for 10 simulated minutes without collision, at a real-time factor of at least 1.0 on the
reference desktop.
4. Robot arm (v0.3)¶
Need |
Provided by |
|---|---|
6- and 7-DoF serial arms, grippers |
rigid_body (MuJoCo first; contact-rich grasping checked on Jolt and PhysX) |
Joint torque, position and velocity control at 500 Hz–1 kHz |
ros2_control + |
Motion planning |
MoveIt 2 2.15.2; the planning scene comes from the same USD through the URDF/SRDF the user already has |
Motor currents, bus voltage, regeneration during deceleration |
electrical |
Winding temperature and derating during duty cycles |
thermal |
Wrist camera, depth camera |
sensors |
Force–torque sensor |
|
Sample assets: assets/robots/arm6/ (a generic 6-DoF arm with illustrative motor parameters;
no vendor model is redistributed without checking its license), assets/worlds/workcell_arm6/.
Acceptance scenario for v0.3: MoveIt 2 plans and executes a pick-and-place cycle; the scope shows phase currents and bus voltage; repeating the cycle at full speed raises the winding temperature until derating limits torque and the trajectory controller reports a tolerance violation. Disabling electrical (ideal torque source) makes the same cycle run without that effect.
Status (v0.3). The sample arm is assets/robots/arm6 (a generic 6-DoF arm with a parallel
gripper; its motors, 48 V supply, brake resistor and thermal nodes in arm6.overlay.yaml) in
assets/worlds/workcell_arm6, driven by joint_trajectory_controller at 1 kHz through the
drives’ position servos (demos/config/arm6_controllers.yaml). MoveIt 2 plans with MoveItCpp
(moveit_py, demos/config/arm6_moveit/, ros2 run lagrange_demos pick_place) through named
poses above and at two stations; the gripper opens and closes, but there is no object to grasp
yet. The scenario: tools/ci/arm_scenario.sh. With arm6_undersized.overlay.yaml (shoulder and
elbow motors one size too small) the shoulder-lift winding heats from 25 °C to 150 °C over 79
full-speed cycles (about 530 simulated seconds), derates to 0.14 and the trajectory controller
aborts the next move on its path tolerance; with electrical off all 80 cycles complete. The
sample’s own motors are sized for the cycle (2.9 K in 15 cycles). Signals for the scopes:
motor/<m>/current_q, bus/dc_48v/voltage, thermal/<m>/temperature. Not yet: a wrist
camera (the raster camera is the next v0.3 step), a grasped object, the arm in USD
(lagrange_import it). At 8x real time MoveIt’s state monitor, fed in wall-clock time, can
lag the simulation; pick_place retries a move once when its start state looks stale.
5. Drone (v0.4)¶
Need |
Provided by |
|---|---|
Multirotor airframes |
rigid_body + rotor_aero + aerodynamics |
Motor and ESC dynamics, battery sag affecting thrust |
electrical at 50 µs |
IMU, barometer, magnetometer, GNSS |
sensors |
Autopilot in the loop |
|
ROS 2 access |
The simulator’s own topics ( |
Wind and gusts |
weather + aerodynamics |
Sample assets: assets/robots/quad_x500/ (a generic 500 mm quadcopter with illustrative
parameters), assets/worlds/open_field/.
Status (v0.4, step 3): quad_x500 exists (URDF, overlay, USD): an X frame of 1.9 kg with four
APC 10x4.7 SF propellers (CT and CP from the UIUC propeller database’s static test), 920 KV-class
motors and a 4S 5 Ah battery. Without an autopilot the server flies it with its built-in
controller (Multicopter.hpp): it takes off and holds 2 m within 1 mm, rotors at 551 rad/s,
about 190 W from the battery (test_the_sample_quadcopter_takes_off_and_hovers). The world
assets/worlds/open_field/ (URDF and USD) is a 50 m field with a painted landing pad at the
origin, a windsock, four trees and a shed, all more than 15 m from the pad; the PX4 and
ArduPilot missions fly their 10 m square over it.
Status (v0.4, step 9): each rotor names its propeller as built, a generic 10-inch two-blade
blade of each hand (assets/propellers/generic_10in_2blade_{ccw,cw}.prop.yaml, NACA 6412
sections at low Reynolds number from NACA Report 586) whose static CT and CP by blade-element
momentum are the APC’s measured ones. The viewer draws the blades (twisted, in their hand,
spinning with their joints); profiles/examples/quad_x500_bem.yaml flies the quadcopter on them
(rotor_aero.fidelity: bem): it hovers at 2 m as on the coefficients, rotors at 548 rad/s,
192 W. Propeller hand and mount (puller or pusher) are physical: a propeller of the wrong hand
turns backwards and gives little thrust (aerodynamics.md §2.1). Variants: folding blades
(quad_x500_folding.overlay.yaml on the same URDF: they hang folded when stopped and open as the
motors spin up), and assets/robots/quad_x500_inverted/, the motors upside down under the arms
with the propellers as pushers; a three-blade propeller is in assets/propellers/ too.
Status (v0.4, step 7): lagrange_mavlink (bridges/mavlink) runs PX4 SITL in lockstep
(lagrange_server --mavlink px4): HIL_SENSOR at the IMU’s rate (FRD, gauss, hPa), HIL_GPS at the
GNSS rate, HIL_ACTUATOR_CONTROLS back to speed-controlling ESCs; lockstep starts with PX4’s first
outputs. PX4 v1.17.0 with the airframe bridges/mavlink/px4/22100_lagrange_quad_x500 takes off,
flies a 10 m square at 5 m and lands (tools/ci/px4_mission.sh, fly_square_mission.py).
ArduPilot runs through its JSON interface (lagrange_server --mavlink ardupilot): ArduCopter
sends servo frames to UDP 9002 and each one is answered, in lockstep at 1 kHz, with the body’s
exact rates, specific force, NED position, velocity and attitude (ArduPilot adds its own sensor
noise and makes GPS, compass and barometer itself). ArduCopter Copter-4.7.2 with
bridges/mavlink/ardupilot/lagrange_quad_x500.parm flies the same square
(tools/ci/ardupilot_mission.sh, calm and --wind). Full output is each rotor’s loaded top
speed from its motor and battery (mavlink::rotorTopSpeed, test_rotor_top_speed; 921 rad/s for
the sample at its motors’ 25 A, where it was a fixed 850 until v1.1), or --mavlink-max-rotor-speed.
Acceptance (v0.4): the PX4 mission passes in 8 m/s of gusty wind (tools/ci/px4_mission.sh --wind, the profile quad_x500_gusty.yaml). Low battery: at full throttle a full pack holds
16.2 V and gives 37.5 N; at 10 % charge the pack sags to 13.9 V, the voltage limits the motors,
and the rotors give 29.0 N, so the climb in 2.5 s halves (23.9 m against 12.6 m;
Multicopter.ALowBatterySagsAndGivesLessThrust). At 3 % the bus browns out at full load, the
drives trip and it does not take off.
Acceptance scenario for v0.4: PX4 SITL in lockstep takes off, flies a square mission in 8 m/s gusty wind and lands; a low battery scenario shows voltage sag reducing available thrust.
6. Car and autonomous car (v0.6)¶
Need |
Provided by |
|---|---|
Vehicle model |
rigid_body (PhysX or MuJoCo chassis and wheels) + vehicle_dynamics |
Roads |
|
Scenarios |
|
Traffic |
traffic (SUMO co-simulation) |
Sensor suite |
sensors: multi-lidar, cameras, radar, GNSS/IMU on Tier 2; weather effects |
Autonomy stack |
|
Zero-copy sensor delivery |
|
Sample assets: assets/robots/sedan/, assets/worlds/city_block/ (four-way junction with
lights, from an OpenDRIVE file authored for the project), assets/worlds/skidpad/.
Acceptance scenario for v0.6: an OpenSCENARIO cut-in runs in fog with SUMO traffic; the ego vehicle is driven by a ros2_control Ackermann controller following a recorded path (the Autoware demonstration is a stretch goal that depends on R7).
7. Huge-world operations (v0.7)¶
See docs/design/huge-worlds.md. Sample: a 40 km coastal tile set built by the geospatial
pipeline from open elevation and map data, with the drone survey profile in
docs/design/formats.md §5.3. Source data licenses (elevation models, OpenStreetMap’s ODbL) are
checked and attributed when the sample is built; ODbL data is not committed to the Apache-2.0
repository, it is fetched by the build script.
8. Sample asset policy¶
In this repo: only files under 1 MB each (CLAUDE.md §9), authored for the project under Apache-2.0 or CC0, with primitive or low-polygon geometry.
In
lagrange-assets(separate repo or release bundles): detailed meshes and textures, each with aLICENSEand a source note. Fetched bytools/fetch_assetswith SHA-256 verification.No third-party robot model is redistributed until its license is recorded in
docs/design/dependencies.md.Every sample robot states in its file that its parameters are illustrative unless a datasheet source is cited next to the value.