urkit 0.5.0__tar.gz → 0.6.0__tar.gz

{urkit-0.5.0 → urkit-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urkit
-Version: 0.5.0
+Version: 0.6.0
 Summary: Universal Robots e-Series control toolkit built on ur_rtde
 Author: URKit Contributors
 License: MIT
@@ -96,8 +96,8 @@ 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
+- **Linux, Windows**: fully supported. The interactive CLIs (`urkit teach`, `urkit points`) are tested on both platforms
+- **macOS**: runs the same POSIX terminal code path as Linux (termios/select); there is no macOS-specific code
 
 ### Robot Setup (one-time)
 
@@ -138,7 +138,7 @@ That's it. No `.urp` files to run, no extra programs needed.
 If you have a Robotiq gripper, install the **Robotiq Gripper Control** URCap first: download from [robotiq.com/support](https://robotiq.com/support), copy the `.urcap` to a USB drive, and install via `☰` → `Settings` → `System` → `URCaps`.
 
 ```python
-from urkit import URRobot, ROBOTIQ_HAND_E  # or ROBOTIQ_2F_85, ROBOTIQ_2F_140, or gripper=None
+from urkit import URRobot, ROBOTIQ_HAND_E  # or ROBOTIQ_2F_85, ROBOTIQ_2F_140, ROBOTIQ_EPICK_SINGLE_S, or gripper=None
 
 robot = URRobot(ip="192.168.1.50", points="points.db", gripper=ROBOTIQ_HAND_E)
 robot.gripper.activate()
@@ -146,8 +146,10 @@ robot.gripper.activate()
 robot.move_to("home")
 robot.move_to("pick", dz=0.05)  # 5cm above
 robot.gripper.close()
+robot.set_held_payload(0.05)    # picked up 50 g: arm compensates gravity
 robot.move_to("place")
 robot.gripper.open()
+robot.set_held_payload(0)       # released: back to gripper-only payload
 ```
 
 The typical workflow:
@@ -195,12 +197,14 @@ The CLI auto-loads `config.yaml` from the current working directory. Pass `--con
 |-----|-------------|---------|
 | `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` |
+| `gripper` | Gripper preset name | `hand-e`, `2f-85`, `2f-140`, `epick-single-s`, `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` |
 
+The loader fails loudly with a reason when a config file exists but is wrong: malformed YAML (file + parse error), a document that is not a mapping, or unknown top-level keys (offending keys + the valid ones; usually a typo). The table above is the complete key set. The only silent case is a missing file, where the CLI runs on flags and built-in defaults.
+
 ### Gripper Config
 
 Built-in preset with overrides:
@@ -291,8 +295,6 @@ urkit init --force                  # overwrite if exists
 
 ### Teach Mode
 
-### Teach Mode
-
 The interactive teach pendant for moving the robot, saving points, and checking telemetry:
 
 ```bash
@@ -305,10 +307,10 @@ urkit teach                          # reads IP from config.yaml
 | Flag | Description |
 |------|-------------|
 | `ip` | Robot IP address (positional, overrides config) |
-| `--gripper` | Gripper preset: `2f-85`, `2f-140`, `hand-e`, `digital`, `none` |
+| `--gripper` | Gripper preset: `2f-85`, `2f-140`, `hand-e`, `epick-single-s`, `digital`, `none` |
 | `--gripper-pin` | Digital gripper output pin (default: 0) |
-| `--gripper-force` | Robotiq force 0-100 |
-| `--gripper-speed` | Robotiq speed 0-100 |
+| `--gripper-force` | 2F grip force 0-100 (EPick: use `max_vacuum` in `gripper_config`) |
+| `--gripper-speed` | 2F movement speed 0-100 (EPick: use `grip_timeout` in `gripper_config`) |
 | `--gripper-close-on-high` | Digital polarity: `true` or `false` |
 | `--points` | Path to `points.db` file (overrides config) |
 | `--config` | Path to config file (default: `config.yaml` in project root or CWD) |
@@ -374,9 +376,10 @@ All movement and orientation keys support **hold-to-repeat**.
         <tr><th>Key</th><th>Action</th></tr>
         <tr><td><code>X</code></td><td>Open</td></tr>
         <tr><td><code>C</code></td><td>Close</td></tr>
-        <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><code>V</code></td><td>Set position % (2F only; hidden for the EPick)</td></tr>
+        <tr><td><code>6</code></td><td>Set speed (2F) / min vacuum (EPick)</td></tr>
+        <tr><td><code>7</code></td><td>Set force (2F) / max vacuum (EPick)</td></tr>
+        <tr><td><code>9</code></td><td>Set held payload (kg, 0 = reset to base)</td></tr>
       </table>
     </td>
     <td align="center" style="width:33%">
@@ -409,10 +412,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=+ 20.0  J3=+160.0
-              J4=+ 50.0  J5=- 80.0  J6=+157.0
+ Position (mm) X= +432.0  Y= +111.0  Z= +227.0
+ 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:
@@ -480,13 +483,16 @@ The constructor takes a few seconds on first call: it validates the connection,
 
 ### Grippers
 
-Three built-in presets:
+Built-in presets:
 
 | Preset | Description |
 |--------|-------------|
 | `ROBOTIQ_HAND_E` | Robotiq Hand-E (2F-85-E) |
 | `ROBOTIQ_2F_85` | Robotiq 2F-85 |
 | `ROBOTIQ_2F_140` | Robotiq 2F-140 |
+| `ROBOTIQ_EPICK_SINGLE_S/L` | EPick + 1 cup (S = Ø40, L = Ø55) |
+| `ROBOTIQ_EPICK_DUAL_S/L` | EPick + 2-cup bracket (S = Ø40, L = Ø55) |
+| `ROBOTIQ_EPICK_QUAD_S/L` | EPick + 4-cup bracket (S = Ø40, L = Ø55) |
 
 ```python
 robot.gripper.activate()              # required before open/close (Robotiq only)
@@ -497,7 +503,7 @@ robot.gripper.open()                  # fully open (blocking by default)
 robot.gripper.close()                 # fully closed, stops on contact
 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_position_percent(50) # 50% open (2F; repurposed on the EPick, see below)
 robot.gripper.set_force(50)           # grip force: 0-100 (Robotiq only)
 robot.gripper.set_speed(80)           # movement speed: 0-100 (Robotiq only)
 
@@ -543,6 +549,83 @@ robot.gripper.close()   # turn pin 3 on
 
 `set_force()` and `set_speed()` are not available for digital grippers.
 
+#### EPick Vacuum Gripper
+
+The EPick presets drive a Robotiq EPick vacuum gripper (e-Series only) over the same RS485 Robotiq protocol as the 2F series, using the legacy Robotiq ASCII commands. They require the **Robotiq Gripper Control** URCap installed (same setup as the 2F presets).
+
+The semantics are inverted compared to the 2F grippers:
+
+```python
+robot.gripper.activate()          # required before open/close
+robot.gripper.close()             # grip: pump on, wait until an object is secured
+robot.gripper.open()              # release: pump off + blow-off, wait until the object is gone
+```
+
+`close()` does not return until the gripper has confirmed a secured object (see Detection below), and raises `GripperError` if no object is detected within the grip timeout. A failed grip leaves the vacuum on, so call `open()` to release before moving again. `open()` waits until the vacuum is lost (the object has dropped).
+
+Grip parameters (set at connect time, or changed between grips):
+
+```python
+robot.gripper.set_max_vacuum(60)    # max vacuum level, 20-100% (default 60, the Robotiq URCap default)
+robot.gripper.set_min_vacuum(40)    # min vacuum level, 10% up to the max vacuum (default 40)
+robot.gripper.set_grip_timeout(30)  # grip timeout in 100 ms units, 0-100 (default 30 = 3 s)
+```
+
+The ranges are enforced at construction and on every setter (max 20-100, min 10 up to the current max, timeout 0-100), and a parameter of one backend passed to another raises `GripperError` instead of being ignored (`force`/`speed` on the EPick, `max_vacuum`/`grip_timeout` on the 2F). The same names work in `config.yaml`:
+
+```yaml
+gripper: epick-single-s
+gripper_config:
+  max_vacuum: 70
+  grip_timeout: 40
+```
+
+With `set_max_vacuum(100)` the pump runs continuously and the gripper cannot confirm a grip; keep the max vacuum below 100% (60 works for typical cups and trays). The same physics applies at lower levels: if the max vacuum is higher than a leaky seal can reach, the pump keeps hunting and never enters the stable hold phase where the secured flag appears, so the grip times out (verified: a marginal-seal object gripped at 60/40 but timed out at 80/50 and 80/30). For leaky seals keep `max_vacuum` low and `min_vacuum` at or below what the seal sustains, not the other way around.
+
+`set_position_mm()`, `get_position_mm()`, and `max_travel_mm()` are not available: the EPick has no finger travel. `set_position_percent(p)` is repurposed as a one-shot vacuum grip: `p=0` releases, `1-100` grips at that vacuum level with the normal secured-object wait (the teach pendant does not expose this; use [6]/[7] and C).
+
+**Payload and TCP.** The bare generator body is 0.706 kg, CoG `[0, 0, 0.0515]`, TCP `[0, 0, 0.113, 0, 0, 0]` (Robotiq EPick manual, Table 6-4); cups and brackets change all three. The kits ship cups in two sizes (Ø 40 mm and Ø 55 mm), so there is one preset per bracket system + cup size (configurations without cups cannot grip and have no preset):
+
+| Preset | Config / CLI name | Setup |
+|--------|-------------------|-------|
+| `ROBOTIQ_EPICK_SINGLE_S` | `epick-single-s` | 1 small (Ø40) cup on the generator port |
+| `ROBOTIQ_EPICK_SINGLE_L` | `epick-single-l` | 1 large (Ø55) cup on the generator port |
+| `ROBOTIQ_EPICK_DUAL_S` | `epick-dual-s` | 2-cup bracket, small cups |
+| `ROBOTIQ_EPICK_DUAL_L` | `epick-dual-l` | 2-cup bracket, large cups |
+| `ROBOTIQ_EPICK_QUAD_S` | `epick-quad-s` | 4-cup bracket, small cups |
+| `ROBOTIQ_EPICK_QUAD_L` | `epick-quad-l` | 4-cup bracket, large cups |
+
+```python
+from urkit import URRobot, ROBOTIQ_EPICK_SINGLE_S
+
+robot = URRobot(ip="192.168.1.50", gripper=ROBOTIQ_EPICK_SINGLE_S)
+```
+
+The TCP z of each preset is the bottom of the cups, the limiting point for approach moves. The presets use the manual's Table 6-4 for the body and bracket stack, and the official Festo datasheets for the cups Robotiq ships (VASB-40-1/4-PUR-B: 30 g / 32 mm, VASB-55-1/4-PUR-B: 39 g / 39 mm); all-small combinations reproduce Table 6-4 exactly:
+
+| Preset | Mass (kg) | CoG z (m) | TCP z (m) |
+|--------|-----------|-----------|-----------|
+| body only (reference) | 0.706 | 0.0515 | 0.113 |
+| `ROBOTIQ_EPICK_SINGLE_S` | 0.736 | 0.0547 | 0.145 |
+| `ROBOTIQ_EPICK_SINGLE_L` | 0.745 | 0.0557 | 0.152 |
+| `ROBOTIQ_EPICK_DUAL_S` | 1.116 | 0.0819 | 0.196 |
+| `ROBOTIQ_EPICK_DUAL_L` | 1.134 | 0.0837 | 0.203 |
+| `ROBOTIQ_EPICK_QUAD_S` | 1.341 | 0.0920 | 0.196 |
+| `ROBOTIQ_EPICK_QUAD_L` | 1.377 | 0.0947 | 0.203 |
+
+Bracket mass is derived (±15 g) and the Ø55 height is CAD-derived (±2 mm); if your setup is critical, measure the actual stack and pass `mass` / `center_of_gravity` / `tcp_offset` overrides, which still work:
+
+```python
+robot = URRobot(
+    ip="192.168.1.50",
+    gripper=ROBOTIQ_EPICK_SINGLE_S,
+    mass=0.74,
+    tcp_offset=[0.0, 0.0, 0.147, 0.0, 0.0, 0.0],
+)
+```
+
+**Detection.** The EPick runs in advanced mode (rMOD=1): the pump reaches the max vacuum level, stops, and the vacuum decays back to the min level. An object is only "secured" while the vacuum is actually held there, so `close()` returns as soon as that secured state is observed on the gripper's object flag. With nothing under the suction cup the vacuum collapses and the secured state never occurs, so `close()` times out and raises `GripperError` after the grip timeout (set via `grip_timeout`). In automatic mode (rMOD=0) the EPick reports a short "seemingly constant" vacuum as an object, which false-positives with no object on the cup, so urkit does not use it.
+
 ### Points & Motion
 
 The points database is optional. Create a robot without one and attach later:
@@ -773,7 +856,7 @@ 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.
+The speed slider controls the pendant's speed multiplier. It's global, persistent (stored on the robot, survives restarts), and affects all motion commands. Because 0% persists as a silent freeze of all motion, the pendant's `[0]` prompt rejects 0 (1-100 only); a deliberate freeze is still possible via the API (`robot.speed_slider = 0`).
 
 #### Changing Default Speed & Acceleration
 
@@ -909,6 +992,27 @@ 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]
 ```
 
+**Held payload.** The controller compensates gravity using the payload, so add the mass of a picked-up object before moving it, and reset after release:
+
+```python
+robot.gripper.close()
+robot.set_held_payload(0.05)                        # holding 50 g, object CoG at the TCP
+robot.set_held_payload(0.05, cog=[0, 0, 0.25])      # object hangs below the flange
+robot.set_held_payload(0)                           # released: back to the base payload
+
+robot.base_payload     # gripper + tooling, kg (no held object)
+robot.held_payload     # currently held mass, kg (0 = none)
+robot.payload          # total (base + held), kg
+```
+
+`set_held_payload(0)` resets to the base payload captured at connect (the gripper preset plus any `mass=` / `center_of_gravity` / `tcp_offset` overrides), never to a literal zero. The combined CoG is the mass-weighted average of the base CoG and the object's CoG (tool coordinates, origin at the flange). A held object that extends the tool does not need a TCP change: give its CoG the deeper z instead.
+
+The base payload can be changed at runtime with `set_payload(...)`: while nothing is held, a manual `set_payload` call becomes the new base (custom fingers, a re-weighed tool). While a payload is held, `set_payload` raises, since the mass would be ambiguous: call `set_held_payload(0)` first.
+
+In the teach pendant, **9** sets the held payload (prompt: `Held payload in kg (0 = reset to base)`); the Payload status row shows the held mass and hints the key, e.g. `1.427kg +0.050 held [9]`. Useful when teaching points while gripping a real part.
+
+**How much to report.** There is no enforced minimum, and over-reporting is harmless. Practical guidance: below ~10 g the sag is sub-millimeter on any e-Series arm and not worth it; from ~50 g up (roughly 1% of a UR5e's rated payload) report it, since full-reach sag reaches several mm; in between, report it for slow precision work (insertion, contact moves) and skip it for coarse moves.
+
 Clean shutdown:
 
 ```python

{urkit-0.5.0 → urkit-0.6.0}/README.md

@@ -70,8 +70,8 @@ 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
+- **Linux, Windows**: fully supported. The interactive CLIs (`urkit teach`, `urkit points`) are tested on both platforms
+- **macOS**: runs the same POSIX terminal code path as Linux (termios/select); there is no macOS-specific code
 
 ### Robot Setup (one-time)
 
@@ -112,7 +112,7 @@ That's it. No `.urp` files to run, no extra programs needed.
 If you have a Robotiq gripper, install the **Robotiq Gripper Control** URCap first: download from [robotiq.com/support](https://robotiq.com/support), copy the `.urcap` to a USB drive, and install via `☰` → `Settings` → `System` → `URCaps`.
 
 ```python
-from urkit import URRobot, ROBOTIQ_HAND_E  # or ROBOTIQ_2F_85, ROBOTIQ_2F_140, or gripper=None
+from urkit import URRobot, ROBOTIQ_HAND_E  # or ROBOTIQ_2F_85, ROBOTIQ_2F_140, ROBOTIQ_EPICK_SINGLE_S, or gripper=None
 
 robot = URRobot(ip="192.168.1.50", points="points.db", gripper=ROBOTIQ_HAND_E)
 robot.gripper.activate()
@@ -120,8 +120,10 @@ robot.gripper.activate()
 robot.move_to("home")
 robot.move_to("pick", dz=0.05)  # 5cm above
 robot.gripper.close()
+robot.set_held_payload(0.05)    # picked up 50 g: arm compensates gravity
 robot.move_to("place")
 robot.gripper.open()
+robot.set_held_payload(0)       # released: back to gripper-only payload
 ```
 
 The typical workflow:
@@ -169,12 +171,14 @@ The CLI auto-loads `config.yaml` from the current working directory. Pass `--con
 |-----|-------------|---------|
 | `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` |
+| `gripper` | Gripper preset name | `hand-e`, `2f-85`, `2f-140`, `epick-single-s`, `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` |
 
+The loader fails loudly with a reason when a config file exists but is wrong: malformed YAML (file + parse error), a document that is not a mapping, or unknown top-level keys (offending keys + the valid ones; usually a typo). The table above is the complete key set. The only silent case is a missing file, where the CLI runs on flags and built-in defaults.
+
 ### Gripper Config
 
 Built-in preset with overrides:
@@ -265,8 +269,6 @@ urkit init --force                  # overwrite if exists
 
 ### Teach Mode
 
-### Teach Mode
-
 The interactive teach pendant for moving the robot, saving points, and checking telemetry:
 
 ```bash
@@ -279,10 +281,10 @@ urkit teach                          # reads IP from config.yaml
 | Flag | Description |
 |------|-------------|
 | `ip` | Robot IP address (positional, overrides config) |
-| `--gripper` | Gripper preset: `2f-85`, `2f-140`, `hand-e`, `digital`, `none` |
+| `--gripper` | Gripper preset: `2f-85`, `2f-140`, `hand-e`, `epick-single-s`, `digital`, `none` |
 | `--gripper-pin` | Digital gripper output pin (default: 0) |
-| `--gripper-force` | Robotiq force 0-100 |
-| `--gripper-speed` | Robotiq speed 0-100 |
+| `--gripper-force` | 2F grip force 0-100 (EPick: use `max_vacuum` in `gripper_config`) |
+| `--gripper-speed` | 2F movement speed 0-100 (EPick: use `grip_timeout` in `gripper_config`) |
 | `--gripper-close-on-high` | Digital polarity: `true` or `false` |
 | `--points` | Path to `points.db` file (overrides config) |
 | `--config` | Path to config file (default: `config.yaml` in project root or CWD) |
@@ -348,9 +350,10 @@ All movement and orientation keys support **hold-to-repeat**.
         <tr><th>Key</th><th>Action</th></tr>
         <tr><td><code>X</code></td><td>Open</td></tr>
         <tr><td><code>C</code></td><td>Close</td></tr>
-        <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><code>V</code></td><td>Set position % (2F only; hidden for the EPick)</td></tr>
+        <tr><td><code>6</code></td><td>Set speed (2F) / min vacuum (EPick)</td></tr>
+        <tr><td><code>7</code></td><td>Set force (2F) / max vacuum (EPick)</td></tr>
+        <tr><td><code>9</code></td><td>Set held payload (kg, 0 = reset to base)</td></tr>
       </table>
     </td>
     <td align="center" style="width:33%">
@@ -383,10 +386,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=+ 20.0  J3=+160.0
-              J4=+ 50.0  J5=- 80.0  J6=+157.0
+ Position (mm) X= +432.0  Y= +111.0  Z= +227.0
+ 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:
@@ -454,13 +457,16 @@ The constructor takes a few seconds on first call: it validates the connection,
 
 ### Grippers
 
-Three built-in presets:
+Built-in presets:
 
 | Preset | Description |
 |--------|-------------|
 | `ROBOTIQ_HAND_E` | Robotiq Hand-E (2F-85-E) |
 | `ROBOTIQ_2F_85` | Robotiq 2F-85 |
 | `ROBOTIQ_2F_140` | Robotiq 2F-140 |
+| `ROBOTIQ_EPICK_SINGLE_S/L` | EPick + 1 cup (S = Ø40, L = Ø55) |
+| `ROBOTIQ_EPICK_DUAL_S/L` | EPick + 2-cup bracket (S = Ø40, L = Ø55) |
+| `ROBOTIQ_EPICK_QUAD_S/L` | EPick + 4-cup bracket (S = Ø40, L = Ø55) |
 
 ```python
 robot.gripper.activate()              # required before open/close (Robotiq only)
@@ -471,7 +477,7 @@ robot.gripper.open()                  # fully open (blocking by default)
 robot.gripper.close()                 # fully closed, stops on contact
 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_position_percent(50) # 50% open (2F; repurposed on the EPick, see below)
 robot.gripper.set_force(50)           # grip force: 0-100 (Robotiq only)
 robot.gripper.set_speed(80)           # movement speed: 0-100 (Robotiq only)
 
@@ -517,6 +523,83 @@ robot.gripper.close()   # turn pin 3 on
 
 `set_force()` and `set_speed()` are not available for digital grippers.
 
+#### EPick Vacuum Gripper
+
+The EPick presets drive a Robotiq EPick vacuum gripper (e-Series only) over the same RS485 Robotiq protocol as the 2F series, using the legacy Robotiq ASCII commands. They require the **Robotiq Gripper Control** URCap installed (same setup as the 2F presets).
+
+The semantics are inverted compared to the 2F grippers:
+
+```python
+robot.gripper.activate()          # required before open/close
+robot.gripper.close()             # grip: pump on, wait until an object is secured
+robot.gripper.open()              # release: pump off + blow-off, wait until the object is gone
+```
+
+`close()` does not return until the gripper has confirmed a secured object (see Detection below), and raises `GripperError` if no object is detected within the grip timeout. A failed grip leaves the vacuum on, so call `open()` to release before moving again. `open()` waits until the vacuum is lost (the object has dropped).
+
+Grip parameters (set at connect time, or changed between grips):
+
+```python
+robot.gripper.set_max_vacuum(60)    # max vacuum level, 20-100% (default 60, the Robotiq URCap default)
+robot.gripper.set_min_vacuum(40)    # min vacuum level, 10% up to the max vacuum (default 40)
+robot.gripper.set_grip_timeout(30)  # grip timeout in 100 ms units, 0-100 (default 30 = 3 s)
+```
+
+The ranges are enforced at construction and on every setter (max 20-100, min 10 up to the current max, timeout 0-100), and a parameter of one backend passed to another raises `GripperError` instead of being ignored (`force`/`speed` on the EPick, `max_vacuum`/`grip_timeout` on the 2F). The same names work in `config.yaml`:
+
+```yaml
+gripper: epick-single-s
+gripper_config:
+  max_vacuum: 70
+  grip_timeout: 40
+```
+
+With `set_max_vacuum(100)` the pump runs continuously and the gripper cannot confirm a grip; keep the max vacuum below 100% (60 works for typical cups and trays). The same physics applies at lower levels: if the max vacuum is higher than a leaky seal can reach, the pump keeps hunting and never enters the stable hold phase where the secured flag appears, so the grip times out (verified: a marginal-seal object gripped at 60/40 but timed out at 80/50 and 80/30). For leaky seals keep `max_vacuum` low and `min_vacuum` at or below what the seal sustains, not the other way around.
+
+`set_position_mm()`, `get_position_mm()`, and `max_travel_mm()` are not available: the EPick has no finger travel. `set_position_percent(p)` is repurposed as a one-shot vacuum grip: `p=0` releases, `1-100` grips at that vacuum level with the normal secured-object wait (the teach pendant does not expose this; use [6]/[7] and C).
+
+**Payload and TCP.** The bare generator body is 0.706 kg, CoG `[0, 0, 0.0515]`, TCP `[0, 0, 0.113, 0, 0, 0]` (Robotiq EPick manual, Table 6-4); cups and brackets change all three. The kits ship cups in two sizes (Ø 40 mm and Ø 55 mm), so there is one preset per bracket system + cup size (configurations without cups cannot grip and have no preset):
+
+| Preset | Config / CLI name | Setup |
+|--------|-------------------|-------|
+| `ROBOTIQ_EPICK_SINGLE_S` | `epick-single-s` | 1 small (Ø40) cup on the generator port |
+| `ROBOTIQ_EPICK_SINGLE_L` | `epick-single-l` | 1 large (Ø55) cup on the generator port |
+| `ROBOTIQ_EPICK_DUAL_S` | `epick-dual-s` | 2-cup bracket, small cups |
+| `ROBOTIQ_EPICK_DUAL_L` | `epick-dual-l` | 2-cup bracket, large cups |
+| `ROBOTIQ_EPICK_QUAD_S` | `epick-quad-s` | 4-cup bracket, small cups |
+| `ROBOTIQ_EPICK_QUAD_L` | `epick-quad-l` | 4-cup bracket, large cups |
+
+```python
+from urkit import URRobot, ROBOTIQ_EPICK_SINGLE_S
+
+robot = URRobot(ip="192.168.1.50", gripper=ROBOTIQ_EPICK_SINGLE_S)
+```
+
+The TCP z of each preset is the bottom of the cups, the limiting point for approach moves. The presets use the manual's Table 6-4 for the body and bracket stack, and the official Festo datasheets for the cups Robotiq ships (VASB-40-1/4-PUR-B: 30 g / 32 mm, VASB-55-1/4-PUR-B: 39 g / 39 mm); all-small combinations reproduce Table 6-4 exactly:
+
+| Preset | Mass (kg) | CoG z (m) | TCP z (m) |
+|--------|-----------|-----------|-----------|
+| body only (reference) | 0.706 | 0.0515 | 0.113 |
+| `ROBOTIQ_EPICK_SINGLE_S` | 0.736 | 0.0547 | 0.145 |
+| `ROBOTIQ_EPICK_SINGLE_L` | 0.745 | 0.0557 | 0.152 |
+| `ROBOTIQ_EPICK_DUAL_S` | 1.116 | 0.0819 | 0.196 |
+| `ROBOTIQ_EPICK_DUAL_L` | 1.134 | 0.0837 | 0.203 |
+| `ROBOTIQ_EPICK_QUAD_S` | 1.341 | 0.0920 | 0.196 |
+| `ROBOTIQ_EPICK_QUAD_L` | 1.377 | 0.0947 | 0.203 |
+
+Bracket mass is derived (±15 g) and the Ø55 height is CAD-derived (±2 mm); if your setup is critical, measure the actual stack and pass `mass` / `center_of_gravity` / `tcp_offset` overrides, which still work:
+
+```python
+robot = URRobot(
+    ip="192.168.1.50",
+    gripper=ROBOTIQ_EPICK_SINGLE_S,
+    mass=0.74,
+    tcp_offset=[0.0, 0.0, 0.147, 0.0, 0.0, 0.0],
+)
+```
+
+**Detection.** The EPick runs in advanced mode (rMOD=1): the pump reaches the max vacuum level, stops, and the vacuum decays back to the min level. An object is only "secured" while the vacuum is actually held there, so `close()` returns as soon as that secured state is observed on the gripper's object flag. With nothing under the suction cup the vacuum collapses and the secured state never occurs, so `close()` times out and raises `GripperError` after the grip timeout (set via `grip_timeout`). In automatic mode (rMOD=0) the EPick reports a short "seemingly constant" vacuum as an object, which false-positives with no object on the cup, so urkit does not use it.
+
 ### Points & Motion
 
 The points database is optional. Create a robot without one and attach later:
@@ -747,7 +830,7 @@ 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.
+The speed slider controls the pendant's speed multiplier. It's global, persistent (stored on the robot, survives restarts), and affects all motion commands. Because 0% persists as a silent freeze of all motion, the pendant's `[0]` prompt rejects 0 (1-100 only); a deliberate freeze is still possible via the API (`robot.speed_slider = 0`).
 
 #### Changing Default Speed & Acceleration
 
@@ -883,6 +966,27 @@ 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]
 ```
 
+**Held payload.** The controller compensates gravity using the payload, so add the mass of a picked-up object before moving it, and reset after release:
+
+```python
+robot.gripper.close()
+robot.set_held_payload(0.05)                        # holding 50 g, object CoG at the TCP
+robot.set_held_payload(0.05, cog=[0, 0, 0.25])      # object hangs below the flange
+robot.set_held_payload(0)                           # released: back to the base payload
+
+robot.base_payload     # gripper + tooling, kg (no held object)
+robot.held_payload     # currently held mass, kg (0 = none)
+robot.payload          # total (base + held), kg
+```
+
+`set_held_payload(0)` resets to the base payload captured at connect (the gripper preset plus any `mass=` / `center_of_gravity` / `tcp_offset` overrides), never to a literal zero. The combined CoG is the mass-weighted average of the base CoG and the object's CoG (tool coordinates, origin at the flange). A held object that extends the tool does not need a TCP change: give its CoG the deeper z instead.
+
+The base payload can be changed at runtime with `set_payload(...)`: while nothing is held, a manual `set_payload` call becomes the new base (custom fingers, a re-weighed tool). While a payload is held, `set_payload` raises, since the mass would be ambiguous: call `set_held_payload(0)` first.
+
+In the teach pendant, **9** sets the held payload (prompt: `Held payload in kg (0 = reset to base)`); the Payload status row shows the held mass and hints the key, e.g. `1.427kg +0.050 held [9]`. Useful when teaching points while gripping a real part.
+
+**How much to report.** There is no enforced minimum, and over-reporting is harmless. Practical guidance: below ~10 g the sag is sub-millimeter on any e-Series arm and not worth it; from ~50 g up (roughly 1% of a UR5e's rated payload) report it, since full-reach sag reaches several mm; in between, report it for slow precision work (insertion, contact moves) and skip it for coarse moves.
+
 Clean shutdown:
 
 ```python

{urkit-0.5.0 → urkit-0.6.0}/pyproject.toml

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

{urkit-0.5.0 → urkit-0.6.0}/src/urkit/__init__.py

@@ -24,7 +24,7 @@ Quick start::
 
 from __future__ import annotations
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"
 
 
 from urkit.exceptions import (
@@ -55,6 +55,12 @@ from urkit.gripper.presets import (
     PRESETS,
     ROBOTIQ_2F_85,
     ROBOTIQ_2F_140,
+    ROBOTIQ_EPICK_DUAL_L,
+    ROBOTIQ_EPICK_DUAL_S,
+    ROBOTIQ_EPICK_QUAD_L,
+    ROBOTIQ_EPICK_QUAD_S,
+    ROBOTIQ_EPICK_SINGLE_L,
+    ROBOTIQ_EPICK_SINGLE_S,
     ROBOTIQ_HAND_E,
 )
 from urkit.motion import FreedriveMode
@@ -76,6 +82,12 @@ __all__ = [
     "ROBOTIQ_2F_85",
     "ROBOTIQ_2F_140",
     "ROBOTIQ_HAND_E",
+    "ROBOTIQ_EPICK_SINGLE_S",
+    "ROBOTIQ_EPICK_SINGLE_L",
+    "ROBOTIQ_EPICK_DUAL_S",
+    "ROBOTIQ_EPICK_DUAL_L",
+    "ROBOTIQ_EPICK_QUAD_S",
+    "ROBOTIQ_EPICK_QUAD_L",
     # Freedrive mode
     "FreedriveMode",
     # Move frame

{urkit-0.5.0 → urkit-0.6.0}/src/urkit/__main__.py

@@ -61,7 +61,8 @@ def main() -> None:
         type=str,
         default=None,
         help="Gripper preset (overrides config file). Use 'none' to disable gripper. "
-             "Accepts: 2f-85, 2f-140, hand-e, digital, none (case-insensitive, _ or -)",
+             "Accepts: 2f-85, 2f-140, hand-e, epick-<system>-<cup>, digital, none "
+             "(case-insensitive, _ or -)",
     )
     teach_parser.add_argument(
         "--gripper-pin",
@@ -73,13 +74,15 @@ def main() -> None:
         "--gripper-force",
         type=int,
         default=None,
-        help="Robotiq gripper force 0-100 (overrides config file)",
+        help="2F grip force 0-100 (EPick: use max_vacuum in the config's gripper_config) "
+             "(overrides config file)",
     )
     teach_parser.add_argument(
         "--gripper-speed",
         type=int,
         default=None,
-        help="Robotiq gripper speed 0-100 (overrides config file)",
+        help="2F movement speed 0-100 (EPick: use grip_timeout in the config's gripper_config) "
+             "(overrides config file)",
     )
     teach_parser.add_argument(
         "--gripper-close-on-high",

{urkit-0.5.0 → urkit-0.6.0}/src/urkit/cli/init.py

@@ -29,7 +29,7 @@ robot_ip: 192.168.1.50
 points_path: points.db
 
 # Gripper preset (optional)
-# Built-in: hand-e, 2f-85, 2f-140
+# Built-in: hand-e, 2f-85, 2f-140, epick-<system>-<cup> (e.g. epick-quad-l)
 # Digital I/O: digital
 # Omit or set to none for no gripper
 gripper: none
@@ -41,11 +41,18 @@ gripper_config:
     # 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)
+    # 2F grippers (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)
 
+    # EPick (vacuum): max_vacuum 20-100, min_vacuum 10 up to max_vacuum,
+    # grip_timeout 0-100 (x100 ms). A 2F param (force/speed) on an EPick
+    # preset raises an error and vice versa.
+    # max_vacuum: 60
+    # min_vacuum: 40
+    # grip_timeout: 30
+
     # Digital gripper
     # pin: 0  # digital output pin
     # close_on_high: true  # true=HIGH closes, false=LOW closes

{urkit-0.5.0 → urkit-0.6.0}/src/urkit/cli/points.py

@@ -19,7 +19,7 @@ from rich.table import Table
 from urkit import __version__
 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.cli.terminal import RawTerminal, read_burst, wait_input
 from urkit.points import Points
 
 
@@ -29,7 +29,6 @@ def points_command(args) -> None:
     Args:
         args: Parsed arguments from argparse (with points subcommand attributes).
     """
-    warn_if_windows()
     _explore_points(args)