slow iswap context manager (#397)

Author: rickwierenga

docs/user_guide/hamilton-star/iswap-module.md

@@ -2,6 +2,24 @@
 
 The `R0` module allows fine grained control of the iSWAP gripper.
 
+## Common tasks
+
+- Parking
+
+You can park the iSWAP using {meth}`~pylabrobot.liquid_handling.backends.hamilton.STAR.STAR.park_iswap`.
+
+```python
+await lh.backend.park_iswap()
+```
+
+- Opening gripper:
+
+You can open the iSWAP gripper using {meth}`~pylabrobot.liquid_handling.backends.hamilton.STAR.STAR.iswap_open_gripper`. Warning: this will release any object that is gripped. Used for error recovery.
+
+```python
+await lh.backend.iswap_open_gripper()
+```
+
 ## Rotations
 
 You can rotate the iSWAP to 12 predifined positions using {meth}`~pylabrobot.liquid_handling.backends.hamilton.STAR.STAR.iswap_rotate`.
@@ -20,3 +38,12 @@ wrist_drive = random.choice([STAR.WristOrientation.LEFT, STAR.WristOrientation.R
 await lh.backend.rotate_iswap_rotation_drive(rotation_drive)
 await lh.backend.rotate_iswap_wrist(wrist_drive)
 ```
+
+## Slow movement
+
+You can make the iswap move more slowly during sensitive operations using {meth}`~pylabrobot.liquid_handling.backends.hamilton.STAR.STAR.slow_iswap`. This is useful when you want to avoid splashing or other disturbances.
+
+```python
+async with lh.backend.slow_iswap():
+  await lh.move_plate(plate, plt_car[1])
+```

pylabrobot/liquid_handling/backends/hamilton/STAR.py

@@ -4,6 +4,7 @@
 import logging
 import re
 from abc import ABCMeta
+from contextlib import asynccontextmanager
 from typing import (
   Callable,
   Dict,
@@ -7811,6 +7812,23 @@ async def request_volume_in_tip(self, channel: int) -> float:
     _, current_volume = resp["qc"]  # first is max volume
     return float(current_volume) / 10
 
+  @asynccontextmanager
+  async def slow_iswap(self, wrist_velocity: int = 20_000, gripper_velocity: int = 20_000):
+    """A context manager that sets the iSWAP to slow speed during the context"""
+    assert 20 <= gripper_velocity <= 75_000
+    assert 20 <= wrist_velocity <= 65_000
+
+    original_wv = (await self.send_command("R0", "RA", ra="wv", fmt="wv#####"))["wv"]
+    original_tv = (await self.send_command("R0", "RA", ra="tv", fmt="tv#####"))["tv"]
+
+    await self.send_command("R0", "AA", wv=gripper_velocity)  # wrist velocity
+    await self.send_command("R0", "AA", tv=wrist_velocity)  # gripper velocity
+    try:
+      yield
+    finally:
+      await self.send_command("R0", "AA", wv=original_wv)
+      await self.send_command("R0", "AA", tv=original_tv)
+
 
 class UnSafe:
   """