roboapi 0.4.2__tar.gz → 0.4.3__tar.gz

{roboapi-0.4.2 → roboapi-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roboapi
-Version: 0.4.2
+Version: 0.4.3
 Summary: Run robot policies on UR and Franka through a browser or an MCP agent.
 Author: PokeBot
 License-Expression: Apache-2.0 AND MIT AND ISC AND OFL-1.1 AND LicenseRef-MiSans
@@ -34,12 +34,6 @@ Requires-Dist: ur_rtde; extra == "ur-cb3"
 Provides-Extra: franka
 Requires-Dist: franky-control<3,>=2.0; extra == "franka"
 Requires-Dist: websockets>=15; extra == "franka"
-Provides-Extra: franka56
-Requires-Dist: franky-control==2.0.0+libfranka.0.13.3; extra == "franka56"
-Requires-Dist: websockets>=15; extra == "franka56"
-Provides-Extra: panda
-Requires-Dist: franky-control==2.0.0+libfranka.0.9.2; extra == "panda"
-Requires-Dist: websockets>=15; extra == "panda"
 Provides-Extra: gripper
 Requires-Dist: minimalmodbus; extra == "gripper"
 Dynamic: license-file
@@ -90,8 +84,8 @@ requires a realtime host.
    | UR CB3 | `uv pip install 'roboapi[ur-cb3,gripper]'` |
    | UR e-Series | `uv pip install 'roboapi[gripper]'` |
    | Franka FR3, system 5.9+ | `uv pip install 'roboapi[franka,gripper]'` |
-   | Franka FR3, system 5.6.0 | `uv pip install 'roboapi[franka56,gripper]' --index https://timschneider42.github.io/franky/whl/libfranka-0.13.3/` |
-   | Franka Panda, system 4.2.1–4.x | `uv pip install 'roboapi[panda,gripper]' --index https://timschneider42.github.io/franky/whl/libfranka-0.9.2/` |
+   | Franka FR3, system 5.6.0 | `uv pip install 'roboapi[franka,gripper]' 'franky-control==2.0.0+libfranka.0.13.3' --index https://timschneider42.github.io/franky/whl/libfranka-0.13.3/` |
+   | Franka Panda, system 4.2.1–4.x | `uv pip install 'roboapi[franka,gripper]' 'franky-control==2.0.0+libfranka.0.9.2' --index https://timschneider42.github.io/franky/whl/libfranka-0.9.2/` |
 
    UR e-Series additionally needs its native runtime built on the host:
 

{roboapi-0.4.2 → roboapi-0.4.3}/README.md

@@ -44,8 +44,8 @@ requires a realtime host.
    | UR CB3 | `uv pip install 'roboapi[ur-cb3,gripper]'` |
    | UR e-Series | `uv pip install 'roboapi[gripper]'` |
    | Franka FR3, system 5.9+ | `uv pip install 'roboapi[franka,gripper]'` |
-   | Franka FR3, system 5.6.0 | `uv pip install 'roboapi[franka56,gripper]' --index https://timschneider42.github.io/franky/whl/libfranka-0.13.3/` |
-   | Franka Panda, system 4.2.1–4.x | `uv pip install 'roboapi[panda,gripper]' --index https://timschneider42.github.io/franky/whl/libfranka-0.9.2/` |
+   | Franka FR3, system 5.6.0 | `uv pip install 'roboapi[franka,gripper]' 'franky-control==2.0.0+libfranka.0.13.3' --index https://timschneider42.github.io/franky/whl/libfranka-0.13.3/` |
+   | Franka Panda, system 4.2.1–4.x | `uv pip install 'roboapi[franka,gripper]' 'franky-control==2.0.0+libfranka.0.9.2' --index https://timschneider42.github.io/franky/whl/libfranka-0.9.2/` |
 
    UR e-Series additionally needs its native runtime built on the host:
 

{roboapi-0.4.2 → roboapi-0.4.3}/docs/development.md

@@ -20,8 +20,9 @@ Device and model substitutes are confined to tests.
 
 For hardware development, add the extras from the [installation table](installation.md#install-from-pypi)
 to `uv sync`, for example `uv sync --locked --extra ur-cb3 --extra gripper`.
-The source project configures the Panda wheel index. FR3 and Panda extras are mutually
-exclusive, including the `franka56` build. Activate `.venv` before following the native build instructions.
+All Franka models use `--extra franka`; the lockfile selects the current FR3 SDK.
+For FR3 5.6 and Panda, install the controller's SDK build after syncing, as shown below.
+Activate `.venv` before following the native build instructions.
 
 ## Frontend
 
@@ -66,13 +67,19 @@ CI runs on Ubuntu 24.04:
 The UR build command compiles the native runtime and runs its offline checks. Franka
 tests cover feedback, load and TCP configuration, native guiding, control handoffs and
 model-specific motion limits. Run SDK-dependent Desk tests
-on Linux with the matching extra:
+on Linux with the matching SDK build:
 
 ```sh
-uv run --locked --extra panda pytest tests/hardware/test_panda_desk.py
-uv run --locked --extra franka56 pytest tests/hardware/test_franka_legacy.py
+uv sync --locked --extra franka --extra gripper
+uv pip install 'franky-control==2.0.0+libfranka.0.13.3' --index https://timschneider42.github.io/franky/whl/libfranka-0.13.3/
+uv run --no-sync pytest tests/hardware/test_panda_desk.py tests/hardware/test_franka_legacy.py
+uv pip install 'franky-control==2.0.0+libfranka.0.9.2' --index https://timschneider42.github.io/franky/whl/libfranka-0.9.2/
+uv run --no-sync pytest tests/hardware/test_panda_desk.py
 ```
 
+Use `--no-sync` with these SDK overrides; syncing again restores the default SDK
+from the lockfile.
+
 SDK imports, native builds and offline tests do not establish
 robot tracking, tool-load accuracy, realtime host readiness or a working hardware deployment.
 

{roboapi-0.4.2 → roboapi-0.4.3}/docs/installation.md

@@ -42,11 +42,12 @@ Run the installation command for one setup, then complete its hardware preparati
 | UR CB3 (UR5) | `uv pip install 'roboapi[ur-cb3,gripper]'` | [UR](#ur); no native build |
 | UR e-Series (UR5e, UR7e) | `uv pip install 'roboapi[gripper]'` | [UR and native control runtime](#ur) |
 | Franka FR3, system 5.9+ | `uv pip install 'roboapi[franka,gripper]'` | [Franka realtime host and Desk](#franka) |
-| Franka FR3, system 5.6.0 | `uv pip install 'roboapi[franka56,gripper]' --index https://timschneider42.github.io/franky/whl/libfranka-0.13.3/` | [Franka](#franka); import the standard load and TCP once |
-| Franka Panda 4.2.1–4.x | `uv pip install 'roboapi[panda,gripper]' --index https://timschneider42.github.io/franky/whl/libfranka-0.9.2/` | [Franka](#franka); import the standard load and TCP once |
+| Franka FR3, system 5.6.0 | `uv pip install 'roboapi[franka,gripper]' 'franky-control==2.0.0+libfranka.0.13.3' --index https://timschneider42.github.io/franky/whl/libfranka-0.13.3/` | [Franka](#franka); import the standard load and TCP once |
+| Franka Panda 4.2.1–4.x | `uv pip install 'roboapi[franka,gripper]' 'franky-control==2.0.0+libfranka.0.9.2' --index https://timschneider42.github.io/franky/whl/libfranka-0.9.2/` | [Franka](#franka); import the standard load and TCP once |
 
-The Franka extras install different builds of the same SDK and cannot share an environment.
-Check the controller's system version in Desk Settings before selecting the extra.
+All Franka models use the `franka` extra. FR3 5.6 and Panda additionally specify a
+matching SDK build in the same command. Only one SDK build can be installed in an environment;
+check the controller's system version in Desk Settings before installing.
 Verify that the CLI is available with `roboapi --help`.
 
 ### Fresh configuration after the rename
@@ -112,8 +113,8 @@ The physical assembly must match the
 The Python SDK wheel supplies the motion library. Select the SDK build for the controller
 using the [compatibility table](https://frankarobotics.github.io/docs/doc/libfranka/docs/compatibility_matrix.html)
 and [franky wheel guide](https://timschneider42.github.io/franky/getting-started/installation.html).
-The locked current FR3 SDK uses libfranka **0.21.2** (system **5.9+**); the `franka56`
-extra uses **0.13.3** for system **5.6.0**. Panda uses **0.9.2**, requiring system
+The locked current FR3 SDK uses libfranka **0.21.2** (system **5.9+**); system **5.6.0**
+uses the SDK build with **0.13.3**. Panda uses **0.9.2**, requiring system
 software **4.2.1 or later in the 4.x series**. Earlier 4.x systems need a robot update.
 Franka preview and calibration use authenticated Desk web interfaces. Check both SDK
 compatibility and Desk feedback during installation.
@@ -181,6 +182,8 @@ FR3 velocity bounds also depend on the measured joint position. Newer FR3 SDKs r
 parameters from the robot's URDF; FR3 5.6 and Panda use their matching official limits.
 Within these bounds, the IK retains step and Cartesian speed caps, a 0.30 rad directional
 slowdown zone with a nullspace centering bias, and a 0.10 rad/s cap on nullspace velocity.
+If that cap conflicts with the current joint bounds, IK uses the smallest attainable
+excess until the cap becomes feasible again; joint bounds and acceleration continuity take priority.
 At the default 50 Hz update rate, the Cartesian caps are 1.125 m/s translation and
 0.5 rad/s rotation; the joint step budget is 0.06 rad per nominal cycle.
 The control trace records repeated-state age for diagnostics. Native SDK faults stop the

roboapi-0.4.3/docs/releases/v0.4.3.md

@@ -0,0 +1,14 @@
+# v0.4.3 — Keep Franka running through nullspace limit transitions
+
+- Fix Franka IK stopping when the nullspace speed cap conflicts with the current
+  joint velocity bounds. Use the smallest necessary transient excess, preserving
+  joint limits and acceleration continuity, then restore the cap when feasible.
+- Handle tangent constraint boundaries directly to avoid numerical solver failures.
+- Cover continuous deceleration and workspace boundary clipping with regression tests.
+- Use one `franka` installation extra for all Franka models. FR3 5.6 and Panda
+  select their matching SDK build explicitly in the installation command.
+
+The shared motion range and its settings are unchanged. Upgrading from 0.4.2 does
+not require recalibration or rebuilding either robot's native runtime. Restart
+RoboAPI after installing the update. Validation is offline; physical motion has
+not been revalidated for this fix.

{roboapi-0.4.2 → roboapi-0.4.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "roboapi"
-version = "0.4.2"
+version = "0.4.3"
 description = "Run robot policies on UR and Franka through a browser or an MCP agent."
 readme = "README.md"
 authors = [{ name = "PokeBot" }]
@@ -31,8 +31,6 @@ dependencies = [
 [project.optional-dependencies]
 ur-cb3 = ["ur_rtde"]
 franka = ["franky-control>=2.0,<3", "websockets>=15"]
-franka56 = ["franky-control==2.0.0+libfranka.0.13.3", "websockets>=15"]
-panda = ["franky-control==2.0.0+libfranka.0.9.2", "websockets>=15"]
 gripper = ["minimalmodbus"]         # pulls pyserial
 
 [dependency-groups]
@@ -53,26 +51,6 @@ include = ["roboapi*"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 
-# These SDK builds install the same Python module and cannot share an environment.
-[tool.uv]
-conflicts = [[{ extra = "franka" }, { extra = "franka56" }, { extra = "panda" }]]
-
-[tool.uv.sources]
-franky-control = [
-    { index = "franky-fr3-56", extra = "franka56" },
-    { index = "franky-panda", extra = "panda" },
-]
-
-[[tool.uv.index]]
-name = "franky-fr3-56"
-url = "https://timschneider42.github.io/franky/whl/libfranka-0.13.3/"
-explicit = true
-
-[[tool.uv.index]]
-name = "franky-panda"
-url = "https://timschneider42.github.io/franky/whl/libfranka-0.9.2/"
-explicit = true
-
 [tool.setuptools.package-data]
 "roboapi" = ["product-names.json"]
 "roboapi.web" = ["static/index.html", "static/assets/*"]

{roboapi-0.4.2 → roboapi-0.4.3}/roboapi/hardware/franka/ik.py

@@ -120,7 +120,7 @@ def _solve_bounded_qp(
     projection_direction: np.ndarray | None = None,
     max_projection: float | None = None,
 ) -> np.ndarray:
-    """Solve the seven-dimensional IK QP with box and nullspace bounds."""
+    """Solve bounded IK, minimizing unavoidable nullspace-cap excess first."""
     if np.any(lower > upper):
         raise ValueError("joint velocity constraints are infeasible")
     constraints = ()
@@ -138,10 +138,21 @@ def _solve_bounded_qp(
         maximum = float(
             np.sum(np.where(direction >= 0.0, direction * upper, direction * lower))
         )
-        if minimum > max_projection or maximum < -max_projection:
-            raise np.linalg.LinAlgError(
-                "nullspace velocity cap is incompatible with the joint velocity box"
-            )
+        if minimum >= max_projection or maximum <= -max_projection:
+            # Acceleration continuity or inward-only bounds can make the cap
+            # unreachable this tick. Take the closest attainable projection,
+            # without relaxing any joint bound. Solve its boundary face directly
+            # rather than asking SLSQP to satisfy a constraint tangent to the box.
+            take_lower = direction > 0.0 if minimum >= max_projection else direction < 0.0
+            solution = np.where(take_lower, lower, upper)
+            free = direction == 0.0
+            if np.any(free):
+                solution[free] = _solve_bounded_qp(
+                    hessian[np.ix_(free, free)],
+                    rhs[free] - hessian[np.ix_(free, ~free)] @ solution[~free],
+                    lower[free], upper[free],
+                )
+            return solution
         constraints = (
             LinearConstraint(direction, -max_projection, max_projection),
         )
@@ -520,8 +531,10 @@ def solve_feedback_leashed_ik(
         upper=upper_velocity,
         max_velocity=config.posture_max_velocity,
     )
-    if abs(float(null_direction @ dq)) > config.posture_max_velocity + 1e-7:
-        raise np.linalg.LinAlgError("final structural-nullspace velocity exceeded its hard cap")
+    # Posture correction must not amplify an unavoidable transient excess.
+    feasible_cap = max(config.posture_max_velocity, abs(float(null_direction @ primary_dq)))
+    if abs(float(null_direction @ dq)) > feasible_cap + 1e-7:
+        raise np.linalg.LinAlgError("posture correction increased nullspace velocity beyond its feasible cap")
     # qd is a bounded local position lead, rebuilt from measured q every tick.
     # The same constrained dq is also the damping reference, so the position
     # and velocity terms agree and no target debt accumulates.

{roboapi-0.4.2 → roboapi-0.4.3}/roboapi.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roboapi
-Version: 0.4.2
+Version: 0.4.3
 Summary: Run robot policies on UR and Franka through a browser or an MCP agent.
 Author: PokeBot
 License-Expression: Apache-2.0 AND MIT AND ISC AND OFL-1.1 AND LicenseRef-MiSans
@@ -34,12 +34,6 @@ Requires-Dist: ur_rtde; extra == "ur-cb3"
 Provides-Extra: franka
 Requires-Dist: franky-control<3,>=2.0; extra == "franka"
 Requires-Dist: websockets>=15; extra == "franka"
-Provides-Extra: franka56
-Requires-Dist: franky-control==2.0.0+libfranka.0.13.3; extra == "franka56"
-Requires-Dist: websockets>=15; extra == "franka56"
-Provides-Extra: panda
-Requires-Dist: franky-control==2.0.0+libfranka.0.9.2; extra == "panda"
-Requires-Dist: websockets>=15; extra == "panda"
 Provides-Extra: gripper
 Requires-Dist: minimalmodbus; extra == "gripper"
 Dynamic: license-file
@@ -90,8 +84,8 @@ requires a realtime host.
    | UR CB3 | `uv pip install 'roboapi[ur-cb3,gripper]'` |
    | UR e-Series | `uv pip install 'roboapi[gripper]'` |
    | Franka FR3, system 5.9+ | `uv pip install 'roboapi[franka,gripper]'` |
-   | Franka FR3, system 5.6.0 | `uv pip install 'roboapi[franka56,gripper]' --index https://timschneider42.github.io/franky/whl/libfranka-0.13.3/` |
-   | Franka Panda, system 4.2.1–4.x | `uv pip install 'roboapi[panda,gripper]' --index https://timschneider42.github.io/franky/whl/libfranka-0.9.2/` |
+   | Franka FR3, system 5.6.0 | `uv pip install 'roboapi[franka,gripper]' 'franky-control==2.0.0+libfranka.0.13.3' --index https://timschneider42.github.io/franky/whl/libfranka-0.13.3/` |
+   | Franka Panda, system 4.2.1–4.x | `uv pip install 'roboapi[franka,gripper]' 'franky-control==2.0.0+libfranka.0.9.2' --index https://timschneider42.github.io/franky/whl/libfranka-0.9.2/` |
 
    UR e-Series additionally needs its native runtime built on the host:
 

{roboapi-0.4.2 → roboapi-0.4.3}/roboapi.egg-info/SOURCES.txt

@@ -20,6 +20,7 @@ docs/releases/v0.3.0.md
 docs/releases/v0.4.0.md
 docs/releases/v0.4.1.md
 docs/releases/v0.4.2.md
+docs/releases/v0.4.3.md
 docs/zh-CN/DESIGN.md
 docs/zh-CN/README.md
 frontend/BRAND.md

{roboapi-0.4.2 → roboapi-0.4.3}/roboapi.egg-info/requires.txt

@@ -12,16 +12,8 @@ tyro<2,>=1.0.16
 franky-control<3,>=2.0
 websockets>=15
 
-[franka56]
-franky-control==2.0.0+libfranka.0.13.3
-websockets>=15
-
 [gripper]
 minimalmodbus
 
-[panda]
-franky-control==2.0.0+libfranka.0.9.2
-websockets>=15
-
 [ur-cb3]
 ur_rtde

{roboapi-0.4.2 → roboapi-0.4.3}/tests/test_workspace.py

@@ -5,7 +5,9 @@ import pytest
 
 from roboapi.config import WorkspaceConfig
 from roboapi.errors import ControlNotReady
-from roboapi.geometry import FrameAdapter, xyzrpy_to_pose7
+from roboapi.geometry import FrameAdapter, obs_pose, xyzrpy_to_pose7
+from roboapi.hardware.franka.ik import solve_feedback_leashed_ik
+from roboapi.hardware.franka.settings import IKConfig
 from roboapi.policy import ActionChunk
 from roboapi.semantics import ACTION_DT, HOME_POSE7
 
@@ -106,3 +108,48 @@ def test_limit_does_not_fault_on_actual_tracking_error_during_run(make_runner):
         assert runner.emb.arm.get_eef_pose()[0] == pytest.approx(0.47)
     finally:
         runner._mode = "idle"
+
+
+@pytest.mark.parametrize("enabled", [False, True])
+def test_franka_decelerates_through_nullspace_change_with_or_without_wall(make_runner, monkeypatch, enabled):
+    runner = make_runner()
+    runner.cfg.workspace = WorkspaceConfig(enabled=enabled)
+    arm = runner.emb.arm.native
+    servo = arm.servo_pose
+    config = IKConfig(posture_max_velocity=0.1)
+    q = np.zeros(7)
+    previous = np.array([2.0, 0, 0, 0, 0, 0, 0])
+    samples = []
+
+    def sample_ik(pose, twist, **kwargs):
+        nonlocal q, previous
+        # A moving arm's redundant direction changes while the requested path stops.
+        angle = 0.0 if not samples else 0.2
+        jacobian = np.hstack([np.eye(6), np.zeros((6, 1))])
+        jacobian[0, [0, 6]] = 0.5 * np.array([np.cos(angle), np.sin(angle)])
+        null_direction = np.array([-np.sin(angle), 0, 0, 0, 0, 0, np.cos(angle)])
+        solved = solve_feedback_leashed_ik(
+            q=q, current_pose7=obs_pose(arm.get_eef_pose()), target_pose7=obs_pose(pose),
+            target_twist=twist, jacobian=jacobian,
+            lower_limits=np.full(7, -3.0), upper_limits=np.full(7, 3.0),
+            dt=config.nominal_dt, config=config, previous_dq=previous,
+        )
+        assert np.all(np.abs(solved.dq - previous)
+                      <= np.asarray(config.max_joint_acceleration) * config.nominal_dt + 1e-8)
+        samples.append((pose[0], twist[0], abs(float(null_direction @ solved.dq))))
+        previous = solved.dq
+        q = q + solved.dq * config.nominal_dt
+        servo(pose, twist, **kwargs)
+
+    monkeypatch.setattr(arm, "servo_pose", sample_ik)
+    targets = np.tile(HOME_POSE7, (17, 1))
+    targets[:, 0] = [0.46, 0.50, 0.54] + [0.58] * 14
+    result = runner.apply_action(ActionChunk(targets, np.ones(len(targets)), 0.0, "test"))
+    assert result["executed"] == len(targets) and not result["aborted"]
+    assert samples[1][2] > config.posture_max_velocity
+    assert samples[-1][2] <= config.posture_max_velocity + 1e-8
+    if enabled:
+        np.testing.assert_allclose([x for x, _, _ in samples[1:]], 0.47)
+        assert all(v <= 0 for _, v, _ in samples[1:])
+    else:
+        assert samples[-1][0] == pytest.approx(0.58)