flexiv-control 0.1.0__py3-none-any.whl

flexiv_control/__init__.py

@@ -0,0 +1,117 @@
+"""flexiv_control -- a unified, real-time execution & safety layer for Flexiv Rizon arms.
+
+One action contract for teleoperation, MPC, reinforcement learning, and
+real-to-sim-to-real manipulation. Backend-agnostic (real Rizon via Flexiv RDK,
+a dependency-free FakeBackend, or MuJoCo), with an optional cross-process server,
+an optional C++ 1 kHz daemon, an optional ROS 2 overlay, a Gymnasium env, and a
+LeRobot adapter.
+
+This is a community project and is **not affiliated with Flexiv Robotics**.
+
+Quick start (no hardware needed)::
+
+    from flexiv_control import Robot, RobotConfig, CartesianChunk
+
+    robot = Robot(RobotConfig(backend="fake"))
+    robot.connect()
+    robot.start_cartesian_impedance()
+    chunk = CartesianChunk.from_waypoint_array([[0.45, 0.0, 0.30, 1.0, 20],
+                                          [0.50, 0.0, 0.25, 0.0, 20]])
+    result = robot.execute_cartesian_chunk(chunk)
+    print(result.success, result.path_tracking_error)
+    robot.disconnect()
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+# --- core data types
+from .types import (  # noqa: F401
+    ControlMode,
+    ForceControlParams,
+    GripperCommand,
+    ImpedanceParams,
+    JointImpedanceParams,
+    RobotState,
+    SafetyStatus,
+    StopReason,
+)
+
+# --- the action contract
+from .action_chunk import (  # noqa: F401
+    CartesianChunk,
+    CartesianDelta,
+    CartesianWaypoint,
+    ChunkRepresentation,
+    ExecutionResult,
+    JointChunk,
+    JointWaypoint,
+)
+
+# --- safety + config
+from .safety import SafetyFilter, SafetyProfile  # noqa: F401
+from .config import RobotConfig, load_safety_profile  # noqa: F401
+
+# --- backends (light ones only; heavy/optional ones load lazily by name)
+from .backends import FakeBackend, RobotBackend, get_backend  # noqa: F401
+
+# --- the one facade
+from .robot import LeaseError, Robot  # noqa: F401
+
+# --- receding-horizon / VLA policy-server seam
+from .recede import RecedingHorizonRunner  # noqa: F401
+from .policy_client import RemotePolicyClient  # noqa: F401
+
+__all__ = [
+    "__version__",
+    # types
+    "ControlMode",
+    "ForceControlParams",
+    "GripperCommand",
+    "ImpedanceParams",
+    "JointImpedanceParams",
+    "RobotState",
+    "SafetyStatus",
+    "StopReason",
+    # action contract
+    "CartesianChunk",
+    "CartesianDelta",
+    "CartesianWaypoint",
+    "ChunkRepresentation",
+    "ExecutionResult",
+    "JointChunk",
+    "JointWaypoint",
+    # safety + config
+    "SafetyFilter",
+    "SafetyProfile",
+    "RobotConfig",
+    "load_safety_profile",
+    # backends
+    "FakeBackend",
+    "RobotBackend",
+    "get_backend",
+    # facade
+    "Robot",
+    "LeaseError",
+    # receding horizon
+    "RecedingHorizonRunner",
+    "RemotePolicyClient",
+]
+
+
+def __getattr__(name: str):
+    """Lazily expose optional, heavier components without importing their deps eagerly."""
+    if name == "RemoteRobot":
+        from .client.remote_robot import RemoteRobot
+
+        return RemoteRobot
+    if name == "FlexivControlServer":
+        from .server.server import FlexivControlServer
+
+        return FlexivControlServer
+    if name == "FlexivRealEnv":
+        from .envs.gym_env import FlexivRealEnv
+
+        return FlexivRealEnv
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

flexiv_control/action_chunk.py

@@ -0,0 +1,372 @@
+"""The unified *action contract*.
+
+This is the single most important module for cross-project reuse. Every high
+level component -- a receding-horizon planner, an MPC loop, an RL policy, a
+SpaceMouse teleop bridge -- emits one of these objects, and every backend knows
+how to execute them. Nobody re-invents "how do I talk to the robot".
+
+Why this exact shape
+--------------------
+Action-chunking and receding-horizon planners typically emit a candidate action
+of the form
+
+    u = ( (x_j, y_j, z_j, w_j, n_j) )_{j=1..H}
+
+i.e. a short sequence of Cartesian waypoints, each with a gripper command ``w_j``
+and a *number of low-level control frames* ``n_j``. That ``n_j`` is precisely a
+duration once you fix a control rate:
+
+    duration_j = n_frames_j / control_hz
+
+``CartesianChunk`` below is that object, generalised so it is also exactly what
+an MPC horizon, a robosuite/MuJoCo rollout, or an RL action-chunk needs:
+  * positions become full SE(3) poses (orientation may be *held* -> position-only
+    chunks map in with zero changes),
+  * per-waypoint stiffness/limits so the *same* chunk can describe a free-space
+    reach and a contact-rich push,
+  * an explicit ``representation`` (absolute vs relative-to-chunk-start) and a
+    predict-vs-execute horizon split (``n_execute`` -> ``horizon_exec``), so the
+    receding-horizon "predict H_pred, execute H_exec, replan" loop (Diffusion
+    Policy Tp/Ta) is first-class rather than implicit,
+  * an explicit safety_profile name so execution is reproducible.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from enum import Enum
+from typing import List, Optional
+
+import numpy as np
+
+from .types import CART_DOF, ForceControlParams, GripperCommand, ImpedanceParams
+
+
+# ----------------------------------------------------------------------------
+# Cartesian
+# ----------------------------------------------------------------------------
+@dataclass
+class CartesianWaypoint:
+    """One Cartesian target.
+
+    ``position`` is always required. ``quaternion`` (w, x, y, z) is optional:
+    leave it ``None`` to *hold the current/previous orientation*, which is what
+    a position-only planner (e.g. one emitting ``(x, y, z)`` waypoints) wants.
+
+    Either ``n_frames`` (a per-waypoint frame count) or ``duration`` may be given. The
+    interpolator converts ``n_frames`` to a duration using the active control
+    rate, so the same chunk runs identically whether the loop is 100 Hz or
+    1 kHz, as long as ``n_frames`` is interpreted at that rate.
+    """
+
+    position: np.ndarray
+    quaternion: Optional[np.ndarray] = None   # (w, x, y, z); None -> hold
+    gripper: Optional[GripperCommand] = None  # None -> hold gripper
+    n_frames: Optional[int] = None            # number of low-level control frames
+    duration: Optional[float] = None          # seconds (alternative to n_frames)
+    frame: str = "base"
+
+    def __post_init__(self) -> None:
+        self.position = np.asarray(self.position, float).reshape(3)
+        if self.quaternion is not None:
+            q = np.asarray(self.quaternion, float).reshape(4)
+            n = np.linalg.norm(q)
+            if n < 1e-9:
+                raise ValueError("zero-norm quaternion")
+            self.quaternion = q / n
+        if self.n_frames is None and self.duration is None:
+            raise ValueError("CartesianWaypoint needs either n_frames or duration")
+        if self.n_frames is not None and self.n_frames <= 0:
+            raise ValueError("n_frames must be positive")
+
+    def resolve_duration(self, control_hz: float) -> float:
+        if self.duration is not None:
+            return float(self.duration)
+        return float(self.n_frames) / float(control_hz)
+
+
+class ChunkRepresentation(str, Enum):
+    """How the waypoint poses in a chunk are interpreted.
+
+    * ``ABSOLUTE`` (default): each waypoint is an absolute target in the chunk's
+      ``frame`` (base by default) -- the ALOHA/DROID convention.
+    * ``RELATIVE_TO_START``: each waypoint is a pose *relative to the TCP pose at
+      the start of the chunk* (composed ``T_abs = T_start . T_rel``) -- the
+      UMI-style relative-trajectory convention that is robust to base/camera
+      calibration drift. It is resolved to absolute at execution time against the
+      live start pose, so a chunk never accumulates sequential step-to-step error.
+
+    Which is better is task/setup dependent (UMI favours relative for
+    calibration-free in-the-wild use; DROID ships absolute), so this is an
+    explicit field, not a baked-in default.
+    """
+
+    ABSOLUTE = "absolute"
+    RELATIVE_TO_START = "relative_to_start"
+
+
+@dataclass
+class CartesianChunk:
+    """A short, bounded sequence of Cartesian waypoints -- the core action type.
+
+    Used by a receding-horizon planner (execute first segment, replan), MPC (the first slice of a
+    horizon), scripted manipulation, and high-level RL.
+    """
+
+    waypoints: List[CartesianWaypoint]
+
+    # Compliance for the whole chunk (a waypoint may override later if needed).
+    impedance: ImpedanceParams = field(default_factory=ImpedanceParams)
+    force_control: Optional[ForceControlParams] = None
+
+    # Kinematic envelope enforced by the interpolator + safety filter.
+    max_tcp_linear_speed: float = 0.25    # m/s
+    max_tcp_angular_speed: float = 0.60   # rad/s
+    max_tcp_linear_acc: float = 1.0       # m/s^2
+    max_tcp_angular_acc: float = 2.0      # rad/s^2
+
+    # Contact envelope (None -> use the safety profile default).
+    max_contact_wrench: Optional[np.ndarray] = None  # [fx,fy,fz,tx,ty,tz]
+
+    # Named safety profile to load before executing (reproducibility).
+    safety_profile: str = "tabletop_safe"
+
+    frame: str = "base"
+
+    # Absolute vs relative-to-chunk-start pose semantics (see ChunkRepresentation).
+    representation: ChunkRepresentation = ChunkRepresentation.ABSOLUTE
+
+    # Receding-horizon split: the chunk *predicts* len(waypoints) (H_pred) but the
+    # robot executes only the first ``n_execute`` (H_exec) before replanning.
+    # None -> execute the whole chunk. Diffusion-Policy reference: predict ~16,
+    # execute ~8.
+    n_execute: Optional[int] = None
+
+    def __post_init__(self) -> None:
+        if not self.waypoints:
+            raise ValueError("CartesianChunk needs at least one waypoint")
+        if self.max_contact_wrench is not None:
+            self.max_contact_wrench = np.asarray(self.max_contact_wrench, float).reshape(CART_DOF)
+
+    @property
+    def horizon(self) -> int:
+        return len(self.waypoints)
+
+    @property
+    def horizon_pred(self) -> int:
+        """Number of predicted waypoints (H_pred)."""
+        return len(self.waypoints)
+
+    @property
+    def horizon_exec(self) -> int:
+        """Number of waypoints actually executed before replanning (H_exec)."""
+        n = self.n_execute if self.n_execute is not None else len(self.waypoints)
+        return max(1, min(int(n), len(self.waypoints)))
+
+    def total_duration(self, control_hz: float) -> float:
+        return sum(w.resolve_duration(control_hz) for w in self.waypoints)
+
+    def resolve_to_absolute(self, start_pose: np.ndarray) -> "CartesianChunk":
+        """Return an ABSOLUTE-representation copy of this chunk.
+
+        Identity if already absolute. For ``RELATIVE_TO_START`` each waypoint is
+        composed onto ``start_pose`` (the live TCP pose at chunk start) as
+        ``T_abs = T_start . T_rel`` -- so relative chunks are re-anchored to the
+        current measured pose each cycle and never accumulate sequential error.
+        """
+        if self.representation == ChunkRepresentation.ABSOLUTE:
+            return self
+        from . import transforms as T
+
+        sp = np.asarray(start_pose, float).reshape(7)
+        s_pos, s_quat = sp[:3], sp[3:7]
+        new_wps: List[CartesianWaypoint] = []
+        for w in self.waypoints:
+            abs_pos = s_pos + T.quat_rotate(s_quat, w.position)
+            abs_quat = (
+                s_quat.copy()
+                if w.quaternion is None
+                else T.quat_normalize(T.quat_mul(s_quat, w.quaternion))
+            )
+            new_wps.append(
+                CartesianWaypoint(
+                    position=abs_pos, quaternion=abs_quat, gripper=w.gripper,
+                    n_frames=w.n_frames, duration=w.duration, frame=w.frame,
+                )
+            )
+        return replace(self, waypoints=new_wps, representation=ChunkRepresentation.ABSOLUTE)
+
+    def for_execution(self, start_pose: np.ndarray) -> "CartesianChunk":
+        """Resolve to absolute and slice to the execution horizon H_exec.
+
+        This is what a ``Robot`` runs: relative chunks become absolute against the
+        live start pose, and only the first ``n_execute`` waypoints are kept (the
+        rest are discarded and re-predicted next cycle -- receding horizon).
+        """
+        c = self.resolve_to_absolute(start_pose)
+        he = self.horizon_exec
+        if he >= len(c.waypoints):
+            return c
+        return replace(c, waypoints=c.waypoints[:he], n_execute=None)
+
+    # -- Convenience constructors -------------------------------------------
+    @classmethod
+    def from_waypoint_array(
+        cls,
+        u: np.ndarray,
+        *,
+        gripper_force: float = 20.0,
+        gripper_span: float = 0.08,
+        hold_orientation: bool = True,
+        **chunk_kwargs,
+    ) -> "CartesianChunk":
+        """Build a chunk directly from a planner's ``(H, 5)`` action array ``u``.
+
+        ``u`` is an ``(H, 5)`` array of rows ``(x, y, z, w, n)`` where ``w`` is a
+        *normalised* gripper command in ``[0, 1]`` (1 = open, 0 = closed) and ``n``
+        is the integer number of low-level control frames. ``w`` is mapped to a
+        physical width ``w * gripper_span`` -- pass your gripper's real stroke as
+        ``gripper_span`` (e.g. RDK ``GripperParams.max_width``); the 0.08 m default
+        is the lab GN01 and must not be assumed for other grippers. Orientation is
+        held from the previous pose; use :meth:`from_pose_array` to command it.
+        """
+        u = np.asarray(u, float)
+        if u.ndim != 2 or u.shape[1] != 5:
+            raise ValueError("u must have shape (H, 5): (x, y, z, w, n)")
+        # An (H, 5) array carries no orientation, so every waypoint holds the
+        # previous orientation (quaternion=None). ``hold_orientation`` is accepted
+        # for API symmetry but is necessarily True for this position-only format;
+        # use ``from_pose_array`` (H,9) if you need to command orientation.
+        if not hold_orientation:
+            raise ValueError(
+                "from_waypoint_array ingests position-only (H,5) actions and cannot "
+                "set orientation; use from_pose_array((H,9)) or build "
+                "CartesianWaypoint(s) with quaternions instead."
+            )
+        wpts: List[CartesianWaypoint] = []
+        for x, y, z, w, n in u:
+            grip = GripperCommand.from_normalized(w, span=gripper_span, force=gripper_force)
+            wpts.append(
+                CartesianWaypoint(
+                    position=[x, y, z],
+                    quaternion=None,
+                    gripper=grip,
+                    n_frames=max(1, int(round(n))),
+                )
+            )
+        return cls(waypoints=wpts, **chunk_kwargs)
+
+    @classmethod
+    def from_pose_array(
+        cls,
+        u: np.ndarray,
+        *,
+        gripper_force: float = 20.0,
+        gripper_span: float = 0.08,
+        **chunk_kwargs,
+    ) -> "CartesianChunk":
+        """Build a chunk from an ``(H, 9)`` array that carries orientation.
+
+        Each row is ``(x, y, z, qw, qx, qy, qz, w, n)``: an SE(3) pose (quaternion
+        w-first) + normalised gripper ``w`` in ``[0, 1]`` + frame count ``n``. This
+        is the orientation-carrying sibling of :meth:`from_waypoint_array`, for
+        policies/planners that emit per-step orientation (full SE(3) action
+        chunks, e.g. ACT/openpi-style). Combine with ``representation=`` and
+        ``n_execute=`` via ``chunk_kwargs`` for relative / receding-horizon use.
+        """
+        u = np.asarray(u, float)
+        if u.ndim != 2 or u.shape[1] != 9:
+            raise ValueError("u must have shape (H, 9): (x,y,z, qw,qx,qy,qz, w, n)")
+        wpts: List[CartesianWaypoint] = []
+        for row in u:
+            grip = GripperCommand.from_normalized(row[7], span=gripper_span, force=gripper_force)
+            wpts.append(
+                CartesianWaypoint(
+                    position=row[:3],
+                    quaternion=row[3:7],
+                    gripper=grip,
+                    n_frames=max(1, int(round(row[8]))),
+                )
+            )
+        return cls(waypoints=wpts, **chunk_kwargs)
+
+
+# ----------------------------------------------------------------------------
+# Delta (relative) servo command -- the RL / MPC / teleop workhorse
+# ----------------------------------------------------------------------------
+@dataclass
+class CartesianDelta:
+    """A relative end-effector move, integrated on top of the current pose.
+
+    This is the standard RL / MPC / teleop action: ``[dx, dy, dz, rx, ry, rz]``
+    plus a gripper command, applied over ``duration`` seconds. The last three are
+    an axis-angle *rotation vector* (not roll/pitch/yaw Euler angles), matching
+    robosuite/MuJoCo ``OSC_POSE`` -- which is what makes sim->real transfer clean.
+    The translation is taken in ``frame`` ("base" or "tcp").
+    """
+
+    delta: np.ndarray                       # length-6, base or tcp frame
+    gripper: Optional[GripperCommand] = None
+    duration: float = 0.05                  # 20 Hz default control step
+    frame: str = "base"
+
+    def __post_init__(self) -> None:
+        self.delta = np.asarray(self.delta, float).reshape(CART_DOF)
+
+
+# ----------------------------------------------------------------------------
+# Joint space (reset / home / MoveIt-plan execution)
+# ----------------------------------------------------------------------------
+@dataclass
+class JointWaypoint:
+    positions: np.ndarray
+    n_frames: Optional[int] = None
+    duration: Optional[float] = None
+
+    def __post_init__(self) -> None:
+        self.positions = np.asarray(self.positions, float)
+        if self.n_frames is None and self.duration is None:
+            raise ValueError("JointWaypoint needs n_frames or duration")
+
+    def resolve_duration(self, control_hz: float) -> float:
+        if self.duration is not None:
+            return float(self.duration)
+        return float(self.n_frames) / float(control_hz)
+
+
+@dataclass
+class JointChunk:
+    waypoints: List[JointWaypoint]
+    max_joint_speed_scale: float = 0.3   # fraction of joint vel limits
+    safety_profile: str = "tabletop_safe"
+
+    def __post_init__(self) -> None:
+        if not self.waypoints:
+            raise ValueError("JointChunk needs at least one waypoint")
+
+
+# ----------------------------------------------------------------------------
+# Execution report -- quantifies the "execution" failure category
+# ----------------------------------------------------------------------------
+@dataclass
+class ExecutionResult:
+    """Returned by every blocking execution call.
+
+    A receding-horizon planner's failure taxonomy typically has an "execution"
+    bucket. This object turns
+    that bucket into something observable and quantifiable rather than a guess:
+    the planner logs ``clipped``/``stop_reason``/``path_tracking_error`` and can
+    attribute a bad outcome to execution vs perception/ranking with evidence.
+    """
+
+    success: bool = True
+    clipped: bool = False
+    stop_reason: str = "none"
+    executed_duration: float = 0.0
+    path_tracking_error: float = 0.0      # max ||pose_cmd - pose_meas|| over run
+    max_tcp_speed: float = 0.0
+    max_joint_speed: float = 0.0
+    max_wrench: float = 0.0
+    gripper_width_final: float = 0.0
+    final_state: Optional["object"] = None  # RobotState; Optional to avoid import cycle
+    log: dict = field(default_factory=dict)

