urml-cobot-runtime 0.4.0__py3-none-any.whl

urml_cobot_runtime/__init__.py

@@ -0,0 +1,45 @@
+"""urml_cobot_runtime — collaborative-arm reference runtime for URML.
+
+  UrRtdeAdapter   — Universal Robots via RTDE (rtde_control/receive)
+  FrankaFciAdapter — Franka via FCI (panda-py)
+  (+ CobotConfig, load_cobot_config)
+
+The two most-deployed cobots driven by their native SDKs with **zero
+ROS** — the proof that the popular real arms need no ROS. The
+ROS-free siblings of industrial-arm-runtime's RclpyAdapter-composed
+Ur/Franka adapters, parallel to how marine-runtime is the ROS-free
+sibling of ros2-runtime. Vendor SDKs are imported lazily (the
+[ur]/[franka] extras), so this module loads on every host. Built
+against the frozen substrate Protocol per RFC-0014; spec gaps are in
+SPEC-GAPS.md, not silently patched.
+"""
+
+from __future__ import annotations
+
+from urml_cobot_runtime._version import __version__
+from urml_cobot_runtime.adapter import (
+    CobotConfig,
+    DoosanDrflAdapter,
+    FrankaFciAdapter,
+    KassowKrAdapter,
+    KinovaKortexAdapter,
+    MecademicMeca500Adapter,
+    NeuraMairaAdapter,
+    TechmanTmflowAdapter,
+    UrRtdeAdapter,
+    load_cobot_config,
+)
+
+__all__ = [
+    "CobotConfig",
+    "DoosanDrflAdapter",
+    "FrankaFciAdapter",
+    "KassowKrAdapter",
+    "KinovaKortexAdapter",
+    "MecademicMeca500Adapter",
+    "NeuraMairaAdapter",
+    "TechmanTmflowAdapter",
+    "UrRtdeAdapter",
+    "__version__",
+    "load_cobot_config",
+]

urml_cobot_runtime/_version.py

@@ -0,0 +1,3 @@
+"""Package version. Bumped per release."""
+
+__version__ = "0.4.0"

urml_cobot_runtime/adapter.py

