From de8c5f70474772042a11b932a8f9858ef0a218b9 Mon Sep 17 00:00:00 2001
From: Rick Wierenga <rick_wierenga@icloud.com>
Date: Thu, 6 Feb 2025 17:43:57 -0800
Subject: [PATCH] slow iswap context manager

---
 docs/user_guide/hamilton-star/iswap-module.md | 27 +++++++++++++++++++
 .../liquid_handling/backends/hamilton/STAR.py | 18 +++++++++++++
 2 files changed, 45 insertions(+)

diff --git a/docs/user_guide/hamilton-star/iswap-module.md b/docs/user_guide/hamilton-star/iswap-module.md
index 7d566c06704..3b4df30687d 100644
--- a/docs/user_guide/hamilton-star/iswap-module.md
+++ b/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])
+```
diff --git a/pylabrobot/liquid_handling/backends/hamilton/STAR.py b/pylabrobot/liquid_handling/backends/hamilton/STAR.py
index e86a2880117..77bee2b14e7 100644
--- a/pylabrobot/liquid_handling/backends/hamilton/STAR.py
+++ b/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:
   """