flexiv_control/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Adapters bridging the controller to external ecosystems (LeRobot, ...)."""
+
+from .lerobot_robot import LeRobotFlexivAdapter, register_with_lerobot  # noqa: F401
+
+__all__ = ["LeRobotFlexivAdapter", "register_with_lerobot"]

flexiv_control/adapters/lerobot_robot.py

@@ -0,0 +1,182 @@
+"""A LeRobot ``Robot``-interface adapter for the Flexiv controller.
+
+LeRobot (HuggingFace) is the de-facto community hub for robot-learning data and
+policies. Conforming to its "Bring Your Own Hardware" ``Robot`` interface lets a
+Flexiv arm plug into LeRobot's data-collection, training, and visualization
+tooling. This adapter exposes the LeRobot ``Robot`` surface; turning the recorded
+frames into a ``LeRobotDataset`` (MP4 + Parquet) is a thin extra step on the
+caller's side against their installed ``lerobot`` version (the dataset API moves
+between releases -- see ``examples/06_lerobot_record.py``).
+
+This adapter exposes the documented LeRobot ``Robot`` surface -- ``connect`` /
+``disconnect`` / ``get_observation`` / ``send_action`` plus ``observation_features``
+and ``action_features`` -- backed by the unified controller (any backend, local
+or via :class:`~flexiv_control.RemoteRobot`).
+
+LeRobot's API has moved between versions; the exact base class / feature schema
+may differ in yours. We therefore keep the adapter standalone (it does *not*
+hard-subclass LeRobot) and import LeRobot lazily only if you ask to register it.
+Verify the feature dict against your installed ``lerobot`` -- search points are
+marked ``# VERIFY:``.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Optional, Union
+
+import numpy as np
+
+from ..config import RobotConfig
+from ..robot import Robot
+from ..types import GripperCommand
+
+
+class LeRobotFlexivAdapter:
+    """Adapts the Flexiv controller to LeRobot's ``Robot`` interface.
+
+    Action and observation are flat Cartesian-delta / state vectors by default,
+    matching :class:`~flexiv_control.envs.FlexivRealEnv` so a policy trained in
+    that env records and replays here unchanged.
+    """
+
+    name = "flexiv_rizon"
+
+    def __init__(
+        self,
+        robot: Optional[object] = None,
+        *,
+        config: Optional[RobotConfig] = None,
+        control_hz: float = 20.0,
+        safety_profile: str = "rl_conservative",
+        pos_scale: float = 0.05,
+        rot_scale: float = 0.20,
+        gripper_open_width: float = 0.08,
+        owner: str = "lerobot",
+    ):
+        self.robot = robot or Robot(config or RobotConfig(control_hz=control_hz))
+        self.control_hz = float(control_hz)
+        self.step_duration = 1.0 / self.control_hz
+        self.safety_profile = safety_profile
+        self.pos_scale = float(pos_scale)
+        self.rot_scale = float(rot_scale)
+        self.gripper_open_width = float(gripper_open_width)
+        self.owner = owner
+        self._connected = False
+
+    # -- LeRobot feature schema ---------------------------------------------
+    # LeRobot's modern Robot interface wants FLAT, bare per-scalar keys whose
+    # value is the Python type ``float`` (cf. SOFollower's ``{f"{m}.pos": float}``).
+    # LeRobot itself adds the ``observation.``/``action.`` prefix and aggregates
+    # the float keys into a single ``observation.state`` / ``action`` vector
+    # (names = the bare keys) via hw_to_dataset_features. get_observation /
+    # send_action below return one scalar per key so build_dataset_frame can
+    # index each by name.
+    _OBS_KEYS = (
+        [f"q.{i}" for i in range(7)]
+        + [f"dq.{i}" for i in range(7)]
+        + [f"tcp_pose.{i}" for i in range(7)]
+        + [f"wrench.{i}" for i in range(6)]
+        + ["gripper_width"]
+    )
+    _ACTION_KEYS = ("dx", "dy", "dz", "droll", "dpitch", "dyaw", "gripper")
+
+    @property
+    def observation_features(self) -> Dict[str, type]:
+        return {k: float for k in self._OBS_KEYS}
+
+    @property
+    def action_features(self) -> Dict[str, type]:
+        return {k: float for k in self._ACTION_KEYS}
+
+    @property
+    def is_connected(self) -> bool:
+        return self._connected
+
+    @property
+    def is_calibrated(self) -> bool:
+        # Rizon is factory-calibrated; calibrate() is a no-op, so report True to
+        # let LeRobot's connect() skip self.calibrate().
+        return True
+
+    # -- lifecycle -----------------------------------------------------------
+    def connect(self, calibrate: bool = True) -> None:  # noqa: ARG002
+        if self._connected:
+            return
+        self.robot.connect()
+        try:
+            self.robot.acquire_lease(self.owner)
+        except TypeError:
+            self.robot.acquire_lease()
+        try:
+            self.robot.set_safety_profile(self.safety_profile)
+        except FileNotFoundError:
+            pass
+        self.robot.start_cartesian_impedance()
+        self._connected = True
+
+    def disconnect(self) -> None:
+        if not self._connected:
+            return
+        try:
+            self.robot.stop()
+            try:
+                self.robot.release_lease()
+            except Exception:
+                pass
+            self.robot.disconnect()
+        finally:
+            self._connected = False
+
+    def calibrate(self) -> None:
+        """No-op: the Rizon is factory-calibrated; impedance/home handle setup."""
+
+    def configure(self) -> None:
+        """No-op hook for LeRobot compatibility."""
+
+    # -- observation / action ------------------------------------------------
+    def get_observation(self) -> Dict[str, float]:
+        # One scalar per bare key, matching observation_features, so LeRobot's
+        # build_dataset_frame can index each by name into observation.state.
+        s = self.robot.get_state()
+        obs: Dict[str, float] = {}
+        for i in range(7):
+            obs[f"q.{i}"] = float(s.q[i])
+        for i in range(7):
+            obs[f"dq.{i}"] = float(s.dq[i])
+        for i in range(7):
+            obs[f"tcp_pose.{i}"] = float(s.tcp_pose[i])
+        for i in range(6):
+            obs[f"wrench.{i}"] = float(s.wrench[i])
+        obs["gripper_width"] = float(s.gripper_width)
+        return obs
+
+    def send_action(
+        self, action: Union[np.ndarray, Dict[str, float]]
+    ) -> Dict[str, float]:
+        # Accept a 7-vector or a per-key dict ({"dx":.., .., "gripper":..}); return
+        # one scalar per action key so the recorded action frame matches features.
+        if isinstance(action, dict):
+            a = np.asarray([action[k] for k in self._ACTION_KEYS], float)
+        else:
+            a = np.asarray(action, float).reshape(7)
+        a = np.clip(a, -1.0, 1.0)
+        delta = np.empty(6)
+        delta[:3] = a[:3] * self.pos_scale
+        delta[3:] = a[3:6] * self.rot_scale
+        width = float(np.clip((a[6] + 1.0) / 2.0, 0.0, 1.0)) * self.gripper_open_width
+        grip = GripperCommand(width=width, force=20.0, grasp=a[6] < 0)
+        self.robot.servo_cartesian_delta(delta, duration=self.step_duration, gripper=grip)
+        return {k: float(v) for k, v in zip(self._ACTION_KEYS, a)}
+
+
+def register_with_lerobot() -> bool:
+    """Attempt to register the adapter with an installed LeRobot.
+
+    NOT IMPLEMENTED: current LeRobot has no stable runtime "register a robot"
+    call -- hardware is registered via a config dataclass decorated with
+    ``@RobotConfig.register_subclass("flexiv_rizon")`` plus the
+    ``make_robot_from_config`` factory, so there is nothing to invoke at runtime
+    here. Use :class:`LeRobotFlexivAdapter` directly; it implements the full
+    LeRobot ``Robot`` surface. Returns ``False`` (no registration performed).
+    """
+    return False