feat: add VirtualGantryPlugin — rope-constraint gantry for humanoid simulation

[eraimondi-jpg]

Summary

Adds a VirtualGantryPlugin that suspends a humanoid robot from a
fixed anchor point using a one-sided cable constraint. Intended as a
safety net during locomotion policy bring-up: the rope catches falls
without constraining normal motion, so the robot can walk and balance
freely.

Physics model

A one-sided spring-damper acting along the radial direction only. When
the straight-line distance from the anchor to the configured attachment
point exceeds rope_length, a tension force is applied toward the
anchor. Because the force is purely radial the robot swings freely like
a pendulum at all times. The damper is applied only when the rope is
extending, preventing the asymmetric energy cycle that bidirectional
damping creates with a one-sided constraint.

On (re-)enable the anchor is placed at [attach_xy, anchor_z] and
rope_length is set to |anchor_z − attach_z| so the rope is just
taut at the moment of activation. On simulation reset the gantry
auto-reactivates and re-anchors above the current attachment position.

Controls

Key	Action
G	Toggle gantry on / off
[	Shorten rope by 0.5 cm
]	Lengthen rope by 0.5 cm

ROS 2 service set_gantry_enabled (mujoco_ros2_control_msgs/srv/SetGantryEnabled) also enables/disables from the command line.

Implementation notes

• GantryKeyboardState singleton: lock-free (std::atomic) struct defined in libmujoco_ros2_control.so and shared between the GLFW UI thread (ROS2ControlGlfwAdapter::OnKey) and the physics thread (VirtualGantryPlugin::update). The singleton is declared in a new header and its definition lives in gantry_keyboard_state.cpp in the main library so there is exactly one instance across DSO boundaries.

• RTLD_GLOBAL fix: pluginlib loads hardware-interface plugins with RTLD_LOCAL, which hides GantryKeyboardState::get from the plugin DSO and causes an undefined-symbol crash. MujocoSystemInterface::load_mujoco_plugins now calls dlopen(RTLD_NOLOAD | RTLD_GLOBAL) on its own DSO path before the ClassLoader is created, promoting visibility in-place without an extra reference count.

• Finite-difference derivative with EMA: rope_dist_dot is computed as d(rope_dist)/dt rather than from cvel to avoid phase errors when physics runs faster than the control loop. An exponential moving average (τ ≈ 10 ms) filters contact/joint noise from the raw 2 ms finite difference. The derivative state is reset to zero whenever the rope goes slack, preventing stale velocity from spiking the damper at the next taut transition.

[lgulich]

Thanks, lgtm overall. See some small comments directly in the code.

Additionally I have a bigger comment on the architecture:

Currently this PR introduces a GantryKeyboardState singleton in the main lib, __attribute__((visibility("default"))), a self re-dlopen with RTLD_GLOBAL|RTLD_NOLOAD, CMAKE_DL_LIBS linkage, and hardcoded G/[/] handling in mujoco_system_interface.cpp — all to let one plugin observe three keys. Any future plugin that wants viewer input will copy this pattern or collide with its bindings.

I would propose we instead add one virtual to MuJoCoROS2ControlPluginBase and fan out GLFW events through it.

// mujoco_ros2_control_plugins_base.hpp
virtual void on_key(int key, int scancode, int action, int mods) {}

// mujoco_system_interface.cpp — replaces the GantryKeyboardState block
for (auto& plugin : plugin_instances_) plugin->on_key(key, scancode, action, mods);

VirtualGantryPlugin then holds its own std::atomic<int> members and overrides on_key. No singleton, no RTLD_GLOBAL, no CMAKE_DL_LIBS, no cross-DSO visibility concerns.

Agent prompt to apply this refactor

Refactor PR #3 of NVIDIA-ISAAC-ROS/mujoco_ros2_control to dispatch GLFW key
events to plugins through a virtual on the base class instead of a shared
singleton. Keep VirtualGantryPlugin in this repo — only touch the keyboard
plumbing.

1. Add to mujoco_ros2_control_plugins_base.hpp:
     virtual void on_key(int key, int scancode, int action, int mods) {}
   Doc it as UI-thread invoked; plugins must hand off to update() via atomics.

2. In mujoco_system_interface.cpp, replace the GantryKeyboardState::get()...
   block in the GLFW key callback with a fan-out loop over plugin_instances_
   calling on_key. Remove the RTLD_GLOBAL/RTLD_NOLOAD re-dlopen block and any
   now-unused `#include <dlfcn.h>`.

3. Delete gantry_keyboard_state.hpp and gantry_keyboard_state.cpp. Drop the
   source entry and CMAKE_DL_LIBS linkage from mujoco_ros2_control/CMakeLists.txt.

4. In VirtualGantryPlugin:
   - Add private std::atomic<int> toggle_counter_{0}, rope_length_ticks_{0}.
   - Override on_key: on GLFW_PRESS/GLFW_REPEAT, fetch_add on G /
     LEFT_BRACKET (-1) / RIGHT_BRACKET (+1) with memory_order_release.
   - In update(), load/exchange with memory_order_acquire.
   - Count every toggle: delta = tc - last; if (delta & 1) flip enabled_.
   - Fix the "Shift+scroll" docstring on rope_length_ and the
     "5 cm per press" comments (actual multiplier is 0.005 = 0.5 cm).
   - Hold state_mutex_ in cleanup() before resetting enable_srv_ / node_
     to avoid UAF with in-flight service callbacks.

5. Verify: `grep -r GantryKeyboardState .` returns no matches. Build with
   colcon, launch sim, confirm G / [ / ] still work and the
   SetGantryEnabled service still toggles.

Commit message: "refactor(plugins): dispatch GLFW key events via plugin
virtual instead of shared singleton".

[lgulich]

Three small inline items alongside the architecture note above.

[eraimondi-jpg]

Done in 84766f5. Replaced the GantryKeyboardState singleton + RTLD_GLOBAL + dlopen/dladdr/CMAKE_DL_LIBS block with a virtual bool on_key(int key, int scancode, int action, int mods) on MuJoCoROS2ControlPluginBase. The GLFW adapter fans out every key event to all loaded plugins; if any plugin returns true (consumed), the event is not forwarded to mj::GlfwAdapter::OnKey so native viewer bindings don't fire. VirtualGantryPlugin overrides on_key() and owns its own std::atomic<int> members (toggle_counter_ and rope_length_ticks_), written with memory_order_release and consumed in update() with memory_order_acquire. grep -r GantryKeyboardState . returns no matches in the source tree.