openral_hal

Hardware Abstraction Layer for OpenRAL — Layer 0 in the eight-layer architecture (CLAUDE.md §2, §6.1). This package owns the HAL Protocol that every robot adapter must satisfy and ships concrete adapters for the robots OpenRAL targets today.

Synopsis

from openral_hal import HAL, SO100FollowerHAL, SO100DigitalTwin
from openral_core import Action, ControlMode

hal: HAL = SO100FollowerHAL(port="/dev/ttyUSB0")        # real SO-100 follower arm
# or, for offline / CI:
hal = SO100DigitalTwin()                          # in-process simulator

hal.connect()
state = hal.read_state()                          # → openral_core.JointState
hal.send_action(
    Action(control_mode=ControlMode.JOINT_POSITION, joint_positions=[0.0]*6)
)
hal.disconnect()

The HAL Protocol is structural: any class with connect / disconnect / read_state / send_action / estop and an embodiment_tag: str field satisfies it. There is no inheritance requirement.

What's in here

Supported robots

The Pydantic descriptions above (e.g. SO100_DESCRIPTION, FRANKA_PANDA_DESCRIPTION) are paired with the canonical YAML manifests under robots/<robot_id>/robot.yaml — the YAML is the source of truth for sensors and capabilities, while the Python description pins the kinematic / safety values that don't change at runtime.

Adding a new MuJoCo-backed robot

For any robot — single-arm, floating-base humanoid, or bimanual — whose MJCF lives in robot_descriptions, gym_aloha, or on disk, no Python file is required:

1. Add robots/<id>/robot.yaml with the usual joints, capabilities, safety blocks plus a sim: block:

   sim:
     # mjcf_uri schemes: robot_descriptions:<module> | gym_aloha:<scene>
     #                    | openarm_v2:bimanual | file:<abs-path>
     mjcf_uri: "robot_descriptions:<module>"
     floating_base: false                       # true for humanoids (G1, H1)
     # Optional joint-index overrides — only needed when the MJCF's qpos
     # order doesn't match description.joints (e.g. OpenArm skips qpos 8
     # and qpos 17 for passive follower fingers).
     # joint_qpos_addr: { joint_a: 0, joint_b: 1 }
     # actuator_index:  { joint_a: 0, joint_b: 1 }
     grippers:                                  # zero, one, or two entries
       - joint: "<gripper_joint_name>"
         ctrl_range: [low, high]
         qpos_addrs: [<qpos_index>, ...]
         qpos_scale: <float>
         read_mode: "sum_over_scale"            # | "affine_low_high" | "passthrough"
         write_mode: "normalised"               # | "passthrough"
         # actuator_index: 6                    # override; defaults to actuator_index map
         # mirror_actuator_index: 7             # Aloha: writes -ctrl to the negative finger
     # keyframe_index: 0                        # mj_resetDataKeyframe at connect (Aloha)
     # seed_ctrl_from_qpos: true                # ctrl = qpos at connect (OpenArm v2)
   

2. Load the manifest and instantiate the HAL — no per-robot class:

   from openral_core import RobotDescription
   from openral_hal import MujocoArmHAL
   desc = RobotDescription.from_yaml("robots/<id>/robot.yaml")
   hal = MujocoArmHAL.from_description(desc, gravity_enabled=False)
   hal.connect()
   

The default 1:1 joint→qpos/actuator mapping (offset by 7/6 if floating_base: true) is correct for every robot in tree without passive-follower qpos quirks; sim.joint_qpos_addr / sim.actuator_index are only needed when the MJCF declares joints in a different order than description.joints (Aloha) or interleaves passive follower-finger slots (OpenArm).

Worked patterns in tree

Pairing with ROS 2 lifecycle nodes

Each HAL adapter has (or will have) a thin ROS 2 lifecycle node under packages/openral_hal_<robot>/:

See each ROS package's README.md for the lifecycle contract, parameters, and topic names.

Tests

• Unit: tests/unit/test_hal.py (RosControlHAL × SimTransport), tests/unit/test_so100_follower_hal.py, tests/unit/test_franka_panda.py, tests/unit/test_franka_panda_real.py, tests/unit/test_sawyer_real.py, tests/unit/test_aloha.py, tests/unit/test_mujoco_arm.py, tests/unit/test_sim_transport.py.
• Protocol conformance: tests/unit/test_hal_protocol_conformance.py parametrizes the HAL invariants across 10 implementations (7 invariants × 10 HALs = 70 cases) — RosControlHAL, SO100FollowerHAL+SO100DigitalTwin, UR5eHAL, UR10eHAL, FrankaPandaHAL, FrankaPandaRealHAL, SawyerRealHAL, AlohaHAL, UR5eRealHAL+SimTransport, UR10eRealHAL+SimTransport.
• Sim (per-HAL contract): tests/sim/test_ur5e_hal_mujoco.py, tests/sim/test_ur10e_hal_mujoco.py, tests/sim/test_franka_panda_hal_mujoco.py, tests/sim/test_so100_follower_hal_mujoco.py, tests/sim/test_aloha_bimanual_hal_mujoco.py, tests/sim/test_g1_hal_mujoco.py, tests/sim/test_h1_hal_mujoco.py, tests/sim/test_smolvla_so100.py.
• Sim (cross-HAL integration): tests/sim/test_all_hals_via_runner.py drives every HAL twin through the production DeployRunner with a real WorldStateAggregator + a trivial echo-current-pose skill. Catches any joint-indexing / units / lifecycle / aggregator / safety wiring breakage at the integration boundary — every per-robot sim test could pass while this one still fails.
• One-line full sweep: just hal-twin-sweep runs both the per-HAL contract suite and the cross-HAL DeployRunner integration suite (~200 tests covering 7 robot families) with the ROS 2 plugin workaround baked in.
• HIL: tests/hil/test_franka_panda.py, tests/hil/test_sawyer.py, tests/hil/test_aloha.py, tests/hil/test_ur5e.py, tests/hil/test_ur10e.py, tests/hil/test_galaxea_a1.py — lab runners only (UR5E_HOST / UR10E_HOST env vars + [self-hosted, lab-ur*] runner labels for the UR pair).
• HIL transport bridges (lab-only): tests/hil/_ros_control_transport.py exposes RosControlHILTransport + make_hil_transport for the single-controller real-HW HALs (UR5e / UR10e / Franka Panda / Sawyer); tests/hil/_aloha_ros_transport.py exposes AlohaHILTransport + make_aloha_hil_transport for the bimanual ALOHA fan-out (4 controllers). Both raise at import time if rclpy is not installed, so HIL tests guard with importlib.util.find_spec("rclpy") before importing them.

Doctest coverage: every adapter file is in Justfile::test-doctest's curated DOCTEST_TARGETS; run just test-doctest to exercise the docstring examples.

See also

• openral_core.RobotDescription, JointSpec, Action, JointState, SafetyEnvelope — the typed contract this package consumes and emits.
• robots/<robot_id>/robot.yaml — canonical description manifests.
• packages/openral_hal_*/README.md — ROS 2 lifecycle node docs.
• CLAUDE.md §6 (architecture discipline) and §10 (exception hierarchy: ROSConfigError / ROSRuntimeError / ROSSafetyViolation are the only exceptions a HAL adapter raises).