The run file¶
Your robot is all you need:
lagrange my_robot.urdf # URDF, or USD, SDFormat, MJCF
lagrange my_robot.usda world.usda # and a world
It starts on an empty ground (or in the world you named), still until you command it. Lagrange is the low level: your code drives each joint, by position, velocity or effort:
ros2 topic pub /joint_commands sensor_msgs/msg/JointState \
"{name: [left_wheel, elbow], velocity: [3.0, .nan], position: [.nan, 0.5]}"
For each name it takes the position if given (not NaN), else the velocity, else the effort. Position
and velocity loops are built in (8 Hz, critically damped on the joint’s inertia, so no tuning, and a
position loop holding against gravity sags slightly); effort goes straight to the joint, limited by
its effort limit. A joint not yet commanded gets no torque. Road vehicles and multicopters keep
their own controllers: /cmd_vel or /ackermann_cmd.
From Python (lagrange.Simulation(robot, joint_control=True)), sim.command_joint(joint, mode, value) returns a JointCommand: true when the joint took it, and when not, reason says why (no
such joint, a mimic joint, a mode its motor does not follow, joint control off);
strict=True raises ValueError with the reason instead. A velocity beyond the joint’s velocity
limit, an effort beyond its effort limit or a position outside its range (from the robot file) is
clamped to it: clamped, value and limit say so
(JointCommand(taken, value=10, clamped to its velocity limit, 10 rad/s)). The viewer’s joint
commands are clamped the same way; /joint_commands is not (an effort is still limited by the
effort limit, as above).
To keep a run’s settings, put them in one file and run that:
lagrange run.yaml
# Only `robot` or `world` is required. Paths are relative to this file.
robot: my_robot.urdf
world: warehouse.usda # none: an empty ground
spawn: [2.0, 0.0, 0.0, 1.57] # x, y, z, yaw
simulate: # what you leave out runs if the robot has what it needs
electrical: false # the ideal torque source: pure physics and navigation testing
sensors: true
site: # also changed while running: lagrange set gravity=1.62 wind_speed=5
gravity: 9.80665 # m/s², downward
wind_speed: 3.0 # m/s; acts on links with AeroAPI_1 and on rotors
wind_from: 270 # degrees, compass: where it blows from
temperature: 293.15 # K
air_density: 1.225 # kg/m³: rotors fly
pressure: 101325 # Pa, with temperature and relative_humidity: the weather runs
relative_humidity: 0.5
geo_origin: [47.3977, 8.5456, 488] # latitude, longitude, height: GNSS and the compass run
physics: mujoco # or jolt
control: joints # each joint on /joint_commands; builtin: the robot's own controller
time: { real_time_factor: 1.0, paused: false }
ros: true
ros_topics: topics.yaml # plugin signals on ROS: writing-a-plugin.md
plugins: [lagrange_tof]
humans: 6,radius=7 # people: tutorial-humans.md
sensor_timing: # how late a sensor's data reaches the robot, in s
imu: {latency: 0.002, jitter: 0.0005}
sensor_faults: # what goes wrong with a sensor, and when: cli.md "Sensor faults"
- {sensor: imu, quantity: angular_rate, mode: bias, value: 0.02, at: 5}
- front_lidar=dropout,at=10,for=2,probability=0.3
water: # still water: it floats what enters it, and lidars see it as water
- {at: [0, 0, 0.5], size: [12, 8], depth: 0.5} # x, y, surface height
record: run.mcap
Keys under simulate are physics, sensors, electrical, thermal, weather, emi, comms,
vehicle_dynamics, traffic and humans. false puts in the domain’s substitute. A mistake in the
file stops the start and says which key.
Electrical needs a power system on the robot: an overlay (overlay: power.yaml,
formats.md §9) or USD electrical schemas.
Changing the site while it runs¶
From a terminal lagrange set gravity=1.62 wind_speed=5, or from any ROS tool ros2 param set /lagrange_ros2_bridge gravity 1.62, or in the viewer’s Environment workspace. The run goes on from
where it is. A value that brings a domain in (the first air density starts the rotors) rebuilds the
run keeping time, poses and joint positions, with velocities from rest. wind_speed alone is enough:
unless given, a wind comes from the north (wind_from, degrees), measured 10 m up over open
grassland (the aerodynamics profile’s wind_reference_height, roughness_length). A checkpoint
(Server::saveState) holds these values, and restoring it puts them back.
A profile is the detailed form, for step sizes and fidelity per domain, run with
lagrange run profile.yaml.