urkit 0.3.19__tar.gz → 0.3.20__tar.gz

{urkit-0.3.19 → urkit-0.3.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urkit
-Version: 0.3.19
+Version: 0.3.20
 Summary: Universal Robots e-Series control toolkit built on ur_rtde
 Author: URKit Contributors
 License: MIT
@@ -424,6 +424,43 @@ 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)
+
+**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.
+
+```python
+# 1. Put the robot in your preferred posture (e.g., "home")
+# 2. Save it: robot.save_point("home")
+# 3. Set as IK reference:
+robot.ik_reference = "home"
+
+# 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)
+```
+
+**In config.yaml** (recommended for permanent setup):
+
+```yaml
+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.
+
+**Per-move override:**
+
+```python
+robot.ik_reference = "home"                    # global default
+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.
+
 #### Points are tool-agnostic
 
 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.
@@ -589,6 +626,7 @@ URKit searches for `config.yaml` in this order:
 | `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` |

{urkit-0.3.19 → urkit-0.3.20}/README.md

@@ -398,6 +398,43 @@ 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)
+
+**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.
+
+```python
+# 1. Put the robot in your preferred posture (e.g., "home")
+# 2. Save it: robot.save_point("home")
+# 3. Set as IK reference:
+robot.ik_reference = "home"
+
+# 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)
+```
+
+**In config.yaml** (recommended for permanent setup):
+
+```yaml
+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.
+
+**Per-move override:**
+
+```python
+robot.ik_reference = "home"                    # global default
+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.
+
 #### Points are tool-agnostic
 
 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.
@@ -563,6 +600,7 @@ URKit searches for `config.yaml` in this order:
 | `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` |

{urkit-0.3.19 → urkit-0.3.20}/pyproject.toml

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

{urkit-0.3.19 → urkit-0.3.20}/src/urkit/__init__.py

@@ -24,7 +24,7 @@ Quick start::
 
 from __future__ import annotations
 
-__version__ = "0.3.19"
+__version__ = "0.3.20"
 
 from urkit.config import load_config, resolve_config
 from urkit.exceptions import (

{urkit-0.3.19 → urkit-0.3.20}/src/urkit/cli/teach.py

@@ -1386,6 +1386,12 @@ def teach_command(args) -> None:
     if gripper_name and isinstance(gripper_name, str):
         gripper_name = gripper_name.lower().replace("_", "-")
     points_path = args.points or config.get("points_path") or "points.db"
+    raw_ik = config.get("ik_reference")
+    ik_reference: str | list[float] | None = None
+    if isinstance(raw_ik, str):
+        ik_reference = raw_ik
+    elif isinstance(raw_ik, list) and len(raw_ik) == 6:
+        ik_reference = raw_ik
 
     # Resolve gripper constructor params from config.yaml gripper_config section
     # and CLI --gripper-* flags (CLI overrides config)
@@ -1454,6 +1460,8 @@ def teach_command(args) -> None:
     if gripper_name:
         print(f"  Gripper: {gripper_name}")
     print(f"  Points:  {points_path}")
+    if ik_reference:
+        print(f"  IK ref:  {ik_reference}")
 
     # URRobot handles everything: safety recovery, remote mode check,
     # power on, brake release, program stop, and RTDE connection.
@@ -1462,6 +1470,7 @@ def teach_command(args) -> None:
             ip=ip,  # type: ignore
             points=points_path,  # type: ignore
             gripper=gripper_config,
+            ik_reference=ik_reference,
             **gripper_kwargs,
         )
         print("  Connected.", flush=True)

{urkit-0.3.19 → urkit-0.3.20}/src/urkit/config.py

@@ -60,6 +60,7 @@ Full config reference::
         max_mm: 50                   # finger travel
     default_vel: 0.5                 # m/s
     default_acc: 0.3                 # m/s²
