roboapi 0.4.2__py3-none-any.whl

roboapi/hardware/ur/native/worker.cpp

@@ -0,0 +1,147 @@
+// IPC adapter for the UR control runtime.
+#include "ur_cpp/control_loop.hpp"
+#include "ur_cpp/robot_io.hpp"
+#include <algorithm>
+#include <cerrno>
+#include <csignal>
+#include <iomanip>
+#include <iostream>
+#include <map>
+#include <sstream>
+#include <stdexcept>
+#include <sys/socket.h>
+#include <unistd.h>
+#include <vector>
+
+std::unique_ptr<RobotIO> openLiveRobotIo(const Args &, std::atomic<bool> &, std::string *);
+std::unique_ptr<RobotIO> openRobotIo(const Args &a, std::atomic<bool> &s, std::string *e) {
+  return openLiveRobotIo(a, s, e);
+}
+static volatile std::sig_atomic_t exiting = 0;
+static void onSignal(int) { exiting = 1; }
+
+static bool transfer(int fd, void *data, size_t size, bool sending) {
+  auto *p = static_cast<char *>(data);
+  while (size) {
+    const auto n = sending ? ::send(fd, p, size, MSG_NOSIGNAL) : ::recv(fd, p, size, 0);
+    if (n < 0 && errno == EINTR && !exiting) continue;
+    if (n <= 0) return false;
+    p += n;
+    size -= static_cast<size_t>(n);
+  }
+  return true;
+}
+static void reply(int fd, const Snapshot &s) {
+  std::array<double, 43> values{};
+  size_t i = 0;
+  for (const auto &v : {s.q_, s.qd_, s.tcp_, s.tcp_speed_, s.wrench_})
+    for (double x : v) values[i++] = x;
+  for (double x : {double(s.mode_), double(s.fault_), double(s.safety_mode_), double(s.ticks_),
+                   s.dt_mean_ms_, s.dt_std_ms_, s.dt_p99_ms_, s.dt_max_ms_, s.rtde_hz_,
+                   s.host_hz_, double(s.program_running_), double(s.loop_alive_), double(s.loop_ok_)})
+    values[i++] = x;
+  auto length = static_cast<uint32_t>(s.last_error_.size());
+  if (!transfer(fd, values.data(), sizeof(values), true) ||
+      !transfer(fd, &length, sizeof(length), true) ||
+      (length && !transfer(fd, const_cast<char *>(s.last_error_.data()), length, true)))
+    throw std::runtime_error("UR IPC closed");
+}
+static std::vector<double> numbers(std::string text, size_t count) {
+  std::replace(text.begin(), text.end(), ',', ' ');
+  std::istringstream stream(text);
+  std::vector<double> values;
+  double x;
+  while (stream >> x) values.push_back(x);
+  if (!stream.eof() || values.size() != count)
+    throw std::invalid_argument("incorrect parameter vector size");
+  return values;
+}
+static void dumpArgs(const Args &a) {
+  std::cout << std::setprecision(17) << "{\"fastloop_freq\":" << a.freq_
+    << ",\"fastloop_rt_prio\":" << a.rt_prio_ << ",\"fastloop_pos_loop_kp\":" << a.pos_kp_
+    << ",\"fastloop_damping_ratio\":" << a.tun_.zeta_ << ",\"fastloop_filter_tau\":" << a.tun_.filter_tau_
+    << ",\"fastloop_wrench_notch\":" << a.tun_.notch_freq_ << ",\"fastloop_max_dt\":" << a.tun_.max_dt_
+    << ",\"fastloop_max_vel\":" << a.tun_.max_vel_ << ",\"fastloop_relaxation_hz\":" << a.tun_.relaxation_hz_;
+  const auto pair = [](const char *key, double x, double y) {
+    std::cout << ",\"" << key << "\":[" << x << ',' << y << ']';
+  };
+  pair("fastloop_mass", a.tun_.M_[0], a.tun_.M_[3]);
+  pair("fastloop_stiffness", a.tun_.K_[0], a.tun_.K_[3]);
+  pair("fastloop_hf_mass_ratio", a.tun_.hf_mass_ratio_[0], a.tun_.hf_mass_ratio_[3]);
+  pair("fastloop_wrench_deadband", a.tun_.deadband_force_, a.tun_.deadband_torque_);
+  pair("fastloop_cmd_vel_limit", a.cmd_vel_trans_, a.cmd_vel_rot_);
+  pair("fastloop_cmd_acc_limit", a.cmd_acc_trans_, a.cmd_acc_rot_);
+  pair("fastloop_speedl_acc_limit", a.speedl_acc_trans_, a.speedl_acc_rot_);
+  pair("fastloop_speedl_jerk_limit", a.speedl_jerk_trans_, a.speedl_jerk_rot_);
+  std::cout << "}\n";
+}
+int main(int argc, char **argv) {
+  std::signal(SIGINT, onSignal);
+  std::signal(SIGTERM, onSignal);
+  Args a;
+  int fd = -1;
+  bool checking = false, zero_on_start = true;
+  const std::map<std::string, double *> scalars{
+    {"fastloop_freq", &a.freq_},
+    {"fastloop_pos_loop_kp", &a.pos_kp_}, {"fastloop_damping_ratio", &a.tun_.zeta_},
+    {"fastloop_filter_tau", &a.tun_.filter_tau_}, {"fastloop_wrench_notch", &a.tun_.notch_freq_},
+    {"fastloop_max_dt", &a.tun_.max_dt_}, {"fastloop_max_vel", &a.tun_.max_vel_}, {"fastloop_relaxation_hz", &a.tun_.relaxation_hz_}};
+  const std::map<std::string, std::pair<double *, double *>> pairs{
+    {"fastloop_cmd_vel_limit", {&a.cmd_vel_trans_, &a.cmd_vel_rot_}},
+    {"fastloop_cmd_acc_limit", {&a.cmd_acc_trans_, &a.cmd_acc_rot_}},
+    {"fastloop_speedl_acc_limit", {&a.speedl_acc_trans_, &a.speedl_acc_rot_}},
+    {"fastloop_speedl_jerk_limit", {&a.speedl_jerk_trans_, &a.speedl_jerk_rot_}},
+    {"fastloop_wrench_deadband", {&a.tun_.deadband_force_, &a.tun_.deadband_torque_}}};
+  try {
+    for (int i = 1; i < argc; ++i) {
+      const std::string key = argv[i];
+      if (key == "--check-config") { checking = true; continue; }
+      if (i + 1 == argc || key.rfind("--", 0) != 0) throw std::invalid_argument("expected --parameter value");
+      const std::string name = key.substr(2), value = argv[++i];
+      if (name == "ip") a.robot_ip_ = value;
+      else if (name == "script") a.script_file_ = value;
+      else if (name == "ipc-fd") fd = std::stoi(value);
+      else if (name == "zero_ft_on_start") zero_on_start = numbers(value, 1)[0] != 0;
+      else if (name == "fastloop_rt_prio") a.rt_prio_ = static_cast<int>(numbers(value, 1)[0]);
+      else if (scalars.count(name)) *scalars.at(name) = numbers(value, 1)[0];
+      else if (pairs.count(name)) {
+        const auto v = numbers(value, 2);
+        *pairs.at(name).first = v[0]; *pairs.at(name).second = v[1];
+      } else if (name == "fastloop_mass" || name == "fastloop_stiffness" || name == "fastloop_hf_mass_ratio") {
+        const auto v = numbers(value, 2);
+        double *out = name == "fastloop_mass" ? a.tun_.M_ : name == "fastloop_stiffness" ? a.tun_.K_ : a.tun_.hf_mass_ratio_;
+        for (int k = 0; k < 6; ++k) out[k] = v[k < 3 ? 0 : 1];
+      } else throw std::invalid_argument("unknown UR driver parameter: " + name);
+    }
+    std::string error;
+    if (!validateArgs(a, error)) throw std::invalid_argument(error);
+    if (checking) { dumpArgs(a); return 0; }
+    if (fd < 0 || a.robot_ip_.empty() || a.script_file_.empty())
+      throw std::invalid_argument("IPC fd, robot address and URScript required");
+    ControlLoop loop(a);
+    loop.start();
+    const bool ready = loop.waitReady(12.0);
+    if (ready && zero_on_start) loop.zeroFt();
+    auto initial = loop.snapshot();
+    if (!ready && initial.last_error_.empty()) initial.last_error_ = "fastloop_start_failed";
+    reply(fd, initial);
+    while (ready && !exiting) {
+      uint8_t op;
+      if (!transfer(fd, &op, sizeof(op), false)) break;
+      vec6 target{};
+      if ((op == 'P' || op == 'C') && !transfer(fd, target.data(), sizeof(target), false)) break;
+      if (op == 'P' || op == 'C') loop.setPoseRef(target, op == 'P');
+      else if (op == 'H') loop.stopMotion();
+      else if (op == 'Z') loop.zeroFt();
+      else if (op == 'Q') { loop.requestStop(); reply(fd, loop.snapshot()); break; }
+      else if (op != 'S') throw std::invalid_argument("unknown IPC operation");
+      reply(fd, loop.snapshot());
+    }
+    loop.requestStop();
+    loop.join();
+  } catch (const std::exception &e) {
+    std::cerr << "[adapter] " << e.what() << '\n';
+    return 1;
+  }
+  return 0;
+}

