urkit 0.1.0__py3-none-any.whl

urkit/__init__.py

@@ -0,0 +1,99 @@
+"""URKit — Universal Robots e-Series control toolkit.
+
+A high-level Python package for Universal Robots e-Series (UR5e, UR10e,
+UR16e) built on ``ur_rtde``. Provides connection validation, named point
+management, motion commands, gripper abstraction, telemetry, geometry
+helpers, and an interactive teach pendant CLI.
+
+Quick start::
+
+    from urkit import URRobot, ROBOTIQ_HAND_E
+
+    robot = URRobot(
+        ip="192.168.1.100",
+        points="points.db",
+        gripper=ROBOTIQ_HAND_E,
+    )
+
+    robot.gripper.activate()
+    robot.move_to("pick")
+    robot.gripper.open()
+    robot.move_to("place")
+    robot.gripper.close()
+"""
+
+from __future__ import annotations
+
+from urkit.config import load_config, resolve_config
+from urkit.exceptions import (
+    URKitError,
+    URKitConnectionError,
+    MotionError,
+    GripperError,
+    PointError,
+    URKitIOError,
+    TelemetryError,
+    URKitRuntimeError,
+    RobotNotInRemoteModeError,
+    RtdeRegisterConflictError,
+)
+from urkit.geometry import (
+    MoveFrame,
+    orient_tcp_down,
+    quat_to_rotvec,
+    quat_to_rpy,
+    rpy_to_quat,
+    rotvec_to_quat,
+)
+from urkit.gripper import Gripper
+from urkit.gripper.presets import (
+    DigitalGripperConfig,
+    GripperPreset,
+    PRESETS,
+    ROBOTIQ_2F_85,
+    ROBOTIQ_2F_140,
+    ROBOTIQ_HAND_E,
+)
+from urkit.motion import FreedriveMode
+from urkit.robot import URRobot
+
+__version__ = "0.0.1"
+
+__all__ = [
+    # Version
+    "__version__",
+    # Config
+    "load_config",
+    "resolve_config",
+    # Core class
+    "URRobot",
+    # Gripper
+    "Gripper",
+    "GripperPreset",
+    "DigitalGripperConfig",
+    "PRESETS",
+    "ROBOTIQ_2F_85",
+    "ROBOTIQ_2F_140",
+    "ROBOTIQ_HAND_E",
+    # Freedrive mode
+    "FreedriveMode",
+    # Move frame
+    "MoveFrame",
+    # Geometry
+    "orient_tcp_down",
+    "quat_to_rotvec",
+    "quat_to_rpy",
+    "rpy_to_quat",
+    "rotvec_to_quat",
+    # Exceptions
+    "URKitError",
+    "URKitConnectionError",
+    "MotionError",
+    "GripperError",
+    "PointError",
+    "URKitIOError",
+    "TelemetryError",
+    "URKitRuntimeError",
+    "RobotNotInRemoteModeError",
+    "RtdeRegisterConflictError",
+]

urkit/__main__.py