+    ik_reference: home               # point name for IK reference posture
     expert_mode: false               # show advanced CLI commands
 """
 

{urkit-0.3.19 → urkit-0.3.20}/src/urkit/robot.py

@@ -10,7 +10,7 @@ from dataclasses import replace
 import logging
 import sys
 import time
-from typing import TYPE_CHECKING, Optional, Union
+from typing import TYPE_CHECKING, Literal, Optional, Union
 from pathlib import Path
 
 if TYPE_CHECKING:
@@ -89,6 +89,26 @@ class URRobot:
             Presets provide mass, CoG, TCP offset, and backend type.
         default_vel: Default linear velocity (m/s).
         default_acc: Default linear acceleration (m/s²).
+        ik_reference: Global reference posture for inverse kinematics.
+            One of:
+
+            - ``None`` (default): No IK reference — the controller picks
+              the IK solution closest to the current joint positions.
+            - ``"current"``: Use the robot's current joint positions
+              as the reference.
+            - A point name (str): Look up the saved point, resolve its
+              pose to joints, and use as the reference. If the point
+              doesn't exist, logs a warning and falls back to current
+              joint positions.
+            - A 6-element list: Use directly as joint angles.
+
+            When set, all motion commands (``move_to``, ``move_relative``,
+            ``move_sequence``) resolve target poses to joint angles using
+            this reference, preventing the robot from unexpectedly flipping
+            its elbow or wrist. Can be overridden per-call by passing
+            ``ik_reference`` to individual motion methods.
+
+            Can be changed at runtime via the ``ik_reference`` property.
         gripper_kwargs: Additional kwargs passed to the gripper backend
             to override preset values (e.g. ``max_mm=80`` for custom
             fingers, ``force=50``, ``speed=80`` for Robotiq).
@@ -99,6 +119,8 @@ class URRobot:
         >>> robot.move_relative([0.01, 0, 0, 0, 0, 0])  # works without points
         >>> robot.points_db = "points.db"  # set lazily
         >>> robot.save_point("home")
+        >>> robot.ik_reference = "home"  # prevent elbow flipping
+        >>> robot.move_to("pick")  # uses home as IK reference
     """
 
     def __init__(
@@ -109,6 +131,7 @@ class URRobot:
         gripper: GripperPreset | DigitalGripperConfig | None = None,
         default_vel: float = 0.5,
         default_acc: float = 0.3,
+        ik_reference: str | list[float] | None = None,
         **gripper_kwargs: object,
     ) -> None:
         self._ip = ip
@@ -117,6 +140,7 @@ class URRobot:
         self._rtde_frequency = 500.0
         self._connection_lost = False
         self._move_frame: MoveFrame = MoveFrame.BASE
+        self._ik_reference: str | list[float] | None = ik_reference
 
         # Target tracking for pose-based arrival detection in is_moving()
         self._move_target_pose: list[float] | None = None
@@ -352,6 +376,7 @@ class URRobot:
         gripper: GripperPreset | DigitalGripperConfig | str | None = None,
         default_vel: float | None = None,
         default_acc: float | None = None,
+        ik_reference: str | list[float] | None = None,
         **gripper_kwargs,
     ) -> "URRobot":
         """Create a URRobot from a YAML config file or dict.
@@ -369,6 +394,8 @@ class URRobot:
                 the ``gripper`` key from config.
             default_vel: Default linear velocity (m/s).
             default_acc: Default linear acceleration (m/s²).
+            ik_reference: IK reference posture name. Overrides the
+                ``ik_reference`` key from config.
             gripper_kwargs: Overrides for gripper preset values
                 (e.g. ``max_mm``, ``force``, ``speed``, ``pin``,
                 ``mass``, ``center_of_gravity``, ``tcp_offset``).
@@ -379,6 +406,7 @@ class URRobot:
             robot_ip: 192.168.1.50
             points_path: points.db
             gripper: hand-e
+            ik_reference: home  # prevent elbow flipping
             gripper_config:
                 mass: 1.5
                 force: 50
@@ -487,12 +515,24 @@ class URRobot:
                 if value is not None:
                     gripper_kwargs[key] = value
 
+        # Resolve ik_reference: explicit kwarg > config > None
+        resolved_ik: str | list[float] | None = None
+        if ik_reference is not None:
+            resolved_ik = ik_reference
+        else:
+            cfg_ik = cfg.get("ik_reference")
+            if isinstance(cfg_ik, str):
+                resolved_ik = cfg_ik
+            elif isinstance(cfg_ik, list) and len(cfg_ik) == 6:
+                resolved_ik = cfg_ik
+
         return cls(
             ip=resolved_ip,
             points=resolved_points,
             gripper=resolved_gripper,
             default_vel=default_vel if default_vel is not None else cfg.get("default_vel", 0.5),  # type: ignore
             default_acc=default_acc if default_acc is not None else cfg.get("default_acc", 0.3),  # type: ignore
+            ik_reference=resolved_ik,
             **gripper_kwargs,
         )
 
@@ -1013,6 +1053,7 @@ class URRobot:
         offset_rx: float = 0.0,
         offset_ry: float = 0.0,
         offset_rz: float = 0.0,
+        ik_reference: str | list[float] | None | Literal["__global__"] = "__global__",
     ) -> None:
         """Move to a saved point or raw pose.
 
@@ -1020,7 +1061,9 @@ class URRobot:
             target: A saved point name (str) or a raw TCP pose
                 [x, y, z, rx, ry, rz].
             linear: If True (default), use Cartesian linear move (moveL).
-                If False, use joint-space move (moveJ).
+                If False, use joint-space move (moveJ). When an IK
+                reference is active, the pose is resolved to joints
+                and a joint-space move is used regardless of this flag.
             offset: Optional offset [dx, dy, dz, drx, dry, drz]
                 applied to the target pose before moving. Mutually
                 exclusive with individual offset_* parameters.
@@ -1036,6 +1079,15 @@ class URRobot:
             offset_rx: Roll offset in radians (default 0.0).
             offset_ry: Pitch offset in radians (default 0.0).
             offset_rz: Yaw offset in radians (default 0.0).
