roboapi 0.4.2__py3-none-any.whl

roboapi/cli.py

@@ -0,0 +1,215 @@
+"""Command-line boot, serving and shutdown lifecycle."""
+
+from __future__ import annotations
+
+import atexit
+from contextlib import contextmanager
+from dataclasses import dataclass
+import json
+import logging
+from pathlib import Path
+import signal
+import sys
+import threading
+import time
+from typing import Annotated, Literal
+
+import tyro
+from tyro.extras import SubcommandApp
+
+from . import config
+from .runtime import Runtime, build
+from .mcp import make_server
+
+logger = logging.getLogger(__name__)
+app = SubcommandApp()
+_shutdown = lambda: None
+
+
+@tyro.conf.configure(tyro.conf.OmitArgPrefixes, tyro.conf.DisallowNone)
+@dataclass(frozen=True)
+class Options:
+    config: Annotated[Path | None, tyro.conf.arg(
+        aliases=["-c"], metavar="PATH", help="Installation YAML.",
+        help_behavior_hint=f"(default: {config.DEFAULT_CONFIG})",
+    )] = None
+    verbose: Annotated[bool, tyro.conf.arg(aliases=["-v"])] = False
+    """Enable debug logging."""
+
+
+def _configure(options: Options) -> None:
+    logging.basicConfig(
+        level=logging.DEBUG if options.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+    sys.setswitchinterval(0.0005)
+
+
+def _boot(options: Options) -> Runtime:
+    global _shutdown
+    _configure(options)
+    try:
+        cfg = config.load(options.config)
+        runner = build(cfg, config_path=options.config or config.DEFAULT_CONFIG)
+    except (OSError, ValueError, TypeError, RuntimeError) as exc:
+        raise SystemExit(f"Startup failed: {exc}") from None
+    done = threading.Event()
+
+    def shutdown(*_):
+        if done.is_set():
+            return
+        done.set()
+        runner.close()
+
+    _shutdown = shutdown
+    atexit.register(shutdown)
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        signal.signal(sig, lambda *_: (shutdown(), sys.exit(0)))
+    state = runner.preview()
+    logger.info("read-only preview: arm=%s, camera=%s; enable control explicitly after calibration",
+                "connected" if state["arm_connected"] else "unavailable",
+                "connected" if state["camera_connected"] else "unavailable")
+    return runner
+
+
+@contextmanager
+def _runtime(options: Options, *, control: bool = False):
+    runner = _boot(options)
+    try:
+        if control:
+            runner.calibration.action("enable_control", {
+                "confirmed": True, "initialization_confirmed": True,
+            })
+        yield runner
+    except (OSError, ValueError, TypeError, RuntimeError) as exc:
+        raise SystemExit(f"Operation failed: {exc}") from None
+    finally:
+        _shutdown()
+
+
+@app.command
+def init(common: Options = Options()) -> int:
+    """Create local installation configuration interactively."""
+    from .initialize import initialize
+
+    _configure(common)
+    try:
+        return initialize(common.config or config.DEFAULT_CONFIG)
+    except (EOFError, KeyboardInterrupt):
+        print("\nInitialization cancelled.", file=sys.stderr)
+        return 1
+    except (OSError, ValueError) as exc:
+        raise SystemExit(f"Initialization failed: {exc}") from None
+
+
+@app.command(is_default=True)
+def serve(common: Options = Options(),
+          transport: Literal["stdio", "streamable-http", "sse"] = "stdio") -> int:
+    """Run the MCP server."""
+    return _serve(common, transport)
+
+
+@app.command
+def export_franka_tool(output: Path = Path("endeffector-config.json")) -> int:
+    """Export the standard Franka load and flange-centre TCP for import in legacy Desk."""
+    from .hardware.franka.desk import export_tool_configuration
+
+    try:
+        print(export_tool_configuration(output))
+    except (OSError, ValueError, TypeError, RuntimeError) as exc:
+        raise SystemExit(f"Tool export failed: {exc}") from None
+    return 0
+
+
+@app.command
+def http(common: Options = Options(), with_mcp: bool = False,
+         transport: Literal["streamable-http", "sse"] = "streamable-http") -> int:
+    """Run the browser interface and HTTP API.
+
+    Args:
+        with_mcp: Also expose MCP on the same runtime.
+        transport: Network MCP transport when --with-mcp is enabled.
+    """
+    return _serve(common, transport if with_mcp else None, browser=True)
+
+
+@app.command
+def state(common: Options = Options()) -> int:
+    """Print installation and runtime status without enabling control."""
+    with _runtime(common) as runner:
+        observation, _ = runner.observation(with_image=False)
+        print(json.dumps(observation, indent=2))
+    return 0
+
+
+@app.command
+def reset(common: Options = Options()) -> int:
+    """Connect control, open the gripper, return Home and disconnect devices."""
+    with _runtime(common, control=True) as runner:
+        print(json.dumps(runner.reset(), indent=2))
+    return 0
+
+
+@app.command
+def smoke(common: Options = Options()) -> int:
+    """Run a real-hardware smoke test; stay next to the robot."""
+    with _runtime(common, control=True) as runner:
+        emb = runner.emb
+        emb.require_control()
+        print("state     :", json.dumps(emb.get_state(), indent=2))
+        image, age = emb.get_camera()
+        print(f"camera    : {image.shape} age={age * 1e3:.0f}ms")
+        print("gripper   : closing to 0.2 ...")
+        emb.gripper.move_blocking(0.2)
+        print(f"            -> {emb.gripper.get_ratio():.3f}")
+        print("gripper   : opening to 1.0 ...")
+        emb.gripper.move_blocking(1.0)
+        print(f"            -> {emb.gripper.get_ratio():.3f}")
+        print("reset     :", json.dumps(runner.reset(), indent=2))
+        print("alive     :", emb.alive, emb.last_error or "")
+        return 0 if emb.alive else 1
+
+
+def _serve(options: Options, transport: str | None, *, browser: bool = False) -> int:
+    runner = _boot(options)
+    cfg = runner.emb.cfg
+    web = None
+    try:
+        if cfg.web.enabled or browser:
+            from .web import start_web
+            web = start_web(runner, cfg.web)
+        if transport is None:
+            while True:
+                time.sleep(0.5)
+        else:
+            server = make_server(runner)
+            net = {} if transport == "stdio" else {"host": cfg.server.host, "port": cfg.server.port}
+            if transport != "stdio" and cfg.server.allowed_hosts:
+                from mcp.server.transport_security import TransportSecuritySettings
+
+                net["transport_security"] = TransportSecuritySettings(
+                    enable_dns_rebinding_protection=True,
+                    allowed_hosts=cfg.server.allowed_hosts,
+                )
+            thread = threading.Thread(
+                target=server.run,
+                kwargs={"transport": transport, **net},
+                name="mcp-serve",
+                daemon=True,
+            )
+            thread.start()
+            while thread.is_alive():
+                thread.join(0.5)
+    except (OSError, ValueError, TypeError, RuntimeError) as exc:
+        raise SystemExit(f"Server failed: {exc}") from None
+    finally:
+        _shutdown()
+        if web is not None:
+            web.shutdown()
+            web.server_close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(app.cli())

roboapi/config/__init__.py

@@ -0,0 +1,22 @@
+"""Public configuration API."""
+
+from .loader import DEFAULT_CONFIG, load, save
+from .models import (
+    ArmConfig,
+    CalibrationConfig,
+    CameraConfig,
+    Config,
+    GripperConfig,
+    PolicyConfig,
+    RuntimeConfig,
+    ServerConfig,
+    WebConfig,
+    WorkspaceConfig,
+)
+
+__all__ = [
+    "ArmConfig", "CalibrationConfig", "CameraConfig", "Config",
+    "GripperConfig",
+    "PolicyConfig", "RuntimeConfig", "ServerConfig",
+    "WebConfig", "WorkspaceConfig", "DEFAULT_CONFIG", "load", "save",
+]

roboapi/config/loader.py

@@ -0,0 +1,119 @@
+"""Load and save the local installation configuration."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, fields, is_dataclass
+import os
+from pathlib import Path
+import shlex
+import tempfile
+from typing import Any, get_type_hints
+
+import yaml
+
+from .models import Config
+
+
+DEFAULT_CONFIG = "~/.config/roboapi/config.yaml"
+
+
+def _build(cls: type, data: Any) -> Any:
+    """Construct nested dataclasses; their constructors reject unknown keys."""
+    if not is_dataclass(cls) or data is None:
+        return data
+    if not isinstance(data, dict):
+        raise TypeError(f"{cls.__name__} expects a mapping, got {type(data).__name__}")
+    kinds = get_type_hints(cls)
+    kwargs = {}
+    for key, value in data.items():
+        if key not in kinds:
+            raise TypeError(f"{cls.__name__} got an unexpected key {key!r}")
+        target = kinds[key]
+        kwargs[key] = _build(target, value) if is_dataclass(target) else value
+    return cls(**kwargs)
+
+
+def load(path: str | Path | None = None) -> Config:
+    """Load the local installation, using the standard path when none is supplied."""
+    target = Path(path if path is not None else DEFAULT_CONFIG).expanduser()
+    try:
+        raw = yaml.safe_load(target.read_text())
+    except FileNotFoundError:
+        command = "roboapi init" if path is None else f"roboapi init --config {shlex.quote(str(target))}"
+        raise FileNotFoundError(f"Installation configuration not found: {target}. Run {command}.") from None
+    except yaml.YAMLError as exc:
+        raise ValueError(f"Invalid installation configuration at {target}: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise TypeError("installation configuration must be a mapping")
+    arm_data = raw.get("arm", {})
+    if not isinstance(arm_data, dict):
+        raise TypeError(f"arm expects a mapping, got {type(arm_data).__name__}")
+    arm_type = arm_data.get("type")
+    if arm_type == "ur":
+        from ..hardware.ur.settings import SERIES
+
+        arm_cls = SERIES.get(arm_data.get("series"))
+        if arm_cls is None:
+            raise ValueError("arm.series must be cb3|e")
+    elif arm_type == "franka":
+        from ..hardware.franka.settings import FrankaArmConfig, ROBOT_MODELS
+
+        if arm_data.get("robot_model") not in ROBOT_MODELS:
+            raise ValueError("arm.robot_model must be panda|fr3")
+        arm_cls = FrankaArmConfig
+    else:
+        raise ValueError(f"arm.type must be ur|franka, got {arm_type!r}")
+    raw = dict(raw)
+    raw.pop("arm", None)
+    cfg = _build(Config, raw)
+    cfg.arm = _build(arm_cls, arm_data)
+    cfg.validate()
+    return cfg
+
+
+def _differences(values, defaults):
+    result = {}
+    for key, value in values.items():
+        if isinstance(value, dict):
+            value = _differences(value, defaults[key])
+            if value:
+                result[key] = value
+        elif value != defaults[key]:
+            result[key] = value
+    return result
+
+
+def _compact(cfg):
+    """Save installation choices; shared hardware defaults stay in their typed models."""
+    result = {}
+    for field in fields(cfg):
+        section = getattr(cfg, field.name)
+        changed = _differences(asdict(section), asdict(type(section)()))
+        if field.name == "arm":
+            changed["type"] = section.type
+            if section.type == "ur":
+                changed["series"] = section.series
+            else:
+                changed["robot_model"] = section.robot_model
+        if field.name == "runtime":
+            changed["inter_chunk_pause_s"] = section.inter_chunk_pause_s
+        if changed:
+            result[field.name] = changed
+    return result
+
+
+def save(cfg: Config, path: str | Path) -> None:
+    """Atomically replace the installation file, keeping credentials in separate files."""
+    cfg.validate()
+    target = Path(path).expanduser()
+    content = yaml.safe_dump(_compact(cfg), sort_keys=False)
+    target.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix=f".{target.name}.", dir=target.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as stream:
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, target)
+    finally:
+        Path(temporary).unlink(missing_ok=True)

roboapi/config/models.py

@@ -0,0 +1,191 @@
+"""Typed application and robot configuration models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import math
+
+from ..semantics import HOME_POSE7
+
+
+@dataclass
+class ArmConfig:
+    """Motion settings shared by every arm implementation."""
+
+    type: str = ""
+    home_gripper: float = 1.0  # 1.0 = open. Reset opens the gripper before returning Home.
+    # Peak speed of an agent-commanded Cartesian move.  Franka also uses the angular value as
+    # a hard cap on pose-feedback rotation, so a newly replaced direct target cannot bypass it.
+    cartesian_speed: float = 0.05  # m/s
+    cartesian_angular_speed: float = 0.4  # rad/s
+    # Corner radius of a waypoint path (robot_move_waypoints) when the waypoint does not say:
+    # the path cuts inside each corner by at most this and keeps moving through it.
+    blend_radius: float = 0.02  # m
+
+
+@dataclass
+class GripperConfig:
+    type: str = "modbus"  # modbus | urcap
+    # modbus: host serial device via USB/RS-485
+    port: str = "/dev/ttyUSB0"
+    slave_id: int = 9
+    baudrate: int = 115200
+    # urcap: UR controller socket; an empty ip reuses arm.ip for UR arms.
+    ip: str = ""
+    tcp_port: int = 63352
+    timeout_s: float = 1.0
+    speed: int = 255
+    force: int = 150
+    rate_hz: float = 100.0
+    # *** CALIBRATE ON REAL HARDWARE *** -- full-stroke travel time at `speed`. An
+    # agent-commanded gripper change is spread over a path at least this long, so the call does
+    # not return while the fingers are still moving.
+    full_travel_s: float = 1.0
+
+
+@dataclass
+class CameraConfig:
+    type: str = "v4l2"
+    device: str = "/dev/video0"
+    stale_after_s: float = 0.5  # a frozen camera makes `alive` false: the VLA would eat a stale frame
+
+
+@dataclass
+class PolicyConfig:
+    type: str = "openai"
+    url: str = ""
+    # Bearer token, read from a file so it never lands in the config -- or in git.
+    token_file: str = ""
+    model: str = ""  # required only by the OpenAI-compatible transport
+    timeout_s: float = 30.0
+    use_env_proxy: bool = True  # false bypasses HTTP(S)_PROXY and other environment proxy settings
+    # Resize before sending: preserve aspect ratio, set only the height, never crop or pad.
+    # Set to null only when the deployment owns preprocessing.
+    image_height: int | None = 360
+
+
+@dataclass
+class RuntimeConfig:
+    # Execute every returned action; chunk length is determined by the policy.
+    inter_chunk_pause_s: float = 0.5  # hold after a completed chunk, then sample fresh input
+    log_dir: str = "./logs"
+    save_images: bool = False
+
+    def validate(self) -> None:
+        pause = self.inter_chunk_pause_s
+        if isinstance(pause, bool) or not isinstance(pause, (int, float)) or not math.isfinite(pause) or pause < 0:
+            raise ValueError("runtime.inter_chunk_pause_s must be a non-negative finite value")
+
+
+@dataclass
+class ServerConfig:
+    host: str = "127.0.0.1"  # the MCP socket. The stdio transport has none and ignores this.
+    port: int = 8000
+    # Explicit public Host headers for a loopback server behind a LAN proxy.
+    # Empty keeps the SDK defaults; this is not a client-IP access list.
+    allowed_hosts: list[str] = field(default_factory=list)
+
+
+@dataclass
+class WebConfig:
+    enabled: bool = True
+    host: str = "127.0.0.1"
+    port: int = 8080
+
+
+@dataclass
+class CalibrationConfig:
+    """Startup frame calibration profile used by the policy/control boundary."""
+
+    profile_file: str = "~/.config/roboapi/calibration.json"
+    tool_id: str = "default"
+
+
+@dataclass
+class WorkspaceConfig:
+    """Soft limits for flange-centre targets in the training frame, in metres."""
+
+    enabled: bool = True
+    min_xyz_m: list[float] = field(default_factory=lambda: [-0.73, -1.06, -0.11])
+    max_xyz_m: list[float] = field(default_factory=lambda: [0.47, 0.14, 1.09])
+
+    def validate(self) -> None:
+        if not isinstance(self.enabled, bool):
+            raise ValueError("workspace.enabled must be a boolean")
+        for name in ("min_xyz_m", "max_xyz_m"):
+            values = getattr(self, name)
+            if (not isinstance(values, (list, tuple)) or len(values) != 3
+                    or any(isinstance(v, bool) or not isinstance(v, (int, float))
+                           or not math.isfinite(v) for v in values)):
+                raise ValueError(f"workspace.{name} must contain three finite numbers")
+        if any(lo >= hi for lo, hi in zip(self.min_xyz_m, self.max_xyz_m)):
+            raise ValueError("Workspace minimum must be below maximum on every axis")
+        if not self.contains(HOME_POSE7[:3]):
+            raise ValueError("Workspace must contain Home [-0.13, -0.46, 0.49] m")
+
+    def contains(self, xyz, *, atol=0.0) -> bool:
+        return all(lo - atol <= value <= hi + atol
+                   for lo, value, hi in zip(self.min_xyz_m, xyz, self.max_xyz_m))
+
+
+@dataclass
+class Config:
+    arm: ArmConfig = field(default_factory=ArmConfig)
+    gripper: GripperConfig = field(default_factory=GripperConfig)
+    camera: CameraConfig = field(default_factory=CameraConfig)
+    policy: PolicyConfig = field(default_factory=PolicyConfig)
+    runtime: RuntimeConfig = field(default_factory=RuntimeConfig)
+    server: ServerConfig = field(default_factory=ServerConfig)
+    web: WebConfig = field(default_factory=WebConfig)
+    calibration: CalibrationConfig = field(default_factory=CalibrationConfig)
+    workspace: WorkspaceConfig = field(default_factory=WorkspaceConfig)
+
+    def validate(self) -> None:
+        arm = self.arm
+        if arm.type not in ("ur", "franka"):
+            raise ValueError(f"arm.type must be ur|franka, got {arm.type!r}")
+        for name, value in (
+            ("cartesian_speed", arm.cartesian_speed),
+            ("cartesian_angular_speed", arm.cartesian_angular_speed),
+        ):
+            if not isinstance(value, (int, float)) or not 0.0 < value < float("inf"):
+                raise ValueError(f"arm.{name} must be a positive finite value")
+        if arm.type == "franka":
+            from ..hardware.franka.settings import FrankaArmConfig
+
+            if not isinstance(arm, FrankaArmConfig):
+                raise ValueError("arm.type=franka requires FrankaArmConfig")
+            arm.validate()
+        if arm.type == "ur":
+            from ..hardware.ur.settings import CB3ArmConfig, ESeriesArmConfig
+
+            if not isinstance(arm, (CB3ArmConfig, ESeriesArmConfig)):
+                raise ValueError("UR requires a CB3 or e-Series configuration")
+            arm.validate()
+        if self.gripper.type not in ("modbus", "urcap"):
+            raise ValueError(f"gripper.type must be modbus|urcap, got {self.gripper.type!r}")
+        if (self.gripper.type == "urcap" and not self.gripper.ip
+                and not (arm.type == "ur" and arm.ip)):
+            raise ValueError("gripper.type=urcap requires a UR controller address")
+        if self.camera.type != "v4l2":
+            raise ValueError(f"camera.type must be v4l2, got {self.camera.type!r}")
+        if self.policy.type != "openai":
+            raise ValueError(f"policy.type must be openai, got {self.policy.type!r}")
+        if self.policy.type == "openai":
+            if not self.policy.url:
+                raise ValueError(f"policy.type={self.policy.type} requires policy.url")
+            if not self.policy.token_file:
+                raise ValueError(f"policy.type={self.policy.type} requires policy.token_file")
+        if self.policy.type == "openai" and not self.policy.model:
+            raise ValueError("policy.type=openai requires policy.model")
+        if not isinstance(self.policy.use_env_proxy, bool):
+            raise ValueError("policy.use_env_proxy must be a boolean")
+        if self.policy.image_height is not None and self.policy.image_height < 1:
+            raise ValueError("policy.image_height must be >= 1 or null")
+        self.runtime.validate()
+        self.workspace.validate()
+        calibration = self.calibration
+        if not isinstance(calibration.profile_file, str) or not calibration.profile_file.strip():
+            raise ValueError("calibration.profile_file is required")
+        if not isinstance(calibration.tool_id, str) or not calibration.tool_id.strip():
+            raise ValueError("calibration.tool_id is required")