urkit 0.4.0__tar.gz → 0.4.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urkit
-Version: 0.4.0
+Version: 0.4.2
 Summary: Universal Robots e-Series control toolkit built on ur_rtde
 Author: URKit Contributors
 License: MIT
@@ -56,12 +56,14 @@ The typical workflow: teach points with the pendant, write a few lines of Python
 
 - [Quick Start](#quick-start)
 - [Configuration](#configuration)
+  - [Create a Config File](#create-a-config-file)
   - [Location](#location)
   - [Keys](#keys)
   - [Gripper Config](#gripper-config)
   - [Saving Config](#saving-config)
   - [Programmatic](#programmatic)
 - [Interactive CLI](#interactive-cli)
+  - [Init](#init)
   - [Teach Mode](#teach-mode)
   - [Points Explorer](#points-explorer)
   - [Key Map](#key-map)
@@ -92,12 +94,40 @@ 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**: `☰` → `System` → `System` → `Network`. Set a static IP on the robot and a matching one on your PC. Both addresses must share the same first three octets (the network), with a different last octet (the host). For example:
-   - **Robot**: `192.168.1.50` / Subnet `255.255.255.0`
-   - **PC**: `192.168.1.1` / Netmask `255.255.255.0`
-   - Verify with `ping 192.168.1.50`. Connect via direct Ethernet cable or a switch.
+1. **Network**: Connect your PC to the robot via Ethernet cable (direct) or a switch.
+
+   First, configure the robot: `☰` → `System` → `System` → `Network`. Set a static IP, e.g., `192.168.1.50` / Subnet `255.255.255.0`.
+
+   Then set a matching static IP on your PC. The exact IP can be anything, as long as the first three octets match the robot's network and the last octet is different:
+
+   **Linux**:
+   - Open `Settings` → `Network` → click the gear icon next to `Wired`
+   - Go to `IPv4` tab → change `Automatic (DHCP)` to `Manual`
+   - Enter Address: `192.168.1.1`, Netmask: `255.255.255.0`
+   - Click `Apply`, then toggle the connection off and on
+
+   **macOS**:
+   - Open `System Settings` → `Network` → click `Ethernet` (or your adapter)
+   - Click `Details...` next to the adapter name → `TCP/IP`
+   - Set `Configure IPv4` to `Manually`
+   - Enter IP: `192.168.1.1`, Subnet Mask: `255.255.255.0`
+   - Click `OK`
+
+   **Windows**:
+   - Open `Settings` → `Network & internet` → `Ethernet`
+   - Click the adapter name (e.g., `Ethernet`) at the top
+   - Under `IP settings`, click `Edit` → select `Manual`
+   - Toggle `IPv4` On, enter IP: `192.168.1.1`, Subnet mask: `255.255.255.0`
+   - Click `Save`
+
+   Verify connectivity: `ping 192.168.1.50`.
 2. **Remote Control**: `☰` → `System` → `Remote Control`: Enable. Press the remote/local button on the pendant.
 3. **Security**: `☰` → `Security` → `Services`: enable RTDE and disable EtherNet/IP, PROFINET, or MODBUS if they're claiming RTDE registers. Save and restart.
 
@@ -122,9 +152,20 @@ robot.gripper.open()
 
 The typical workflow:
 
-1. **Teach points.** Use the CLI to position the robot and save named waypoints.
-2. **Write code.** Create a robot, move to points by name, apply offsets, run sequences.
-3. **Iterate.** Add more points, tweak your code, repeat.
+1. **Scaffold config.** Run `urkit init` to create a default `config.yaml`.
+2. **Edit it.** Set your robot IP, gripper type, and other settings.
+3. **Teach points.** Run `urkit teach` (auto-loads config) to position the robot and save waypoints.
+4. **Write code.** Load the config and move to points by name:
+
+```python
+from urkit import URRobot
+
+robot = URRobot.from_config("config.yaml")
+robot.move_to("home")
+robot.move_to("pick", offset_z=0.05)
+```
+
+5. **Iterate.** Add more points, tweak your code, repeat.
 
 ---
 
@@ -132,9 +173,21 @@ The typical workflow:
 
 URKit uses a YAML config file (`config.yaml`) to persist settings between sessions.
 
+### Create a Config File
+
+Generate a default config with all options documented:
+
+```bash
+urkit init                          # writes config.yaml in CWD
+urkit init --output station_a.yaml  # custom path
+urkit init --force                  # overwrite if exists
+```
+
+Edit the generated file with your robot IP and gripper settings.
+
 ### Location
 
-URKit searches for `config.yaml` in the current working directory, or an explicit path via `--config`.
+The CLI auto-loads `config.yaml` from the current working directory. Pass `--config` for a custom path.
 
 ### Keys
 
@@ -224,7 +277,19 @@ robot = URRobot.from_config({"robot_ip": "192.168.1.50", "gripper": "2f-85"})  #
 
 ## Interactive CLI
 
-URKit provides two CLI tools: **teach** for interactive robot control, and **points** for browsing saved waypoints.
+URKit provides three CLI tools: **init** to scaffold a config file, **teach** for interactive robot control, and **points** for browsing saved waypoints.
+
+### Init
+
+Generate a default config file with all options documented:
+
+```bash
+urkit init                          # writes config.yaml in CWD
+urkit init --output station_a.yaml  # custom path
+urkit init --force                  # overwrite if exists
+```
+
+### Teach Mode
 
 ### Teach Mode
 
@@ -603,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.0 → urkit-0.4.2}/README.md

@@ -30,12 +30,14 @@ The typical workflow: teach points with the pendant, write a few lines of Python
 
 - [Quick Start](#quick-start)
 - [Configuration](#configuration)
+  - [Create a Config File](#create-a-config-file)
   - [Location](#location)
   - [Keys](#keys)
   - [Gripper Config](#gripper-config)
   - [Saving Config](#saving-config)
   - [Programmatic](#programmatic)
 - [Interactive CLI](#interactive-cli)
+  - [Init](#init)
   - [Teach Mode](#teach-mode)
   - [Points Explorer](#points-explorer)
   - [Key Map](#key-map)
@@ -66,12 +68,40 @@ 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**: `☰` → `System` → `System` → `Network`. Set a static IP on the robot and a matching one on your PC. Both addresses must share the same first three octets (the network), with a different last octet (the host). For example:
-   - **Robot**: `192.168.1.50` / Subnet `255.255.255.0`
-   - **PC**: `192.168.1.1` / Netmask `255.255.255.0`
-   - Verify with `ping 192.168.1.50`. Connect via direct Ethernet cable or a switch.
+1. **Network**: Connect your PC to the robot via Ethernet cable (direct) or a switch.
+
+   First, configure the robot: `☰` → `System` → `System` → `Network`. Set a static IP, e.g., `192.168.1.50` / Subnet `255.255.255.0`.
+
+   Then set a matching static IP on your PC. The exact IP can be anything, as long as the first three octets match the robot's network and the last octet is different:
+
+   **Linux**:
+   - Open `Settings` → `Network` → click the gear icon next to `Wired`
+   - Go to `IPv4` tab → change `Automatic (DHCP)` to `Manual`
+   - Enter Address: `192.168.1.1`, Netmask: `255.255.255.0`
+   - Click `Apply`, then toggle the connection off and on
+
+   **macOS**:
+   - Open `System Settings` → `Network` → click `Ethernet` (or your adapter)
+   - Click `Details...` next to the adapter name → `TCP/IP`
+   - Set `Configure IPv4` to `Manually`
+   - Enter IP: `192.168.1.1`, Subnet Mask: `255.255.255.0`
+   - Click `OK`
+
+   **Windows**:
+   - Open `Settings` → `Network & internet` → `Ethernet`
+   - Click the adapter name (e.g., `Ethernet`) at the top
+   - Under `IP settings`, click `Edit` → select `Manual`
+   - Toggle `IPv4` On, enter IP: `192.168.1.1`, Subnet mask: `255.255.255.0`
+   - Click `Save`
+
+   Verify connectivity: `ping 192.168.1.50`.
 2. **Remote Control**: `☰` → `System` → `Remote Control`: Enable. Press the remote/local button on the pendant.
 3. **Security**: `☰` → `Security` → `Services`: enable RTDE and disable EtherNet/IP, PROFINET, or MODBUS if they're claiming RTDE registers. Save and restart.
 
@@ -96,9 +126,20 @@ robot.gripper.open()
 
 The typical workflow:
 
-1. **Teach points.** Use the CLI to position the robot and save named waypoints.
-2. **Write code.** Create a robot, move to points by name, apply offsets, run sequences.
-3. **Iterate.** Add more points, tweak your code, repeat.
+1. **Scaffold config.** Run `urkit init` to create a default `config.yaml`.
+2. **Edit it.** Set your robot IP, gripper type, and other settings.
+3. **Teach points.** Run `urkit teach` (auto-loads config) to position the robot and save waypoints.
+4. **Write code.** Load the config and move to points by name:
+
+```python
+from urkit import URRobot
+
+robot = URRobot.from_config("config.yaml")
+robot.move_to("home")
+robot.move_to("pick", offset_z=0.05)
+```
+
+5. **Iterate.** Add more points, tweak your code, repeat.
 
 ---
 
@@ -106,9 +147,21 @@ The typical workflow:
 
 URKit uses a YAML config file (`config.yaml`) to persist settings between sessions.
 
+### Create a Config File
+
+Generate a default config with all options documented:
+
+```bash
+urkit init                          # writes config.yaml in CWD
+urkit init --output station_a.yaml  # custom path
+urkit init --force                  # overwrite if exists
+```
+
+Edit the generated file with your robot IP and gripper settings.
+
 ### Location
 
-URKit searches for `config.yaml` in the current working directory, or an explicit path via `--config`.
+The CLI auto-loads `config.yaml` from the current working directory. Pass `--config` for a custom path.
 
 ### Keys
 
@@ -198,7 +251,19 @@ robot = URRobot.from_config({"robot_ip": "192.168.1.50", "gripper": "2f-85"})  #
 
 ## Interactive CLI
 
-URKit provides two CLI tools: **teach** for interactive robot control, and **points** for browsing saved waypoints.
+URKit provides three CLI tools: **init** to scaffold a config file, **teach** for interactive robot control, and **points** for browsing saved waypoints.
+
+### Init
+
+Generate a default config file with all options documented:
+
+```bash
+urkit init                          # writes config.yaml in CWD
+urkit init --output station_a.yaml  # custom path
+urkit init --force                  # overwrite if exists
+```
+
+### Teach Mode
 
 ### Teach Mode
 
@@ -577,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.0 → urkit-0.4.2}/pyproject.toml

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

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

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

{urkit-0.4.0 → urkit-0.4.2}/src/urkit/__main__.py

@@ -12,6 +12,7 @@ from __future__ import annotations
 import argparse
 import sys
 
+from urkit.cli.init import init_command
 from urkit.cli.teach import teach_command
 from urkit.cli.points import points_command
 
@@ -25,6 +26,24 @@ def main() -> None:
 
     subparsers = parser.add_subparsers(dest="command", help="Available commands")
 
+    # init subcommand
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Scaffold a default config.yaml",
+    )
+    init_parser.add_argument(
+        "--output",
+        type=str,
+        default="config.yaml",
+        help="Output path (default: config.yaml in CWD)",
+    )
+    init_parser.add_argument(
+        "--force",
+        action="store_true",
+        default=False,
+        help="Overwrite existing file",
+    )
+
     # teach subcommand
     teach_parser = subparsers.add_parser(
         "teach",
@@ -113,7 +132,9 @@ def main() -> None:
         parser.print_help()
         sys.exit(1)
 
-    if args.command == "teach":
+    if args.command == "init":
+        init_command(args)
+    elif args.command == "teach":
         teach_command(args)
     elif args.command == "points":
         points_command(args)

{urkit-0.4.0 → 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.2/src/urkit/cli/init.py

@@ -0,0 +1,83 @@
+"""urkit init — scaffold a default config.yaml file.
+
+Generates a commented config file with all available options so the
+user can edit it for their setup.
+
+Usage:
+    urkit init                          # writes config.yaml in CWD
+    urkit init --output station_a.yaml  # custom path
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_DEFAULT_TEMPLATE = """\
+# urkit config — edit and save as config.yaml
+# Generated by: urkit init
+#
+# Load it:
+#   Python:  robot = URRobot.from_config("config.yaml")
+#   CLI:     urkit teach  (auto-loads config.yaml)
+#   CLI:     urkit teach --config station_a.yaml
+
+# Robot IP address (required)
+robot_ip: 192.168.1.50
+
+# Path to SQLite points database (optional, created if missing)
+points_path: points.db
+
+# Gripper preset (optional)
+# Built-in: hand-e, 2f-85, 2f-140
+# Digital I/O: digital
+# Omit or set to none for no gripper
+gripper: none
+
+# Gripper overrides (optional)
+gripper_config:
+    # Physical properties (override preset defaults)
+    # mass: 1.0  # kg
+    # center_of_gravity: [0.0, 0.0, 0.0]  # [x, y, z] in meters
+    # tcp_offset: [0.0, 0.0, 0.175, 0.0, 0.0, 0.0]  # [x, y, z, rx, ry, rz]
+
+    # Robotiq-specific (hand-e, 2f-85, 2f-140)
+    # force: 100  # grip force 0-100
+    # speed: 100  # movement speed 0-100
+    # max_mm: 85  # max finger travel (e.g. 85 for 2F-85)
+
+    # Digital gripper
+    # pin: 0  # digital output pin
+    # close_on_high: true  # true=HIGH closes, false=LOW closes
+
+# IK reference posture (optional)
+# Set to a saved point name to prevent elbow/wrist flipping between moves
+# ik_reference: home
+
+# Default motion parameters (optional)
+# default_vel: 0.5  # m/s
+# default_acc: 0.3  # m/s²
+
+# Expert mode (optional) — disable safety speed clamping in CLI
+# expert_mode: false
+"""
+
+
+def init_command(args: object) -> None:
+    """Execute the init command to scaffold a default config file.
+
+    Args:
+        args: Parsed arguments with 'output' and 'force' attributes.
+    """
+    output = Path(getattr(args, "output", "config.yaml") or "config.yaml")
+    force = getattr(args, "force", False)
+
+    if output.exists() and not force:
+        print(f"Error: {output} already exists.")
+        print("  Remove it first or use --force to overwrite.")
+        sys.exit(1)
+
+    output.write_text(_DEFAULT_TEMPLATE)
+    print(f"Created {output}")
+    print("Edit it with your robot IP and gripper settings, then run:")
+    print("  urkit teach")

{urkit-0.4.0 → 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")