urkit 0.4.1__tar.gz → 0.4.2__tar.gz

{urkit-0.4.1 → urkit-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urkit
-Version: 0.4.1
+Version: 0.4.2
 Summary: Universal Robots e-Series control toolkit built on ur_rtde
 Author: URKit Contributors
 License: MIT
@@ -94,6 +94,11 @@ The `-U` (upgrade) flag ensures you always get the latest version. This project
 
 Requires Python 3.8+ and a Universal Robots e-Series (UR3e to UR30).
 
+### Platform Support
+
+- **Linux, macOS**: fully supported
+- **Windows**: the Python library works on Windows. The interactive CLIs (`urkit teach`, `urkit points`) run on Windows but are **not fully tested and not officially supported**. A warning is printed at startup. If you hit input or console problems, use Linux, macOS, or WSL2
+
 ### Robot Setup (one-time)
 
 1. **Network**: Connect your PC to the robot via Ethernet cable (direct) or a switch.
@@ -663,7 +668,7 @@ Default is `None` (controller handles IK natively). Set it globally when most of
 
 #### Point Management
 
-Points are stored in the active TCP frame, so they work with any tool. Swap grippers and your saved points stay valid.
+Points are stored as absolute TCP poses in the robot base frame. When you move to a point, the controller moves whatever TCP is currently active to that base-frame pose, so the tool tip lands at the same physical location. Change the TCP offset (or swap grippers) and your saved points stay valid.
 
 ```python
 robot.save_point("here")

{urkit-0.4.1 → urkit-0.4.2}/README.md

@@ -68,6 +68,11 @@ The `-U` (upgrade) flag ensures you always get the latest version. This project
 
 Requires Python 3.8+ and a Universal Robots e-Series (UR3e to UR30).
 
+### Platform Support
+
+- **Linux, macOS**: fully supported
+- **Windows**: the Python library works on Windows. The interactive CLIs (`urkit teach`, `urkit points`) run on Windows but are **not fully tested and not officially supported**. A warning is printed at startup. If you hit input or console problems, use Linux, macOS, or WSL2
+
 ### Robot Setup (one-time)
 
 1. **Network**: Connect your PC to the robot via Ethernet cable (direct) or a switch.
@@ -637,7 +642,7 @@ Default is `None` (controller handles IK natively). Set it globally when most of
 
 #### Point Management
 
-Points are stored in the active TCP frame, so they work with any tool. Swap grippers and your saved points stay valid.
+Points are stored as absolute TCP poses in the robot base frame. When you move to a point, the controller moves whatever TCP is currently active to that base-frame pose, so the tool tip lands at the same physical location. Change the TCP offset (or swap grippers) and your saved points stay valid.
 
 ```python
 robot.save_point("here")

{urkit-0.4.1 → urkit-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "urkit"
-version = "0.4.1"
+version = "0.4.2"
 description = "Universal Robots e-Series control toolkit built on ur_rtde"
 readme = "README.md"
 license = {text = "MIT"}

{urkit-0.4.1 → urkit-0.4.2}/src/urkit/__init__.py

@@ -24,7 +24,7 @@ Quick start::
 
 from __future__ import annotations
 
-__version__ = "0.4.1"
+__version__ = "0.4.2"
 
 
 from urkit.exceptions import (

{urkit-0.4.1 → urkit-0.4.2}/src/urkit/cli/connection_monitor.py

@@ -144,10 +144,17 @@ class ConnectionMonitor:
         logger.info("Connection monitor loop exited")
 
     def _trigger(self, reason: str) -> None:
-        """Record fault reason and send SIGALRM to interrupt blocking calls."""
+        """Record fault reason and send SIGALRM to interrupt blocking calls.
+
+        On Windows there is no self-signal: the fault_detected flag is
+        the only interruption path, and callers poll it between and
+        after RTDE calls.
+        """
         self._reason = reason
         self._fault_event.set()
         logger.info("Fault detected: %s", reason)
+        if not hasattr(signal, "SIGALRM"):
+            return
         try:
             os.kill(os.getpid(), signal.SIGALRM)
         except OSError as e:

{urkit-0.4.1 → urkit-0.4.2}/src/urkit/cli/points.py

@@ -9,9 +9,7 @@ from __future__ import annotations
 
 import difflib
 import io
-import select
 import sys
-import termios
 import time
 from pathlib import Path
 
@@ -20,6 +18,7 @@ from rich.table import Table
 
 from urkit.config import _load_config as load_config
 from urkit.cli.colors import blue, cyan, dim, yellow
+from urkit.cli.terminal import RawTerminal, read_burst, wait_input, warn_if_windows
 from urkit.points import Points
 
 
@@ -29,6 +28,7 @@ def points_command(args) -> None:
     Args:
         args: Parsed arguments from argparse (with points subcommand attributes).
     """
+    warn_if_windows()
     _explore_points(args)
 
 
@@ -120,12 +120,8 @@ def _interactive_points_filter(points_db: Points, all_points: list[str], points_
     refresh_error = None
 
     # Set terminal to raw mode
-    old_settings = termios.tcgetattr(sys.stdin)
-    new_settings = termios.tcgetattr(sys.stdin)
-    new_settings[3] = new_settings[3] & ~(termios.ICANON | termios.ECHO)
-    termios.tcsetattr(sys.stdin, termios.TCSADRAIN, new_settings)
-
-    fd = sys.stdin.fileno()
+    raw = RawTerminal()
+    raw.enable()
 
     try:
         while True:
@@ -238,44 +234,41 @@ def _interactive_points_filter(points_db: Points, all_points: list[str], points_
                 last_refresh = time.time()
 
             # Check for input (non-blocking to allow periodic refresh)
-            rlist, _, _ = select.select([fd], [], [], 0.1)
-            if not rlist:
+            if not wait_input(0.1):
                 continue
 
-            # Read input
+            # Read the full input burst. On Unix an arrow key arrives as
+            # \x1b[A in the same burst; on Windows the terminal shim
+            # translates arrow keys to the same byte sequence.
             try:
-                ch = sys.stdin.read(1)
+                text = read_burst(0.0).decode("ascii", errors="replace")
             except Exception:
                 break
+            if not text:
+                continue
 
-            if ch == "\x1b":  # ESC or arrow key or function key
-                # Use longer timeout to reliably detect sequences
-                rlist, _, _ = select.select([fd], [], [], 0.2)
-                if rlist:
-                    # There's more input, likely an arrow or function key sequence
-                    try:
-                        ch2 = sys.stdin.read(1)
-                        if ch2 == "[":
-                            ch3 = sys.stdin.read(1)
-                            if ch3 == "A":  # Up arrow - scroll up
-                                scroll = max(0, scroll - 1)
-                                needs_redraw = True
-                            elif ch3 == "B":  # Down arrow - scroll down
-                                filtered = [p for p in all_points_sorted if filter_str == "" or filter_str.lower() in p.lower()]
-                                scroll = min(len(filtered) - 1, scroll + 1) if filtered else 0
-                                needs_redraw = True
-                    except Exception:
-                        break
+            if text.startswith("\x1b"):  # ESC or arrow key or function key
+                # A bare ESC may still be the first byte of a sequence
+                # that arrives late; wait a bit before treating it as quit.
+                if text == "\x1b":
+                    text = text + read_burst(0.2).decode("ascii", errors="replace")
+                if text.endswith("[A"):  # Up arrow - scroll up
+                    scroll = max(0, scroll - 1)
+                    needs_redraw = True
+                elif text.endswith("[B"):  # Down arrow - scroll down
+                    filtered = [p for p in all_points_sorted if filter_str == "" or filter_str.lower() in p.lower()]
+                    scroll = min(len(filtered) - 1, scroll + 1) if filtered else 0
+                    needs_redraw = True
                 else:
-                    # No more input, so this was just ESC — quit
+                    # Just ESC (or an unrecognized sequence) — quit
                     break
-            elif ch == "\x7f" or ch == "\x08":  # Backspace
+            elif text == "\x7f" or text == "\x08":  # Backspace
                 if filter_str:
                     filter_str = filter_str[:-1]
                     scroll = 0
                     needs_redraw = True
-            elif ch.isprintable():
-                filter_str += ch
+            elif text.isprintable():
+                filter_str += text
                 scroll = 0
                 needs_redraw = True
 
@@ -283,7 +276,7 @@ def _interactive_points_filter(points_db: Points, all_points: list[str], points_
         # Ctrl+C — exit gracefully without traceback
         pass
     finally:
-        termios.tcsetattr(sys.stdin, termios.TCSADRAIN, old_settings)
+        raw.disable()
         sys.stdout.write("\n")
 
 

{urkit-0.4.1 → urkit-0.4.2}/src/urkit/cli/teach.py

@@ -16,18 +16,21 @@ import ipaddress
 import logging
 import math
 import os
-import select
 import signal
 import sys
-import termios
 import time
-import tty
 from pathlib import Path
 
 import yaml
 
-from urkit.config import _load_config as load_config
 from urkit.cli.colors import blue, cyan, dim, green, red, yellow
+from urkit.cli.terminal import (
+    RawTerminal,
+    read_burst,
+    wait_input,
+    warn_if_windows,
+)
+from urkit.config import _load_config as load_config
 from urkit.cli.connection_monitor import ConnectionMonitor
 from urkit.cli.points import _interactive_points_filter
 from urkit.connection import (
@@ -181,38 +184,6 @@ def _validate_ip(ip: str) -> bool:
 
 
 
-# ------------------------------------------------------------------
-# Raw terminal I/O
-# ------------------------------------------------------------------
-
-class _RawTerminal:
-    """Manage raw terminal mode with tcgetattr/tcsetattr.
-
-    Context-manager based: enters raw mode on __enter__, restores on __exit__.
-    Single-character non-blocking reads via getkey().
-    """
-
-    def __enter__(self) -> "_RawTerminal":
-        self._old_settings = termios.tcgetattr(sys.stdin)
-        tty.setcbreak(sys.stdin.fileno())
-        return self
-
-    def __exit__(self, *args) -> None:
-        if hasattr(self, "_old_settings"):
-            termios.tcsetattr(sys.stdin, termios.TCSADRAIN, self._old_settings)
-
-    def getkey(self) -> str:
-        """Read a single character without waiting for Enter.
-
-        Returns:
-            Single character string, or empty string if no input.
-        """
-        ready, _, _ = select.select([sys.stdin], [], [], 0.05)
-        if ready:
-            return sys.stdin.read(1)
-        return ""
-
-
 # ------------------------------------------------------------------
 # UI rendering
 # ------------------------------------------------------------------
@@ -469,16 +440,19 @@ def _draw_help() -> None:
 # Point submenus (restore canonical terminal for multi-char input)
 # ------------------------------------------------------------------
 
-def _configure_terminal() -> list:
-    """Disable canonical mode and echo."""
-    old_settings = termios.tcgetattr(sys.stdin)
-    tty.setcbreak(sys.stdin.fileno())
-    return old_settings
+# Raw terminal shared by the main loop, the SIGINT handler, and the
+# exit path. All terminal setup goes through the cross-platform shim.
+_raw_terminal = RawTerminal()
+
 
+def _configure_terminal() -> None:
+    """Enter raw terminal mode (no canonical, no echo)."""
+    _raw_terminal.enable()
 
-def _restore_terminal(old_settings: list) -> None:
+
+def _restore_terminal() -> None:
     """Restore canonical mode and echo."""
-    termios.tcsetattr(sys.stdin, termios.TCSADRAIN, old_settings)
+    _raw_terminal.disable()
 
 
 def _read_input(prompt: str, max_len: int = 30) -> str | None:
@@ -494,51 +468,50 @@ def _read_input(prompt: str, max_len: int = 30) -> str | None:
     Returns:
         Input string, or None if cancelled (ESC/empty).
     """
-    old_settings = termios.tcgetattr(sys.stdin)
-    tty.setcbreak(sys.stdin.fileno())
-    # Disable echo — we handle character display ourselves to avoid conflicts
-    settings = termios.tcgetattr(sys.stdin)
-    settings[3] = settings[3] & ~termios.ECHO
-    termios.tcsetattr(sys.stdin, termios.TCSADRAIN, settings)
+    raw = RawTerminal()
+    raw.enable()
 
     sys.stdout.write(prompt)
     sys.stdout.flush()
 
     name = ""
-    while True:
-        ready, _, _ = select.select([sys.stdin], [], [], 0.1)
-        if not ready:
-            if _cli_monitor and _cli_monitor.fault_detected:
-                termios.tcsetattr(sys.stdin, termios.TCSADRAIN, old_settings)
-                raise URKitConnectionError(
-                    f"Robot fault detected: {_cli_monitor._reason or 'RTDE connection lost'}. "
-                    "RTDE connection lost."
-                )
-            continue
-        ch = sys.stdin.read(1)
-        if ch == "\x1b":
-            sys.stdout.write("\033[K")
-            sys.stdout.flush()
-            return None
-        elif ch == "\x03":  # Ctrl+C
-            sys.stdout.write("\033[K")
-            sys.stdout.flush()
-            return None
-        elif ch == "\x08" or ch == "\x7f":  # Backspace
-            if name:
-                name = name[:-1]
-                sys.stdout.write("\b \b")
-                sys.stdout.flush()
-        elif ch == "\n" or ch == "\r":
-            sys.stdout.write("\033[K")
-            sys.stdout.flush()
-            break
-        elif len(name) < max_len and ch.isprintable():
-            name += ch
-            sys.stdout.write(ch)
-            sys.stdout.flush()
+    try:
+        while True:
+            if not wait_input(0.1):
+                if _cli_monitor and _cli_monitor.fault_detected:
+                    raise URKitConnectionError(
+                        f"Robot fault detected: {_cli_monitor._reason or 'RTDE connection lost'}. "
+                        "RTDE connection lost."
+                    )
+                continue
+            text = read_burst(0.0).decode("ascii", errors="replace")
+            if not text:
+                continue
+            done = False
+            for ch in text:
+                if ch == "\x1b" or ch == "\x03":  # ESC or Ctrl+C → cancel
+                    sys.stdout.write("\033[K")
+                    sys.stdout.flush()
+                    return None
+                elif ch == "\x08" or ch == "\x7f":  # Backspace
+                    if name:
+                        name = name[:-1]
+                        sys.stdout.write("\b \b")
+                        sys.stdout.flush()
+                elif ch == "\n" or ch == "\r":
+                    sys.stdout.write("\033[K")
+                    sys.stdout.flush()
+                    done = True
+                    break
+                elif len(name) < max_len and ch.isprintable():
+                    name += ch
+                    sys.stdout.write(ch)
+                    sys.stdout.flush()
+            if done:
+                break
+    finally:
+        raw.disable()
 
-    termios.tcsetattr(sys.stdin, termios.TCSADRAIN, old_settings)
     sys.stdout.write("\r\033[K\n")
     sys.stdout.flush()
     return name.strip()
@@ -606,12 +579,8 @@ def _filter_select_points(
     cursor = 0
 
     # Set terminal to raw mode once, outside the loop
-    old_settings = termios.tcgetattr(sys.stdin)
-    new_settings = termios.tcgetattr(sys.stdin)
-    new_settings[3] = new_settings[3] & ~(termios.ICANON | termios.ECHO)
-    termios.tcsetattr(sys.stdin, termios.TCSADRAIN, new_settings)
-
-    fd = sys.stdin.fileno()
+    raw = RawTerminal()
+    raw.enable()
 
     try:
         while True:
@@ -645,27 +614,19 @@ def _filter_select_points(
 
             sys.stdout.flush()
 
-            ready, _, _ = select.select([fd], [], [], 0.1)
-            if not ready:
+            # Wait for input, then read the full burst (e.g. the
+            # 3-byte \x1b[A arrow-key sequence) in one go.
+            raw_bytes = read_burst(0.1)
+            if not raw_bytes:
                 if _cli_monitor and _cli_monitor.fault_detected:
-                    termios.tcsetattr(sys.stdin, termios.TCSADRAIN, old_settings)
                     raise URKitConnectionError(
                         f"Robot fault detected: {_cli_monitor._reason or 'RTDE connection lost'}. "
                         "RTDE connection lost."
                     )
                 continue
 
-            # Read all bytes that arrived together — avoids Python text-mode
-            # buffering silently consuming escape sequence bytes.
-            # After select() says ready, os.read() gets everything the terminal
-            # sent in one burst (e.g., \x1b[A for up-arrow). A second read
-            # would block, so we only read once per select() notification.
-            raw = os.read(fd, 64)
-            if not raw:
-                continue
-
             # Decode and parse sequentially, handling multi-byte escape sequences
-            text = raw.decode("ascii", errors="replace")
+            text = raw_bytes.decode("ascii", errors="replace")
             i = 0
             while i < len(text):
                 ch = text[i]
@@ -698,7 +659,7 @@ def _filter_select_points(
 
                 i += 1
     finally:
-        termios.tcsetattr(sys.stdin, termios.TCSADRAIN, old_settings)
+        raw.disable()
 
 
 def _submenu_goto_point(
@@ -764,10 +725,9 @@ def _submenu_goto_point(
                 robot, name, mode_label, start_pose, target_pose, is_cartesian, max_progress
             )
             max_progress = pct
-            ready, _, _ = select.select([sys.stdin], [], [], 0.05)
-            if ready:
-                key = sys.stdin.read(1)
-                if key == " ":  # Space to cancel
+            if wait_input(0.05):
+                key = read_burst(0.0).decode("ascii", errors="replace")
+                if " " in key:  # Space to cancel
                     cancelled = True
                     break
 
@@ -905,11 +865,8 @@ def _submenu_orient_tcp(
 ) -> None:
     """Interactive submenu to orient TCP along a base-axis direction."""
     cursor = 0
-    old_settings = termios.tcgetattr(sys.stdin)
-    new_settings = termios.tcgetattr(sys.stdin)
-    new_settings[3] = new_settings[3] & ~(termios.ICANON | termios.ECHO)
-    termios.tcsetattr(sys.stdin, termios.TCSADRAIN, new_settings)
-    fd = sys.stdin.fileno()
+    raw = RawTerminal()
+    raw.enable()
 
     try:
         while True:
@@ -926,20 +883,15 @@ def _submenu_orient_tcp(
             sys.stdout.write(f"\n  {dim('Enter')} to orient {green(_TCP_ORIENT_OPTIONS[cursor][0])}\n")
             sys.stdout.flush()
 
-            ready, _, _ = select.select([fd], [], [], 0.1)
-            if not ready:
+            raw_bytes = read_burst(0.1)
+            if not raw_bytes:
                 if _cli_monitor and _cli_monitor.fault_detected:
-                    termios.tcsetattr(sys.stdin, termios.TCSADRAIN, old_settings)
                     raise URKitConnectionError(
                         f"Robot fault detected: {_cli_monitor._reason or 'RTDE connection lost'}. "
                         "RTDE connection lost."
                     )
                 continue
-
-            raw = os.read(fd, 64)
-            if not raw:
-                continue
-            text = raw.decode("ascii", errors="replace")
+            text = raw_bytes.decode("ascii", errors="replace")
             i = 0
             selected = None
             while i < len(text):
@@ -964,7 +916,7 @@ def _submenu_orient_tcp(
             if selected is not None:
                 break
     finally:
-        termios.tcsetattr(sys.stdin, termios.TCSADRAIN, old_settings)
+        raw.disable()
 
     if selected is None:
         messages.append("Cancelled")
@@ -1019,11 +971,8 @@ def _submenu_freedrive_axes(
         axes = [1, 1, 1, 1, 1, 1]
 
     cursor = 0
-    old_settings = termios.tcgetattr(sys.stdin)
-    new_settings = termios.tcgetattr(sys.stdin)
-    new_settings[3] = new_settings[3] & ~(termios.ICANON | termios.ECHO)
-    termios.tcsetattr(sys.stdin, termios.TCSADRAIN, new_settings)
-    fd = sys.stdin.fileno()
+    raw = RawTerminal()
+    raw.enable()
 
     try:
         while True:
@@ -1043,14 +992,10 @@ def _submenu_freedrive_axes(
             sys.stdout.write(f"  {dim('Enter')} to apply · {dim('ESC')} to cancel\n")
             sys.stdout.flush()
 
-            ready, _, _ = select.select([fd], [], [], 0.1)
-            if not ready:
-                continue
-
-            raw = os.read(fd, 64)
-            if not raw:
+            raw_bytes = read_burst(0.1)
+            if not raw_bytes:
                 continue
-            text = raw.decode("ascii", errors="replace")
+            text = raw_bytes.decode("ascii", errors="replace")
             i = 0
             applied = False
             while i < len(text):
@@ -1077,7 +1022,7 @@ def _submenu_freedrive_axes(
             if applied:
                 break
     finally:
-        termios.tcsetattr(sys.stdin, termios.TCSADRAIN, old_settings)
+        raw.disable()
 
     if sum(axes) == 0:
         messages.append("Cancelled — at least 1 axis must be active")
@@ -1203,11 +1148,11 @@ def _teach_pendant(
         print("Error: stdin is not a terminal. Run from an interactive shell.")
         sys.exit(1)
 
-    old_settings = termios.tcgetattr(sys.stdin)
-
     # SIGINT handler: restore terminal and exit when Ctrl+C pressed.
-    # tty.setcbreak() keeps ISIG enabled, so Ctrl+C generates SIGINT.
-    # os._exit() works even when blocked in C library code.
+    # On Unix, raw mode keeps ISIG enabled, so Ctrl+C generates SIGINT.
+    # On Windows, Ctrl+C arrives as a raw 0x03 byte instead (handled by
+    # the main loop's exit key path). os._exit() works even when blocked
+    # in C library code.
     def _sigint_handler(signum: int, frame: object) -> None:
         try:
             if state["freedrive"]:
@@ -1224,7 +1169,7 @@ def _teach_pendant(
         except Exception:
             pass
         try:
-            _restore_terminal(old_settings)
+            _restore_terminal()
         except Exception:
             pass
         sys.stderr.write("\nInterrupted.\n")
@@ -1235,7 +1180,13 @@ def _teach_pendant(
     # Connection watchdog: detects faults and interrupts blocking calls.
     monitor = ConnectionMonitor(robot)
     monitor.start()
-    _old_sigalrm = signal.signal(signal.SIGALRM, monitor.alarm_handler)
+    # SIGALRM does not exist on Windows: the monitor sets its
+    # fault_detected flag instead, and the input-wait loops below check
+    # it every 50ms. Faults during long blocking RTDE calls surface
+    # when the call returns rather than being interrupted immediately.
+    _old_sigalrm = None
+    if hasattr(signal, "SIGALRM"):
+        _old_sigalrm = signal.signal(signal.SIGALRM, monitor.alarm_handler)
     global _cli_monitor
     _cli_monitor = monitor  # used by _read_input and _filter_select_points
 
@@ -1254,8 +1205,7 @@ def _teach_pendant(
 
                 # --- Wait for a key ---
                 while True:
-                    ready, _, _ = select.select([sys.stdin], [], [], 0.05)
-                    if ready:
+                    if wait_input(0.05):
                         break
 
                     # Periodic refresh while in freedrive — robot may be moving by hand
@@ -1278,17 +1228,10 @@ def _teach_pendant(
                 # behind — when the user switches from one movement key to
                 # another, the last buffered copy of the old key fires one final
                 # move in the wrong direction before the new key is read.
-                # Fix: after select() signals ready, drain all immediately
-                # available bytes (non-blocking) and use the last one.
-                key = ""
-                while True:
-                    ready, _, _ = select.select([sys.stdin], [], [], 0.0)
-                    if not ready:
-                        break
-                    ch = sys.stdin.read(1).lower()
-                    if not ch:
-                        break
-                    key = ch
+                # Fix: drain all immediately available bytes
+                # (non-blocking) and use the last one.
+                key_text = read_burst(0.0).decode("ascii", errors="replace")
+                key = key_text[-1].lower() if key_text else ""
                 if not key:
                     continue
 
@@ -1550,14 +1493,15 @@ def _teach_pendant(
         finally:
             # Stop monitor and restore signal handler
             monitor.stop()
-            signal.signal(signal.SIGALRM, _old_sigalrm)
+            if _old_sigalrm is not None:
+                signal.signal(signal.SIGALRM, _old_sigalrm)
 
     finally:
         _urkit_logger.removeHandler(_log_handler)
         _urkit_logger.propagate = True
         # Restore terminal
         try:
-            _restore_terminal(old_settings)
+            _restore_terminal()
         except Exception:
             pass
         print("\n  Exiting teach pendant.")
@@ -1570,6 +1514,8 @@ def teach_command(args) -> None:
         args: Parsed arguments from argparse (with teach subcommand attributes).
     """
 
+    warn_if_windows()
+
     # Configure logging
     if args.verbose:
         logging.basicConfig(

urkit-0.4.2/src/urkit/cli/terminal.py

@@ -0,0 +1,233 @@
+"""Cross-platform raw terminal input for the interactive CLIs.
+
+The CLIs need three things from the platform:
+
+1. Raw mode on stdin (no line buffering, no echo) with a way to
+   restore the original settings, even on error paths.
+2. Non-blocking input reads: "is there input?" and "read everything
+   currently buffered" (a burst, e.g. the 3-byte arrow-key sequence).
+3. On Windows only: ANSI escape processing on stdout so colors and
+   cursor codes render.
+
+Unix backend: termios + tty + select, exactly the syscalls the CLIs
+used to issue directly.
+
+Windows backend: msvcrt with console input mode changed via kernel32.
+The console does not emit ANSI sequences for special keys, so the
+backend translates extended keycodes (prefix byte 0xE0/0x00 + scan
+code) into the same byte sequences a Unix terminal sends. This keeps
+the CLI key-parsing code identical on both platforms.
+
+Windows limitation: with ENABLE_PROCESSED_INPUT disabled, Ctrl+C is
+delivered as a raw 0x03 byte instead of raising KeyboardInterrupt.
+The CLIs already handle 0x03 as an exit key, and it matters that
+Ctrl+C is a byte rather than an exception here: an exception would
+bypass terminal restore.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import sys
+import time
+from typing import Any
+
+if sys.platform == "win32":
+    import msvcrt
+else:
+    import select
+    import termios
+    import tty
+
+if sys.platform == "win32":
+    # CDLL is used instead of WinDLL because ctypes.WinDLL is only
+    # exposed in the Windows type stubs; on 64-bit Windows both use
+    # the same calling convention.
+    _kernel32 = ctypes.CDLL("kernel32", use_last_error=True)
+    _STD_INPUT_HANDLE = -10
+    _STD_OUTPUT_HANDLE = -11
+    _ENABLE_PROCESSED_INPUT = 0x0001
+    _ENABLE_LINE_INPUT = 0x0002
+    _ENABLE_ECHO_INPUT = 0x0004
+    _ENABLE_VIRTUAL_TERMINAL_PROCESSING = 0x0004
+
+    # msvcrt extended-key scan codes (after the 0xE0/0x00 prefix byte)
+    # mapped to the ANSI CSI sequences a Unix terminal emits for the
+    # same key.
+    _EXTENDED_KEYS: dict[int, str] = {
+        0x48: "\x1b[A",  # Up
+        0x50: "\x1b[B",  # Down
+        0x4D: "\x1b[C",  # Right
+        0x4B: "\x1b[D",  # Left
+        0x47: "\x1b[H",  # Home
+        0x4F: "\x1b[F",  # End
+        0x49: "\x1b[5~",  # Page Up
+        0x51: "\x1b[6~",  # Page Down
+        0x52: "\x1b[2~",  # Insert
+        0x53: "\x1b[3~",  # Delete
+    }
+
+    def _console_mode(handle: int) -> int:
+        mode = ctypes.c_uint32()
+        if not _kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+            raise OSError(
+                "GetConsoleMode failed (stdin is not a console). "
+                "Run from an interactive shell."
+            )
+        return mode.value
+
+    def _set_console_mode(handle: int, mode: int) -> None:
+        if not _kernel32.SetConsoleMode(handle, mode):
+            raise OSError("SetConsoleMode failed")
+
+    def _enable_ansi_output() -> None:
+        """Enable ANSI escape processing on stdout.
+
+        No-op on Windows Terminal and recent conhost; needed on
+        older conhost versions. Best effort: some non-console
+        stdout handles (redirected output) reject it.
+        """
+        try:
+            handle = _kernel32.GetStdHandle(_STD_OUTPUT_HANDLE)
+            mode = _console_mode(handle)
+            _set_console_mode(
+                handle, mode | _ENABLE_VIRTUAL_TERMINAL_PROCESSING
+            )
+        except OSError:
+            pass
+
+
+def warn_if_windows() -> None:
+    """Print a notice when the interactive CLI runs on Windows.
+
+    Call at the top of interactive CLI commands. No-op on other
+    platforms. Windows CLI support is not fully tested.
+    """
+    if sys.platform == "win32":
+        print(
+            "Warning: Windows CLI support is not fully tested and not "
+            "officially supported. If you hit input or console problems, "
+            "use Linux, macOS, or WSL2."
+        )
+
+
+class RawTerminal:
+    """Raw (cbreak, no-echo) mode for stdin.
+
+    Usage:
+        with RawTerminal():
+            ...
+    or manually, where restore must also happen on explicit error
+    paths:
+        raw = RawTerminal()
+        raw.enable()
+        ...
+        raw.disable()   # idempotent, safe to call multiple times
+    """
+
+    def __init__(self) -> None:
+        self._enabled = False
+        self._old_settings: list[Any] | None = None
+        self._old_mode: int | None = None
+        self._stdin_handle: int | None = None
+
+    def enable(self) -> None:
+        """Enter raw mode. Idempotent."""
+        if self._enabled:
+            return
+        if sys.platform == "win32":
+            self._stdin_handle = _kernel32.GetStdHandle(_STD_INPUT_HANDLE)
+            self._old_mode = _console_mode(self._stdin_handle)
+            # Disable processed input, line input, and echo. Ctrl+C
+            # arrives as raw byte 0x03 (handled by the CLIs) instead
+            # of KeyboardInterrupt, which would skip terminal restore.
+            _set_console_mode(
+                self._stdin_handle,
+                self._old_mode
+                & ~(
+                    _ENABLE_PROCESSED_INPUT
+                    | _ENABLE_LINE_INPUT
+                    | _ENABLE_ECHO_INPUT
+                ),
+            )
+            _enable_ansi_output()
+        else:
+            self._old_settings = termios.tcgetattr(sys.stdin)
+            tty.setcbreak(sys.stdin.fileno())
+        self._enabled = True
+
+    def disable(self) -> None:
+        """Restore the original terminal settings. Idempotent."""
+        if not self._enabled:
+            return
+        if sys.platform == "win32":
+            if self._stdin_handle is None or self._old_mode is None:
+                raise RuntimeError("RawTerminal disabled before enable()")
+            _set_console_mode(self._stdin_handle, self._old_mode)
+        else:
+            if self._old_settings is None:
+                raise RuntimeError("RawTerminal disabled before enable()")
+            termios.tcsetattr(
+                sys.stdin, termios.TCSADRAIN, self._old_settings
+            )
+        self._enabled = False
+
+    def __enter__(self) -> "RawTerminal":
+        self.enable()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.disable()
+
+
+def _win_read_pending() -> bytes:
+    """Read all pending console input, translating extended keys to
+    the ANSI CSI sequences a Unix terminal would have emitted."""
+    if sys.platform == "win32":
+        out = bytearray()
+        while msvcrt.kbhit():
+            byte = msvcrt.getch()
+            if byte in (b"\xe0", b"\x00"):
+                code = msvcrt.getch()
+                seq = _EXTENDED_KEYS.get(code)
+                if seq is None:
+                    # Unrecognized function key (F1-F12 etc.): drop it
+                    continue
+                out += seq.encode("ascii")
+            else:
+                out += byte
+        return bytes(out)
+    raise RuntimeError("_win_read_pending is Windows-only")
+
+
+def wait_input(timeout: float) -> bool:
+    """Return True if any stdin input is available within timeout."""
+    if sys.platform == "win32":
+        deadline = time.monotonic() + timeout
+        while not msvcrt.kbhit():
+            if time.monotonic() >= deadline:
+                return False
+            time.sleep(0.005)
+        return True
+    ready, _, _ = select.select([sys.stdin], [], [], timeout)
+    return bool(ready)
+
+
+def read_burst(timeout: float) -> bytes:
+    """Wait up to timeout for input, then return everything currently
+    buffered as one burst (e.g. the full \\x1b[A arrow-key sequence).
+
+    Returns b"" if no input arrives within timeout.
+
+    On Unix this is select() + a single os.read(), the same burst
+    semantics as reading once after a select() notification. On
+    Windows every pending key event is consumed.
+    """
+    if sys.platform == "win32":
+        if not wait_input(timeout):
+            return b""
+        return _win_read_pending()
+    if not wait_input(timeout):
+        return b""
+    return os.read(sys.stdin.fileno(), 64)

{urkit-0.4.1 → urkit-0.4.2}/src/urkit/points.py

@@ -14,11 +14,14 @@ from urkit.geometry import MoveFrame, transform_pose_delta
 
 @dataclass(frozen=True, slots=True)
 class Point:
-    """A robot waypoint stored as a TCP pose.
+    """A robot waypoint stored as a TCP pose in the base frame.
 
-    Stores the TCP pose (from ``getActualTCPPose()``). The UR controller
-    interprets the stored pose in whatever TCP frame is active at playback
-    time, making points tool-agnostic by design.
+    Stores the TCP pose from ``getActualTCPPose()`` as an absolute
+    position in the robot base frame. When passed to ``moveL()`` or
+    ``moveJ()``, the controller moves whatever TCP is currently active
+    to that base-frame position. This means saved points remain valid
+    after TCP changes: the tool tip arrives at the same physical
+    location regardless of which tool is mounted.
 
     Returned by Points attribute/subscript access. Pass directly
     to URRobot.move_to(). Points loaded from the database carry a
@@ -26,7 +29,7 @@ class Point:
 
     Fields:
         name: Point name (key in the database, empty string for ad-hoc points).
-        pose: TCP pose [x, y, z, rx, ry, rz] in meters/radians.
+        pose: TCP pose [x, y, z, rx, ry, rz] in base frame, meters/radians.
     """
 
     name: str

{urkit-0.4.1 → urkit-0.4.2}/src/urkit/robot.py

@@ -1891,19 +1891,20 @@ class URRobot:
         """Save a named point.
 
         When *pose* is omitted, saves the current TCP pose from
-        getActualTCPPose(). When *pose* is provided, saves that
+        ``getActualTCPPose()``. When *pose* is provided, saves that
         arbitrary pose directly without moving the robot.
 
-        The UR controller interprets the stored pose in whatever TCP
-        frame is active at playback time, making points tool-agnostic
-        by design.
+        The pose is stored as an absolute position in the robot base
+        frame. At playback, ``moveL()`` moves whatever TCP is currently
+        active to that base-frame position, so saved points remain
+        valid after TCP changes.
 
         Overwrites if a point with the same name already exists.
 
         Args:
             name: Name for the saved point.
-            pose: TCP pose [x, y, z, rx, ry, rz]. Defaults to current
-                robot position.
+            pose: TCP pose [x, y, z, rx, ry, rz] in base frame.
+                Defaults to current robot position.
 
         Returns:
             The saved Point object.

{urkit-0.4.1 → urkit-0.4.2}/src/urkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urkit
-Version: 0.4.1
+Version: 0.4.2
 Summary: Universal Robots e-Series control toolkit built on ur_rtde
 Author: URKit Contributors
 License: MIT
@@ -94,6 +94,11 @@ The `-U` (upgrade) flag ensures you always get the latest version. This project
 
 Requires Python 3.8+ and a Universal Robots e-Series (UR3e to UR30).
 
+### Platform Support
+
+- **Linux, macOS**: fully supported
+- **Windows**: the Python library works on Windows. The interactive CLIs (`urkit teach`, `urkit points`) run on Windows but are **not fully tested and not officially supported**. A warning is printed at startup. If you hit input or console problems, use Linux, macOS, or WSL2
+
 ### Robot Setup (one-time)
 
 1. **Network**: Connect your PC to the robot via Ethernet cable (direct) or a switch.
@@ -663,7 +668,7 @@ Default is `None` (controller handles IK natively). Set it globally when most of
 
 #### Point Management
 
-Points are stored in the active TCP frame, so they work with any tool. Swap grippers and your saved points stay valid.
+Points are stored as absolute TCP poses in the robot base frame. When you move to a point, the controller moves whatever TCP is currently active to that base-frame pose, so the tool tip lands at the same physical location. Change the TCP offset (or swap grippers) and your saved points stay valid.
 
 ```python
 robot.save_point("here")

{urkit-0.4.1 → urkit-0.4.2}/src/urkit.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ src/urkit/cli/connection_monitor.py
 src/urkit/cli/init.py
 src/urkit/cli/points.py
 src/urkit/cli/teach.py
+src/urkit/cli/terminal.py
 src/urkit/gripper/__init__.py
 src/urkit/gripper/base.py
 src/urkit/gripper/digital.py