add kx2 backend

docs/api/pylabrobot.hamilton.rst

@@ -123,7 +123,7 @@ STAR Liquid Handler
 .. autoclass:: pylabrobot.hamilton.liquid_handlers.star.iswap.iSWAPBackend.ParkParams
    :members:
 
-.. autoclass:: pylabrobot.hamilton.liquid_handlers.star.iswap.iSWAPBackend.CloseGripperParams
+.. autoclass:: pylabrobot.hamilton.liquid_handlers.star.iswap.iSWAPBackend.GripParams
    :members:
 
 .. autoclass:: pylabrobot.hamilton.liquid_handlers.star.iswap.iSWAPBackend.PickUpParams

docs/api/pylabrobot.paa.rst

@@ -0,0 +1,32 @@
+.. currentmodule:: pylabrobot.paa
+
+pylabrobot.paa package
+======================
+
+KX2
+---
+
+.. currentmodule:: pylabrobot.paa.kx2
+
+.. autosummary::
+  :toctree: _autosummary
+  :nosignatures:
+  :recursive:
+
+    KX2
+    KX2Driver
+    KX2ArmBackend
+    KX2BarcodeReader
+    KX2BarcodeReaderDriver
+    KX2BarcodeReaderBackend
+    KX2Config
+    Axis
+
+.. autoclass:: pylabrobot.paa.kx2.arm_backend.KX2ArmBackend.CartesianMoveParams
+   :members:
+
+.. autoclass:: pylabrobot.paa.kx2.arm_backend.KX2ArmBackend.JointMoveParams
+   :members:
+
+.. autoclass:: pylabrobot.paa.kx2.arm_backend.KX2ArmBackend.GripParams
+   :members:

docs/api/pylabrobot.rst

@@ -43,6 +43,7 @@ Manufacturers
     pylabrobot.mettler_toledo
     pylabrobot.molecular_devices
     pylabrobot.opentrons
+    pylabrobot.paa
     pylabrobot.qinstruments
     pylabrobot.tecan
     pylabrobot.thermo_fisher

docs/resources/index.md

@@ -55,7 +55,7 @@ PLR's `Resource` subclasses in the inheritance tree are:
   <tr><td><a href="introduction.html">Resource</a></td></tr>
   <!-- Arm subtree -->
   <tr><td>├── <a href="deck/deck.html">Arm</a></td></tr>
-  <tr><td>│   ├── ArticulatedArm</td></tr>
+  <tr><td>│   ├── ArticulatedGripperArm</td></tr>
   <tr><td>│   ├── CartesianArm</td></tr>
   <tr><td>│   └── SCARA</td></tr>
 

docs/user_guide/_getting-started/installation.md

@@ -52,6 +52,7 @@ Different machines use different communication modes. Replace `[usb]` with one o
 | `cytation-microscopy` | numpy (1.26), opencv-python | Cytation imager |
 | `sila` | zeroconf, grpcio | SiLA devices |
 | `pico` | opencv-python, numpy, sila | ImageXpress Pico microscope |
+| `canopen` | canopen (pulls python-can) | CANopen devices: e.g. PAA KX2 plate handler. Also requires a vendor CAN driver: PEAK PCAN-Basic on macOS/Windows, the in-tree `peak_pci` module on Linux |
 | `dev` | All of the above + testing/linting tools | Development |
 
 Or install all dependencies:

docs/user_guide/brooks/precise_flex/hello-world.ipynb

