add global ik_reference to prevent elbow/wrist flipping

- Global ik_reference on URRobot (constructor, property, from_config)
- ik_reference in config.yaml for persistent setup
- ik_reference in CLI teach pendant (reads config, shows at boot)
- Per-call ik_reference parameter on move_to, move_relative, move_sequence
- README documentation with recommendation to always use ik_reference
- 21 unit tests for move_sequence with ik_reference

Author: rodolfo-verde

CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.20] — 2026-07-27
+
+### Added
+- Global `ik_reference` setting on `URRobot` — set once, applies to all motion commands (`move_to`, `move_relative`, `move_sequence`) to prevent elbow/wrist flipping (IK ambiguity)
+- `ik_reference` in config.yaml and `from_config()` — persistent setup without code changes
+- `ik_reference` in CLI teach pendant — reads from config.yaml, shows at boot
+- Per-call `ik_reference` parameter on `move_to()`, `move_relative()`, `move_sequence()` — override global default per move
+- README documentation with recommendation to always use `ik_reference` for stable motion
+
 ## [0.3.19] — 2026-07-27
 
 ### Changed

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` |

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"}

src/urkit/__init__.py

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

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)

src/urkit/config.py

@@ -60,6 +60,7 @@
         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
 """