make some private, grip parameters for pick_plate, width is required

Author: rickwierenga

docs/user_guide/_getting-started/units.md

@@ -12,3 +12,4 @@ Unless otherwise specified, these are the units used in PyLabRobot:
 | Speed              | millimeters/second (mm/s) |
 | Flow Rate          | microliters/second (µL/s) |
 | Temperature        | degrees Celsius (°C)      |
+| Force              | Newtons (N)               |

pylabrobot/arms/backend.py

@@ -15,12 +15,9 @@ class VerticalAccess:
   picking from a plate stack or tube rack on the deck.
 
   Args:
-    approach_height_mm: Height above the target position to move to before
-                        descending to grip (default: 100mm)
-    clearance_mm: Vertical distance to retract after gripping before lateral
-                  movement (default: 100mm)
-    gripper_offset_mm: Additional vertical offset added when holding a plate,
-                      accounts for gripper thickness (default: 10mm)
+    approach_height_mm: Height above the target position to move to before descending to grip (default: 100mm)
+    clearance_mm: Vertical distance to retract after gripping before lateral movement (default: 100mm)
+    gripper_offset_mm: Additional vertical offset added when holding a plate, accounts for gripper thickness (default: 10mm)
   """
 
   approach_height_mm: float = 100
@@ -36,14 +33,10 @@ class HorizontalAccess:
   accessing plates in a hotel-style storage system.
 
   Args:
-    approach_distance_mm: Horizontal distance in front of the target to stop
-                         before moving in to grip (default: 50mm)
-    clearance_mm: Horizontal distance to retract after gripping before lifting
-                  (default: 50mm)
-    lift_height_mm: Vertical distance to lift the plate after horizontal retract,
-                   before lateral movement (default: 100mm)
-    gripper_offset_mm: Additional vertical offset added when holding a plate,
-                      accounts for gripper thickness (default: 10mm)
+    approach_distance_mm: Horizontal distance in front of the target to stop before moving in to grip (default: 50mm)
+    clearance_mm: Horizontal distance to retract after gripping before lifting (default: 50mm)
+    lift_height_mm: Vertical distance to lift the plate after horizontal retract, before lateral movement (default: 100mm)
+    gripper_offset_mm: Additional vertical offset added when holding a plate, accounts for gripper thickness (default: 10mm)
   """
 
   approach_distance_mm: float = 50
@@ -59,91 +52,77 @@ class SCARABackend(MachineBackend, metaclass=ABCMeta):
   """Backend for a robotic arm"""
 
   @abstractmethod
-  async def open_gripper(self):
+  async def open_gripper(self, gripper_width: float) -> None:
     """Open the arm's gripper."""
-    ...
 
   @abstractmethod
-  async def close_gripper(self):
+  async def close_gripper(self, gripper_width: float) -> None:
     """Close the arm's gripper."""
-    ...
 
   @abstractmethod
   async def is_gripper_closed(self) -> bool:
     """Check if the gripper is currently closed."""
-    ...
 
   @abstractmethod
-  async def halt(self):
+  async def halt(self) -> None:
     """Stop any ongoing movement of the arm."""
-    ...
 
   @abstractmethod
-  async def home(self):
+  async def home(self) -> None:
     """Home the arm to its default position."""
-    ...
 
   @abstractmethod
-  async def move_to_safe(self):
+  async def move_to_safe(self) -> None:
     """Move the arm to a predefined safe position."""
-    ...
 
   @abstractmethod
   async def approach(
     self,
     position: Union[PreciseFlexCartesianCoords, JointCoords],
     access: Optional[AccessPattern] = None,
-  ):
+  ) -> None:
     """Move the arm to an approach position (offset from target).
 
     Args:
       position: Target position (CartesianCoords or JointCoords)
-      access: Access pattern defining how to approach the target.
-              Defaults to VerticalAccess() if not specified.
+      access: Access pattern defining how to approach the target.  Defaults to VerticalAccess() if not specified.
     """
-    ...
 
   @abstractmethod
   async def pick_plate(
     self,
     position: Union[PreciseFlexCartesianCoords, JointCoords],
+    plate_width: float,
     access: Optional[AccessPattern] = None,
-  ):
+  ) -> None:
     """Pick a plate from the specified position.
 
     Args:
       position: Target position for pickup
-      access: Access pattern defining how to approach and retract.
-              Defaults to VerticalAccess() if not specified.
+      access: Access pattern defining how to approach and retract.  Defaults to VerticalAccess() if not specified.
     """
-    ...
 
   @abstractmethod
   async def place_plate(
     self,
     position: Union[PreciseFlexCartesianCoords, JointCoords],
     access: Optional[AccessPattern] = None,
-  ):
+  ) -> None:
     """Place a plate at the specified position.
 
     Args:
       position: Target position for placement
-      access: Access pattern defining how to approach and retract.
-              Defaults to VerticalAccess() if not specified.
+      access: Access pattern defining how to approach and retract.  Defaults to VerticalAccess() if not specified.
     """
-    ...
 
   @abstractmethod
-  async def move_to(self, position: Union[PreciseFlexCartesianCoords, JointCoords]):
-    """Move the arm to a specified position in 3D space."""
-    ...
+  async def move_to(self, position: Union[PreciseFlexCartesianCoords, JointCoords]) -> None:
+    """Move the arm to a specified position in 3D space or in joint space."""
 
   @abstractmethod
   async def get_joint_position(self) -> JointCoords:
-    """Get the current position of the arm in 3D space."""
-    ...
+    """Get the current position of the arm in joint space."""
 
   @abstractmethod
   async def get_cartesian_position(self) -> PreciseFlexCartesianCoords:
     """Get the current position of the arm in 3D space."""
-    ...