+            ik_reference: Per-call IK reference override. One of:
+
+                - ``"__global__"`` (default): Use the robot's global
+                  ``ik_reference`` setting.
+                - ``None``: Explicitly disable IK reference for this
+                  move (use controller's default behavior).
+                - ``"current"``: Use current joint positions.
+                - A point name (str): Look up and resolve to joints.
+                - A 6-element list: Use directly as joint angles.
 
         Raises:
             MotionError: If the move fails or IK has no solution.
@@ -1048,6 +1100,8 @@ class URRobot:
             >>> robot.move_to("pick", offset_x=0.01, offset_z=-0.02)
             >>> robot.move_to("pick", offset=[0, 0, 0.05, 0, 0.1, 0])  # full
             >>> robot.move_to([0.5, 0, 0.3, 0, 0, 0])  # raw pose
+            >>> robot.move_to("pick", ik_reference="home")  # per-call override
+            >>> robot.move_to("pick", ik_reference=None)  # disable for one move
         """
         self._check_connection()
         self._disable_freedrive_guard()
@@ -1082,22 +1136,32 @@ class URRobot:
         vel = vel if vel is not None else self._default_vel
         acc = acc if acc is not None else self._default_acc
 
-        # Store target for pose-based arrival detection
-        if linear:
-            self._move_target_pose = list(pose)
-            self._move_target_joints = None
-        else:
-            self._move_target_joints = None  # set below after IK
-            self._move_target_pose = list(pose)
+        # Resolve effective ik_reference: per-call > global
+        effective_ik = (
+            self._ik_reference if ik_reference == "__global__" else ik_reference
+        )
 
         try:
-            if linear:
+            if effective_ik is not None:
+                # IK reference active: resolve pose to joints with qnear,
+                # then moveJ (prevents elbow/wrist flipping)
+                qnear = self._resolve_ik_reference(effective_ik)
+                joints = self.inverse_kinematics(pose, seed=qnear)
+                self._move_target_joints = list(joints)
+                self._move_target_pose = list(pose)
+                self._motion.movej(joints, vel=vel, acc=acc, asynchronous=asynchronous)
+            elif linear:
+                # No IK reference, linear mode: standard moveL
                 if not self._rtde_c.getInverseKinematicsHasSolution(pose):
                     raise MotionError(f"Pose unreachable: {pose}")
+                self._move_target_pose = list(pose)
+                self._move_target_joints = None
                 self._motion.movel(pose, vel=vel, acc=acc, asynchronous=asynchronous)
             else:
+                # No IK reference, joint mode: resolve IK without qnear
                 joints = self.inverse_kinematics(pose)
                 self._move_target_joints = list(joints)
+                self._move_target_pose = list(pose)
                 self._motion.movej(joints, vel=vel, acc=acc, asynchronous=asynchronous)
         except MotionError:
             raise
@@ -1212,6 +1276,7 @@ class URRobot:
         delta_rx: float = 0.0,
         delta_ry: float = 0.0,
         delta_rz: float = 0.0,
+        ik_reference: str | list[float] | None | Literal["__global__"] = "__global__",
     ) -> None:
         """Relative Cartesian move from the current position.
 
@@ -1222,7 +1287,9 @@ class URRobot:
             delta: [dx, dy, dz, drx, dry, drz] in meters/radians.
                 Mutually exclusive with individual delta_* parameters.
             linear: If True (default), use Cartesian linear move.
-                If False, solve IK and use joint-space move.
+                If False, solve IK and use joint-space move. When an IK
+                reference is active, the pose is resolved to joints
+                and a joint-space move is used regardless of this flag.
             frame: Coordinate frame for the delta. Falls back to the
                 current ``move_frame`` property (BASE or TOOL).
             vel: Velocity override. Falls back to default_vel.
@@ -1235,6 +1302,15 @@ class URRobot:
             delta_rx: Roll delta in radians (default 0.0).
             delta_ry: Pitch delta in radians (default 0.0).
             delta_rz: Yaw delta in radians (default 0.0).
+            ik_reference: Per-call IK reference override. One of:
+
+                - ``"__global__"`` (default): Use the robot's global
+                  ``ik_reference`` setting.
+                - ``None``: Explicitly disable IK reference for this
+                  move (use controller's default behavior).
+                - ``"current"``: Use current joint positions.
+                - A point name (str): Look up and resolve to joints.
+                - A 6-element list: Use directly as joint angles.
 
         Raises:
             MotionError: If the move fails.
@@ -1277,29 +1353,91 @@ class URRobot:
         acc = acc if acc is not None else self._default_acc
         effective_frame = frame or self._move_frame
 
+        # Resolve effective ik_reference: per-call > global
+        effective_ik = (
+            self._ik_reference if ik_reference == "__global__" else ik_reference
+        )
+
         try:
             current = list(self._rtde_r.getActualTCPPose())
             target = transform_pose_delta(current, final_delta, effective_frame)
 
-            # Store target for arrival detection
-            if linear:
+            if effective_ik is not None:
+                # IK reference active: resolve pose to joints with qnear
+                qnear = self._resolve_ik_reference(effective_ik)
+                joints = self.inverse_kinematics(target, seed=qnear)
+                self._move_target_joints = list(joints)
                 self._move_target_pose = list(target)
-                self._move_target_joints = None
-            else:
+                self._motion.movej(joints, vel=vel, acc=acc, asynchronous=asynchronous)
+            elif linear:
+                # No IK reference, linear mode: standard moveL
                 self._move_target_pose = list(target)
                 self._move_target_joints = None
-
-            if linear:
                 self._motion.movel(target, vel=vel, acc=acc, asynchronous=asynchronous)
             else:
+                # No IK reference, joint mode: resolve IK without qnear
                 joints = self.inverse_kinematics(target)
                 self._move_target_joints = list(joints)
+                self._move_target_pose = list(target)
                 self._motion.movej(joints, vel=vel, acc=acc, asynchronous=asynchronous)
         except MotionError:
             raise
         except Exception as e:
             raise MotionError(f"Relative move failed: {e}")
 
+    def _resolve_ik_reference(
+        self,
+        ik_reference: str | list[float],
+    ) -> list[float]:
+        """Resolve an ik_reference specifier to joint angles.
+
+        Args:
+            ik_reference: One of:
+                - ``"current"`` — use the robot's current joint positions.
+                - A point name (str) — look up the point, resolve its pose
+                  to joints via IK. If the point doesn't exist, fall back
+                  to current joint positions with a warning.
+                - A 6-element list — use directly as joint angles.
+
+        Returns:
+            6 joint angles in radians.
+        """
+        if ik_reference == "current":
+            return list(self._rtde_r.getActualQ())
+
+        if isinstance(ik_reference, list) and len(ik_reference) == 6:
+            return list(ik_reference)
+
+        if isinstance(ik_reference, str):
+            # Try to look up as a named point
+            if self._points is None:
+                logger.warning(
+                    "ik_reference='%s': points DB not configured, "
+                    "falling back to current joint positions.",
+                    ik_reference,
+                )
+                return list(self._rtde_r.getActualQ())
+
+            point = self._points.get(ik_reference)
+            if point is None:
+                logger.warning(
+                    "ik_reference='%s': point not found, "
+                    "falling back to current joint positions. "
+                    "Available: %s",
+                    ik_reference,
+                    self._points.list(),
+                )
+                return list(self._rtde_r.getActualQ())
+
+            # Resolve the point's pose to joints (no qnear — just need
+            # a representative joint config for this posture)
+            return self.inverse_kinematics(point.pose)
+
+        raise MotionError(
+            f"ik_reference must be a point name, 'current', or 6 joint "
+            f"angles, got {type(ik_reference).__name__}."
+        )
+
     def move_sequence(
         self,
         targets: list[str | list[float]],
@@ -1309,29 +1447,79 @@ class URRobot:
         vel: float | None = None,
         acc: float | None = None,
         asynchronous: bool = False,
+        ik_reference: str | list[float] | None | Literal["__global__"] = "__global__",
     ) -> None:
         """Move through a sequence of points.
 
-        Executes each target in order using individual moveL/moveJ calls.
-        Convenience method to condense multiple moves into one call.
+        Executes each target in order. When ``ik_reference`` is provided,
+        all poses are resolved to joint targets using chained inverse
+        kinematics (each pose resolves relative to the previous one),
+        then executed as a single blended joint-space path via
+        ``moveJ(path)``. This prevents the robot from unexpectedly
+        flipping its elbow or wrist between waypoints.
+
+        Without ``ik_reference``, falls back to individual ``moveL``/
+        ``moveJ_IK`` calls (legacy behavior, no blending).
 
         Args:
             targets: List of saved point names or raw poses
                 [x, y, z, rx, ry, rz].
-            linear: If True (default), use Cartesian linear moves (moveL).
-                If False, use joint-space moves (moveJ).
-            blend_radius: Currently ignored. Kept for API compatibility.
+            linear: Used only when ``ik_reference`` is ``None``.
+                If True (default), use Cartesian linear moves (moveL).
+                If False, use joint-space moves (moveJ_IK).
+                Ignored when ``ik_reference`` is set (always uses
+                joint-space path for IK stability).
+            blend_radius: Blend radius in meters. Used only when
+                ``ik_reference`` is set — applied between consecutive
+                waypoints in the joint path. Default 0.0 (stop at each
+                waypoint). When set, the robot rounds corners instead
+                of stopping at intermediate waypoints.
             vel: Velocity override. Falls back to default_vel.
             acc: Acceleration override. Falls back to default_acc.
-            asynchronous: Currently ignored.
+            asynchronous: If True, move runs in background. Used only
+                when ``ik_reference`` is set (path-based moves support
+                async). Ignored in legacy mode.
+            ik_reference: Reference posture for inverse kinematics
+                resolution. One of:
+
+                - ``"__global__"`` (default): Use the robot's global
+                  ``ik_reference`` setting. If the global setting is
+                  ``None``, falls back to legacy behavior.
+                - ``None``: Explicitly disable IK reference for this
+                  sequence (use controller's default behavior).
+                - ``"current"``: Use the robot's current joint
+                  positions as the starting reference.
+                - A point name (str): Look up the saved point,
+                  resolve its pose to joints, and use as the
+                  starting reference. If the point doesn't exist,
+                  falls back to current joint positions with a
+                  warning.
+                - A 6-element list: Use directly as joint angles.
+
+                The reference is **chained** through the sequence:
+                the first pose resolves relative to the reference,
+                the second relative to the first's resolved joints,
+                and so on. This keeps the arm configuration
+                (elbow up/down, wrist orientation) consistent
+                throughout the entire sequence.
 
         Raises:
-            MotionError: If the sequence fails or fewer than 2 targets.
-            PointError: If a named point is not found.
+            MotionError: If the sequence fails, fewer than 2 targets,
+                or IK resolution fails for a pose.
+            PointError: If a named target point is not found.
 
         Example:
-            >>> # Move through waypoints, stop at each
+            >>> # Legacy: individual moveL calls, no IK control
             >>> robot.move_sequence(["a", "b", "c"])
+
+            >>> # IK-stable: resolve to joints, blend between waypoints
+            >>> robot.move_sequence(["a", "b", "c"],
+            ...                      ik_reference="home",
+            ...                      blend_radius=0.02)
+
+            >>> # Start from current posture
+            >>> robot.move_sequence(["a", "b", "c"],
+            ...                      ik_reference="current")
         """
         self._check_connection()
         self._disable_freedrive_guard()
@@ -1344,23 +1532,67 @@ class URRobot:
         v = vel if vel is not None else self._default_vel
         a = acc if acc is not None else self._default_acc
 
-        for i, target in enumerate(targets):
-            point = self._lookup_point(target)
-            label = (
-                f"'{target}'" if isinstance(target, str) else str(target[:3])
-            )
+        # Resolve effective ik_reference: per-call > global
+        effective_ik = (
+            self._ik_reference if ik_reference == "__global__" else ik_reference
+        )
+
+        if effective_ik is not None:
+            # --- IK-stable path mode: resolve all poses to joints,
+            #     build blended joint path, single moveJ(path) call. ---
+            qnear = self._resolve_ik_reference(effective_ik)
+            logger.info("move_sequence: ik_reference resolved to %s", qnear)
+
+            path: list[list[float]] = []
+            for i, target in enumerate(targets):
+                point = self._lookup_point(target)
+                label = (
+                    f"'{target}'" if isinstance(target, str)
+                    else str(target[:3])
+                )
+
+                # Chain qnear: each pose resolves relative to previous
+                joints = self.inverse_kinematics(point.pose, seed=qnear)
+                logger.info(
+                    "move_sequence: %s (%d/%d) → joints %s",
+                    label, i + 1, len(targets),
+                    [f"{j:.3f}" for j in joints],
+                )
+
+                # 9-element path: [j0..j5, velocity, acceleration, blend]
+                # Last waypoint gets blend=0 (come to rest)
+                r = blend_radius if i < len(targets) - 1 else 0.0
+                path.append([*joints, v, a, r])
+                qnear = joints  # chain to next
+
             logger.info(
-                "move_sequence: %s (%d/%d)", label, i + 1, len(targets)
+                "move_sequence: executing blended joint path (%d waypoints, "
+                "blend=%.3f m)", len(path), blend_radius
             )
             try:
-                if linear:
-                    self._rtde_c.moveL(list(point.pose), v, a)
-                else:
-                    self._rtde_c.moveJ_IK(
-                        list(point.pose), self._rtde_r.getActualQ(), v, a
-                    )
+                self._rtde_c.moveJ(path, asynchronous=asynchronous)
             except Exception as e:
-                raise MotionError(f"move_sequence failed at target {i}: {e}")
+                raise MotionError(f"move_sequence path execution failed: {e}")
+        else:
+            # --- Legacy mode: individual moveL/moveJ_IK calls. ---
+            for i, target in enumerate(targets):
+                point = self._lookup_point(target)
+                label = (
+                    f"'{target}'" if isinstance(target, str)
+                    else str(target[:3])
+                )
+                logger.info(
+                    "move_sequence: %s (%d/%d)", label, i + 1, len(targets)
+                )
+                try:
+                    if linear:
+                        self._rtde_c.moveL(list(point.pose), v, a)
+                    else:
+                        self._rtde_c.moveJ_IK(list(point.pose), v, a)
+                except Exception as e:
+                    raise MotionError(
+                        f"move_sequence failed at target {i}: {e}"
+                    )
 
     def zero_ft_sensor(self) -> None:
         """Zero the robot's force/torque sensor.
@@ -1495,6 +1727,34 @@ class URRobot:
         """Current default acceleration (m/s²) for motion commands."""
         return self._default_acc
 
+    @property
+    def ik_reference(self) -> str | list[float] | None:
+        """Current global IK reference posture.
+
+        Returns the reference used for inverse kinematics resolution
+        in motion commands. One of:
+
+        - ``None``: No reference (controller picks IK solution).
+        - ``"current"``: Use current joint positions.
+        - A point name (str): Look up and resolve to joints.
+        - A 6-element list: Use directly as joint angles.
+
+        Example:
+            >>> robot.ik_reference = "home"
+            >>> robot.move_to("pick")  # uses home as IK reference
+            >>> robot.ik_reference = None  # disable
+        """
+        return self._ik_reference
+
+    @ik_reference.setter
+    def ik_reference(self, value: str | list[float] | None) -> None:
+        """Set the global IK reference posture.
+
+        Args:
+            value: Reference posture (see getter docstring).
+        """
+        self._ik_reference = value
+
     def set_speed(self, vel: float) -> None:
         """Change the default velocity for subsequent motions.
 

{urkit-0.3.19 → urkit-0.3.20}/src/urkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urkit
-Version: 0.3.19
+Version: 0.3.20
 Summary: Universal Robots e-Series control toolkit built on ur_rtde
 Author: URKit Contributors
 License: MIT
@@ -424,6 +424,43 @@ 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)
+
+**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.
+
+```python
+# 1. Put the robot in your preferred posture (e.g., "home")
+# 2. Save it: robot.save_point("home")
+# 3. Set as IK reference:
+robot.ik_reference = "home"
+
+# 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)
+```
+
+**In config.yaml** (recommended for permanent setup):
+
+```yaml
+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.
+
+**Per-move override:**
+
+```python
+robot.ik_reference = "home"                    # global default
+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.
+
 #### Points are tool-agnostic
 
 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.
@@ -589,6 +626,7 @@ URKit searches for `config.yaml` in this order:
 | `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` |

{urkit-0.3.19 → urkit-0.3.20}/src/urkit.egg-info/SOURCES.txt

@@ -33,5 +33,6 @@ tests/test_geometry.py
 tests/test_gripper.py
 tests/test_gripper_factory.py
 tests/test_gripper_presets.py
+tests/test_move_sequence.py
 tests/test_points.py
 tests/test_robot_integration.py

urkit-0.3.20/tests/test_move_sequence.py

@@ -0,0 +1,296 @@
+"""Unit tests for move_sequence with ik_reference and blending.
+
+Tests the IK resolution, path building, and blending logic
+without requiring a real robot.
+"""
+
+from __future__ import annotations
+
+import logging
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from urkit.exceptions import MotionError, PointError
+from urkit.points import Point, Points
+
+
+# ------------------------------------------------------------------
+# Fixtures
+# ------------------------------------------------------------------
+
+
+@pytest.fixture
+def mock_rtde_c():
+    """Mock RTDEControlInterface."""
+    mock = MagicMock()
+    mock.isConnected.return_value = True
+    mock.getInverseKinematicsHasSolution.return_value = True
+    mock.getInverseKinematics.return_value = [0.0, -0.5, 0.5, -1.5, 1.5, 0.0]
+    return mock
+
+
+@pytest.fixture
+def mock_rtde_r():
+    """Mock RTDEReceiveInterface."""
+    mock = MagicMock()
+    mock.getActualQ.return_value = [0.0, -1.0, 1.0, -1.57, 1.57, 0.0]
+    mock.getActualTCPPose.return_value = [0.5, 0.0, 0.3, 0.0, 0.0, 0.0]
+    return mock
+
+
+@pytest.fixture
+def mock_points(tmp_path):
+    """Create a temporary points database with test data."""
+    db_path = tmp_path / "test_points.db"
+    pts = Points(db_path)
+    pts.save(Point(name="home", pose=[0.5, 0.0, 0.3, 0.0, 0.0, 0.0]))
+    pts.save(Point(name="pick", pose=[0.3, 0.2, 0.1, 0.0, 0.0, 0.0]))
+    pts.save(Point(name="place", pose=[0.3, -0.2, 0.1, 0.0, 0.0, 0.0]))
+    return pts
+
+
+@pytest.fixture
+def robot(mock_rtde_c, mock_rtde_r, mock_points, tmp_path):
+    """Create a URRobot with mocked RTDE interfaces."""
+    with patch("urkit.robot._validate_connection"), \
+         patch("urkit.robot._check_remote_mode"), \
+         patch("urkit.robot._connect_rtde") as mock_connect, \
+         patch("urkit.robot._connect_dashboard"), \
+         patch("urkit.robot._try_recover_safety"):
+        
+        # Set up the connect mock to populate rtde interfaces
+        mock_connect.return_value = (mock_rtde_c, mock_rtde_r)
+        
+        from urkit.robot import URRobot
+        robot = object.__new__(URRobot)  # bypass __init__
+        robot._ip = "127.0.0.1"
+        robot._rtde_c = mock_rtde_c
+        robot._rtde_r = mock_rtde_r
+        robot._rtde_frequency = 500.0
+        robot._connection_lost = False
+        robot._default_vel = 0.5
+        robot._default_acc = 0.3
+        robot._points = mock_points
+        robot._move_frame = None
+        robot._move_target_joints = None
+        robot._ik_reference = None
+        
+        # Mock the motion object
+        robot._motion = MagicMock()
+        
+        # Mock _check_connection and _disable_freedrive_guard
+        robot._check_connection = MagicMock()
+        robot._disable_freedrive_guard = MagicMock()
+        
+        # Mock inverse_kinematics to delegate to rtde_c
+        original_ik = robot.inverse_kinematics.__func__ if hasattr(robot.inverse_kinematics, '__func__') else None
+        
+        def mock_ik(pose, seed=None):
+            qnear = seed if seed is not None else []
+            if not mock_rtde_c.getInverseKinematicsHasSolution(pose, qnear):
+                raise MotionError(f"No IK solution for pose {pose}")
+            return mock_rtde_c.getInverseKinematics(pose, qnear)
+        
+        # Bind mock_ik to the robot instance
+        import types
+        robot.inverse_kinematics = types.MethodType(
+            lambda self, pose, seed=None: mock_ik(pose, seed), robot
+        )
+        
+        return robot
+
+
+# ------------------------------------------------------------------
+# Tests: _resolve_ik_reference
+# ------------------------------------------------------------------
+
+
+class TestResolveIkReference:
+    """Test the _resolve_ik_reference helper method."""
+
+    def test_current_returns_actual_joints(self, robot, mock_rtde_r):
+        result = robot._resolve_ik_reference("current")
+        assert result == list(mock_rtde_r.getActualQ())
+
+    def test_point_name_resolves_to_joints(self, robot, mock_rtde_c):
+        """Named point should be looked up and resolved via IK."""
+        result = robot._resolve_ik_reference("home")
+        # Should call inverse_kinematics with the point's pose
+        assert len(result) == 6
+        # The mock returns the default IK result
+        assert result == [0.0, -0.5, 0.5, -1.5, 1.5, 0.0]
+
+    def test_missing_point_falls_back_to_current(self, robot, mock_rtde_r, caplog):
+        """Non-existent point name should fall back to current joints."""
+        with caplog.at_level(logging.WARNING):
+            result = robot._resolve_ik_reference("nonexistent")
+        assert result == list(mock_rtde_r.getActualQ())
+        assert "point not found" in caplog.text or "falling back" in caplog.text
+
+    def test_joints_list_used_directly(self, robot):
+        """Raw joint list should be returned as-is."""
+        joints = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6]
+        result = robot._resolve_ik_reference(joints)
+        assert result == joints
+
+    def test_no_points_db_falls_back(self, robot, mock_rtde_r, caplog):
+        """When points DB is None, should fall back to current joints."""
+        robot._points = None
+        result = robot._resolve_ik_reference("home")
+        assert result == list(mock_rtde_r.getActualQ())
+
+
+# ------------------------------------------------------------------
+# Tests: move_sequence validation
+# ------------------------------------------------------------------
+
+
+class TestMoveSequenceValidation:
+    """Test move_sequence input validation."""
+
+    def test_requires_at_least_two_targets(self, robot):
+        with pytest.raises(MotionError, match="at least 2"):
+            robot.move_sequence(["single_point"])
+
+    def test_empty_targets_raises(self, robot):
+        with pytest.raises(MotionError, match="at least 2"):
+            robot.move_sequence([])
+
+
+# ------------------------------------------------------------------
+# Tests: move_sequence legacy mode (no ik_reference)
+# ------------------------------------------------------------------
+
+
+class TestMoveSequenceLegacy:
+    """Test move_sequence without ik_reference (legacy behavior)."""
+
+    def test_linear_mode_calls_movel(self, robot, mock_rtde_c):
+        """Without ik_reference and linear=True, should call moveL."""
+        robot.move_sequence(["home", "pick"])
+        # Should have called moveL twice (once per target)
+        assert mock_rtde_c.moveL.call_count == 2
+
+    def test_joints_mode_calls_movej_ik(self, robot, mock_rtde_c):
+        """Without ik_reference and linear=False, should call moveJ_IK."""
+        robot.move_sequence(["home", "pick"], linear=False)
+        assert mock_rtde_c.moveJ_IK.call_count == 2
+
+    def test_raw_poses_work(self, robot, mock_rtde_c):
+        """Raw pose lists should work as targets."""
+        poses = [
+            [0.5, 0.0, 0.3, 0.0, 0.0, 0.0],
+            [0.3, 0.2, 0.1, 0.0, 0.0, 0.0],
+        ]
+        robot.move_sequence(poses)
+        assert mock_rtde_c.moveL.call_count == 2
+
+
+# ------------------------------------------------------------------
+# Tests: move_sequence with ik_reference
+# ------------------------------------------------------------------
+
+
+class TestMoveSequenceWithIkReference:
+    """Test move_sequence with ik_reference for IK stability."""
+
+    def test_ik_reference_resolves_path(self, robot, mock_rtde_c):
+        """With ik_reference, should call moveJ(path) once."""
+        robot.move_sequence(["home", "pick", "place"], ik_reference="current")
+        # Should call moveJ once with a path (not individual moveL)
+        assert mock_rtde_c.moveJ.call_count == 1
+        # moveL should NOT be called
+        assert mock_rtde_c.moveL.call_count == 0
+
+    def test_path_format_is_nine_elements(self, robot, mock_rtde_c):
+        """Each waypoint in the path should have 9 elements."""
+        robot.move_sequence(["home", "pick"], ik_reference="current")
+        call_args = mock_rtde_c.moveJ.call_args
+        path = call_args[0][0]  # first positional arg
+        assert len(path) == 2  # two waypoints
+        for waypoint in path:
+            assert len(waypoint) == 9  # [j0..j5, vel, acc, blend]
+
+    def test_last_waypoint_has_zero_blend(self, robot, mock_rtde_c):
+        """Last waypoint should have blend_radius=0 (come to rest)."""
+        robot.move_sequence(
+            ["home", "pick", "place"],
+            ik_reference="current",
+            blend_radius=0.02,
+        )
+        path = mock_rtde_c.moveJ.call_args[0][0]
+        # Last waypoint blend should be 0
+        assert path[-1][8] == 0.0
+        # Intermediate waypoints should have the blend radius
+        assert path[0][8] == 0.02
+
+    def test_chained_ik_calls(self, robot, mock_rtde_c):
+        """IK should be called once per target (chained)."""
+        # Reset the call count
+        mock_rtde_c.getInverseKinematics.reset_mock()
+        
+        robot.move_sequence(["home", "pick", "place"], ik_reference="current")
+        
+        # 3 targets = 3 IK calls (each chained from previous)
+        assert mock_rtde_c.getInverseKinematics.call_count == 3
+
+    def test_ik_reference_point_name(self, robot, mock_rtde_c):
+        """ik_reference as a point name should resolve via IK."""
+        robot.move_sequence(["pick", "place"], ik_reference="home")
+        assert mock_rtde_c.moveJ.call_count == 1
+
+    def test_ik_reference_joints_list(self, robot, mock_rtde_c):
+        """ik_reference as a raw joints list should work."""
+        ref_joints = [0.0, -1.0, 1.0, -1.57, 1.57, 0.0]
+        robot.move_sequence(["pick", "place"], ik_reference=ref_joints)
+        assert mock_rtde_c.moveJ.call_count == 1
+
+    def test_async_passed_through(self, robot, mock_rtde_c):
+        """asynchronous parameter should be passed to moveJ(path)."""
+        robot.move_sequence(
+            ["home", "pick"],
+            ik_reference="current",
+            asynchronous=True,
+        )
+        call_kwargs = mock_rtde_c.moveJ.call_args[1]
+        assert call_kwargs.get("asynchronous") is True
+
+    def test_vel_acc_in_path(self, robot, mock_rtde_c):
+        """Velocity and acceleration should be in each path waypoint."""
+        robot.move_sequence(
+            ["home", "pick"],
+            ik_reference="current",
+            vel=0.8,
+            acc=0.5,
+        )
+        path = mock_rtde_c.moveJ.call_args[0][0]
+        for waypoint in path:
+            assert waypoint[6] == 0.8  # velocity
+            assert waypoint[7] == 0.5  # acceleration
+
+    def test_defaults_used_when_no_vel_acc(self, robot, mock_rtde_c):
+        """Default vel/acc should be used when not specified."""
+        robot._default_vel = 0.5
+        robot._default_acc = 0.3
+        robot.move_sequence(["home", "pick"], ik_reference="current")
+        path = mock_rtde_c.moveJ.call_args[0][0]
+        for waypoint in path:
+            assert waypoint[6] == 0.5
+            assert waypoint[7] == 0.3
+
+    def test_global_ik_reference_used_when_not_specified(self, robot, mock_rtde_c):
+        """When ik_reference is not specified, should use global setting."""
+        robot._ik_reference = "home"
+        mock_rtde_c.getInverseKinematics.reset_mock()
+        robot.move_sequence(["pick", "place"])  # no ik_reference arg
+        # Should use global ik_reference and call moveJ(path)
+        assert mock_rtde_c.moveJ.call_count == 1
+        assert mock_rtde_c.getInverseKinematics.call_count >= 2
+
+    def test_per_call_overrides_global(self, robot, mock_rtde_c):
+        """Per-call ik_reference=None should override global setting."""
+        robot._ik_reference = "home"
+        robot.move_sequence(["pick", "place"], ik_reference=None)
+        # Should use legacy mode (individual moveL)
+        assert mock_rtde_c.moveL.call_count == 2