urkit 0.3.25__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urkit
-Version: 0.3.25
+Version: 0.4.0
 Summary: Universal Robots e-Series control toolkit built on ur_rtde
 Author: URKit Contributors
 License: MIT
@@ -28,15 +28,39 @@ Requires-Dist: rich>=15
 
 [![PyPI](https://img.shields.io/pypi/v/urkit.svg)](https://pypi.org/project/urkit/)
 
-**URKit** is a Python toolkit for [Universal Robots](https://www.universal-robots.com/) e-Series robots that makes the common stuff simple and gets out of the way for everything else.
+**URKit** makes it easy to get a Universal Robots e-Series robot moving from Python.
 
-Built on [`ur_rtde`](https://sdurobotics.gitlab.io/ur_rtde/), it packages the operations you reach for most: connecting, moving to named points, gripper control, telemetry, and I/O, while exposing the raw RTDE interfaces for anything deeper.
+## What it is
+
+A thin layer over [`ur_rtde`](https://sdurobotics.gitlab.io/ur_rtde/) that handles the common stuff: connecting, teaching named points, moving between them, gripper control, telemetry. Raw RTDE interfaces are exposed for anything deeper.
+
+No .urp files, no Dashboard API, no extra programs to run on the robot. Just connect over the network and go. Handles power-on, brake release, and RTDE setup in the constructor so you don't have to.
+
+Comes with an interactive teach pendant CLI for positioning the robot and saving waypoints, plus a Python API for scripting motion, gripper control, I/O, and telemetry.
+
+## When to use this
+
+Projects where the robot is part of something bigger. Computer vision, machine learning, sensor fusion, data logging. If your project lives in Python, keep the robot control in Python too.
+
+Built for labs and research setups where you need to get the robot moving fast and integrate it with other software. Not designed as a drop-in replacement for Polyscope in production cells, but perfectly capable for anything that runs from a PC.
+
+## How it works
+
+Use the CLI to position the robot and save named waypoints. Then reference them by name in your code: move to points, apply offsets, run sequences. Points are stored in a local SQLite database, no robot-side setup needed.
+
+The typical workflow: teach points with the pendant, write a few lines of Python to string them together, run it. Add vision, add sensors, add logic. The robot is just one component in your pipeline.
 
 ---
 
 ## Table of Contents
 
 - [Quick Start](#quick-start)
+- [Configuration](#configuration)
+  - [Location](#location)
+  - [Keys](#keys)
+  - [Gripper Config](#gripper-config)
+  - [Saving Config](#saving-config)
+  - [Programmatic](#programmatic)
 - [Interactive CLI](#interactive-cli)
   - [Teach Mode](#teach-mode)
   - [Points Explorer](#points-explorer)
@@ -46,8 +70,10 @@ Built on [`ur_rtde`](https://sdurobotics.gitlab.io/ur_rtde/), it packages the op
   - [Grippers](#grippers)
   - [Points & Motion](#points--motion)
   - [Telemetry](#telemetry)
+- [More API](#more-api)
   - [Digital I/O](#digital-io)
-- [Configuration](#configuration)
+  - [Geometry](#geometry)
+  - [Robot Lifecycle](#robot-lifecycle)
 - [Advanced](#advanced)
   - [Raw RTDE Access](#raw-rtde-access)
   - [Connection Lifecycle](#connection-lifecycle)
@@ -62,7 +88,7 @@ Built on [`ur_rtde`](https://sdurobotics.gitlab.io/ur_rtde/), it packages the op
 pip install -U urkit
 ```
 
-The `-U` (upgrade) flag ensures you always get the latest version — this project is in early development and changes frequently.
+The `-U` (upgrade) flag ensures you always get the latest version. This project is in early development and changes frequently.
 
 Requires Python 3.8+ and a Universal Robots e-Series (UR3e to UR30).
 
@@ -102,6 +128,100 @@ The typical workflow:
 
 ---
 
+## Configuration
+
+URKit uses a YAML config file (`config.yaml`) to persist settings between sessions.
+
+### Location
+
+URKit searches for `config.yaml` in the current working directory, or an explicit path via `--config`.
+
+### Keys
+
+| Key | Description | Example |
+|-----|-------------|---------|
+| `robot_ip` | Robot IP address | `192.168.1.50` |
+| `points_path` | Path to SQLite points database | `points.db` |
+| `gripper` | Gripper preset name | `hand-e`, `2f-85`, `2f-140`, `digital` |
+| `ik_reference` | IK reference posture (prevents elbow flipping) | `home` |
+| `default_vel` | Default linear velocity (m/s) | `0.5` |
+| `default_acc` | Default linear acceleration (m/s²) | `0.3` |
+| `expert_mode` | Disable safety speed clamping | `false` |
+
+### Gripper Config
+
+Built-in preset with overrides:
+
+```yaml
+gripper: hand-e
+gripper_config:
+  force: 50
+  speed: 80
+```
+
+Digital I/O gripper:
+
+```yaml
+gripper: digital
+gripper_config:
+  pin: 3
+  close_on_high: true
+```
+
+Custom gripper (arbitrary payload + TCP offset, no backend):
+
+```yaml
+gripper:
+  mass: 0.5
+  center_of_gravity: [0.0, 0.0, 0.0]
+  tcp_offset: [0.0, 0.0, 0.175, 0.0, 0.0, 0.0]
+  backend: none
+```
+
+Override physical properties on a built-in preset:
+
+```yaml
+gripper: 2f-85
+gripper_config:
+  mass: 1.2
+  center_of_gravity: [0.0, 0.0, 0.07]
+  tcp_offset: [0.0, 0.0, 0.200, 0.0, 0.0, 0.0]
+```
+
+### CLI Override Precedence
+
+1. **CLI flags.** `urkit teach 192.168.1.50 --gripper none`
+2. **Config file.** Values from `config.yaml`
+3. **Built-in defaults.** `points.db`, no gripper, 0.5 m/s velocity
+
+### Saving Config
+
+The CLI **never** modifies your config file automatically. Press **Y** inside the teach pendant to save. This way you only save settings you've actually tested.
+
+```bash
+urkit teach 192.168.1.50 --gripper hand-e  # test, then press Y
+urkit teach                               # next time: reads from config
+```
+
+Multiple workcells:
+
+```bash
+urkit teach --config station_a.yaml   # press Y to save
+urkit teach --config station_b.yaml   # separate config
+```
+
+### Programmatic
+
+```python
+from urkit import URRobot
+
+robot = URRobot.from_config("config.yaml")
+robot = URRobot.from_config("config.yaml", ip="10.0.0.50")  # override IP
+robot = URRobot.from_config({"robot_ip": "192.168.1.50", "gripper": "2f-85"})  # dict, no file
+```
+
+---
+
 ## Interactive CLI
 
 URKit provides two CLI tools: **teach** for interactive robot control, and **points** for browsing saved waypoints.
@@ -192,7 +312,6 @@ All movement and orientation keys support **hold-to-repeat**.
         <tr><td><code>V</code></td><td>Set position (mm)</td></tr>
         <tr><td><code>6</code></td><td>Set speed (0-100)</td></tr>
         <tr><td><code>7</code></td><td>Set force (0-100)</td></tr>
-        <tr><td colspan="3">Gripper line shows: `Connected 25.0mm (50%) F=100 S=100`</td></tr>
       </table>
     </td>
     <td align="center" style="width:33%">
@@ -208,10 +327,11 @@ All movement and orientation keys support **hold-to-repeat**.
     <td align="center" style="width:34%">
       <table>
         <tr><th>Key</th><th>Action</th></tr>
-        <tr><td><code>F</code></td><td>Freedrive (OFF → ALL → XYZ+Rz)</td></tr>
+        <tr><td><code>F</code></td><td>Freedrive toggle (ALL ↔ XYZ)</td></tr>
+        <tr><td><code>3</code></td><td>Freedrive axis menu (toggle individual axes)</td></tr>
         <tr><td><code>M</code></td><td>Toggle frame (BASE / TOOL)</td></tr>
         <tr><td><code>N</code></td><td>Go To mode (Cartesian / Joint)</td></tr>
-        <tr><td><code>T</code></td><td>Orient TCP down (180°)</td></tr>
+        <tr><td><code>T</code></td><td>Open TCP orient submenu (6 directions)</td></tr>
         <tr><td><code>Y</code></td><td>Save config to file</td></tr>
         <tr><td><code>ESC</code></td><td>Exit</td></tr>
       </table>
@@ -224,10 +344,10 @@ All movement and orientation keys support **hold-to-repeat**.
 The teach pendant shows live joint angles alongside TCP position and orientation:
 
 ```
- Position      X=+0.432  Y=+0.111  Z=+0.227
- Orientation   R=+131.3  P=-121.0  Y= +8.0
- Joints        J1=+150.0  J2=+020.0  J3=+160.0
-               J4=+050.0  J5=-080.0  J6=+157.0
+ Position     X=+0.432  Y=+0.111  Z=+0.227
+ Orientation  R=+131.3  P=-121.0  Y=  +8.0
+ Joints       J1=+150.0  J2=+ 20.0  J3=+160.0
+              J4=+ 50.0  J5=- 80.0  J6=+157.0
 ```
 
 Joint angles color-code proximity to mechanical limits:
@@ -237,20 +357,20 @@ Joint angles color-code proximity to mechanical limits:
 
 UR e-Series joint limits:
 
-| Joint | Range | Notes |
-|-------|-------|-------|
-| J1 (shoulder pan) | ±360° | Full rotation |
-| J2 (shoulder lift) | ±360° | Full rotation |
-| J3 (elbow) | ±180° | Physically restricted — shoulder lift gets in the way |
-| J4 (wrist 1) | ±360° | Full rotation |
-| J5 (wrist 2) | ±360° | Full rotation |
-| J6 (wrist 3) | ±360° | Tool flange unlimited rotation |
+| Joint | Range |
+|-------|-------|
+| J1 (shoulder pan) | ±360° |
+| J2 (shoulder lift) | ±360° |
+| J3 (elbow) | ±360° |
+| J4 (wrist 1) | ±360° |
+| J5 (wrist 2) | ±360° |
+| J6 (wrist 3) | ±360° |
+
 
-Thresholds scale with each joint's range, so warning zones feel proportional across all joints.
 
 ### Safety
 
-By default, **Go To** and **TCP Down** movements use a slow velocity (0.125 m/s) so its safer for anyone standing near the robot. The user's speed slider still applies as a global multiplier on top of this.
+By default, **Go To** and **TCP orient** movements use a slow velocity (0.125 m/s) so its safer for anyone standing near the robot. The user's speed slider still applies as a global multiplier on top of this.
 
 Delta movements (W/S/A/D/Q/E) use step-size-based velocities that scale with the speed slider set by the user.
 
@@ -289,12 +409,9 @@ robot = URRobot(
 )
 ```
 
-From a config file:
+See [Configuration](#configuration) for `from_config()` usage.
 
-```python
-robot = URRobot.from_config("config.yaml")
-robot = URRobot.from_config("config.yaml", ip="10.0.0.50")  # override IP
-```
+The constructor takes a few seconds on first call: it validates the connection, checks remote mode, powers on the robot, releases brakes, and connects RTDE. Subsequent calls are faster if the robot is already running.
 
 ### Grippers
 
@@ -302,21 +419,25 @@ Three built-in presets:
 
 | Preset | Description |
 |--------|-------------|
-| `ROBOTIQ_HAND_E` | Robotiq 2F-140-E (Hand-E series) |
+| `ROBOTIQ_HAND_E` | Robotiq Hand-E (2F-85-E) |
 | `ROBOTIQ_2F_85` | Robotiq 2F-85 |
 | `ROBOTIQ_2F_140` | Robotiq 2F-140 |
 
 ```python
 robot.gripper.activate()              # required before open/close (Robotiq only)
+robot.gripper.deactivate()            # deactivate (Robotiq only)
 robot.gripper.is_activated()          # check activation state
 
 robot.gripper.open()                  # fully open (blocking by default)
 robot.gripper.close()                 # fully closed, stops on contact
-robot.gripper.open(wait=False)        # non-blocking return
-robot.gripper.set_position_mm(20)     # 20mm open (Robotiq only, 0 = closed)
-robot.gripper.set_position_percent(50) # 50% open (Robotiq only, 0 = open, 100 = closed)
+robot.gripper.open(wait=False)        # non-blocking return (waits for position)
+robot.gripper.set_position_mm(20)     # 20mm open (Robotiq only, 0 = fully closed)
+robot.gripper.set_position_percent(50) # 50% open (Robotiq only, 0 = fully open, 100 = fully closed)
 robot.gripper.set_force(50)           # grip force: 0-100 (Robotiq only)
 robot.gripper.set_speed(80)           # movement speed: 0-100 (Robotiq only)
+
+robot.gripper.get_position_mm()       # last commanded position in mm
+robot.gripper.max_travel_mm()         # max finger travel (e.g. 85.0 for 2F-85)
 ```
 
 Override preset values for custom fingers:
@@ -325,6 +446,19 @@ Override preset values for custom fingers:
 robot = URRobot(ip="192.168.1.50", points="points.db", gripper=ROBOTIQ_HAND_E, max_mm=120)
 ```
 
+Override physical properties (e.g., custom fingers or added hardware change the weight):
+
+```python
+robot = URRobot(
+    ip="192.168.1.50",
+    points="points.db",
+    gripper=ROBOTIQ_HAND_E,
+    mass=1.2,                          # override preset mass
+    center_of_gravity=[0.0, 0.0, 0.07], # override CoG
+    tcp_offset=[0.0, 0.0, 0.180, 0, 0, 0],  # override TCP offset
+)
+```
+
 #### Digital I/O Grippers
 
 Robotiq grippers use a serial protocol over the robot's RS485 port. If you have a suction cup, solenoid, or any actuator controlled by a single digital output pin, use `DigitalGripperConfig` instead. It just turns that pin on (close) and off (open).
@@ -360,6 +494,7 @@ robot.move_to("pick")                      # linear move (default)
 robot.move_to("pick", linear=False)        # joint move
 robot.move_to("pick", vel=1.0, acc=0.5)    # override speed
 robot.move_to("pick", asynchronous=True)   # non-blocking, returns immediately
+robot.move_to([0.5, 0, 0.3, 0, 0, 0])      # raw pose (no points DB needed)
 ```
 
 - **Linear (moveL):** TCP moves in a straight line. Predictable path, slower near complex orientations.
@@ -377,20 +512,20 @@ robot.move_to("pick", asynchronous=True)
 while robot.is_moving():
     time.sleep(0.01)
 
-# Or cancel mid-move
+# Or cancel mid-move (see [Speed Control](#speed-control) for `stop()`)
 robot.move_to("pick", asynchronous=True)
 while robot.is_moving():
     if should_cancel:
-        robot.stop()  # sends stopL + stopJ
+        robot.stop()
         break
     time.sleep(0.01)
 ```
 
-**Teach pendant Go To** uses this pattern internally — Space cancels the move and returns to the menu.
+**Teach pendant Go To** uses this pattern internally. Space cancels the move and returns to the menu.
 
 #### Pose Format
 
-A pose is `[x, y, z, rx, ry, rz]`: position in meters and orientation as a **rotation vector** (axis-angle in radians). This is not RPY (roll/pitch/yaw). The teach pendant displays RPY in degrees, which is a different representation. Values you see on the pendant won't match `get_tcp_pose()` directly.
+A pose is `[x, y, z, rx, ry, rz]`: position in meters and orientation as a **rotation vector** (axis-angle in radians). This is not RPY (roll/pitch/yaw). The teach pendant displays RPY in degrees, which is a different representation. Values you see on the pendant won't match `get_current_point()` directly.
 
 #### Offsets
 
@@ -407,8 +542,8 @@ robot.move_to("pick", offset=[0, 0, 0.05, 0, 0.1, 0])  # full with rotation
 Get a pose without moving. Useful for logging, comparisons, or custom motion:
 
 ```python
-pose = robot.get_pose("pick")
-pose = robot.get_pose("pick", offset=[0, 0, 0.05, 0, 0, 0])  # with offset
+point = robot.get_point("pick")
+point = robot.get_point("pick", offset=[0, 0, 0.05, 0, 0, 0])  # with offset
 robot.move_to(pose)  # move to the resolved pose later
 ```
 
@@ -424,11 +559,11 @@ robot.move_relative(delta_z=0.05)  # 5cm along tool Z
 - **BASE** (default): delta relative to robot base
 - **TOOL**: delta relative to TCP orientation
 
-#### IK Reference (recommended)
+#### IK Reference
 
 **Problem:** When the robot has multiple valid joint configurations to reach the same TCP pose (e.g., elbow up vs. elbow down), it can unexpectedly flip its posture between moves. This is called an **IK ambiguity** and it causes "weird" movements where the robot takes a strange path or flips its wrist.
 
-**Solution:** Set an **IK reference posture** — a saved point that defines your preferred arm configuration. The robot then stays close to that posture for all moves.
+**Solution:** Set an **IK reference posture**, a saved point that defines your preferred arm configuration. The robot then stays close to that posture for all moves.
 
 ```python
 # 1. Put the robot in your preferred posture (e.g., "home")
@@ -436,7 +571,7 @@ robot.move_relative(delta_z=0.05)  # 5cm along tool Z
 # 3. Set as IK reference:
 robot.ik_reference = "home"
 
-# Now all moves stay close to that posture — no elbow flipping
+# Now all moves stay close to that posture, no elbow flipping
 robot.move_to("pick")
 robot.move_to("place")
 robot.move_relative(delta_z=-0.05)
@@ -449,7 +584,7 @@ robot_ip: 192.168.1.50
 ik_reference: home    # prevents weird elbow/wrist flips
 ```
 
-**How it works:** The robot's inverse kinematics solver uses the reference posture as a bias (`qnear`). The TCP still reaches the exact same pose, but the arm configuration (elbow up/down, wrist orientation) stays consistent with your reference.
+**How it works:** The robot's inverse kinematics solver uses the reference posture as a bias (`qnear`). The TCP still reaches the exact same pose, but the arm configuration (elbow up/down, wrist orientation) stays consistent with your reference. Under the hood, poses are resolved to joint angles and sent as `moveJ` instead of `moveL`.
 
 **Per-move override:**
 
@@ -459,14 +594,17 @@ robot.move_to("weird_pose", ik_reference=None) # one move without it
 robot.move_to("back", ik_reference="current") # use current joints
 ```
 
-**When to use it:** Almost always. If you've ever seen the robot move in a way that looked "wrong" or flipped its elbow unexpectedly, this is what fixes it. Set it once in config.yaml and forget about it.
+**When to use it:**
 
-#### Points are tool-agnostic
+- **Use it** for sequences of positional moves between waypoints: pick/place paths, assembly sequences, anything where the robot travels between distant points. It prevents elbow/wrist flipping.
+- **Don't use it** for rotation-heavy movements (orientation adjustments, fine-tuning angles). The `qnear` seed can push joints into unexpected configs for pure rotations, and you lose the controller's native Cartesian trajectory planner (lookahead, smoothing). Set `ik_reference=None` for these moves.
 
-Points are stored in the active TCP frame, so they work with any tool. If you swap grippers and set the correct TCP offset, your saved points remain valid.
+Default is `None` (controller handles IK natively). Set it globally when most of your moves are positional, and override per-move when you need rotations.
 
 #### Point Management
 
+Points are stored in the active TCP frame, so they work with any tool. Swap grippers and your saved points stay valid.
+
 ```python
 robot.save_point("here")
 robot.point_names()           # ["home", "pick", "place"]
@@ -481,16 +619,36 @@ robot.import_points("backup.json")
 ```python
 robot.move_relative(delta_y=0.01)  # 1cm along Y
 robot.move_relative(delta_z=0.05, frame=MoveFrame.TOOL)  # 5cm along tool Z
-robot.move_relative([0, 0.01, 0, 0, 0, 0])
+robot.move_relative([0, 0.01, 0, 0, 0, 0])  # full 6-element delta
 ```
 
+Individual delta parameters (`delta_x`, `delta_y`, `delta_z`, `delta_rx`, `delta_ry`, `delta_rz`) are mutually exclusive with the `delta` list. Use one or the other.
+
 #### Sequences
 
 ```python
-# Chain multiple moves into one call
-robot.move_sequence(["a", "b", "c"])
+# Both styles work:
+robot.move_sequence("a", "b", "c")          # variadic
+robot.move_sequence(["a", "b", "c"])        # list
+```
+
+`move_sequence` builds a path from all targets and executes it in a single call with blending. Requires at least 2 targets. Two modes:
+
+**With `ik_reference`** (positional paths): All poses resolve to joints using chained inverse kinematics. The first pose resolves relative to the reference, the second relative to the first's resolved joints, and so on. Executed as a single `moveJ(path)` call. Keeps the arm configuration consistent (no elbow flipping):
+
+```python
+robot.ik_reference = "home"
+robot.move_sequence(["a", "b", "c"], blend_radius=0.02)  # 2cm blend
+```
+
+**Without `ik_reference`** (Cartesian path): Builds a blended `moveL(path)`. The controller handles IK natively, better for rotation-heavy sequences where `ik_reference` causes unexpected joint behavior:
+
+```python
+robot.move_sequence(["a", "b", "c"], blend_radius=0.02)  # blended Cartesian path
 ```
 
+Before sending any move, it checks that each pose has a valid IK solution. Unreachable poses raise `MotionError`. If a named point doesn't exist, it raises `PointError` instead of silently falling back.
+
 #### Contact Detection
 
 ```python
@@ -513,8 +671,8 @@ robot.move_until_contact(speed_z=-0.02, timeout=10.0, max_distance=0.2)
 for _ in range(3):
     if robot.move_until_contact(speed_z=-0.02, timeout=10.0, max_distance=0.2):
         break  # contact detected
-    # No contact — back off and retry
-    robot.move_by(z=0.01)
+    # No contact, back off and retry
+    robot.move_relative(delta_z=0.01)
 
 # Manual zero (e.g. before custom force-based logic)
 robot.zero_ft_sensor()
@@ -532,40 +690,41 @@ robot.move_velocity([0, 0, -0.02, 0, 0, 0], duration=1.0)
 from urkit import FreedriveMode
 
 robot.enable_freedrive()              # all 6 axes free
-robot.enable_freedrive(FreedriveMode.XYZ)      # linear axes + Rz rotation
-robot.enable_freedrive(FreedriveMode.ROTATION) # rotation only
+robot.enable_freedrive(FreedriveMode.XYZ)      # linear axes only (X, Y, Z)
+robot.enable_freedrive(FreedriveMode.ROTATION) # rotation only (Roll, Pitch, Yaw)
+robot.enable_freedrive([1, 1, 1, 1, 0, 0])    # custom: X+Y+Z+Roll+Pitch
 robot.disable_freedrive()             # disable before sending motion commands
 robot.is_freedrive_active             # check state
 ```
 
+**Teach pendant:** Press `F` to toggle freedrive (ALL ↔ XYZ). Press `3` to open the axis selection menu arrow keys navigate, space toggles each axis on/off, enter applies.
+
 #### Speed Control
 
 ```python
 robot.stop()                          # stop current move immediately (stopL + stopJ)
 robot.speed_stop()                    # stop velocity-controlled motion (not E-stop)
-robot.set_speed_slider(0.5)           # 50% velocity cap
-robot.get_speed_slider()              # read current slider (0.0-1.0)
+robot.speed_slider = 0.5           # 50% velocity cap
+robot.speed_slider              # read current slider (0.0-1.0)
 ```
 
 The speed slider controls the pendant's speed multiplier. It's global, persistent, and affects all motion commands.
 
 #### Changing Default Speed & Acceleration
 
-Override the constructor defaults at runtime — all subsequent moves pick up the new values:
+Override the constructor defaults at runtime. All subsequent moves pick up the new values:
 
 ```python
-robot.set_speed(0.1)   # slow for precision work
+robot.default_vel = 0.1   # slow for precision work
 robot.move_to("insert")
-robot.set_speed(0.5)   # back to normal
+robot.default_vel = 0.5   # back to normal
 
-robot.set_acc(0.05)    # gentle acceleration
+robot.default_acc = 0.05    # gentle acceleration
 
 robot.default_vel      # read current velocity (m/s)
 robot.default_acc      # read current acceleration (m/s²)
 ```
 
-Soft warnings log when values exceed typical robot limits (> 2 m/s for velocity, > 6 m/s² for acceleration). The controller may clamp aggressive values based on payload and configuration.
-
 #### Inverse Kinematics
 
 ```python
@@ -575,121 +734,124 @@ joints = robot.inverse_kinematics([0.5, 0, 0.3, 0, 0, 0])
 ### Telemetry
 
 ```python
-pose = robot.get_tcp_pose()           # [x, y, z, rx, ry, rz]
-joints = robot.get_joint_positions()  # [j0..j5]
-force = robot.get_tcp_force()         # [fx, fy, fz, mx, my, mz]
-mode = robot.get_robot_mode()         # "REMOTE_CONTROL", "SERVOING", etc.
-payload = robot.get_payload()         # kg
-robot.is_moving()                     # bool — any joint/TCP velocity non-zero
-robot.is_protective_stopped()         # bool
-robot.is_emergency_stopped()          # bool
-robot.current_point()                 # {"pose": [...], "joints": [...]}
-robot.is_at_pose(target)              # bool — TCP within 1mm / 0.5°
-robot.is_at_joints(target)            # bool — all joints within 0.001 rad
+pose = robot.get_current_point()           # [x, y, z, rx, ry, rz]
+pose = robot.get_current_point(offset_z=0.05)  # with offset
+joints = robot.get_joint_positions()       # [j0..j5]
+force = robot.get_tcp_force()              # [fx, fy, fz, mx, my, mz]
+mode = robot.get_robot_mode()              # "REMOTE_CONTROL", "SERVOING", etc.
+payload = robot.payload                    # kg
+robot.is_protective_stopped()              # bool
+robot.is_emergency_stopped()               # bool
 ```
 
-`is_moving()` is the simplest way to poll — `is_at_pose()` / `is_at_joints()` for precise target checking:
+#### Arrival Detection
+
+`is_moving()` tracks the target pose or joints stored by `move_to()` and compares against the current position. Returns `False` when within tolerance:
 
 ```python
 robot.move_to("pick", asynchronous=True)
 
-# Simple: wait until robot stops
+# Wait until arrived (default tolerances: 2mm position, ~2° orientation)
 while robot.is_moving():
     time.sleep(0.01)
 
-# Precise: check against specific target
-while not robot.is_at_pose(target_pose):
+# Tighter tolerances
+while robot.is_moving(position_tolerance=0.001, orientation_tolerance=0.017):
+    time.sleep(0.01)
+
+# Joint moves, tighter joint tolerance
+while robot.is_moving(joint_tolerance=0.001):
     time.sleep(0.01)
 ```
 
+For joint-space moves (when `ik_reference` is active or `linear=False`), `is_moving()` compares joint angles. For Cartesian moves, it compares TCP pose. When no target is set (e.g., after a relative move without `move_to`), it returns `False`.
+
+---
+
+## More API
+
+Less common but useful when you need them.
+
 ### Digital I/O
 
+Pins 0–7 are standard, 8–15 configurable, 16–17 tool.
+
 ```python
+# Outputs
 robot.set_digital_output(0, True)
 robot.set_digital_outputs({0: True, 1: False, 8: True})
-robot.set_digital_outputs(False)      # clear all
+robot.set_digital_outputs(False)      # clear all pins 0–15
+robot.get_digital_output(0)           # read back output state
 
+# Inputs
 robot.get_digital_input(0)
-robot.get_analog_input(0)
-robot.get_tool_input(0)
-
 robot.wait_for_input(0, True, timeout=10.0)  # block until pin 0 goes high
-```
-
----
 
-## Configuration
-
-URKit uses a YAML config file (`config.yaml`) to persist settings between sessions.
+# Analog
+robot.get_analog_input(0)             # read analog input (pin 0–1)
+robot.get_analog_output(0)            # read analog output (pin 0–1)
 
-### Location
+# Tool I/O
+robot.get_tool_input(0)               # tool digital input (pin 0–1)
+robot.get_tool_output(0)              # tool digital output (pin 0–1)
+```
 
-URKit searches for `config.yaml` in this order:
-1. Explicit path via `--config` flag or `load_config("path")`
-2. Project root (where `src/urkit` lives)
-3. Current working directory
+### Geometry
 
-### Keys
+Conversion utilities for rotation vectors, quaternions, and RPY angles (rxyz convention, same as UR teach pendant):
 
-| Key | Description | Example |
-|-----|-------------|---------|
-| `robot_ip` | Robot IP address | `192.168.1.50` |
-| `points_path` | Path to SQLite points database | `points.db` |
-| `gripper` | Gripper preset name | `hand-e`, `2f-85`, `2f-140`, `digital` |
-| `ik_reference` | IK reference posture (prevents elbow flipping) | `home` |
-| `default_vel` | Default linear velocity (m/s) | `0.5` |
-| `default_acc` | Default linear acceleration (m/s²) | `0.3` |
-| `expert_mode` | Disable safety speed clamping | `false` |
+```python
+from urkit import (
+    orient_tcp,
+    orient_tcp_down,
+    quat_to_rotvec,
+    quat_to_rpy,
+    rpy_to_quat,
+    rotvec_to_quat,
+)
 
-### Gripper Config
+# Orient TCP along an arbitrary direction (minimal rotation)
+new_pose = orient_tcp(current_pose, [0, 0, -1])  # point down
+new_pose = orient_tcp(current_pose, [1, 0, 0])   # point forward
 
-```yaml
-gripper: digital
-gripper_config:
-  pin: 3
-  close_on_high: true
-```
+# Orient TCP straight down (convenience wrapper)
+new_pose = orient_tcp_down(current_pose)
 
-```yaml
-gripper: hand-e
-gripper_config:
-  force: 50
-  speed: 80
+# Rotation conversions
+q = rotvec_to_quat([0, 0, 1.57])   # rotvec → quaternion (x, y, z, w)
+rv = quat_to_rotvec(q)              # quaternion → rotvec
+rpy = quat_to_rpy(q)                # quaternion → RPY (radians)
+q = rpy_to_quat(0, 0, 1.57)        # RPY → quaternion
 ```
 
-### CLI Override Precedence
-
-1. **CLI flags.** `urkit teach 192.168.1.50 --gripper none`
-2. **Config file.** Values from `config.yaml`
-3. **Built-in defaults.** `points.db`, no gripper, 0.5 m/s velocity
+### Robot Lifecycle
 
-### Saving Config
-
-The CLI **never** modifies your config file automatically. Press **Y** inside the teach pendant to save. This way you only save settings you've actually tested.
+Manual power and brake control via the Dashboard:
 
-```bash
-urkit teach 192.168.1.50 --gripper hand-e  # test, then press Y
-urkit teach                               # next time: reads from config
+```python
+robot.power_on()          # power on (skips if already on)
+robot.release_brakes()    # release brakes (enable control)
+robot.recover()           # clear protective stop
+robot.power_off()         # power off
 ```
 
-Multiple workcells:
+The constructor handles all of this automatically. Use these methods when you need fine-grained control (e.g., recovering from a safety stop without recreating the robot).
 
-```bash
-urkit teach --config station_a.yaml   # press Y to save
-urkit teach --config station_b.yaml   # separate config
+TCP and payload can be set manually (gripper presets do this automatically):
+
+```python
+robot.tcp_offset = [0, 0, 0.15, 0, 0, 0]
+robot.set_payload(1.5, [0, 0, 0.05])  # mass (kg), center of gravity [x, y, z]
 ```
 
-### Programmatic
+Clean shutdown:
 
 ```python
-from urkit import load_config, resolve_config
-
-config = load_config()                          # auto-resolve
-config = load_config("/path/to/my.yaml")        # explicit path
-path = resolve_config()                         # returns Path or None
-robot = URRobot.from_config({"robot_ip": "192.168.1.50", "gripper": "2f-85"})
+robot.disconnect()  # close RTDE, Dashboard, points DB, gripper
 ```
 
+`disconnect()` is called automatically on garbage collection. Call it explicitly to release resources immediately.
+
 ---
 
 ## Advanced
@@ -713,8 +875,6 @@ robot.connection_lost       # bool: check if RTDE dropped
 robot.reconnect_rtde()      # reconnect after a drop
 ```
 
-`disconnect()` is called automatically when the robot object is garbage collected.
-
 ### Error Handling
 
 ```python
@@ -742,13 +902,8 @@ Common runtime errors:
 
 When the robot enters protective stop or the RTDE connection drops, motion commands raise `URKitConnectionError` and the program should exit. The CLI handles this automatically.
 
-### Connection Notes
-
-The `URRobot` constructor takes a few seconds on first call: it validates the connection, checks remote mode, powers on the robot, releases brakes, and connects RTDE. Subsequent calls are faster if the robot is already running.
-
 ---
 
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for the full version history.
-