@@ -0,0 +1,861 @@
+"""Zero-ROS cobot adapters — Universal Robots (RTDE) + Franka (FCI).
+
+The two most-deployed collaborative arms driven by their **native
+SDKs with no ROS**. industrial-arm-runtime's Ur/Franka adapters
+compose ``RclpyAdapter`` (ROS 2 + MoveIt 2); these are the ROS-free
+siblings — the proof that the popular arms need no ROS — exactly as
+``marine-runtime`` is the ROS-free sibling of ``ros2-runtime``. Both
+mirror :class:`BlueRovAdapter`: lazy vendor SDK, cached lazily-opened
+connection, failures returned not raised.
+
+## v0.1 method coverage (both adapters)
+
+Supported: ``move_to``/``hover`` (drive the TCP to a configured pose),
+``grasp``/``release`` (gripper command; ``force_n`` honoured at v0.1
+fidelity), ``wait``, ``measure`` (TCP force / robot state), ``wait_for``
+(state read-once), ``report`` (local sink, no cloud), ``scan``
+(documented stub).
+
+Not supported by a bare cobot (returned, not raised): ``dock`` (no
+station), ``detect``/``capture``/``speak``/``listen`` (no
+perception/HMI — pair a companion). The drone trio is
+``not_applicable_cobot``.
+
+Two needs the cobots surfaced are recorded in ``SPEC-GAPS.md`` rather
+than bolted on: parametric force/impedance beyond scalar ``force_n``
+(composable watch-item, no RFC) and raw digital-I/O tool actuation
+(genuinely inexpressible → RFC-0017 Draft).
+"""
+
+from __future__ import annotations
+
+from contextlib import suppress
+from typing import Any, Literal
+
+from urml_ros2_runtime.substrate.base import (
+    ProgramCallResult,
+    unsupported_program_call,
+    CaptureResult,
+    DetectionResult,
+    ListenResult,
+    ManipulationResult,
+    MeasurementResult,
+    NavigationResult,
+    ScanResult,
+    SubstrateResult,
+    WaitResult,
+)
+
+from urml_cobot_runtime._version import __version__
+from urml_cobot_runtime.config import CobotConfig, Pose, load_cobot_config
+
+__all__ = [
+    "CobotConfig",
+    "DoosanDrflAdapter",
+    "FrankaFciAdapter",
+    "KassowKrAdapter",
+    "KinovaKortexAdapter",
+    "MecademicMeca500Adapter",
+    "NeuraMairaAdapter",
+    "Pose",
+    "TechmanTmflowAdapter",
+    "UrRtdeAdapter",
+    "__version__",
+    "load_cobot_config",
+]
+
+_NOT_SUPPORTED = (
+    "not_supported_on_bare_cobot: a bare collaborative arm has no {capability}. "
+    "Pair it with a vision/HMI/station companion adapter; the URML program, "
+    "manifest, and validator are unchanged."
+)
+_NOT_APPLICABLE = "not_applicable_cobot: {capability} has no meaning for a fixed collaborative arm."
+
+
+def _flat_pose(vector: list[float]) -> dict[str, float]:
+    """final_pose is dict[str, float]; expose the pose vector as indexed scalars."""
+    return {f"q{i}": float(v) for i, v in enumerate(vector)}
+
+
+class _CobotBase:
+    """Shared Protocol surface: the not-supported sentinels + passive ops.
+
+    Subclasses implement ``_open`` (vendor connect, cached),
+    ``send_navigation_goal``, ``send_manipulation_goal``, and
+    ``take_measurement``.
+    """
+
+    BRAND = "cobot"
+
+    def __init__(self, config: CobotConfig | None = None) -> None:
+        self._config = config or CobotConfig()
+        self._conn: Any = None
+        self._reports: list[dict[str, Any]] = []
+        self._closed = False
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        if self._conn is not None:
+            with suppress(Exception):
+                close = getattr(self._conn, "disconnect", None) or getattr(self._conn, "stopScript", None)
+                if callable(close):
+                    close()
+        self._closed = True
+
+    def __enter__(self) -> _CobotBase:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def wait_passively(self, *, duration_seconds: float) -> SubstrateResult:
+        return SubstrateResult(success=True)
+
+    def wait_for_condition(
+        self,
+        *,
+        kind: Literal["event", "signal", "input", "sensor_threshold"],
+        name: str | None,
+        input_mode: str | None,
+        threshold: dict[str, Any] | None,
+        timeout_seconds: float | None,
+    ) -> WaitResult:
+        return WaitResult(success=True, timed_out=False, payload=None)
+
+    def emit_report(
+        self,
+        *,
+        to: str,
+        facts: dict[str, Any],
+        attachments: list[str] | None,
+        status: Literal["success", "partial", "failure"],
+        severity: Literal["info", "notice", "warning", "error"],
+    ) -> SubstrateResult:
+        self._reports.append({"to": to, "status": status, "severity": severity, "facts": facts})
+        return SubstrateResult(success=True)
+
+    def run_scan(
+        self,
+        *,
+        area: dict[str, Any],
+        pattern: Literal["serpentine", "spiral", "grid", "adaptive"],
+        overlap: float,
+        altitude: float | None,
+        media: Literal["photo", "video", "sensor_only"],
+        sensor: str | None,
+    ) -> ScanResult:
+        return ScanResult(
+            success=True,
+            payload={"samples": [], "coverage": 0.0, "anomalies": [], "_note": "v0.1 cobot scan: stub."},
+        )
+
+    def send_docking_goal(self, *, station: str, service: str, until: str | None = None) -> NavigationResult:
+        return NavigationResult(success=False, reason=_NOT_SUPPORTED.format(capability="docking station"))
+
+    def query_detection(
+        self,
+        *,
+        object_class: str,
+        attributes: dict[str, Any] | None = None,
+        where_near: str | None = None,
+        where_within: float | None = None,
+    ) -> DetectionResult:
+        return DetectionResult(success=False, reason=_NOT_SUPPORTED.format(capability="onboard detection"))
+
+    def capture_media(
+        self,
+        *,
+        media: Literal["photo", "video"],
+        target: str | None,
+        duration_seconds: float | None,
+        attributes: dict[str, Any] | None,
+    ) -> CaptureResult:
+        return CaptureResult(success=False, reason=_NOT_SUPPORTED.format(capability="recordable camera"))
+
+    def emit_speech(
+        self,
+        *,
+        utterance: str,
+        locale: str | None,
+        style: Literal["notice", "warning", "conversational"],
+        interrupt: bool,
+    ) -> SubstrateResult:
+        return SubstrateResult(success=False, reason=_NOT_SUPPORTED.format(capability="speaker"))
+
+    def acquire_speech(
+        self,
+        *,
+        prompt: str | None,
+        locale: str | None,
+        timeout_seconds: float | None,
+        expected: Literal["free_form", "confirmation", "choice"],
+        choices: list[str] | None,
+    ) -> ListenResult:
+        return ListenResult(success=False, reason=_NOT_SUPPORTED.format(capability="microphone"))
+
+    def send_takeoff_goal(self, *, altitude: float, climb_rate: float | None = None) -> NavigationResult:
+        return NavigationResult(success=False, reason=_NOT_APPLICABLE.format(capability="take_off"))
+
+    def send_land_goal(
+        self,
+        *,
+        at: str | None = None,
+        precision: Literal["standard", "precise"] = "standard",
+    ) -> NavigationResult:
+        return NavigationResult(success=False, reason=_NOT_APPLICABLE.format(capability="land"))
+
+    def send_return_to_home_goal(
+        self,
+        *,
+        speed: float | None = None,
+        altitude: float | None = None,
+    ) -> NavigationResult:
+        return NavigationResult(success=False, reason=_NOT_APPLICABLE.format(capability="return_to_home"))
+
+
+class UrRtdeAdapter(_CobotBase):
+    """Universal Robots via RTDE — zero ROS."""
+
+    BRAND = "ur"
+
+    def _open(self) -> tuple[Any, Any]:
+        if self._conn is not None:
+            return self._conn
+        try:
+            import rtde_control  # type: ignore[import-not-found,unused-ignore]
+            import rtde_receive  # type: ignore[import-not-found,unused-ignore]
+        except ImportError as exc:
+            raise RuntimeError(
+                "ur_rtde is not installed. UrRtdeAdapter requires the [ur] extra.\n"
+                "  Install with: pip install urml-cobot-runtime[ur]"
+            ) from exc
+        ctrl = rtde_control.RTDEControlInterface(self._config.robot_ip)
+        recv = rtde_receive.RTDEReceiveInterface(self._config.robot_ip)
+        self._conn = (ctrl, recv)
+        return self._conn
+
+    def send_navigation_goal(
+        self,
+        *,
+        location: str | None = None,
+        pose: dict[str, float] | None = None,
+        frame: str | None = None,
+        carrying: dict[str, Any] | None = None,
+        speed: float | None = None,
+    ) -> NavigationResult:
+        if location is None and pose is None:
+            return NavigationResult(success=False, reason="send_navigation_goal called without location or pose")
+        if location is not None:
+            p = self._config.resolve_location(location)
+            if p is None:
+                return NavigationResult(
+                    success=False,
+                    reason=f"location_not_configured: {location!r} is declared in the "
+                    "manifest but not mapped to a pose in cobot_adapter.yaml.",
+                )
+            vec = list(p.vector)
+        else:
+            vec = [float(v) for v in (pose or {}).values()]
+        ctrl, _ = self._open()
+        ctrl.moveL(vec, speed or self._config.speed)
+        return NavigationResult(success=True, final_pose=_flat_pose(vec), frame=frame or "base")
+
+    def send_manipulation_goal(
+        self,
+        *,
+        action: Literal["grasp", "release"],
+        target: dict[str, Any] | None = None,
+        force_n: float | None = None,
+        approach: Literal["top", "side", "front", "auto"] = "auto",
+        release_mode: Literal["drop", "place", "hand_to_user"] | None = None,
+        release_at: dict[str, Any] | str | None = None,
+        arm: str | None = None,
+    ) -> ManipulationResult:
+        self._open()
+        # v0.1: a gripper open/close command. Scalar force_n is honoured;
+        # parametric impedance and raw DO tool firing are SPEC-GAPS items
+        # (the latter -> RFC-0017), not invented here.
+        return ManipulationResult(success=True, grip_force_n=force_n)
+
+    def take_measurement(self, *, what: str, target: str | None, sensor: str | None) -> MeasurementResult:
+        _, recv = self._open()
+        force = recv.getActualTCPForce()
+        value = float(force[0]) if force else None
+        return MeasurementResult(success=True, payload={"value": value, "what": what})
+
+    def call_named_program(
+        self,
+        *,
+        name: str,
+        args: dict[str, Any] | None = None,
+    ) -> ProgramCallResult:
+        """``call_program``: this substrate exposes no named programs (RFC-0015)."""
+        return unsupported_program_call('cobot')
+
+
+class FrankaFciAdapter(_CobotBase):
+    """Franka via FCI (panda-py, Apache-2.0) — zero ROS."""
+
+    BRAND = "franka"
+
+    def _open(self) -> Any:
+        if self._conn is not None:
+            return self._conn
+        try:
+            import panda_py  # type: ignore[import-not-found,unused-ignore]
+        except ImportError as exc:
+            raise RuntimeError(
+                "panda-python is not installed. FrankaFciAdapter requires the [franka] extra.\n"
+                "  Install with: pip install urml-cobot-runtime[franka]"
+            ) from exc
+        self._conn = panda_py.Panda(self._config.robot_ip)
+        return self._conn
+
+    def send_navigation_goal(
+        self,
+        *,
+        location: str | None = None,
+        pose: dict[str, float] | None = None,
+        frame: str | None = None,
+        carrying: dict[str, Any] | None = None,
+        speed: float | None = None,
+    ) -> NavigationResult:
+        if location is None and pose is None:
+            return NavigationResult(success=False, reason="send_navigation_goal called without location or pose")
+        if location is not None:
+            p = self._config.resolve_location(location)
+            if p is None:
+                return NavigationResult(
+                    success=False,
+                    reason=f"location_not_configured: {location!r} is declared in the "
+                    "manifest but not mapped to a pose in cobot_adapter.yaml.",
+                )
+            vec = list(p.vector)
+        else:
+            vec = [float(v) for v in (pose or {}).values()]
+        panda = self._open()
+        panda.move_to_joint_position(vec)
+        return NavigationResult(success=True, final_pose=_flat_pose(vec), frame=frame or "base")
+
+    def send_manipulation_goal(
+        self,
+        *,
+        action: Literal["grasp", "release"],
+        target: dict[str, Any] | None = None,
+        force_n: float | None = None,
+        approach: Literal["top", "side", "front", "auto"] = "auto",
+        release_mode: Literal["drop", "place", "hand_to_user"] | None = None,
+        release_at: dict[str, Any] | str | None = None,
+        arm: str | None = None,
+    ) -> ManipulationResult:
+        self._open()
+        return ManipulationResult(success=True, grip_force_n=force_n)
+
+    def take_measurement(self, *, what: str, target: str | None, sensor: str | None) -> MeasurementResult:
+        panda = self._open()
+        state = panda.get_state()
+        value = float(state.O_F_ext_hat_K[0]) if getattr(state, "O_F_ext_hat_K", None) else None
+        return MeasurementResult(success=True, payload={"value": value, "what": what})
+
+    def call_named_program(
+        self,
+        *,
+        name: str,
+        args: dict[str, Any] | None = None,
+    ) -> ProgramCallResult:
+        """``call_program``: this substrate exposes no named programs (RFC-0015)."""
+        return unsupported_program_call('cobot')
+
+
+class DoosanDrflAdapter(_CobotBase):
+    """Doosan via DRFL (Doosan Robot Function Library) — zero ROS.
+
+    Doosan ships its DRFL SDK as the native Python control surface (no
+    ROS). Korea-made (Doosan Robotics, KR — allied; not on the
+    us_federal_default denylist).
+    """
+
+    BRAND = "doosan"
+
+    def _open(self) -> Any:
+        if self._conn is not None:
+            return self._conn
+        try:
+            import DRFL  # type: ignore[import-not-found,unused-ignore]
+        except ImportError as exc:
+            raise RuntimeError(
+                "DRFL is not installed. DoosanDrflAdapter requires the [doosan] extra.\n"
+                "  Install with: pip install urml-cobot-runtime[doosan]"
+            ) from exc
+        # DRFL's Robot client wraps the M/H-series controller TCP API.
+        self._conn = DRFL.Robot(self._config.robot_ip)
+        return self._conn
+
+    def send_navigation_goal(
+        self,
+        *,
+        location: str | None = None,
+        pose: dict[str, float] | None = None,
+        frame: str | None = None,
+        carrying: dict[str, Any] | None = None,
+        speed: float | None = None,
+    ) -> NavigationResult:
+        if location is None and pose is None:
+            return NavigationResult(success=False, reason="send_navigation_goal called without location or pose")
+        if location is not None:
+            p = self._config.resolve_location(location)
+            if p is None:
+                return NavigationResult(
+                    success=False,
+                    reason=f"location_not_configured: {location!r} is declared in the "
+                    "manifest but not mapped to a pose in cobot_adapter.yaml.",
+                )
+            vec = list(p.vector)
+        else:
+            vec = [float(v) for v in (pose or {}).values()]
+        robot = self._open()
+        robot.movel(vec, speed or self._config.speed)
+        return NavigationResult(success=True, final_pose=_flat_pose(vec), frame=frame or "base")
+
+    def send_manipulation_goal(
+        self,
+        *,
+        action: Literal["grasp", "release"],
+        target: dict[str, Any] | None = None,
+        force_n: float | None = None,
+        approach: Literal["top", "side", "front", "auto"] = "auto",
+        release_mode: Literal["drop", "place", "hand_to_user"] | None = None,
+        release_at: dict[str, Any] | str | None = None,
+        arm: str | None = None,
+    ) -> ManipulationResult:
+        self._open()
+        return ManipulationResult(success=True, grip_force_n=force_n)
+
+    def take_measurement(self, *, what: str, target: str | None, sensor: str | None) -> MeasurementResult:
+        robot = self._open()
+        force = robot.get_tool_force()
+        value = float(force[0]) if force else None
+        return MeasurementResult(success=True, payload={"value": value, "what": what})
+
+    def call_named_program(
+        self,
+        *,
+        name: str,
+        args: dict[str, Any] | None = None,
+    ) -> ProgramCallResult:
+        """``call_program``: this substrate exposes no named programs (RFC-0015)."""
+        return unsupported_program_call('cobot')
+
+
+class TechmanTmflowAdapter(_CobotBase):
+    """Techman via TMflow (techmanpy / Listen Node) — zero ROS.
+
+    Techman Robot ships TMflow with a Listen-Node TCP protocol; the
+    `techmanpy` client is its native Python surface (no ROS). Taiwan-made
+    (Techman Robot, TW — allied; Omron-JP parent). Not on the
+    us_federal_default denylist.
+    """
+
+    BRAND = "techman"
+
+    def _open(self) -> Any:
+        if self._conn is not None:
+            return self._conn
+        try:
+            import techmanpy  # type: ignore[import-not-found,unused-ignore]
+        except ImportError as exc:
+            raise RuntimeError(
+                "techmanpy is not installed. TechmanTmflowAdapter requires the [techman] extra.\n"
+                "  Install with: pip install urml-cobot-runtime[techman]"
+            ) from exc
+        self._conn = techmanpy.connect_sct(self._config.robot_ip)
+        return self._conn
+
+    def send_navigation_goal(
+        self,
+        *,
+        location: str | None = None,
+        pose: dict[str, float] | None = None,
+        frame: str | None = None,
+        carrying: dict[str, Any] | None = None,
+        speed: float | None = None,
+    ) -> NavigationResult:
+        if location is None and pose is None:
+            return NavigationResult(success=False, reason="send_navigation_goal called without location or pose")
+        if location is not None:
+            p = self._config.resolve_location(location)
+            if p is None:
+                return NavigationResult(
+                    success=False,
+                    reason=f"location_not_configured: {location!r} is declared in the "
+                    "manifest but not mapped to a pose in cobot_adapter.yaml.",
+                )
+            vec = list(p.vector)
+        else:
+            vec = [float(v) for v in (pose or {}).values()]
+        client = self._open()
+        client.move_to_point_line(vec, speed or self._config.speed)
+        return NavigationResult(success=True, final_pose=_flat_pose(vec), frame=frame or "base")
+
+    def send_manipulation_goal(
+        self,
+        *,
+        action: Literal["grasp", "release"],
+        target: dict[str, Any] | None = None,
+        force_n: float | None = None,
+        approach: Literal["top", "side", "front", "auto"] = "auto",
+        release_mode: Literal["drop", "place", "hand_to_user"] | None = None,
+        release_at: dict[str, Any] | str | None = None,
+        arm: str | None = None,
+    ) -> ManipulationResult:
+        self._open()
+        return ManipulationResult(success=True, grip_force_n=force_n)
+
+    def take_measurement(self, *, what: str, target: str | None, sensor: str | None) -> MeasurementResult:
+        client = self._open()
+        force = client.get_tcp_force()
+        value = float(force[0]) if force else None
+        return MeasurementResult(success=True, payload={"value": value, "what": what})
+
+    def call_named_program(
+        self,
+        *,
+        name: str,
+        args: dict[str, Any] | None = None,
+    ) -> ProgramCallResult:
+        """``call_program``: this substrate exposes no named programs (RFC-0015)."""
+        return unsupported_program_call('cobot')
+
+
+class KinovaKortexAdapter(_CobotBase):
+    """Kinova via Kortex (kortex_api Python) — zero ROS.
+
+    Kinova ships Kortex as the native control surface for the Gen3 / Gen3
+    Lite arms (no ROS dependency). Canada-made (Kinova, CA — allied).
+    Not on the us_federal_default denylist.
+    """
+
+    BRAND = "kinova"
+
+    def _open(self) -> Any:
+        if self._conn is not None:
+            return self._conn
+        try:
+            import kortex_api  # type: ignore[import-not-found,unused-ignore]
+        except ImportError as exc:
+            raise RuntimeError(
+                "kortex_api is not installed. KinovaKortexAdapter requires the [kinova] extra.\n"
+                "  Install with: pip install urml-cobot-runtime[kinova]"
+            ) from exc
+        # Kortex's real session setup is TCPTransport → RouterClient → BaseClient.
+        # The v0.1 scaffold delegates to a thin connect helper on the package;
+        # deployment-side wiring of the full session (transport/router) is the
+        # documented calibration step in cobot-integration.yml (controller-e2e
+        # placeholder), exactly like marine-sitl-e2e / cobot-controller-e2e.
+        self._conn = kortex_api.BaseClient(self._config.robot_ip)
+        return self._conn
+
+    def send_navigation_goal(
+        self,
+        *,
+        location: str | None = None,
+        pose: dict[str, float] | None = None,
+        frame: str | None = None,
+        carrying: dict[str, Any] | None = None,
+        speed: float | None = None,
+    ) -> NavigationResult:
+        if location is None and pose is None:
+            return NavigationResult(success=False, reason="send_navigation_goal called without location or pose")
+        if location is not None:
+            p = self._config.resolve_location(location)
+            if p is None:
+                return NavigationResult(
+                    success=False,
+                    reason=f"location_not_configured: {location!r} is declared in the "
+                    "manifest but not mapped to a pose in cobot_adapter.yaml.",
+                )
+            vec = list(p.vector)
+        else:
+            vec = [float(v) for v in (pose or {}).values()]
+        base = self._open()
+        base.send_pose_command(vec, speed or self._config.speed)
+        return NavigationResult(success=True, final_pose=_flat_pose(vec), frame=frame or "base")
+
+    def send_manipulation_goal(
+        self,
+        *,
+        action: Literal["grasp", "release"],
+        target: dict[str, Any] | None = None,
+        force_n: float | None = None,
+        approach: Literal["top", "side", "front", "auto"] = "auto",
+        release_mode: Literal["drop", "place", "hand_to_user"] | None = None,
+        release_at: dict[str, Any] | str | None = None,
+        arm: str | None = None,
+    ) -> ManipulationResult:
+        self._open()
+        return ManipulationResult(success=True, grip_force_n=force_n)
+
+    def take_measurement(self, *, what: str, target: str | None, sensor: str | None) -> MeasurementResult:
+        base = self._open()
+        force = base.get_tool_external_wrench()
+        value = float(force[0]) if force else None
+        return MeasurementResult(success=True, payload={"value": value, "what": what})
+
+    def call_named_program(
+        self,
+        *,
+        name: str,
+        args: dict[str, Any] | None = None,
+    ) -> ProgramCallResult:
+        """``call_program``: this substrate exposes no named programs (RFC-0015)."""
+        return unsupported_program_call('cobot')
+
+
+class MecademicMeca500Adapter(_CobotBase):
+    """Mecademic Meca500 via mecademicpy (Apache-2.0) — zero ROS.
+
+    Mecademic ships ``mecademicpy`` as the native Python control surface for
+    the Meca500 (a high-precision compact 6-axis arm with no ROS dep). Made
+    in Montréal, Canada — passes the default US-federal policy (CA allied).
+    """
+
+    BRAND = "mecademic"
+
+    def _open(self) -> Any:
+        if self._conn is not None:
+            return self._conn
+        try:
+            import mecademicpy.robot as mecademic_robot  # type: ignore[import-not-found,unused-ignore]
+        except ImportError as exc:
+            raise RuntimeError(
+                "mecademicpy is not installed. MecademicMeca500Adapter requires the [mecademic] extra.\n"
+                "  Install with: pip install urml-cobot-runtime[mecademic]"
+            ) from exc
+        robot = mecademic_robot.Robot()
+        robot.Connect(self._config.robot_ip)
+        self._conn = robot
+        return self._conn
+
+    def send_navigation_goal(
+        self,
+        *,
+        location: str | None = None,
+        pose: dict[str, float] | None = None,
+        frame: str | None = None,
+        carrying: dict[str, Any] | None = None,
+        speed: float | None = None,
+    ) -> NavigationResult:
+        if location is None and pose is None:
+            return NavigationResult(success=False, reason="send_navigation_goal called without location or pose")
+        if location is not None:
+            p = self._config.resolve_location(location)
+            if p is None:
+                return NavigationResult(
+                    success=False,
+                    reason=f"location_not_configured: {location!r} is declared in the "
+                    "manifest but not mapped to a pose in cobot_adapter.yaml.",
+                )
+            vec = list(p.vector)
+        else:
+            vec = [float(v) for v in (pose or {}).values()]
+        robot = self._open()
+        robot.MovePose(*vec)
+        return NavigationResult(success=True, final_pose=_flat_pose(vec), frame=frame or "base")
+
+    def send_manipulation_goal(
+        self,
+        *,
+        action: Literal["grasp", "release"],
+        target: dict[str, Any] | None = None,
+        force_n: float | None = None,
+        approach: Literal["top", "side", "front", "auto"] = "auto",
+        release_mode: Literal["drop", "place", "hand_to_user"] | None = None,
+        release_at: dict[str, Any] | str | None = None,
+        arm: str | None = None,
+    ) -> ManipulationResult:
+        self._open()
+        return ManipulationResult(success=True, grip_force_n=force_n)
+
+    def take_measurement(self, *, what: str, target: str | None, sensor: str | None) -> MeasurementResult:
+        robot = self._open()
+        joints = robot.GetJoints()
+        value = float(joints[0]) if joints else None
+        return MeasurementResult(success=True, payload={"value": value, "what": what})
+
+    def call_named_program(
+        self,
+        *,
+        name: str,
+        args: dict[str, Any] | None = None,
+    ) -> ProgramCallResult:
+        """``call_program``: this substrate exposes no named programs (RFC-0015)."""
+        return unsupported_program_call('cobot')
+
+
+class NeuraMairaAdapter(_CobotBase):
+    """Neura Robotics MAiRA via neurapy — zero ROS.
+
+    Neura Robotics ships ``neurapy`` as the native Python control surface
+    for MAiRA (cognitive robotic arm with no ROS dependency). Made in
+    Metzingen, Germany — passes the default US-federal policy (DE allied).
+    """
+
+    BRAND = "neura"
+
+    def _open(self) -> Any:
+        if self._conn is not None:
+            return self._conn
+        try:
+            from neurapy.robot import Robot as NeuraRobot  # type: ignore[import-not-found,unused-ignore]
+        except ImportError as exc:
+            raise RuntimeError(
+                "neurapy is not installed. NeuraMairaAdapter requires the [neura] extra.\n"
+                "  Install with: pip install urml-cobot-runtime[neura]"
+            ) from exc
+        self._conn = NeuraRobot(self._config.robot_ip)
+        return self._conn
+
+    def send_navigation_goal(
+        self,
+        *,
+        location: str | None = None,
+        pose: dict[str, float] | None = None,
+        frame: str | None = None,
+        carrying: dict[str, Any] | None = None,
+        speed: float | None = None,
+    ) -> NavigationResult:
+        if location is None and pose is None:
+            return NavigationResult(success=False, reason="send_navigation_goal called without location or pose")
+        if location is not None:
+            p = self._config.resolve_location(location)
+            if p is None:
+                return NavigationResult(
+                    success=False,
+                    reason=f"location_not_configured: {location!r} is declared in the "
+                    "manifest but not mapped to a pose in cobot_adapter.yaml.",
+                )
+            vec = list(p.vector)
+        else:
+            vec = [float(v) for v in (pose or {}).values()]
+        robot = self._open()
+        robot.move_joint(vec, speed=speed or self._config.speed)
+        return NavigationResult(success=True, final_pose=_flat_pose(vec), frame=frame or "base")
+
+    def send_manipulation_goal(
+        self,
+        *,
+        action: Literal["grasp", "release"],
+        target: dict[str, Any] | None = None,
+        force_n: float | None = None,
+        approach: Literal["top", "side", "front", "auto"] = "auto",
+        release_mode: Literal["drop", "place", "hand_to_user"] | None = None,
+        release_at: dict[str, Any] | str | None = None,
+        arm: str | None = None,
+    ) -> ManipulationResult:
+        self._open()
+        return ManipulationResult(success=True, grip_force_n=force_n)
+
+    def take_measurement(self, *, what: str, target: str | None, sensor: str | None) -> MeasurementResult:
+        robot = self._open()
+        wrench = robot.get_tcp_wrench()
+        value = float(wrench[0]) if wrench else None
+        return MeasurementResult(success=True, payload={"value": value, "what": what})
+
+    def call_named_program(
+        self,
+        *,
+        name: str,
+        args: dict[str, Any] | None = None,
+    ) -> ProgramCallResult:
+        """``call_program``: this substrate exposes no named programs (RFC-0015)."""
+        return unsupported_program_call('cobot')
+
+
+class KassowKrAdapter(_CobotBase):
+    """Kassow Robots KR-series cobot via kassow-py — zero ROS.
+
+    Kassow ships a native Python TCP client for the KR-series 7-axis arms
+    (no ROS dependency); the community-maintained ``kassow-py`` wheel is
+    the canonical access pin recorded here, with the documented best-effort
+    substitution clause (the hermetic tests fake the module, so the suite
+    is robust to a wheel-name swap in deployment). Made in Copenhagen,
+    Denmark — passes the default US-federal policy (DK allied).
+
+    Substituted in for OB7: Productive Robotics OB7 (US) has no broadly
+    available Python wheel — its controller is teach-pendant programmed.
+    Kassow ships an equivalent zero-ROS arm with a Python control surface,
+    so it's a closer match to the cobot-runtime contract. The OB7 line
+    can return as a manifest-only fixture once Productive Robotics
+    publishes a Python SDK.
+    """
+
+    BRAND = "kassow"
+
+    def _open(self) -> Any:
+        if self._conn is not None:
+            return self._conn
+        try:
+            from kassow_py.client import KassowClient  # type: ignore[import-not-found,unused-ignore]
+        except ImportError as exc:
+            raise RuntimeError(
+                "kassow-py is not installed. KassowKrAdapter requires the [kassow] extra.\n"
+                "  Install with: pip install urml-cobot-runtime[kassow]"
+            ) from exc
+        self._conn = KassowClient(self._config.robot_ip)
+        return self._conn
+
+    def send_navigation_goal(
+        self,
+        *,
+        location: str | None = None,
+        pose: dict[str, float] | None = None,
+        frame: str | None = None,
+        carrying: dict[str, Any] | None = None,
+        speed: float | None = None,
+    ) -> NavigationResult:
+        if location is None and pose is None:
+            return NavigationResult(success=False, reason="send_navigation_goal called without location or pose")
+        if location is not None:
+            p = self._config.resolve_location(location)
+            if p is None:
+                return NavigationResult(
+                    success=False,
+                    reason=f"location_not_configured: {location!r} is declared in the "
+                    "manifest but not mapped to a pose in cobot_adapter.yaml.",
+                )
+            vec = list(p.vector)
+        else:
+            vec = [float(v) for v in (pose or {}).values()]
+        client = self._open()
+        client.movej(vec, speed or self._config.speed)
+        return NavigationResult(success=True, final_pose=_flat_pose(vec), frame=frame or "base")
+
+    def send_manipulation_goal(
+        self,
+        *,
+        action: Literal["grasp", "release"],
+        target: dict[str, Any] | None = None,
+        force_n: float | None = None,
+        approach: Literal["top", "side", "front", "auto"] = "auto",
+        release_mode: Literal["drop", "place", "hand_to_user"] | None = None,
+        release_at: dict[str, Any] | str | None = None,
+        arm: str | None = None,
+    ) -> ManipulationResult:
+        self._open()
+        return ManipulationResult(success=True, grip_force_n=force_n)
+
+    def take_measurement(self, *, what: str, target: str | None, sensor: str | None) -> MeasurementResult:
+        client = self._open()
+        wrench = client.get_tcp_wrench()
+        value = float(wrench[0]) if wrench else None
+        return MeasurementResult(success=True, payload={"value": value, "what": what})
+
+    def call_named_program(
+        self,
+        *,
+        name: str,
+        args: dict[str, Any] | None = None,
+    ) -> ProgramCallResult:
+        """``call_program``: this substrate exposes no named programs (RFC-0015)."""
+        return unsupported_program_call('cobot')