roboapi/hardware/ur/position.py

@@ -0,0 +1,253 @@
+"""Position-only UR CB3 control using ur_rtde."""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+
+import numpy as np
+
+from ... import geometry as geo
+from .dashboard import Dashboard
+
+logger = logging.getLogger(__name__)
+
+NUM_JOINTS = 6
+
+
+_SAFETY_MODE_NAMES = {
+    1: "normal", 2: "reduced", 3: "protective_stop", 4: "recovery", 5: "safeguard_stop",
+    6: "system_emergency_stop", 7: "robot_emergency_stop", 8: "violation", 9: "fault",
+    10: "validate_joint_id", 11: "undefined", 12: "automatic_mode_safeguard_stop",
+    13: "system_three_position_enabling_stop",
+}
+_EXTERNAL_RESET_SAFETY_MODES = frozenset({4, 5, 6, 7, 12, 13})
+_FAULTED_SAFETY_MODES = frozenset({8, 9, 10, 11})
+_ROBOT_MODE_NAMES = {
+    -1: "no_controller", 0: "disconnected", 1: "confirm_safety", 2: "booting", 3: "power_off",
+    4: "power_on", 5: "idle", 6: "backdrive", 7: "running", 8: "updating_firmware",
+}
+
+
+class PositionArm:
+    """CB3 position control through a paced RTDE servoL stream."""
+
+    def __init__(self, cfg) -> None:
+        self.cfg = cfg
+        self._c = None
+        self._r = None
+        self._error: str | None = None
+        # One owner for vendor calls and targets; RTDEControlInterface is not thread-safe.
+        self._lock = threading.RLock()
+        self._target: np.ndarray | None = None
+        self._stop = threading.Event()
+        self._paused = threading.Event()  # held during controller recovery
+        self._thread: threading.Thread | None = None
+        self._period = 1.0 / float(cfg.servo_hz)
+        self._dashboard = Dashboard(cfg.ip)
+        self._version: tuple[int, int] | None = None
+
+    # -- connection --------------------------------------------------------
+    @property
+    def live(self) -> bool:
+        with self._lock:
+            if self._c is None or self._r is None or self._error is not None:
+                return False
+            try:
+                if not self._c.isConnected() or not self._r.isConnected():
+                    self._error = "rtde_disconnected"
+                elif not self._c.isProgramRunning():
+                    self._error = "control_script_stopped"
+            except Exception:
+                self._error = "rtde_disconnected"
+            return self._error is None
+
+    @property
+    def last_error(self) -> str | None:
+        return self._error
+
+    def _connect(self) -> None:
+        import rtde_control
+        import rtde_receive
+
+        self._version = self._dashboard.version()
+        if self._version[0] != 3:
+            raise ValueError("CB3 position control requires a PolyScope 3 controller")
+        self._c = rtde_control.RTDEControlInterface(self.cfg.ip)
+        # Receive follows the configured CB3 servo rate.
+        self._r = rtde_receive.RTDEReceiveInterface(self.cfg.ip, float(self.cfg.servo_hz))
+        self._error = None
+        if self._c.setWatchdog(self.cfg.watchdog_hz) is False:
+            raise RuntimeError("RTDE watchdog setup rejected")
+
+    def connect(self) -> None:
+        try:
+            with self._lock:
+                self._connect()
+        except Exception:
+            self._close()
+            raise
+        self._stop.clear()
+        self._thread = threading.Thread(target=self._servo_loop, name="ur-servo", daemon=True)
+        self._thread.start()
+
+    def disconnect(self) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+        self._close()
+
+    def _close(self) -> None:
+        with self._lock:
+            if self._c is not None:
+                try:
+                    self.hold()
+                except Exception:
+                    logger.warning("UR stop could not be confirmed during disconnect", exc_info=True)
+                try:
+                    if self._c.isConnected() and self._c.isProgramRunning():
+                        if self._c.stopScript() is False:
+                            logger.warning("UR control script stop rejected")
+                except Exception:
+                    logger.warning("UR control script stop could not be confirmed", exc_info=True)
+            for iface in (self._c, self._r):
+                try:
+                    if iface is not None:
+                        iface.disconnect()
+                except Exception:
+                    pass
+            self._c = self._r = None
+            self._target = None
+
+    # -- state -------------------------------------------------------------
+    def get_joints(self) -> np.ndarray:
+        return np.asarray(self._r.getActualQ(), dtype=np.float64)
+
+    def get_eef_pose(self) -> np.ndarray:
+        return geo.rotvec6_to_pose7(np.asarray(self._r.getActualTCPPose(), dtype=np.float64))
+
+    def get_tcp_offset(self) -> np.ndarray:
+        return np.asarray(self._c.getTCPOffset(), dtype=np.float64)
+
+    def get_tcp_speed(self) -> np.ndarray:
+        return np.asarray(self._r.getActualTCPSpeed(), dtype=np.float64)
+
+    # -- commands ----------------------------------------------------------
+    def servo_pose(self, pose7: np.ndarray, twist: np.ndarray | None = None, *, position_only=False) -> None:
+        del twist, position_only  # CB3 always uses position control.
+        p = np.asarray(pose7, dtype=np.float64)
+        if p.shape != (7,):
+            raise ValueError(f"servo_pose expects pose7d, got shape {p.shape}")
+        if not self.live:
+            raise RuntimeError(f"not_alive: {self._error}. Call recover().")
+        with self._lock:
+            if self._paused.is_set():
+                return  # Recovery owns the connection; do not queue a stale pose.
+            self._target = p.copy()
+
+    def hold(self) -> None:
+        """Stop the active servo and clear queued targets."""
+        with self._lock:
+            self._target = None
+            if self._c is None or not self._c.isConnected() or not self._c.isProgramRunning():
+                return
+            if self._c.servoStop() is False:
+                self._error = "servo_stop_rejected"
+                raise RuntimeError(self._error)
+
+    def _servo_loop(self) -> None:
+        """Latest Cartesian target to servoL, paced by absolute deadlines."""
+        next_at = time.monotonic()
+        while not self._stop.is_set():
+            next_at += self._period
+            time.sleep(max(0.0, next_at - time.monotonic()))
+            with self._lock:
+                if not self.live:
+                    continue
+                try:
+                    if self._paused.is_set() or self._target is None:
+                        if self._c.kickWatchdog() is False:
+                            raise RuntimeError("watchdog_rejected")
+                        continue
+                    target = self._target.copy()
+                    accepted = self._c.servoL(
+                        geo.pose7_to_rotvec6(target).tolist(), 1.0, 1.4, self._period,
+                        self.cfg.servo_lookahead_time, self.cfg.servo_gain,
+                    )
+                    if accepted is False:
+                        raise RuntimeError(self._rejection_reason())
+                except Exception as exc:
+                    self._error = f"servo_failed: {exc}"
+                    try:
+                        self.hold()
+                    except Exception:
+                        logger.warning("UR fault stop could not be confirmed", exc_info=True)
+
+    def _rejection_reason(self) -> str:
+        """Turn a rejected command into a name a person (or an LLM) can act on."""
+        try:
+            if not self._c.isConnected() or not self._r.isConnected():
+                return "rtde_disconnected"
+            safety = int(self._r.getSafetyMode())
+            name = _SAFETY_MODE_NAMES.get(safety, f"mode_{safety}")
+            if safety == 3:
+                return "protective_stop"
+            if safety in _EXTERNAL_RESET_SAFETY_MODES:
+                return f"external_reset_required:{name}"
+            if safety in _FAULTED_SAFETY_MODES:
+                return f"safety_fault:{name}"
+            robot_mode = int(self._r.getRobotMode())
+            if robot_mode != 7:
+                return f"robot_not_running:{_ROBOT_MODE_NAMES.get(robot_mode, robot_mode)}"
+            if int(self._r.getRobotStatus()) & 0b10 == 0:
+                return "control_script_stopped"
+        except Exception:
+            return "rtde_disconnected"
+        return "servo_rejected"
+
+    # -- recovery ----------------------------------------------------------
+    def recover(self, should_stop=None) -> None:
+        """Recover the controller and recreate its RTDE control connection."""
+        self._paused.set()
+        try:
+            self.hold()
+            deadline = time.monotonic() + 30.0
+            detail = "dashboard_error"
+            while time.monotonic() < deadline:
+                if should_stop is not None and should_stop():
+                    raise RuntimeError("UR recovery cancelled")
+                ready, detail = self._dashboard.step(should_stop=should_stop)
+                if detail == "motion_interrupted":
+                    raise RuntimeError("UR recovery cancelled")
+                if ready:
+                    break
+                if detail.startswith(("external_reset_required", "remote_control_required",
+                                      "confirm_safety_required", "unsupported_")):
+                    self._error = detail
+                    raise RuntimeError(
+                        f"{detail}: a person has to clear this at the robot -- roboapi cannot."
+                    )
+                time.sleep(2.0)
+            else:
+                self._error = detail
+                raise RuntimeError(f"recover timed out: {detail}")
+
+            # A Dashboard transition invalidates RTDE objects held from before the fault:
+            # both sides must be recreated, not reused.
+            with self._lock:
+                self._close()
+                self._connect()
+                if not self._c.isProgramRunning() and self._c.reuploadScript() is False:
+                    self._error = "control_script_reupload_rejected"
+                    raise RuntimeError(self._error)
+                if should_stop is not None and should_stop():
+                    self.hold()
+                    raise RuntimeError("UR recovery cancelled")
+            q = self.get_joints()
+            if q.shape != (NUM_JOINTS,) or not np.all(np.isfinite(q)):
+                self._error = "invalid_feedback"
+                raise RuntimeError(self._error)
+            self._error = None
+        finally:
+            self._paused.clear()