@@ -0,0 +1,116 @@
+"""urkit CLI entry point.
+
+Usage:
+    urkit teach 192.168.1.100
+    urkit teach 192.168.1.100 --gripper=hand-e
+    urkit points list
+    urkit points list --filter "pick*"
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from urkit.cli.teach import teach_command
+from urkit.cli.points import points_command
+
+
+def main() -> None:
+    """Main CLI dispatcher for urkit subcommands."""
+    parser = argparse.ArgumentParser(
+        prog="urkit",
+        description="URKit — Universal Robots e-Series control toolkit",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # teach subcommand
+    teach_parser = subparsers.add_parser(
+        "teach",
+        help="Launch interactive teach pendant",
+    )
+    teach_parser.add_argument(
+        "ip",
+        type=str,
+        nargs="?",
+        default=None,
+        help="Robot IP address (overrides config file)",
+    )
+    teach_parser.add_argument(
+        "--gripper",
+        type=str,
+        default=None,
+        choices=["2f-85", "2f-140", "hand-e", "digital"],
+        help="Gripper preset (overrides config file)",
+    )
+    teach_parser.add_argument(
+        "--gripper-pin",
+        type=int,
+        default=None,
+        help="Digital gripper output pin (overrides config file)",
+    )
+    teach_parser.add_argument(
+        "--gripper-force",
+        type=int,
+        default=None,
+        help="Robotiq gripper force 0-100 (overrides config file)",
+    )
+    teach_parser.add_argument(
+        "--gripper-speed",
+        type=int,
+        default=None,
+        help="Robotiq gripper speed 0-100 (overrides config file)",
+    )
+    teach_parser.add_argument(
+        "--gripper-close-on-high",
+        type=str,
+        default=None,
+        choices=["true", "false"],
+        help="Digital gripper polarity: true=HIGH closes, false=LOW closes",
+    )
+    teach_parser.add_argument(
+        "--points",
+        type=str,
+        default=None,
+        help="Path to points.db file (overrides config file)",
+    )
+    teach_parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        default=False,
+        help="Show verbose output (useful for debugging connection issues)",
+    )
+
+    # points subcommand
+    points_parser = subparsers.add_parser(
+        "points",
+        help="Browse saved points interactively",
+    )
+    points_parser.add_argument(
+        "points_path",
+        type=str,
+        nargs="?",
+        default=None,
+        help="Path to points.db file (defaults to points.db in config or current directory)",
+    )
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    if args.command == "teach":
+        teach_command(args)
+    elif args.command == "points":
+        points_command(args)
+
+
+def main_entry() -> None:
+    """Entry point for console script."""
+    main()
+
+
+if __name__ == "__main__":
+    main_entry()

urkit/cli/__init__.py

@@ -0,0 +1,6 @@
+"""CLI subcommand dispatch for urkit."""
+
+from urkit.cli.teach import teach_command
+from urkit.cli.points import points_command
+
+__all__ = ["teach_command", "points_command"]

urkit/cli/colors.py

@@ -0,0 +1,99 @@
+"""Cross-platform terminal color helpers.
+
+Uses colorama for Windows compatibility. Detects dark/light terminal
+and adjusts colors for readability.
+"""
+
+from __future__ import annotations
+
+import os
+
+import colorama
+
+colorama.init()
+
+# ANSI codes (colorama makes these work on Windows)
+RST = "\033[0m"
+BOLD = "\033[1m"
+
+
+def _is_dark_terminal() -> bool:
+    """Detect if the terminal is using a dark background."""
+    cfbg = os.environ.get("COLORFGBG", "")
+    if cfbg and ":" in cfbg:
+        try:
+            bg = int(cfbg.split(":")[1])
+            return bg in (0, 1, 2, 3, 4, 5, 6)
+        except (ValueError, IndexError):
+            pass
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("TERM_PROGRAM") == "vscode":
+        theme = os.environ.get("VSCODE_THEME_COLORID", "")
+        return "dark" in theme.lower()
+    return True
+
+
+# Two complete palettes
+_DARK = {
+    "DIM": "\033[2m",
+    "GREEN": "\033[92m",
+    "YELLOW": "\033[93m",
+    "BLUE": "\033[94m",
+    "CYAN": "\033[96m",
+    "RED": "\033[91m",
+    "WHITE": "\033[97m",
+}
+
+_LIGHT = {
+    "DIM": "\033[2m",
+    "GREEN": "\033[32m",
+    "YELLOW": "\033[33m",
+    "BLUE": "\033[34m",
+    "CYAN": "\033[36m",
+    "RED": "\033[31m",
+    "WHITE": "\033[37m",
+}
+
+_PALETTE = _DARK if _is_dark_terminal() else _LIGHT
+
+DIM = _PALETTE["DIM"]
+GREEN = _PALETTE["GREEN"]
+YELLOW = _PALETTE["YELLOW"]
+BLUE = _PALETTE["BLUE"]
+CYAN = _PALETTE["CYAN"]
+RED = _PALETTE["RED"]
+WHITE = _PALETTE["WHITE"]
+
+
+def _wrap(text: str, *codes: str) -> str:
+    """Wrap text with ANSI codes and reset."""
+    return "".join(codes) + text + RST
+
+
+def bold(text: str) -> str:
+    return _wrap(text, BOLD)
+
+
+def green(text: str) -> str:
+    return _wrap(text, GREEN)
+
+
+def yellow(text: str) -> str:
+    return _wrap(text, YELLOW)
+
+
+def blue(text: str) -> str:
+    return _wrap(text, BLUE)
+
+
+def cyan(text: str) -> str:
+    return _wrap(text, CYAN)
+
+
+def red(text: str) -> str:
+    return _wrap(text, RED)
+
+
+def dim(text: str) -> str:
+    return _wrap(text, DIM)

urkit/cli/connection_monitor.py

@@ -0,0 +1,154 @@
+"""Connection monitoring for the teach pendant CLI.
+
+Runs a daemon thread that periodically checks the RTDE connection
+and robot safety state. Sends SIGALRM to interrupt blocking RTDE
+calls when a fault or connection drop is detected.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import signal
+import threading
+from typing import TYPE_CHECKING
+
+from urkit.exceptions import URKitConnectionError
+
+if TYPE_CHECKING:
+    from urkit.robot import URRobot
+
+logger = logging.getLogger(__name__)
+
+
+class ConnectionMonitor:
+    """Background thread that monitors RTDE connection and robot state.
+
+    Checks isConnected() on the RTDE interfaces and the robot's
+    protective/emergency stop state. When a fault is detected, sends
+    SIGALRM to the process to interrupt any blocking RTDE call.
+
+    Args:
+        robot: URRobot instance to monitor.
+        interval: Seconds between checks (default 0.5).
+        grace_period: Seconds to wait before the first check (default
+            2.0). Prevents false triggers while the CLI is initializing.
+
+    Example:
+        >>> monitor = ConnectionMonitor(robot)
+        >>> monitor.start()
+        >>> signal.signal(signal.SIGALRM, monitor.alarm_handler)
+        >>> try:
+        ...     # main loop with blocking RTDE calls
+        ... except URKitConnectionError as e:
+        ...     print(f"Fault: {e}")
+        >>> monitor.stop()
+    """
+
+    def __init__(
+        self,
+        robot: "URRobot",
+        interval: float = 0.5,
+        grace_period: float = 2.0,
+    ) -> None:
+        self._robot = robot
+        self._interval = interval
+        self._grace_period = grace_period
+        self._stop_event = threading.Event()
+        self._fault_event = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._reason: str | None = None
+
+    def start(self) -> None:
+        """Start the monitoring thread."""
+        if self._thread is not None and self._thread.is_alive():
+            return
+        self._stop_event.clear()
+        self._fault_event.clear()
+        self._reason = None
+        self._thread = threading.Thread(
+            target=self._monitor_loop,
+            daemon=True,
+            name="connection-monitor",
+        )
+        self._thread.start()
+        logger.info("Connection monitor started (interval=%.1fs)", self._interval)
+
+    def stop(self) -> None:
+        """Stop the monitoring thread."""
+        self._stop_event.set()
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+        self._thread = None
+        logger.info("Connection monitor stopped")
+
+    @property
+    def is_alive(self) -> bool:
+        """Return whether the monitoring thread is running."""
+        return self._thread is not None and self._thread.is_alive()
+
+    @property
+    def fault_detected(self) -> bool:
+        """Return True if a fault has been detected by the monitor."""
+        return self._fault_event.is_set()
+
+    def alarm_handler(self, signum: int, frame: object) -> None:
+        """Signal handler for SIGALRM. Raises URKitConnectionError.
+
+        Install this as the SIGALRM handler before entering any
+        blocking RTDE call:
+            signal.signal(signal.SIGALRM, monitor.alarm_handler)
+        """
+        reason = self._reason or "RTDE connection lost"
+        raise URKitConnectionError(
+            f"Robot fault detected: {reason}. RTDE connection lost."
+        )
+
+    def _monitor_loop(self) -> None:
+        """Main monitoring loop running in the daemon thread."""
+        # Grace period — wait before the first check so the CLI has time
+        # to draw the screen and set up terminal mode. Prevents SIGALRM
+        # from interrupting a blocking call before the UI is ready.
+        if self._grace_period > 0:
+            logger.info("Monitor grace period: %.1fs", self._grace_period)
+            if self._stop_event.wait(self._grace_period):
+                return
+
+        while not self._stop_event.wait(self._interval):
+            try:
+                # Check RTDE connection status
+                rtde_c = self._robot.rtde_control
+                if not rtde_c.isConnected():
+                    self._trigger("RTDE control connection lost")
+                    return
+
+                # Check for protective stop
+                if self._robot.is_protective_stopped():
+                    self._trigger("Robot is in protective stop")
+                    return
+
+                # Check for emergency stop
+                if self._robot.is_emergency_stopped():
+                    self._trigger("Robot is in emergency stop")
+                    return
+
+            except URKitConnectionError:
+                # Re-raise alarm-triggered errors
+                raise
+            except Exception as e:
+                # Any exception reading state suggests connection issues
+                logger.warning("Connection monitor error: %s", e)
+                self._trigger(f"Robot connection fault: {e}")
+                return
+
+        logger.info("Connection monitor loop exited")
+
+    def _trigger(self, reason: str) -> None:
+        """Record fault reason and send SIGALRM to interrupt blocking calls."""
+        self._reason = reason
+        self._fault_event.set()
+        logger.info("Fault detected: %s", reason)
+        try:
+            os.kill(os.getpid(), signal.SIGALRM)
+        except OSError as e:
+            logger.error("Failed to send SIGALRM: %s", e)