Writing a plugin¶
A plugin extends Lagrange without changing it: a new sensor, a new domain (gas, radiation, a
crowd), a substitute for a built-in domain, or a whole physics engine. It is a shared library
built against one C header, lagrange_plugin.h, and loaded when the simulator starts:
lagrange --robot my_robot.urdf --plugin my_plugin
This chapter builds one from the template, then walks through the time-of-flight sensor that comes with Lagrange, then a physics engine. The design is RFC 0008; the interface is RFC 0001. Read Concepts first for signals, units and the scheduler.
1. Start from the template¶
cp -r tools/templates/lagrange_plugin_template ~/ws/src/my_lagrange_plugin
cd ~/ws && source ~/lagrange/install/setup.bash # or /opt/ros/lyrical/setup.bash with the debs
colcon build && colcon test --packages-select my_lagrange_plugin
source install/setup.bash
lagrange --plugin my_lagrange_plugin
The package (ament_cmake) builds one MODULE library from src/my_sensor.c, installs it to
lib/, and registers it in the lagrange_plugins resource index, which is how --plugin my_lagrange_plugin finds it by name (a path, or a directory in $LAGRANGE_PLUGIN_PATH, also
work). Its test runs the plugin in a headless simulator with the sample AMR. The library links
nothing of Lagrange’s: the header is the whole interface.
2. The interface¶
A library exports one function, lagrange_plugin_get_module(major, minor, index), which returns
its modules one index at a time (NULL after the last, or for an ABI major it was not built
for). A module is a table of functions (lagrange_module_api):
Function |
When |
Does |
|---|---|---|
|
each run |
allocates the module; keeps |
|
before wiring |
reads the world and its settings; declares every input and output with its unit |
|
after wiring |
writes the first value of every output |
|
every step |
reads inputs, computes, writes outputs. No allocation, no blocking, no I/O |
|
checkpoints, rebuilds |
the whole dynamic state, for deterministic runs |
|
the floating origin moved |
positions the module keeps move by −shift |
|
Its fields say what it is: domain and name, whether it is a substitute, whether it is
deterministic, the lowest capability tier it runs on, and its step (preferred_step_ns).
What a module does in the run depends on its domain:
its own domain (
acme_gas): it runs whenever it is loaded;--domain acme_gas=offturns it off. Its settings come from the profile:plugins: [{library: my_plugin, config: {gain: 2}}], read withconfig_get_real("gain", &out)andconfig_get_string;a built-in domain, as a substitute:
domains: {electrical: {enabled: false, substitute: acme_bench}};rigid_body, as a backend:--physics NAME(section 5).
Signals and units¶
A signal is a name (sensor/front_tof/range, <class>/<instance>/<quantity>), a type (scalar,
pose, wrench, array, …) and a unit: SI dimensions, a scale (1 for SI) and a quantity kind that
tells torque from energy. Units are checked when the run is wired: a mismatch stops the start,
naming both modules and both units; nothing is ever converted. Inputs say how they see a writer
at another rate (hold: last value, extrapolated, or averaged over the window), whether they
may stay unconnected (optional, then default_value), and whether they read the writer’s
previous step (feedback, which breaks a loop).
The signals other modules write are listed by lagrange graph and in the viewer’s Signals
workspace: body/<b>/pose, joint/<j>/position, env/air_density, sensor/<s>/ranges, and so
on. Declaring a body’s pose as an input also orders the module after physics.
Seeing the scene (ABI 1.1)¶
In declare and init a module reads the world: world_body_count and world_body (name,
parent, mass, inertia, poses), world_joint, world_collider (shapes, hulls, height fields),
world_sensor and its parameters, world_site (gravity, the region origin). Each getter fills
a struct whose first field, struct_size, the plugin sets, so newer fields can be added later
without breaking it. In step it can cast rays and query overlaps against every collider where
physics put it: scene_ray, scene_rays, scene_overlap_sphere. They are exact and
deterministic (the CPU lidar’s caster) and safe from several threads during one step. A 1.1
plugin checks the host’s struct_size before calling them, so it can refuse politely on a 1.0
host. C++ plugins can read the whole world into containers with the header-only
lagrange/plugin_sdk/World.hpp.
Rules¶
stepmust not allocate, block, read files or talk to the network: it runs on the simulation’s clock, possibly faster than real time.Determinism: noise comes from
context->seedandcontext->step_index(a counter-based generator), never from the clock orrand(). A module that is deterministic sets the flag and saves its whole state; one that is not (it takes input from outside) clears it.A plugin is native code in the simulator’s process: load only plugins you would run as programs. Only the person starting the simulator loads them (
--plugin, or a profile read at start); a viewer never can.
3. A sensor: time of flight¶
core/plugin_abi/samples/tof_sensor.c (installed as lagrange_tof) implements every custom
sensor of kind tof. A robot file declares one like any Gazebo sensor; a <sensor> of a type
Lagrange does not simulate itself becomes a custom sensor with its parameters by path:
<gazebo reference="base_link">
<sensor name="front_tof" type="tof">
<pose>0.25 0 0.1 0 0.3 0</pose>
<update_rate>50</update_rate>
<tof><range><min>0.02</min><max>4</max></range><fov>0.44</fov>
<noise><stddev>0.005</stddev></noise></tof>
</sensor>
</gazebo>
In declare it walks the sensors, keeps those whose kind is tof, reads range/max, fov and
noise/stddev with world_sensor_param_real, finds its body with world_body, and declares the
body’s pose as an input and sensor/front_tof/range (m) and valid as outputs. In step, on
the steps its rate asks for, it composes the body’s pose with the mount, casts a ray (or a 5 × 5
grid over its field of view) along the sensor’s +x with scene_ray, skips hits on its own body,
keeps the nearest, and adds Gaussian noise from the step’s seed. Its test checks the range to the
ground against the exact beam–plane distance (server/test/test_plugins.cpp).
To see it on ROS 2, map the signal to a topic (--ros-topics, The lagrange
command):
publish:
- {signal: sensor/front_tof/range, topic: /front_tof/range, type: sensor_msgs/msg/Range,
frame: front_tof, params: {min_range: 0.02, max_range: 4.0, field_of_view: 0.44}}
4. Commands from ROS 2¶
A topic can become a signal the plugin reads, again without the plugin linking ROS:
subscribe:
- {topic: /acme/valve, type: std_msgs/msg/Float64, signal: acme/valve/command, unit: "1"}
5. A physics engine¶
A module of domain rigid_body replaces MuJoCo: lagrange --plugin my_engine --physics NAME.
Its contract, what it outputs and accepts per joint and body, is
rigid_body.md §8.
It reads the whole world in declare (bodies, joints, colliders) and steps it.
modules/rigid_body/jolt_backend/src/jolt_plugin.cpp is the worked example: the Jolt engine as
a plugin (--plugin lagrange_jolt --physics jolt_abi). It reads the world with the SDK, rebuilds
the world tables, and runs the same engine code as the built-in Jolt backend, whose signal
access goes through a small interface (JoltBackend::SignalIo) implemented over the ABI’s
declare and bus functions.
The conformance suite checks an engine against the contract: a falling box, a pendulum’s period, friction on a slope, a stack of boxes, the sample AMR’s loop against MuJoCo, determinism and state restore:
LAGRANGE_CONFORMANCE=my_engine@libmy_engine.so \
ros2 run lagrange_server lagrange_physics_conformance
6. When it does not load¶
The simulator logs every module it loaded and what it is for ([plugins] acme_gas/gas from .../libacme_gas.so (its own domain; ...)), and stops the start with a reason when it cannot:
Message |
Means |
|---|---|
|
not built, not installed, or the workspace not sourced |
|
built for another major version, or |
|
the plugin’s unit (or quantity kind) is not the other module’s |
|
nothing writes an input that is not optional |
|
the module refused, with its |
|
a profile from the viewer named a library the simulator was not started with |