roboapi/hardware/ur/settings.py

@@ -0,0 +1,95 @@
+"""UR controller generations and their standard control settings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import math
+from pathlib import Path
+import sys
+
+from ...config.models import ArmConfig
+
+
+def _positive(name, value):
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value <= 0:
+        raise ValueError(f"arm.{name} must be positive and finite")
+
+
+@dataclass
+class URArmConfig(ArmConfig):
+    type: str = "ur"
+    ip: str = ""
+
+    def validate(self) -> None:
+        if not self.ip:
+            raise ValueError("arm.type=ur requires arm.ip")
+
+
+@dataclass
+class CB3ArmConfig(URArmConfig):
+    series: str = "cb3"
+    servo_hz: float = 100.0
+    servo_gain: float = 300.0
+    watchdog_hz: float = 2.0
+    servo_lookahead_time: float = 0.1
+
+    def validate(self) -> None:
+        super().validate()
+        if self.series != "cb3":
+            raise ValueError("CB3 configuration requires arm.series=cb3")
+        for name in ("servo_hz", "servo_gain", "servo_lookahead_time", "watchdog_hz"):
+            _positive(name, getattr(self, name))
+        if self.watchdog_hz >= self.servo_hz:
+            raise ValueError("arm.watchdog_hz must be below arm.servo_hz")
+
+
+@dataclass
+class ESeriesArmConfig(URArmConfig):
+    series: str = "e"
+    rate_hz: float = 125.0
+    zero_ft_on_start: bool = True
+    fastloop_freq: float = 500.0
+    fastloop_rt_prio: int = 0
+    fastloop_mass: list[float] = field(default_factory=lambda: [6.0, 0.075])
+    fastloop_stiffness: list[float] = field(default_factory=lambda: [400.0, 11.25])
+    fastloop_damping_ratio: float = 3.5
+    fastloop_hf_mass_ratio: list[float] = field(default_factory=lambda: [1.5, 2.0])
+    fastloop_relaxation_hz: float = 5.0
+    fastloop_filter_tau: float = 0.005
+    fastloop_wrench_deadband: list[float] = field(default_factory=lambda: [2.5, 0.075])
+    fastloop_wrench_notch: float = 0.0
+    fastloop_max_dt: float = 0.015
+    fastloop_max_vel: float = 0.35
+    fastloop_cmd_vel_limit: list[float] = field(default_factory=lambda: [1.0, 2.5])
+    fastloop_cmd_acc_limit: list[float] = field(default_factory=lambda: [3.0, 8.0])
+    fastloop_pos_loop_kp: float = 15.0
+    fastloop_speedl_acc_limit: list[float] = field(default_factory=lambda: [25.0, 30.0])
+    fastloop_speedl_jerk_limit: list[float] = field(default_factory=lambda: [2000.0, 2000.0])
+    fastloop_binary: str = field(default_factory=lambda: str(Path(sys.prefix) / "bin/roboapi-ur-loop"))
+    fastloop_script: str = field(default_factory=lambda: str(Path(sys.prefix) / "share/roboapi-ur-loop/external_control.urscript"))
+    fastloop_log_dir: str = "./logs/ur-native"
+    native_rpc_timeout_s: float = 0.5
+    native_state_stale_after_s: float = 0.25
+
+    def validate(self) -> None:
+        super().validate()
+        if self.series != "e":
+            raise ValueError("e-Series configuration requires arm.series=e")
+        _positive("rate_hz", self.rate_hz)
+        if not isinstance(self.zero_ft_on_start, bool):
+            raise ValueError("UR boolean parameters must be boolean")
+        # Native validateArgs owns the admissible ranges of the control-law tuning.
+        for name, count in (("fastloop_mass", 2), ("fastloop_stiffness", 2),
+                            ("fastloop_hf_mass_ratio", 2), ("fastloop_wrench_deadband", 2),
+                            ("fastloop_cmd_vel_limit", 2), ("fastloop_cmd_acc_limit", 2),
+                            ("fastloop_speedl_acc_limit", 2), ("fastloop_speedl_jerk_limit", 2)):
+            values = getattr(self, name)
+            if len(values) != count or not all(isinstance(x, (int, float)) and math.isfinite(x) for x in values):
+                raise ValueError(f"arm.{name} must contain {count} finite values")
+        for name in ("native_rpc_timeout_s", "native_state_stale_after_s"):
+            _positive(name, getattr(self, name))
+        if self.native_state_stale_after_s < 2.0 / self.rate_hz:
+            raise ValueError("native feedback freshness must allow at least two poll periods")
+
+
+SERIES = {"cb3": CB3ArmConfig, "e": ESeriesArmConfig}

roboapi/images.py

@@ -0,0 +1,16 @@
+"""Camera previews shared by the web and MCP interfaces."""
+
+import io
+
+import numpy as np
+from PIL import Image
+
+
+def preview_jpeg(image: np.ndarray, width: int = 640, quality: int = 75) -> bytes:
+    """Encode a small preview, preserving the camera's field of view and aspect ratio."""
+    preview = Image.fromarray(image)
+    if preview.width > width:
+        preview = preview.resize((width, preview.height * width // preview.width), Image.Resampling.BILINEAR)
+    buffer = io.BytesIO()
+    preview.save(buffer, format="JPEG", quality=quality)
+    return buffer.getvalue()

roboapi/initialize.py

@@ -0,0 +1,137 @@
+"""One-time interactive installation setup; saves configuration without contacting devices."""
+
+from __future__ import annotations
+
+from getpass import getpass
+from pathlib import Path
+import shlex
+
+from . import config
+from .config import DEFAULT_CONFIG
+from .hardware.franka.settings import FrankaArmConfig
+from .hardware.ur.settings import SERIES
+from .policy.settings import validate_policy_endpoint, write_policy_token
+
+
+def _ask(label, default=""):
+    while True:
+        value = input(f"{label}" + (f" [{default}]" if default else "") + ": ").strip()
+        if value or default:
+            return value or default
+        print("Enter a value.")
+
+
+def _choose(label, choices, default="1"):
+    print(label)
+    for index, choice in enumerate(choices, 1):
+        print(f"  {index}. {choice}")
+    while True:
+        value = _ask("Choose", default)
+        if value.isdigit() and 1 <= int(value) <= len(choices):
+            return int(value) - 1
+        print("Choose one of the listed numbers.")
+
+
+def _device(label, patterns, default):
+    devices = sorted({str(path) for pattern in patterns for path in Path("/dev").glob(pattern)})
+    if devices:
+        print(f"{label} devices:")
+        for index, device in enumerate(devices, 1):
+            print(f"  {index}. {device}")
+        while True:
+            value = _ask(f"{label} number or path", "1")
+            if not value.isdigit():
+                return value
+            if 1 <= int(value) <= len(devices):
+                return devices[int(value) - 1]
+            print("Choose a listed number or enter a device path.")
+    return _ask(f"{label} path", default)
+
+
+def _secret(label, path):
+    while True:
+        value = getpass(label + (" [Enter to keep saved value]" if path.is_file() else "") + ": ").strip()
+        if value:
+            return value
+        if path.is_file() and path.read_text().strip():
+            return None
+        print("Enter a value.")
+
+
+def initialize(path_text=DEFAULT_CONFIG):
+    path = Path(path_text).expanduser().resolve()
+    if path.exists() and input(f"Replace existing configuration at {path}? [y/N]: ").strip().lower() != "y":
+        print("Configuration kept.")
+        return 0
+    from .naming import PRODUCT_NAME
+    print(f"{PRODUCT_NAME} installation setup")
+    kind = _choose("Robot", ["UR CB3 (position control)", "UR e-Series (compliant control)",
+                             "Franka FR3", "Franka Panda (system software 4.2.1–4.x)"])
+    cfg = config.Config()
+    desk_password = None
+    if kind < 2:
+        print("Find the robot address in PolyScope's network settings.")
+        cfg.arm = SERIES["cb3" if kind == 0 else "e"](ip=_ask("Robot address"))
+        connection = _choose("Robotiq connection", ["Through the UR controller (URCap)",
+                                                  "Host serial port (USB / RS-485)"], default="")
+        cfg.gripper = (config.GripperConfig(type="urcap") if connection == 0
+                       else config.GripperConfig(type="modbus", rate_hz=30.0))
+    else:
+        print("Use the Control cabinet's Shop Floor network address shown in Desk settings.")
+        cfg.arm = FrankaArmConfig.for_model(
+            "fr3" if kind == 2 else "panda", host=_ask("Robot address"),
+        )
+        cfg.gripper = config.GripperConfig(type="modbus", rate_hz=30.0)
+    cfg.camera.type = "v4l2"
+    cfg.camera.device = _device("Wrist camera", ["v4l/by-id/*video-index0"], "/dev/video0")
+    if cfg.gripper.type == "modbus":
+        cfg.gripper.port = _device("Gripper serial", ["serial/by-id/*"], "/dev/ttyUSB0")
+    if kind >= 2:
+        cfg.arm.desk_user = _ask("Desk user", "franka")
+        cfg.arm.desk_password_file = str(path.parent / "desk-password")
+        desk_password = _secret("Desk password", Path(cfg.arm.desk_password_file))
+    while True:
+        url = _ask("Model Base URL")
+        model = _ask("Model", "vision-1")
+        try:
+            url, model = validate_policy_endpoint(url, model)
+            break
+        except ValueError as exc:
+            print(str(exc))
+    cfg.policy = config.PolicyConfig(type="openai", url=url, model=model,
+                                    token_file=str(path.parent / "model-api-key"))
+    api_key = _secret("Model API key", Path(cfg.policy.token_file))
+    print("After each action chunk, wait before capturing the next observation. Actions run at 30 Hz.")
+    default_pause = str(cfg.runtime.inter_chunk_pause_s)
+    while True:
+        try:
+            cfg.runtime.inter_chunk_pause_s = float(_ask("Wait after each action chunk (seconds)", default_pause))
+            cfg.runtime.validate()
+            break
+        except ValueError:
+            print("Enter a non-negative finite number of seconds.")
+    print("Runs have no automatic time limit. Stop through MCP, the browser, or Ctrl+C.")
+    cfg.runtime.log_dir = str(path.parent / "logs")
+    cfg.calibration.profile_file = str(path.parent / "calibration.json")
+    cfg.calibration.tool_id = "robotiq-flange-center-v1"
+    cfg.validate()
+
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    secrets = [(cfg.policy.token_file, api_key)]
+    if kind >= 2:
+        secrets.append((cfg.arm.desk_password_file, desk_password))
+    for secret_path, value in secrets:
+        if value is not None:
+            write_policy_token(secret_path, value)
+        else:
+            Path(secret_path).chmod(0o600)
+    config.save(cfg, path)
+    print(f"Saved configuration: {path}")
+    if cfg.arm.type == "franka":
+        print("Franka setup uses the standard assembly load and a flange-centre TCP with aligned axes.")
+        print("FR3 5.6 / Panda 4.x: run 'roboapi export-franka-tool' and apply the preset in Desk before calibration.")
+    print(f"Browser: roboapi http -c {shlex.quote(str(path))}")
+    print(f"MCP: roboapi serve -c {shlex.quote(str(path))}")
+    print("Then open http://127.0.0.1:8080/ and choose Devices > Calibrate to set up coordinates and enable control.")
+    print("Later, use Settings on http://127.0.0.1:8080/ to change the model connection or chunk wait.")
+    return 0