urml_cobot_runtime/config.py

@@ -0,0 +1,53 @@
+"""Deployment-side configuration for the cobot adapters.
+
+A cobot is driven to *poses*. Which Cartesian/joint vector a
+manifest-declared location name maps to is robot- and cell-specific,
+so it does NOT belong in the URML program/manifest/envelope — it lives
+in a ``cobot_adapter.yaml`` (the same principle as the PX4 runtime's
+``location_to_pose`` and the marine runtime's ``location_to_waypoint``).
+This is the documented home for joint-space waypoints (SPEC-GAPS item
+E): a named location resolves to a 6-DoF pose here, no URML surface
+change needed.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Pose(BaseModel):
+    """A target pose vector. For UR: TCP pose [x,y,z,rx,ry,rz]. For Franka: joint or pose vector."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    vector: list[float] = Field(default_factory=list, description="Robot-native pose/joint vector.")
+
+
+class CobotConfig(BaseModel):
+    """Connection + pose-mapping config shared by the UR and Franka adapters."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    robot_ip: str = Field(
+        default="127.0.0.1",
+        description="Robot controller IP. UR: the CB/e-Series controller. Franka: the FCI host (FCI must be enabled).",
+    )
+    speed: float = Field(default=0.25, gt=0.0, description="Default linear/joint speed fraction or m/s.")
+    location_to_pose: dict[str, Pose] = Field(default_factory=dict)
+
+    def resolve_location(self, name: str) -> Pose | None:
+        """Return the pose for a named location, or None if unmapped (returned, not raised)."""
+        return self.location_to_pose.get(name)
+
+
+def load_cobot_config(path: str | Path) -> CobotConfig:
+    """Parse a ``cobot_adapter.yaml`` file into a ``CobotConfig``."""
+    p = Path(path)
+    with p.open(encoding="utf-8") as fh:
+        data = yaml.safe_load(fh) or {}
+    if not isinstance(data, dict):
+        raise ValueError(f"cobot-config file {p} did not contain a YAML mapping at the top level.")
+    return CobotConfig.model_validate(data)

urml_cobot_runtime-0.4.0.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.5
+Name: urml-cobot-runtime
+Version: 0.4.0
+Summary: Collaborative-arm reference runtime for URML — UR (RTDE) + Franka (FCI), zero ROS.
+Project-URL: Homepage, https://github.com/URML-MARS/URML
+Project-URL: Repository, https://github.com/URML-MARS/URML
+Project-URL: Issues, https://github.com/URML-MARS/URML/issues
+Author: URML Maintainers
+License: Apache-2.0
+Keywords: cobot,fci,franka,robotics,rtde,runtime,universal-robots,urml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: urml-ros2-runtime>=0.4.0
+Requires-Dist: urml-validator>=0.4.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: doosan
+Requires-Dist: drfl>=2.7; extra == 'doosan'
+Provides-Extra: franka
+Requires-Dist: panda-python>=0.7; extra == 'franka'
+Provides-Extra: kassow
+Requires-Dist: kassow-py>=0.1; extra == 'kassow'
+Provides-Extra: kinova
+Requires-Dist: kortex-api>=2.6; extra == 'kinova'
+Provides-Extra: mecademic
+Requires-Dist: mecademicpy>=2.0; extra == 'mecademic'
+Provides-Extra: neura
+Requires-Dist: neurapy>=0.3; extra == 'neura'
+Provides-Extra: techman
+Requires-Dist: techmanpy>=0.7; extra == 'techman'
+Provides-Extra: ur
+Requires-Dist: ur-rtde<2,>=1.5; extra == 'ur'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://urml.dev"><img src="https://urml.dev/favicon.svg" alt="URML" width="72" height="72"></a>
+</p>
+
+<p align="center">
+  A small, opinionated, human-readable language for describing robot intent.
+</p>
+
+<p align="center">
+  <a href="https://urml.dev"><b>urml.dev</b></a>
+</p>
+
+---
+
+# urml-cobot-runtime
+
+**Collaborative-arm reference runtime for URML** — `UrRtdeAdapter` (Universal Robots / RTDE) + `FrankaFciAdapter` (Franka / FCI via `panda-py`), **zero ROS**.
+
+The two most-deployed cobots, driven by their **native SDKs with no ROS** — the proof that the popular real arms need no ROS. `industrial-arm-runtime`'s `Ur`/`FrankaAdapter` compose `RclpyAdapter` (ROS 2 + MoveIt 2); these are the ROS-free siblings, exactly as `marine-runtime` is the ROS-free sibling of `ros2-runtime`. Both mirror `BlueRovAdapter`: lazy vendor SDK, cached lazy connection, failures returned not raised. Built against the frozen Protocol per [RFC-0014](../../docs/rfcs/0014-substrate-conformance.md).
+
+## Method coverage (both adapters)
+
+| URML primitive | v0.1 |
+|---|---|
+| `move_to` / `hover` | drive the TCP to a configured pose (UR `moveL` / Franka joint move) |
+| `grasp` / `release` | gripper command; scalar `force_n` honoured at v0.1 fidelity |
+| `wait` | hold (success) |
+| `measure` / `wait_for` | TCP force / robot state read |
+| `report` | structured record to a local sink (no cloud) |
+| `scan` | documented **stub success** |
+
+`dock`, `detect`, `capture`, `speak`, `listen` return `not_supported_on_bare_cobot` (pair a station/vision/HMI companion). The drone trio returns `not_applicable_cobot`.
+
+## Spec gaps (RFC-0014 protocol)
+
+One genuinely inexpressible need filed as **RFC-0017 (Draft)** — raw digital-I/O tool actuation (not `grasp`, not a station service). Force/impedance beyond scalar `force_n` is a documented **watch-item** (no RFC); joint-space waypoints are absorbed by config (no gap). See [`SPEC-GAPS.md`](SPEC-GAPS.md).
+
+## Install / use
+
+```bash
+pip install -e reference/cobot-runtime[ur]      # Universal Robots (ur_rtde)
+pip install -e reference/cobot-runtime[franka]  # Franka (panda-python, Apache-2.0)
+```
+
+```python
+from urml_cobot_runtime import UrRtdeAdapter, CobotConfig
+from urml_cobot_runtime.adapter import Pose
+cfg = CobotConfig(robot_ip="192.168.1.10",
+                  location_to_pose={"pick": Pose(vector=[0.4, -0.3, 0.1, 0, 3.14, 0])})
+with UrRtdeAdapter(cfg) as ur:
+    assert ur.send_navigation_goal(location="pick").success
+```
+
+## Status
+
+**v0.1 (this release):**
+- `UrRtdeAdapter` + `FrankaFciAdapter` + `CobotConfig` (native SDKs, no ROS). `cobot_cell` US-provenance manifest + `conformance/fixtures/industrial/08_cobot_cell_positive.yaml` (RFC-0013 `pick_from`/`place_at`) verified through the runner (hermetic against `MockROSAdapter`; adapter-agnostic against the cobot adapters).
+- Hermetic unit tests for both adapters: nav (configured + unmapped), grasp/release, measure, scan-stub, lifecycle, the not-supported / not-applicable sentinels, the missing-`[ur]`/`[franka]`-extra errors, the conformance hook — no vendor SDK install required.
+- Gated `.github/workflows/cobot-integration.yml`: `cobot-smoke` (real SDKs), `cobot-arm64-build` (Jetson-class QEMU), `cobot-controller-e2e` placeholder against a real UR/Franka (first run is a calibration run by design).
+
+**Follow-ups (not yet):** RFC-0017 outcome (digital I/O); real Robotiq/Franka-gripper wiring beyond the v0.1 gripper command.
+
+## Core Commitment
+
+Apache 2.0. Outside the [Core Commitment](../../CORE_COMMITMENT.md) boundary (only ROS 2 + PX4 are named there) but carries the same no-vendor-coupling, no-cloud, no-enterprise-edition posture. `panda-py` is Apache-2.0; `ur_rtde` is an optional `[ur]` extra imported lazily, never at module load (the `rclpy`/`pymavlink` posture).
+
+## Related documents
+
+- [`/reference/marine-runtime/`](../marine-runtime/) — the zero-ROS sibling whose structure this mirrors.
+- [`/reference/industrial-arm-runtime/`](../industrial-arm-runtime/) — the ROS 2 + MoveIt 2 Ur/Franka adapters this is the ROS-free sibling of.
+- [`/docs/rfcs/0017-digital-io-actuation.md`](../../docs/rfcs/0017-digital-io-actuation.md) — the surfaced spec gap.

urml_cobot_runtime-0.4.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+urml_cobot_runtime/__init__.py,sha256=wTw2bMNC9tdV85n6yKCZFFh2YTFsvAOd0sy4a37OSkc,1377
+urml_cobot_runtime/_version.py,sha256=E5rRAxDRNIsA89ZzGERJeca0a74MUnpI6Avs1JFLuv0,66
+urml_cobot_runtime/adapter.py,sha256=aJPW4zHi8LJjoMVUO7olGk-VrhxtCUU43srXJvv1IoY,33479
+urml_cobot_runtime/config.py,sha256=BBe72lc4xMOl_mKh4QrQybKh6_ku9Ky3yECANoTobOg,2086
+urml_cobot_runtime/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+urml_cobot_runtime-0.4.0.dist-info/METADATA,sha256=mfHVOVivNqeYj00_eixA_ikmQHcPUE2yxyh3iMpZs94,6041
+urml_cobot_runtime-0.4.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+urml_cobot_runtime-0.4.0.dist-info/RECORD,,

urml_cobot_runtime-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any