@@ -40,24 +40,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "id": "klqi0r4257k",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "2026-04-20 21:20:11,081 - pylabrobot.brooks.precise_flex - INFO - [PreciseFlex 10.0.0.1] connected: port=10100\n"
-     ]
-    }
-   ],
-   "source": [
-    "from pylabrobot.brooks import PreciseFlex400\n",
-    "\n",
-    "pf = PreciseFlex400(host=\"10.0.0.1\", port=10100, has_rail=True)\n",
-    "await pf.setup()"
-   ]
+   "outputs": [],
+   "source": "from pylabrobot.brooks import PreciseFlex400\n\n# closed_gripper_position is the firmware-unit value at min_gripper_width.\n# Calibrate against your specific gripper before first use.\npf = PreciseFlex400(host=\"10.0.0.1\", closed_gripper_position=500.0, port=10100, has_rail=True)\nawait pf.setup()"
   },
   {
    "cell_type": "markdown",
@@ -74,7 +61,7 @@
    "source": [
     "## Arm capabilities\n",
     "\n",
-    "The PreciseFlex exposes an {class}`~pylabrobot.capabilities.arms.orientable_arm.OrientableArm` on `pf.arm`. For the full arm API, see [Arms](../../capabilities/arms)."
+    "The PreciseFlex exposes an {class}`~pylabrobot.capabilities.arms.orientable_arm.OrientableGripperArm` on `pf.arm`. For the full arm API, see [Arms](../../capabilities/arms)."
    ]
   },
   {
@@ -87,34 +74,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": null,
    "id": "trbcgxwrh6k",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "2026-04-20 21:20:11,097 - pylabrobot.brooks.precise_flex - INFO - [PreciseFlex 10.0.0.1] open_gripper: width_mm=120\n",
-      "2026-04-20 21:20:11,233 - pylabrobot.brooks.precise_flex - INFO - [PreciseFlex 10.0.0.1] close_gripper: width_mm=80\n"
-     ]
-    },
-    {
-     "data": {
-      "text/plain": [
-       "False"
-      ]
-     },
-     "execution_count": 4,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "await pf.arm.open_gripper(gripper_width=120)\n",
-    "await pf.arm.close_gripper(gripper_width=80)\n",
-    "await pf.arm.backend.is_gripper_closed()"
-   ]
+   "outputs": [],
+   "source": "await pf.arm.move_gripper(width=120, force_sensing=False)\nawait pf.arm.move_gripper(width=80, force_sensing=True)\nawait pf.arm.backend.is_gripper_closed()"
   },
   {
    "cell_type": "code",
@@ -126,13 +90,13 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "PreciseFlexGripperLocation(location=Coordinate(x=262.0253, y=0.0042, z=1.501), rotation=Rotation(x=-180, y=90, z=0.0010000000000864489), rail=0.015, orientation='left', wrist='ccw')\n",
+      "PreciseFlexCartesianPose(location=Coordinate(x=262.0253, y=0.0042, z=1.501), rotation=Rotation(x=-180, y=90, z=0.0010000000000864489), rail=0.015, orientation='left', wrist='ccw')\n",
       "{<PFAxis.RAIL: 6>: 0.015, <PFAxis.BASE: 1>: 1.501, <PFAxis.SHOULDER: 2>: 72.977, <PFAxis.ELBOW: 3>: 199.323, <PFAxis.WRIST: 4>: -272.299, <PFAxis.GRIPPER: 5>: 79.8}\n"
      ]
     }
    ],
    "source": [
-    "c = await pf.arm.backend.request_gripper_location()\n",
+    "c = await pf.arm.backend.request_gripper_pose()\n",
     "j = await pf.arm.backend.request_joint_position()\n",
     "print(c)\n",
     "print(j)"
@@ -173,7 +137,7 @@
     {
      "data": {
       "text/plain": [
-       "PreciseFlexGripperLocation(location=Coordinate(x=262.0253, y=0.0042, z=1.501), rotation=Rotation(x=-180, y=90, z=0.0010000000000864489), rail=0.015, orientation='right', wrist='ccw')"
+       "PreciseFlexCartesianPose(location=Coordinate(x=262.0253, y=0.0042, z=1.501), rotation=Rotation(x=-180, y=90, z=0.0010000000000864489), rail=0.015, orientation='right', wrist='ccw')"
       ]
      },
      "execution_count": 7,
@@ -391,4 +355,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

docs/user_guide/capabilities/arms.md

@@ -1,15 +1,16 @@
 # Arms
 
-Arms are capabilities for picking up, moving, and placing labware (plates, lids, etc.) on the deck. PLR provides two arm types:
+Arms are capabilities for picking up, moving, and placing labware (plates, lids, etc.) on the deck. PLR provides three arm types:
 
-- {class}`~pylabrobot.capabilities.arms.arm.GripperArm` -- a fixed-axis gripper arm (e.g. Hamilton core grippers). Grips along a single axis.
-- {class}`~pylabrobot.capabilities.arms.orientable_arm.OrientableArm` -- a rotatable gripper arm (e.g. Hamilton iSWAP). Can grip from any direction.
+- {class}`~pylabrobot.capabilities.arms.arm.FixedAxisGripperArm`: a fixed-axis gripper arm (e.g. Hamilton core grippers). Grips along a single deck-fixed axis.
+- {class}`~pylabrobot.capabilities.arms.orientable_arm.OrientableGripperArm`: a rotatable gripper arm (e.g. Hamilton iSWAP). Can grip from any direction.
+- {class}`~pylabrobot.capabilities.arms.articulated_arm.ArticulatedGripperArm`: a fully articulated arm (e.g. UFACTORY xArm 6). Pick/drop with arbitrary 3D rotation.
 
-Both inherit from `_BaseArm`, which is a {class}`~pylabrobot.capabilities.capability.Capability`.
+All three inherit from {class}`~pylabrobot.capabilities.arms.arm.GripperArm` (the abstract base that owns gripper-width control), which in turn extends `_BaseArm`, a {class}`~pylabrobot.capabilities.capability.Capability`.
 
 ## When to use
 
-Use arms to move plates, lids, and other labware between deck positions -- from a hotel to a reader, from a reader to a shaker, from a shaker to a centrifuge, etc.
+Use arms to move plates, lids, and other labware between deck positions: from a hotel to a reader, from a reader to a shaker, from a shaker to a centrifuge, etc.
 
 ## Setup
 
@@ -21,7 +22,7 @@ from pylabrobot.hamilton.star import STAR
 lh = STAR(name="star", ...)
 await lh.setup()
 
-# the arm is at lh.iswap (OrientableArm) or lh.core_gripper (GripperArm)
+# the arm is at lh.iswap (OrientableGripperArm) or lh.core_gripper (FixedAxisGripperArm)
 await lh.iswap.move_resource(plate, to=heater_shaker)
 ```
 
@@ -50,22 +51,61 @@ await lh.iswap.move_resource(
 )
 ```
 
-### OrientableArm: grip direction
+### OrientableGripperArm: grip direction
 
-```python
-from pylabrobot.capabilities.arms.standard import GripDirection
+`direction` is the world yaw of the gripper's front finger, in degrees,
+**CCW about +Z with 0° = +X**. You can pass a float, or one of the
+cardinal-direction strings:
 
-await lh.iswap.pick_up_resource(plate, direction=GripDirection.LEFT)
-await lh.iswap.drop_resource(reader, direction=GripDirection.FRONT)
+```python
+await lh.iswap.pick_up_resource(plate, direction="left")     # = 180°
+await lh.iswap.drop_resource(reader, direction="front")      # = 270°
+await lh.iswap.move_to_location(coord, direction=45.0)       # 45° CCW from +X
 ```
 
+| String      | Degrees | World axis (deck frame) |
+|:------------|--------:|:------------------------|
+| `"right"`   |   `0°`  | `+X`                    |
+| `"back"`    |  `90°`  | `+Y`                    |
+| `"left"`    | `180°`  | `-X`                    |
+| `"front"`   | `270°`  | `-Y`                    |
+
 ## Tips and gotchas
 
 - **Coordinates are in the reference resource's frame** (typically the deck). The arm computes gripper target coordinates from the resource's position, dimensions, and the destination type.
 - **`pickup_distance_from_bottom`** controls how far up from the bottom of the resource the gripper grips. If `None`, the resource's `preferred_pickup_location` is used, or a default of 5 mm from the top (`size_z - 5`).
 - **Resource tree is updated automatically.** After a successful `drop_resource`, the resource is unassigned from its old parent and assigned to the destination.
-- **`GripOrientation`** is either a {class}`~pylabrobot.capabilities.arms.standard.GripDirection` enum (`FRONT`, `RIGHT`, `BACK`, `LEFT`) or a float in degrees.
-- **`request_gripper_location()`** queries the hardware for the current end effector position. `get_picked_up_resource()` returns the internally tracked state (no hardware call).
+- **`GripperOrientation`** is either a {data}`~pylabrobot.capabilities.arms.standard.GripperDirection` string literal (`"front"`, `"right"`, `"back"`, `"left"`) or a float in degrees, measured CCW about world +Z with 0° = +X.
+- **`request_gripper_pose()`** queries the hardware for the current end effector position. `get_picked_up_resource()` returns the internally tracked state (no hardware call).
+
+## Grippers
+
+Gripper actuation goes through a single fundamental call, `move_gripper(width, force_sensing)`, which has two modes:
+
+- `force_sensing=False`: drive the jaws to `width` mm without force feedback. The jaws reach exactly that width.
+- `force_sensing=True`: close toward `width` mm with force feedback, stopping on contact. The final width may be larger than the target.
+
+Widths are always in mm. Each backend declares its hardware limits via `min_gripper_width` and `max_gripper_width` (either may be `None` if the gripper has no commandable open/close at that end).
+
+`open_gripper()` and `close_gripper()` are convenience wrappers built on top: `open_gripper()` calls `move_gripper(max_gripper_width, force_sensing=False)` and `close_gripper()` calls `move_gripper(min_gripper_width, force_sensing=True)`. They take no width but still forward `backend_params` so backend-specific options (e.g. `iSWAPBackend.GripParams`) work the same as with `move_gripper`. They raise `NotImplementedError` if the corresponding limit is `None`.
+
+## Migration
+
+The arm capability was reshaped in the v1b1 release. The old
+`pylabrobot.arms` shim package has been removed; import from
+`pylabrobot.capabilities.arms.*` instead.
+
+| Old | New |
+|:----|:----|
+| `pylabrobot.arms.GripperArm` (concrete) | {class}`~pylabrobot.capabilities.arms.arm.FixedAxisGripperArm` |
+| `pylabrobot.arms.OrientableArm` | {class}`~pylabrobot.capabilities.arms.orientable_arm.OrientableGripperArm` |
+| `pylabrobot.arms.ArticulatedArm` | {class}`~pylabrobot.capabilities.arms.articulated_arm.ArticulatedGripperArm` |
+| `iSWAPBackend.CloseGripperParams` | {class}`~pylabrobot.hamilton.liquid_handlers.star.iswap.iSWAPBackend.GripParams` |
+| `open_gripper(width=...)` / `close_gripper(width=...)` | `move_gripper(width=..., force_sensing=...)` |
+
+The name `GripperArm` still exists in `pylabrobot.capabilities.arms.arm` but
+now refers to the abstract base. Code that did `class MyArm(GripperArm)` over
+the old concrete class should subclass `FixedAxisGripperArm` instead.
 
 ## Supported hardware
 
@@ -74,4 +114,4 @@ await lh.iswap.drop_resource(reader, direction=GripDirection.FRONT)
 
 ## API reference
 
-See {class}`~pylabrobot.capabilities.arms.arm.GripperArm`, {class}`~pylabrobot.capabilities.arms.orientable_arm.OrientableArm`, {class}`~pylabrobot.capabilities.arms.backend.GripperArmBackend`, and {class}`~pylabrobot.capabilities.arms.backend.OrientableGripperArmBackend`.
+See {class}`~pylabrobot.capabilities.arms.arm.GripperArm`, {class}`~pylabrobot.capabilities.arms.arm.FixedAxisGripperArm`, {class}`~pylabrobot.capabilities.arms.orientable_arm.OrientableGripperArm`, {class}`~pylabrobot.capabilities.arms.articulated_arm.ArticulatedGripperArm`, {class}`~pylabrobot.capabilities.arms.backend.GripperArmBackend`, and {class}`~pylabrobot.capabilities.arms.backend.OrientableGripperArmBackend`.

docs/user_guide/hamilton/star/core-grippers.ipynb

@@ -67,7 +67,7 @@
    "source": [
     "## Moving resources\n",
     "\n",
-    "Use {meth}`~pylabrobot.hamilton.liquid_handlers.star.star.STAR.core_grippers` as an async context manager. It picks up the gripper tools when entering and returns them when exiting. The yielded {class}`~pylabrobot.capabilities.arms.arm.GripperArm` has two APIs:\n",
+    "Use {meth}`~pylabrobot.hamilton.liquid_handlers.star.star.STAR.core_grippers` as an async context manager. It picks up the gripper tools when entering and returns them when exiting. The yielded {class}`~pylabrobot.capabilities.arms.arm.FixedAxisGripperArm` has two APIs:\n",
     "\n",
     "- `move_resource`: a single call that picks up a resource and drops it at a destination.\n",
     "- `pick_up_resource` and `drop_resource`: two separate calls for more control over timing."
@@ -157,4 +157,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}

docs/user_guide/hamilton/star/hardware/replacing-iswap.md

@@ -84,11 +84,10 @@ await star.driver.iswap.reengage_break()  # firmware command "R0BO"
 
 ```python
 from pylabrobot.hamilton.liquid_handlers.star.iswap import iSWAPBackend
-from pylabrobot.capabilities.arms.standard import GripDirection
 
 await star.driver.iswap.rotate(
   rotation_drive=iSWAPBackend.RotationDriveOrientation.RIGHT,
-  grip_direction=GripDirection.BACK,
+  grip_direction="back",
 )
 ```
 
@@ -97,7 +96,7 @@ await star.driver.iswap.rotate(
 ```python
 await star.driver.iswap.rotate(
   rotation_drive=iSWAPBackend.RotationDriveOrientation.LEFT,
-  grip_direction=GripDirection.BACK,
+  grip_direction="back",
 )
 ```