OpenMHS family: ros2

ROS 2 topics, services and actions through RosDriver

Generated by MHS/registry/build_registry.py on 2026-10-20T00:00:00Z from 262 registry records and their task cards. A plan, not a conformance claim.

• bridge_status: available
• helper: RosDriver
• exemplar: MHS/drivers/robots/avidbots__flatland

Launch

Every driver package starts the same way; per-repo configuration (environment id, model path, port, baud rate, VISA resource) lives in the package's driver.py, never in launch flags:

mhs serve <driver-dir>

A package is done when python3 -m mhs.driver check <driver-dir> --backend fake exits 0 (evidence contract_checked; a fake never yields an MHS-Device level).

Registry coverage

• Repos: 262
• Decisions: bridge-runtime 68, family-config 51, reference 18, skip 125
• Waves: 3: 29, 5: 22, 9: 211
• Dispatchable now: 0
• Modes: hardware 86, simulated 56

Applicability

ROS 2 packages (package.xml) in a repo whose main family is ROS: triage rule 9, family:ros; set ros_version = 2. The implemented RosDriver is a configuration-only helper over rosbridge JSON topics, services and explicit action profiles. Set ros_version to the node's version; a C++ node does not need an invented Python native class. The operator runs upstream nodes and rosbridge separately. The optional WebSocket transport has no default endpoint; fake and offline sim backends provide their own transport and cannot fall back to a live WebSocket. A simulated class can use an explicit operator simulation_deployment through backend="sim"; its endpoint, complete fidelity and separate deployment identity are validated before connecting (see ROS driver deployment).

Every binding carries source_ref: path/in/clone:LINE (or a bounded range) showing its endpoint and type at the pinned commit. Add type_ref when the type is declared elsewhere. For relative/private names, record the exact upstream token as source_name and configure the resolved absolute endpoint. The gate checks the same endpoint or a namespace-qualified suffix; it does not validate an operator's remapping or ROS graph. Use catalogue classes only when their semantics match; otherwise request an x-cap extension with an inline schema in RESULT.json. Numeric actuation limits need source evidence or Limit.operator_required.

See the ROS driver guide for binding syntax and the Flatland exemplar for a ROS 1 clock observation and acknowledged pause/resume services. Flatland is a structural example, not evidence of live ROS 1 or ROS 2 compatibility. Its /clock is observation-only because the upstream publisher becomes silent while paused; automatic resource snapshots must not require a sample that a command can stop producing.

Capability mapping

Class ids come from python3 -m mhs.driver catalog search <words>. The deprecated classes cap.device.describe.v1, cap.world.state.v1, cap.world.snapshot.v1 and cap.world.restore.v1 are replaced by the protocol methods mhs.devices.get, mhs.resource.read, mhs.snapshot and mhs.restore.

Safety

The risk floor of a device is the highest catalogue risk_class of its classes (CAP-017); a driver may declare a higher risk, never a lower one. Hardware at R1 or above needs a declared native stop and a non-empty safe state. Every ROS hardware backend, including R0 and human-authored packages, requires a schema-valid lock with a human reviewed_by entry of scope hardware before a backend factory or connection can run. Models keep reviewed_by null. The usual allow_hardware=True and persistent state_dir requirements still apply. A signed lock is a local review record, not cryptographic attestation or safety certification.

Use a source-backed upstream stop service or fixed stop action and describe the resulting safe_state. Trace its callback, native synchronization and terminal ownership; the endpoint name or a client timeout does not prove prompt stopping. Service transport success and application success are distinct: an Empty response can use success={"path": "$", "equals": {}}; other services require their actual success field/code. An input-free Action(safe_state=True) service or fixed action has a separate bounded admission path during the latch; a raw command-map flag cannot grant that permission. An unresolved or erroneous action stop retains ownership and prevents another stop goal from preempting it. The helper fences queued actuating sends and interrupts pending ordinary requests when stopped. A timeout/disconnect after transmission has an unknown outcome; ordinary commands are not replayed. A historical safety fault permits a fresh bounded protective attempt only after prior stop owners and passive teardown ended safely; it still prevents achievement, reset and motion. See the ROS driver guide for the complete lifecycle and freshness rules. ROS is a transport, not a safety layer; the independent physical stop remains authoritative.

Fidelity

Declare the deployed model's fidelity, not a simulator's generic capabilities or default timing. A RecordingRosTransport fake runs no physics and establishes only contract_checked evidence; mark invented observations as placeholders and describe absent dynamics and pacing in gaps. Model the actual upstream response shapes and negative cases, including service/application failures and stopping when exposed. Passing fake gates never establish an MHS-Device level, live ROS compatibility or hardware behavior.

Pitfalls

ROS 2 launch files can start hardware drivers; DDS domains are not an isolation boundary. QoS configuration, authentication, graph discovery, hosting action servers, automatic reconnect/replay and fragment reassembly are outside this helper. Topic reads subscribe for a new arrival; explicit event IDs must match the active subscription, but an ID-less event cannot establish its original subscription or producer sample age. The message-size limit applies after receipt of a complete WebSocket frame, not before allocation. Action execution requires both native terminal success and an application predicate; uncertain goals block new mutations until terminal reconciliation and an acknowledged safety reset. ROS 2 native action deployments must test nonblocking goal handling and independent stop responsiveness. Large images and point clouds need an artifact path rather than inline payload claims.

First task cards

• gh.universalrobots/universal_robots_ros2_driver: family-config, wave 3, rank 1, MHS/registry/tasks/robots/universalrobots__universal_robots_ros2_driver.json
• gh.misterblue/ros2_raspicam_node: family-config, wave 3, rank 3, MHS/registry/tasks/robots/misterblue__ros2_raspicam_node.json
• gh.realsenseai/realsense-ros: family-config, wave 3, rank 8, MHS/registry/tasks/robots/realsenseai__realsense-ros.json
• gh.frankarobotics/franka_ros2: family-config, wave 3, rank 10, MHS/registry/tasks/robots/frankarobotics__franka_ros2.json
• gh.christianrauch/raspicam2_node: family-config, wave 3, rank 12, MHS/registry/tasks/robots/christianrauch__raspicam2_node.json

Sources

• Task cards: MHS/registry/tasks/<track>/<owner>__<repo>.json (schema/taskcard.schema.json).
• Triage rules and the helper table: MHS/registry/triage.py; curated decisions: MHS/registry/overrides/.
• Driver API and gate: MHS/sdk/docs/driver-authoring.md; exemplars: MHS/drivers/.
• ROS binding, transport and review contract.
• Driver authoring, model/human review, and safety specification.
• Flatland fake, tests, source facts, and result/evidence scope.