puda-drivers 0.0.2__py3-none-any.whl → 0.0.3__py3-none-any.whl

puda_drivers/move/gcode.py

@@ -1,22 +1,38 @@
 """
-A standalone Python class for controlling G-code devices
-via serial communication.
+G-code controller for motion systems.
 
-Provides methods for connection management, basic movement commands, and port discovery.
+This module provides a Python interface for controlling G-code compatible motion
+systems (e.g., QuBot) via serial communication. Supports absolute and relative
+positioning, homing, and position synchronization.
 """
 
 import re
-from typing import Optional, Dict, Tuple
 import logging
+from typing import Optional, Dict, Tuple
+
 from puda_drivers.core.serialcontroller import SerialController
 
 
 class GCodeController(SerialController):
+    """
+    Controller for G-code compatible motion systems.
+
+    This class provides methods for controlling multi-axis motion systems that
+    understand G-code commands, including homing, absolute/relative movement,
+    and position synchronization.
+
+    Attributes:
+        DEFAULT_FEEDRATE: Default feed rate in mm/min (3000)
+        MAX_FEEDRATE: Maximum allowed feed rate in mm/min (3000)
+        TOLERANCE: Position synchronization tolerance in mm (0.01)
+    """
+
     DEFAULT_FEEDRATE = 3000  # mm/min
     MAX_FEEDRATE = 3000  # mm/min
     TOLERANCE = 0.01  # tolerance for position sync in mm
 
     PROTOCOL_TERMINATOR = "\r"
+    VALID_AXES = "XYZA"
 
     def __init__(
         self,
@@ -26,19 +42,22 @@ class GCodeController(SerialController):
         feed: int = DEFAULT_FEEDRATE,
     ):
         """
-        Initializes the GCodeController.
+        Initialize the G-code controller.
 
         Args:
-            port (Optional[str]): The serial port (e.g., 'COM5'). Defaults to None.
-            baudrate (int): The baud rate for serial communication. Defaults to 9600.
-            timeout (int): The read/write timeout in seconds. Defaults to 5.
+            port_name: Serial port name (e.g., '/dev/ttyACM0' or 'COM3')
+            baudrate: Baud rate for serial communication. Defaults to 9600.
+            timeout: Timeout in seconds for operations. Defaults to 20.
+            feed: Initial feed rate in mm/min. Defaults to 3000.
         """
         super().__init__(port_name, baudrate, timeout)
 
-        # Initialize instance-specific logger
         self._logger = logging.getLogger(__name__)
         self._logger.info(
-            f"GCodeController initialized with port='{port_name}', baudrate={baudrate}, timeout={timeout}"
+            "GCodeController initialized with port='%s', baudrate=%s, timeout=%s",
+            port_name,
+            baudrate,
+            timeout,
         )
 
         # Tracks internal position state
@@ -52,78 +71,102 @@ class GCodeController(SerialController):
         self._is_absolute_mode: bool = True  # absolute mode by default
 
     @property
-    def feed(self):
-        """The current feed rate."""
+    def feed(self) -> int:
+        """Get the current feed rate in mm/min."""
         return self._feed
 
     @feed.setter
-    def feed(self, new_feed: int):
-        """Set the movement feed rate, enforcing the maximum limit."""
+    def feed(self, new_feed: int) -> None:
+        """
+        Set the movement feed rate, enforcing the maximum limit.
 
-        # 1. Ensure the value is positive
+        Args:
+            new_feed: New feed rate in mm/min (must be > 0)
+
+        Raises:
+            ValueError: If feed rate is not positive
+        """
         if new_feed <= 0:
-            error_msg = f"Attempted to set invalid feed rate: {new_feed}. Must be > 0."
+            error_msg = (
+                f"Attempted to set invalid feed rate: {new_feed}. Must be > 0."
+            )
             self._logger.error(error_msg)
             raise ValueError(error_msg)
 
-        # 2. Check and enforce the maximum rate
         if new_feed > self.MAX_FEEDRATE:
-            # Log the change and cap the value
             self._logger.warning(
-                f"Requested feed rate ({new_feed}) exceeds maximum ({self.MAX_FEEDRATE}). "
-                f"Setting feed rate to maximum: {self.MAX_FEEDRATE}."
+                "Requested feed rate (%s) exceeds maximum (%s). "
+                "Setting feed rate to maximum: %s.",
+                new_feed,
+                self.MAX_FEEDRATE,
+                self.MAX_FEEDRATE,
             )
             self._feed = self.MAX_FEEDRATE
         else:
-            # Set the value normally
             self._feed = new_feed
-            self._logger.debug(f"Feed rate set to: {self._feed} mm/min.")
+            self._logger.debug("Feed rate set to: %s mm/min.", self._feed)
 
     def _build_command(self, command: str) -> str:
-        """Helper function to build a G-code command with terminator."""
+        """
+        Build a G-code command with terminator.
+
+        Args:
+            command: G-code command string (without terminator)
+
+        Returns:
+            Complete command string with terminator
+        """
         return f"{command}{self.PROTOCOL_TERMINATOR}"
 
-    def home(self, axis: Optional[str] = None) -> None:
+    def _validate_axis(self, axis: str) -> str:
         """
-        Homes one or all axes (G28 command).
+        Validate and normalize an axis name.
 
         Args:
-            axis (str, optional): The axis to home ('X', 'Y', 'Z', 'A', etc.).
-                                  If None, homes all axes (G28).
+            axis: Axis name to validate
+
+        Returns:
+            Uppercase axis name
 
         Raises:
-            ValueError: If an invalid axis character is provided.
+            ValueError: If axis is not valid
         """
-        valid_axes = "XYZA"
+        axis_upper = axis.upper()
+        if axis_upper not in self.VALID_AXES:
+            self._logger.error(
+                "Invalid axis '%s' provided. Must be one of: %s.",
+                axis_upper,
+                ", ".join(self.VALID_AXES),
+            )
+            raise ValueError(
+                f"Invalid axis. Must be one of: {', '.join(self.VALID_AXES)}."
+            )
+        return axis_upper
 
-        # 1. Axis Validation and Normalization, Command Construction
-        if axis:
-            axis = axis.upper()
-            if axis not in valid_axes:
-                self._logger.error(
-                    f"Invalid axis '{axis}' provided for homing. Must be one of: {', '.join(valid_axes)}."
-                )
-                raise ValueError(
-                    f"Invalid axis. Must be one of: {', '.join(valid_axes)}."
-                )
+    def home(self, axis: Optional[str] = None) -> None:
+        """
+        Home one or all axes (G28 command).
 
+        Args:
+            axis: Optional axis to home ('X', 'Y', 'Z', 'A').
+                  If None, homes all axes.
+
+        Raises:
+            ValueError: If an invalid axis is provided
+        """
+        if axis:
+            axis = self._validate_axis(axis)
             cmd = f"G28 {axis}"
             home_target = axis
         else:
             cmd = "G28"
             home_target = "All"
 
-        # 2. Command Execution
-        self._logger.info(f"[{cmd}] homing axis/axes: {home_target} **")
-        # self._send_command(self._build_command(cmd))
-        self._send_command("G28\r")
-        self._logger.info(f"Homing of {home_target} completed.")
+        self._logger.info("[%s] homing axis/axes: %s **", cmd, home_target)
+        self._send_command(self._build_command(cmd))
+        self._logger.info("Homing of %s completed.", home_target)
 
-        # Verify position after homing
-        # self.sync_position()
-
-        # 3. Internal Position Update (Optimistic Zeroing)
-        # If the homing was for a specific axis, zero only that axis.
+        # Update internal position (optimistic zeroing)
         if axis:
             self.current_position[axis] = 0.0
         else:
@@ -131,7 +174,8 @@ class GCodeController(SerialController):
                 self.current_position[key] = 0.0
 
         self._logger.debug(
-            f"Internal position updated (optimistically zeroed) to {self.current_position}"
+            "Internal position updated (optimistically zeroed) to %s",
+            self.current_position,
         )
 
     def move_absolute(
@@ -143,10 +187,23 @@ class GCodeController(SerialController):
         feed: Optional[int] = None,
     ) -> None:
         """
-        Moves the device to an absolute position (G90 + G1 command).
+        Move to an absolute position (G90 + G1 command).
+
+        Args:
+            x: Target X position (optional)
+            y: Target Y position (optional)
+            z: Target Z position (optional)
+            a: Target A position (optional)
+            feed: Feed rate for this move (optional, uses current feed if not specified)
         """
+        feed_rate = feed if feed is not None else self._feed
         self._logger.info(
-            f"Preparing absolute move to X:{x}, Y:{y}, Z:{z}, A:{a} at F:{feed if feed is not None else self._feed}"
+            "Preparing absolute move to X:%s, Y:%s, Z:%s, A:%s at F:%s",
+            x,
+            y,
+            z,
+            a,
+            feed_rate,
         )
 
         # Ensure absolute mode is active
@@ -166,10 +223,23 @@ class GCodeController(SerialController):
         feed: Optional[int] = None,
     ) -> None:
         """
-        Moves the device relative to the current position (G91 + G1 command).
+        Move relative to the current position (G91 + G1 command).
+
+        Args:
+            x: Relative X movement (optional)
+            y: Relative Y movement (optional)
+            z: Relative Z movement (optional)
+            a: Relative A movement (optional)
+            feed: Feed rate for this move (optional, uses current feed if not specified)
         """
+        feed_rate = feed if feed is not None else self._feed
         self._logger.info(
-            f"Preparing relative move by dX:{x}, dY:{y}, dZ:{z}, dA:{a} at F:{feed if feed is not None else self._feed}"
+            "Preparing relative move by dX:%s, dY:%s, dZ:%s, dA:%s at F:%s",
+            x,
+            y,
+            z,
+            a,
+            feed_rate,
         )
 
         # Ensure relative mode is active
@@ -188,70 +258,154 @@ class GCodeController(SerialController):
         a: Optional[float] = None,
         feed: Optional[int] = None,
     ) -> None:
-        """Internal helper for executing G1 move commands."""
+        """
+        Internal helper for executing G1 move commands with safe movement pattern.
 
-        # 1. Map axis names to their input values
-        move_deltas = {"X": x, "Y": y, "Z": z, "A": a}
+        Safe move pattern:
+        1. If X or Y movement is needed, first move Z to 0 (safe height)
+        2. Then move X, Y (and optionally A) to target
+        3. Finally move Z to target position (if specified)
 
-        move_cmd = "G1"
+        Args:
+            x: X axis value (optional)
+            y: Y axis value (optional)
+            z: Z axis value (optional)
+            a: A axis value (optional)
+            feed: Feed rate (optional)
+        """
+        # Calculate target positions
         target_pos = self.current_position.copy()
-        movement_occurred = False
-
-        # 2. Build the G-code command and calculate target position
-        for axis, value in move_deltas.items():
-            if value is not None:
-                move_cmd += f" {axis}{value}"
+        has_x = x is not None
+        has_y = y is not None
+        has_z = z is not None
+        has_a = a is not None
 
-                # Calculate the target position
-                if self._is_absolute_mode:
-                    target_pos[axis] = value
-                else:
-                    target_pos[axis] = self.current_position[axis] + value
+        if not (has_x or has_y or has_z or has_a):
+            self._logger.warning(
+                "Move command issued without any axis movement. Skipping transmission."
+            )
+            return
 
-                movement_occurred = True
+        # Calculate target positions
+        if self._is_absolute_mode:
+            if has_x:
+                target_pos["X"] = x
+            if has_y:
+                target_pos["Y"] = y
+            if has_z:
+                target_pos["Z"] = z
+            if has_a:
+                target_pos["A"] = a
+        else:
+            if has_x:
+                target_pos["X"] = self.current_position["X"] + x
+            if has_y:
+                target_pos["Y"] = self.current_position["Y"] + y
+            if has_z:
+                target_pos["Z"] = self.current_position["Z"] + z
+            if has_a:
+                target_pos["A"] = self.current_position["A"] + a
 
-        # 3. Add on Feed Rate to command
         feed_rate = feed if feed is not None else self._feed
-        # Final safety check on the rate used in the command
         if feed_rate > self.MAX_FEEDRATE:
             feed_rate = self.MAX_FEEDRATE
-        move_cmd += f" F{feed_rate}"
 
-        # 4. Check for movement and return if none
-        if not movement_occurred:
-            self._logger.warning(
-                "Move command issued without any axis movement. Skipping transmission."
-            )
-            return
+        # Safe move pattern: Z to 0, then XY, then Z to target
+        needs_xy_move = has_x or has_y
+        current_z = self.current_position["Z"]
+        target_z = target_pos["Z"] if has_z else current_z
 
-        # 5. Execute command and update position (Optimistic update)
-        self._logger.info(f"Executing move command: {move_cmd}")
-        self._send_command(self._build_command(move_cmd))
+        # Step 1: Move Z to safe height (0) if XY movement is needed and Z is not already at 0
+        if needs_xy_move and abs(current_z) > 0.001:  # Small tolerance for floating point
+            self._logger.info(
+                "Safe move: Raising Z to safe height (0) before XY movement"
+            )
+            if self._is_absolute_mode:
+                move_cmd = "G1 Z0"
+            else:
+                # In relative mode, move by negative current_z to reach 0
+                move_cmd = f"G1 Z{-current_z}"
+            move_cmd += f" F{feed_rate}"
+            self._send_command(self._build_command(move_cmd))
+            self.current_position["Z"] = 0.0
+            self._logger.debug("Z moved to safe height (0)")
+
+        # Step 2: Move X, Y (and optionally A) to target
+        if needs_xy_move or has_a:
+            move_cmd = "G1"
+            if has_x:
+                # Use target position in absolute mode, relative value in relative mode
+                if self._is_absolute_mode:
+                    move_cmd += f" X{target_pos['X']}"
+                else:
+                    move_cmd += f" X{x}"
+            if has_y:
+                if self._is_absolute_mode:
+                    move_cmd += f" Y{target_pos['Y']}"
+                else:
+                    move_cmd += f" Y{y}"
+            if has_a:
+                if self._is_absolute_mode:
+                    move_cmd += f" A{target_pos['A']}"
+                else:
+                    move_cmd += f" A{a}"
+            move_cmd += f" F{feed_rate}"
+
+            self._logger.info("Executing XY move command: %s", move_cmd)
+            self._send_command(self._build_command(move_cmd))
+
+            # Update position for moved axes
+            if has_x:
+                self.current_position["X"] = target_pos["X"]
+            if has_y:
+                self.current_position["Y"] = target_pos["Y"]
+            if has_a:
+                self.current_position["A"] = target_pos["A"]
+
+        # Step 3: Move Z to target position (if Z movement was requested)
+        if has_z:
+            z_needs_move = abs(target_z - (0.0 if needs_xy_move else current_z)) > 0.001
+            if z_needs_move:
+                if self._is_absolute_mode:
+                    move_cmd = f"G1 Z{target_z} F{feed_rate}"
+                else:
+                    # In relative mode, use the original z value
+                    move_cmd = f"G1 Z{z} F{feed_rate}"
+                
+                if needs_xy_move:
+                    self._logger.info(
+                        "Safe move: Lowering Z to target position: %s", target_z
+                    )
+                else:
+                    self._logger.info("Executing Z move command: %s", move_cmd)
+                
+                self._send_command(self._build_command(move_cmd))
+                self.current_position["Z"] = target_z
 
         self._logger.info(
-            f"Move complete. Updating internal position from {self.current_position} to {target_pos}"
+            "Move complete. Final position: %s", self.current_position
         )
+        self._logger.debug("New internal position: %s", self.current_position)
 
-        self.current_position = target_pos
-        self._logger.debug(f"New internal position: {self.current_position}")
-
-        # 6. Post-Move Position Synchronization Check
+        # Post-move position synchronization check
         self.sync_position()
 
     def query_position(self) -> Dict[str, float]:
         """
-        Queries the Qubot for its current machine position (M114 command).
+        Query the current machine position (M114 command).
 
         Returns:
-            Dict[str, float]: A dictionary containing the updated X, Y, Z, and A positions.
+            Dictionary containing X, Y, Z, and A positions
+
+        Note:
+            Returns an empty dictionary if the query fails or no positions are found.
         """
         self._logger.info("Querying current machine position (M114).")
         self._send_command(self._build_command("M114"))
         res: str = self._read_response()
 
         # Extract position values using regex
-        pattern = re.compile(r"([XYZAE]):(\-?\d+\.\d+)")
-        # Find all matches (e.g., [('X', '0.000'), ('Y', '0.000'), ...])
+        pattern = re.compile(r"([XYZA]):(-?\d+\.\d+)")
         matches = pattern.findall(res)
 
         position_data: Dict[str, float] = {}
@@ -261,7 +415,9 @@ class GCodeController(SerialController):
                 position_data[axis] = float(value_str)
             except ValueError:
                 self._logger.error(
-                    f"Failed to convert position value '{value_str}' for axis {axis} to float."
+                    "Failed to convert position value '%s' for axis %s to float.",
+                    value_str,
+                    axis,
                 )
                 continue
 
@@ -269,31 +425,33 @@ class GCodeController(SerialController):
 
     def sync_position(self) -> Tuple[bool, Dict[str, float]]:
         """
-        Queries the Qubot for its current machine position (M114) and
-        automatically adjusts the controller's internal 'current_position'
-        if a discrepancy is found.
+        Synchronize internal position with actual machine position.
+
+        Queries the machine position and compares it with the internal position.
+        If a discrepancy greater than the tolerance is found, attempts to correct
+        it by moving to the internal position.
 
         Returns:
-            Tuple[bool, Dict[str, float]]: A tuple where the first element
-            is True if a synchronization/adjustment occurred, and the second
-            is the final, synchronized position dictionary.
+            Tuple of (adjustment_occurred: bool, final_position: Dict[str, float])
+            where adjustment_occurred is True if a correction move was made.
+
+        Note:
+            This method may recursively call itself if a correction move is made.
         """
         self._logger.info("Starting position synchronization check (M114).")
 
-        # 1. Query the actual machine position
+        # Query the actual machine position
         queried_position = self.query_position()
 
-        # Check if the query was unsuccessful (only returns empty dict)
         if not queried_position:
             self._logger.warning("Query position failed. Cannot synchronize.")
             return False, self.current_position
 
-        # 2. Compare internal vs. queried position
+        # Compare internal vs. queried position
         axis_keys = ["X", "Y", "Z", "A"]
         adjustment_needed = False
 
         for axis in axis_keys:
-            # Check if axis exists in both dictionaries and if they differ significantly
             if (
                 axis in self.current_position
                 and axis in queried_position
@@ -301,25 +459,24 @@ class GCodeController(SerialController):
                 > self.TOLERANCE
             ):
                 self._logger.warning(
-                    f"Position mismatch found on {axis} axis: "
-                    f"Internal={self.current_position[axis]:.3f}, "
-                    f"Queried={queried_position[axis]:.3f}"
+                    "Position mismatch found on %s axis: Internal=%.3f, Queried=%.3f",
+                    axis,
+                    self.current_position[axis],
+                    queried_position[axis],
                 )
-
                 adjustment_needed = True
-
             elif axis in queried_position:
-                # Update internal position with actual queried position if it differs very slightly
+                # Update internal position with queried position if it differs slightly
                 self.current_position[axis] = queried_position[axis]
 
-        # 3. Perform Re-Synchronization Move if needed
+        # Perform re-synchronization move if needed
         if adjustment_needed:
             self._logger.info(
-                f"** DISCREPANCY DETECTED. Moving robot back to internal position: {self.current_position} **"
+                "** DISCREPANCY DETECTED. Moving robot back to internal position: %s **",
+                self.current_position,
             )
 
             try:
-                # Extract the X, Y, Z, A coordinates from the internal position for the move
                 target_x = self.current_position.get("X")
                 target_y = self.current_position.get("Y")
                 target_z = self.current_position.get("Z")
@@ -328,31 +485,29 @@ class GCodeController(SerialController):
                 self.move_absolute(x=target_x, y=target_y, z=target_z, a=target_a)
                 self._logger.info("Synchronization move successfully completed.")
 
-                # recursive call to verify position after move
-                self.sync_position()
-            except Exception as e:
-                self._logger.error(f"Synchronization move failed: {e}")
-                adjustment_needed = False  # Indicate failure in adjustment, though original discrepancy remains.
+                # Recursive call to verify position after move
+                return self.sync_position()
+            except (ValueError, RuntimeError, OSError) as e:
+                self._logger.error("Synchronization move failed: %s", e)
+                adjustment_needed = False
 
         final_position = self.current_position.copy()
 
         if adjustment_needed:
             self._logger.info(
-                f"Position check complete. Internal position is synchronized with machine."
+                "Position check complete. Internal position is synchronized with machine."
             )
         else:
             self._logger.info("No adjustment was made.")
 
-        # Note: If adjustment_needed was True, it means a move was attempted.
-        # We return the initial state of adjustment_needed (i.e., if a move was triggered).
         return adjustment_needed, final_position
 
     def get_info(self) -> str:
         """
-        Queries the Qubot for machine information (M115 command).
+        Query machine information (M115 command).
 
         Returns:
-            str: The machine information string.
+            Machine information string from the device
         """
         self._logger.info("Querying machine information (M115).")
         self._send_command(self._build_command("M115"))
@@ -361,7 +516,10 @@ class GCodeController(SerialController):
 
     def get_internal_position(self) -> Dict[str, float]:
         """
-        Returns the internally tracked position.
+        Get the internally tracked position.
+
+        Returns:
+            Dictionary containing the current internal position for all axes
         """
-        self._logger.debug(f"Returning internal position: {self.current_position}")
-        return self.current_position
+        self._logger.debug("Returning internal position: %s", self.current_position)
+        return self.current_position.copy()

puda_drivers/transfer/liquid/sartorius/sartorius.py

@@ -1,34 +1,53 @@
-import time
+"""
+Sartorius rLINE pipette controller.
+
+This module provides a Python interface for controlling Sartorius rLINE® electronic
+pipettes and robotic dispensers via serial communication.
+
+Reference: https://api.sartorius.com/document-hub/dam/download/34901/Sartorius-rLine-technical-user-manual-v1.1.pdf
+"""
+
 import logging
 from typing import Optional
+
 from puda_drivers.core.serialcontroller import SerialController
+
 from .constants import STATUS_CODES
 
 
 class SartoriusDeviceError(Exception):
     """Custom exception raised when the Sartorius device reports an error."""
 
-    pass
-
 
 class SartoriusController(SerialController):
     """
-    A standalone Python class for controlling a Sartorius pipette or robotic
-    dispenser via serial communication, using a custom, byte-based command protocol.
+    Controller for Sartorius rLINE® pipettes and robotic dispensers.
+
+    This class provides methods for controlling pipette operations including
+    aspiration, dispensing, tip ejection, and speed control via serial communication.
+
+    Attributes:
+        DEFAULT_BAUDRATE: Default baud rate for serial communication (9600)
+        DEFAULT_TIMEOUT: Default timeout for operations (10 seconds)
+        MICROLITER_PER_STEP: Conversion factor from steps to microliters (0.5 µL/step)
+        MIN_SPEED: Minimum speed setting (1)
+        MAX_SPEED: Maximum speed setting (6)
     """
 
-    # --- Protocol Constants (Hypothetical) ---
+    # Protocol Constants
     DEFAULT_BAUDRATE = 9600
     DEFAULT_TIMEOUT = 10
 
     PROTOCOL_SOH = "\x01"
     SLAVE_ADDRESS = "1"
-    PROTOCOL_TERMINATOR = "º\r"  # Assuming 'º' is part of the terminator sequence
+    PROTOCOL_TERMINATOR = "º\r"
 
-    # --- Sartorius rLine Settings ---
-    STEPS_PER_MICROLITER = 2
+    # Sartorius rLine Settings
+    MICROLITER_PER_STEP = 0.5
     SUCCESS_RESPONSE = "ok"
     ERROR_RESPONSE = "err"
+    MIN_SPEED = 1
+    MAX_SPEED = 6
 
     def __init__(
         self,
@@ -36,15 +55,37 @@ class SartoriusController(SerialController):
         baudrate: int = DEFAULT_BAUDRATE,
         timeout: int = DEFAULT_TIMEOUT,
     ):
+        """
+        Initialize the Sartorius controller.
+
+        Args:
+            port_name: Serial port name (e.g., '/dev/ttyUSB0' or 'COM3')
+            baudrate: Baud rate for serial communication. Defaults to 9600.
+            timeout: Timeout in seconds for operations. Defaults to 10.
+        """
         super().__init__(port_name, baudrate, timeout)
         self._logger = logging.getLogger(__name__)
         self._logger.info(
-            f"Sartorius Controller initialized with port='{port_name}', baudrate={baudrate}, timeout={timeout}"
+            "Sartorius Controller initialized with port='%s', baudrate=%s, timeout=%s",
+            port_name,
+            baudrate,
+            timeout,
         )
 
     def _build_command(self, command_code: str, value: str = "") -> str:
-        """Helper to assemble the custom command string."""
-        cmd = (
+        """
+        Build a command string according to the Sartorius protocol.
+
+        Command format: <SOH><SLAVE_ADDRESS>R<COMMAND_CODE><VALUE><TERMINATOR>
+
+        Args:
+            command_code: Single character command code
+            value: Optional value string to append to the command
+
+        Returns:
+            Complete command string ready to send
+        """
+        return (
             self.PROTOCOL_SOH
             + self.SLAVE_ADDRESS
             + "R"
@@ -52,207 +93,306 @@ class SartoriusController(SerialController):
             + value
             + self.PROTOCOL_TERMINATOR
         )
-        return cmd
 
-    def initialize(self) -> None:
-        """
-        Initializes the pipette unit (RZ command).
+    def _check_response_error(self, response: str, operation: str) -> None:
         """
-        command = self._build_command(command_code="Z")
-        self._logger.info("** Initializing Pipette Head (RZ) **")
+        Check if a response contains an error and raise an exception if so.
 
-        self._send_command(command)
-        res: str = self._read_response()
+        Args:
+            response: Response string from the device
+            operation: Description of the operation being performed (for error message)
 
-        if "err" in res:
+        Raises:
+            SartoriusDeviceError: If the response contains an error
+        """
+        if self.ERROR_RESPONSE in response.lower():
             raise SartoriusDeviceError(
-                f"Pipette initialization failed with error: {res}"
+                f"{operation} failed. Device returned error: {response}"
+            )
+
+    def _validate_speed(self, speed: int, direction: str = "speed") -> None:
+        """
+        Validate that a speed value is within the allowed range.
+
+        Args:
+            speed: Speed value to validate
+            direction: Direction description for error message (e.g., "Inward", "Outward")
+
+        Raises:
+            ValueError: If speed is outside the valid range
+        """
+        if not self.MIN_SPEED <= speed <= self.MAX_SPEED:
+            raise ValueError(
+                f"{direction} speed must be between {self.MIN_SPEED} and {self.MAX_SPEED}, "
+                f"got {speed}"
             )
+
+    def _validate_no_leading_zeros(self, value: int, command_name: str) -> str:
+        """
+        Validate that a numeric value has no leading zeros when converted to string.
+
+        Args:
+            value: Numeric value to validate
+            command_name: Command name for error message (e.g., "RP", "RE")
+
+        Returns:
+            String representation of the value
+
+        Raises:
+            ValueError: If the value has leading zeros
+        """
+        value_str = str(value)
+        if len(value_str) > 1 and value_str.startswith("0"):
+            raise ValueError(
+                f"{command_name} command value must not have leading zeros. "
+                f"Got: {value_str}"
+            )
+        return value_str
+
+    def _execute_command(
+        self, command_code: str, value: str = "", operation: str = ""
+    ) -> str:
+        """
+        Execute a command and return the response.
+
+        Args:
+            command_code: Command code to execute
+            value: Optional value for the command
+            operation: Description of the operation (for logging and error messages)
+
+        Returns:
+            Response string from the device
+
+        Raises:
+            SartoriusDeviceError: If the device returns an error
+        """
+        command = self._build_command(command_code, value)
+        self._send_command(command)
+        response = self._read_response()
+        self._check_response_error(response, operation or f"Command {command_code}")
+        return response
+
+    def initialize(self) -> None:
+        """
+        Initialize the pipette unit (RZ command).
+
+        This command resets the pipette to its initial state and should be called
+        before performing other operations.
+
+        Raises:
+            SartoriusDeviceError: If initialization fails
+        """
+        self._logger.info("** Initializing Pipette Head (RZ) **")
+        self._execute_command("Z", operation="Pipette initialization")
         self._logger.info("** Pipette Initialization Complete **")
 
-    # different from docs
     def get_inward_speed(self) -> int:
         """
-        Queries the current aspirating speed (SI command). Speed is 1-6.
+        Query the current aspirating speed (DI command).
+
+        Returns:
+            Current inward speed setting (1-6)
+
+        Raises:
+            SartoriusDeviceError: If the query fails
         """
-        command = self._build_command(command_code="DI")
         self._logger.info("** Querying Inward Speed (DI) **")
+        response = self._execute_command("DI", operation="Inward speed query")
 
-        self._send_command(command)
-        res: str = self._read_response()
-        if "err" in res:
-            raise SartoriusDeviceError(f"Inward speed query failed with error: {res}")
+        if len(response) < 2:
+            raise SartoriusDeviceError(
+                f"Invalid response format for inward speed query: {response}"
+            )
 
-        self._logger.info(f"** Current Inward Speed: {res[1]} **")
-        return int(res[1])
+        speed = int(response[1])
+        self._logger.info("** Current Inward Speed: %s **", speed)
+        return speed
 
     def set_inward_speed(self, speed: int) -> None:
         """
-        Sets the aspirating speed (SI command). Speed is 1-6.
-        """
-        if not 1 <= speed <= 6:
-            raise ValueError("Inward speed must be between 1 and 6.")
+        Set the aspirating speed (SI command).
 
-        command = self._build_command(command_code="I", value=str(speed))
-        self._logger.info(f"** Setting Inward Speed (SI, Speed: {speed}) **")
+        Args:
+            speed: Speed setting (1-6, where 1 is slowest and 6 is fastest)
 
-        self._send_command(command)
-        res: str = self._read_response()
-        if "err" in res:
-            raise SartoriusDeviceError(f"Setting inward speed failed with error: {res}")
-        self._logger.info(f"** Inward Speed Set to {speed} Successfully **")
+        Raises:
+            ValueError: If speed is outside the valid range
+            SartoriusDeviceError: If setting the speed fails
+        """
+        self._validate_speed(speed, "Inward")
+        self._logger.info("** Setting Inward Speed (SI, Speed: %s) **", speed)
+        self._execute_command("I", value=str(speed), operation="Setting inward speed")
+        self._logger.info("** Inward Speed Set to %s Successfully **", speed)
 
     def get_outward_speed(self) -> int:
         """
-        Queries the current dispensing speed (DO command). Speed is 1-6.
+        Query the current dispensing speed (DO command).
+
+        Returns:
+            Current outward speed setting (1-6)
+
+        Raises:
+            SartoriusDeviceError: If the query fails
         """
-        command = self._build_command(command_code="DO")
         self._logger.info("** Querying Outward Speed (DO) **")
+        response = self._execute_command("DO", operation="Outward speed query")
 
-        self._send_command(command)
-        res: str = self._read_response()
-        if "err" in res:
-            raise SartoriusDeviceError(f"Outward speed query failed with error: {res}")
+        if len(response) < 2:
+            raise SartoriusDeviceError(
+                f"Invalid response format for outward speed query: {response}"
+            )
 
-        self._logger.info(f"** Current Outward Speed: {res[1]} **")
-        return int(res[1])
+        speed = int(response[1])
+        self._logger.info("** Current Outward Speed: %s **", speed)
+        return speed
 
     def set_outward_speed(self, speed: int) -> None:
         """
-        Sets the dispensing speed (SO command). Speed is 1-6.
-        """
-        if not 1 <= speed <= 6:
-            raise ValueError("Outward speed must be between 1 and 6.")
+        Set the dispensing speed (SO command).
 
-        self._logger.info(f"** Setting Outward Speed (SO, Speed: {speed}) **")
+        Args:
+            speed: Speed setting (1-6, where 1 is slowest and 6 is fastest)
 
-        command = self._build_command(command_code="O", value=str(speed))
-        self._send_command(command)
-        res: str = self._read_response()
-        if "err" in res:
-            raise SartoriusDeviceError(
-                f"Setting outward speed failed with error: {res}"
-            )
-        self._logger.info(f"** Outward Speed Set to {speed} Successfully **")
+        Raises:
+            ValueError: If speed is outside the valid range
+            SartoriusDeviceError: If setting the speed fails
+        """
+        self._validate_speed(speed, "Outward")
+        self._logger.info("** Setting Outward Speed (SO, Speed: %s) **", speed)
+        self._execute_command("O", value=str(speed), operation="Setting outward speed")
+        self._logger.info("** Outward Speed Set to %s Successfully **", speed)
 
     def run_to_position(self, position: int) -> None:
         """
-        Drives the piston to the absolute step position nnn (RP command).
-        Steps must be given without leading zeros.
-        """
-        position_str = str(position)
-        # Check if position has leading zeros (RP030 is incorrect)
-        if len(position_str) > 1 and position_str.startswith("0"):
-            raise ValueError("Position value for RP must not have leading zeros.")
-
-        command = self._build_command(command_code="P", value=position_str)
-        self._logger.info(f"** Run to absolute Position (RP, Position: {position}) **")
-
-        self._send_command(command)
-        res: str = self._read_response()
-        if "err" in res:
-            raise SartoriusDeviceError(f"Run to position failed with error: {res}")
+        Drive the piston to an absolute step position (RP command).
 
-        self._logger.info(f"** Reached Position {position} Successfully **")
+        Args:
+            position: Target position in steps (must not have leading zeros)
 
-    def aspirate(self, amount: int) -> None:
+        Raises:
+            ValueError: If position has leading zeros
+            SartoriusDeviceError: If the command fails
         """
-        Aspirates fluid, amount in microliters.
+        position_str = self._validate_no_leading_zeros(position, "RP")
+        self._logger.info("** Run to absolute Position (RP, Position: %s) **", position)
+        self._execute_command("P", value=position_str, operation="Run to position")
+        self._logger.info("** Reached Position %s Successfully **", position)
+
+    def aspirate(self, amount: float) -> None:
         """
-        steps = amount * self.STEPS_PER_MICROLITER
-        command = self._build_command(command_code="I", value=str(steps))
-        self._logger.info(f"** Aspirating {amount} uL (RI{steps}) **")
+        Aspirate fluid from the current location.
 
-        self._send_command(command)
-        res: str = self._read_response()
-        if "err" in res:
-            raise SartoriusDeviceError(f"Aspirate failed with error: {res}")
-        self._logger.info(f"** Aspirated {amount} uL Successfully **")
+        Args:
+            amount: Volume to aspirate in microliters (µL)
 
-    def dispense(self, amount: int) -> None:
+        Raises:
+            ValueError: If amount is negative or zero
+            SartoriusDeviceError: If aspiration fails
         """
-        Dispenses fluid, moving the plunger outwards by nnn steps (RO command).
-        Steps must be given without leading zeros.
-        """
-        steps = amount * self.STEPS_PER_MICROLITER
+        if amount <= 0:
+            raise ValueError(f"Aspiration amount must be positive, got {amount}")
 
-        command = self._build_command(command_code="O", value=str(steps))
-        self._logger.info(f"** Dispensing {amount} uL (RO{steps}) **")
+        steps = int(amount / self.MICROLITER_PER_STEP)
+        self._logger.info("** Aspirating %s uL (RI%s steps) **", amount, steps)
+        self._execute_command("I", value=str(steps), operation="Aspirate")
+        self._logger.info("** Aspirated %s uL Successfully **", amount)
 
-        self._send_command(command)
-        res: str = self._read_response()
-        if "err" in res:
-            raise SartoriusDeviceError(f"Dispense failed with error: {res}")
-        self._logger.info(f"** Dispensed {amount} uL Successfully **")
+    def dispense(self, amount: float) -> None:
+        """
+        Dispense fluid at the current location.
 
-    def eject_tip(self, return_position: Optional[int] = None) -> None:
+        Args:
+            amount: Volume to dispense in microliters (µL)
+
+        Raises:
+            ValueError: If amount is negative or zero
+            SartoriusDeviceError: If dispensing fails
         """
-        Runs the tip eject cycle (RE command).
-        If return_position is None (RE), returns to position 0.
-        If return_position is specified (RE nnn), returns to that position.
+        if amount <= 0:
+            raise ValueError(f"Dispense amount must be positive, got {amount}")
+
+        steps = int(amount / self.MICROLITER_PER_STEP)
+        self._logger.info("** Dispensing %s uL (RO%s steps) **", amount, steps)
+        self._execute_command("O", value=str(steps), operation="Dispense")
+        self._logger.info("** Dispensed %s uL Successfully **", amount)
+
+    def eject_tip(self, return_position: int = 30) -> None:
         """
-        if return_position is not None:
-            position_str = str(return_position)
-            if len(position_str) > 1 and position_str.startswith("0"):
-                raise ValueError(
-                    "Return position value for RE must not have leading zeros."
-                )
-            command = self._build_command(command_code="E", value=position_str)
-            self._logger.info(
-                f"** Ejecting Tip and returning to position {return_position} (RE {return_position}) **"
-            )
-        else:
-            command = self._build_command(command_code="E")
-            self._logger.info("** Ejecting Tip and returning to position 0 (RE) **")
+        Eject the pipette tip (RE command).
 
-        self._send_command(command)
-        res: str = self._read_response()
-        if "err" in res:
-            raise SartoriusDeviceError(f"Tip ejection failed with error: {res}")
+        Args:
+            return_position: Position to return to after ejection. Defaults to 30.
+
+        Raises:
+            ValueError: If return_position has leading zeros
+            SartoriusDeviceError: If tip ejection fails
+        """
+        position_str = self._validate_no_leading_zeros(return_position, "RE")
+        self._logger.info(
+            "** Ejecting Tip and returning to position %s (RE %s) **",
+            return_position,
+            return_position,
+        )
+        self._execute_command(
+            "E", value=position_str, operation="Eject tip with return position"
+        )
         self._logger.info("** Tip Ejection Complete **")
 
     def run_blowout(self, return_position: Optional[int] = None) -> None:
         """
-        Runs the blowout cycle (RB command).
-        If return_position is None (RB), completes the blowout.
-        If return_position is specified (RB nnn), returns to that position.
+        Run the blowout cycle to clear residual liquid (RB command).
+
+        Args:
+            return_position: Optional position to return to after blowout.
+                           If None, completes blowout without returning.
+
+        Raises:
+            ValueError: If return_position has leading zeros
+            SartoriusDeviceError: If blowout fails
         """
         if return_position is not None:
-            position_str = str(return_position)
-            if len(position_str) > 1 and position_str.startswith("0"):
-                raise ValueError(
-                    "Return position value for RB must not have leading zeros."
-                )
-            command = self._build_command(command_code="B", value=position_str)
+            position_str = self._validate_no_leading_zeros(
+                return_position, "RB"
+            )
             self._logger.info(
-                f"** Running Blowout and returning to position {return_position} (RB {return_position}) **"
+                "** Running Blowout and returning to position %s (RB %s) **",
+                return_position,
+                return_position,
+            )
+            self._execute_command(
+                "B", value=position_str, operation="Blowout with return position"
             )
         else:
-            command = self._build_command(command_code="B")
             self._logger.info("** Running Blowout (RB) **")
+            self._execute_command("B", operation="Blowout")
 
-        self._send_command(command)
-        res: str = self._read_response()
-        if "err" in res:
-            raise SartoriusDeviceError(f"Blowout failed with error: {res}")
         self._logger.info("** Blowout Complete **")
 
     def get_status(self) -> str:
         """
-        Queries the current status of the pipette (DS command).
-        Returns a status code string.
+        Query the current status of the pipette (DS command).
+
+        Returns:
+            Status code character (single character string)
+
+        Raises:
+            SartoriusDeviceError: If the status query fails
         """
-        command = self._build_command(command_code="DS")
         self._logger.info("** Querying Pipette Status (DS) **")
+        response = self._execute_command("DS", operation="Status query")
 
-        self._send_command(command)
-        res: str = self._read_response()
-        if "err" in res:
-            raise SartoriusDeviceError(f"Status query failed with error: {res}")
+        if len(response) < 2:
+            raise SartoriusDeviceError(
+                f"Invalid response format for status query: {response}"
+            )
 
-        if len(res) > 1 and res[1] in STATUS_CODES:
-            status_message = STATUS_CODES[res[1]]
-            self._logger.info(f"Pipette Status Code [{res[1]}]: {status_message}")
+        status_code = response[1]
+        if status_code in STATUS_CODES:
+            status_message = STATUS_CODES[status_code]
+            self._logger.info("Pipette Status Code [%s]: %s", status_code, status_message)
         else:
-            self._logger.info(f"Pipette Status Code [{res[1]}]: Unknown Status Code")
-        return res[1]
+            self._logger.warning(
+                "Pipette Status Code [%s]: Unknown Status Code", status_code
+            )
+
+        return status_code

{puda_drivers-0.0.2.dist-info → puda_drivers-0.0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: puda-drivers
-Version: 0.0.2
+Version: 0.0.3
 Summary: Hardware drivers for the PUDA platform.
 Project-URL: Homepage, https://github.com/zhao-bears/puda-drivers
 Project-URL: Issues, https://github.com/zhao-bears/puda-drivers/issues

{puda_drivers-0.0.2.dist-info → puda_drivers-0.0.3.dist-info}/RECORD

@@ -3,15 +3,15 @@ puda_drivers/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 puda_drivers/core/__init__.py,sha256=JM6eWTelwcmjTGM3gprQlJWzPGEpIdRrDmbCHtGoKyM,119
 puda_drivers/core/serialcontroller.py,sha256=-wdQqq30yb6dSsNwA2FQec5HUh0U3j71OOMt6pbQIpc,7230
 puda_drivers/move/__init__.py,sha256=i7G5VKD5FgnmC21TLxoASVtC88IrPUTLDJrTnp99u-0,35
-puda_drivers/move/gcode.py,sha256=DjXxLO5UVaL7-BffRlvC1MQI21bX14zTTwXymLAEugc,13390
+puda_drivers/move/gcode.py,sha256=1KkpgwXBiNrcV4Ilc-6n-ADQwOVwVgK_9x08LKhbE5g,18106
 puda_drivers/move/grbl/__init__.py,sha256=vBeeti8DVN2dACi1rLmHN_UGIOdo0s-HZX6mIepLV5I,98
 puda_drivers/move/grbl/api.py,sha256=loj8_Vap7S9qaD0ReHhgxr9Vkl6Wp7DGzyLkZyZ6v_k,16995
 puda_drivers/move/grbl/constants.py,sha256=4736CRDzLGWVqGscLajMlrIQMyubsHfthXi4RF1CHNg,9585
 puda_drivers/transfer/liquid/sartorius/__init__.py,sha256=QGpKz5YUwa8xCdSMXeZ0iRU-hRVqAWNPK0mlMTuzv8I,101
 puda_drivers/transfer/liquid/sartorius/api.py,sha256=jxwIJmY2k1K2ts6NC2ZgFTe4MOiH8TGnJeqYOqNa3rE,28250
 puda_drivers/transfer/liquid/sartorius/constants.py,sha256=mcsjLrVBH-RSodH-pszstwcEL9wwbV0vOgHbGNxZz9w,2770
-puda_drivers/transfer/liquid/sartorius/sartorius.py,sha256=Nf2EkKWcPOnzFSmAvxs2zwGXFeOC98Nsg1FtArts45w,9885
-puda_drivers-0.0.2.dist-info/METADATA,sha256=rLtN2A0N7z90pHiPHTSbDJMPnyKz-6ZJGIJ5JQlb0ZI,5153
-puda_drivers-0.0.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-puda_drivers-0.0.2.dist-info/licenses/LICENSE,sha256=7EI8xVBu6h_7_JlVw-yPhhOZlpY9hP8wal7kHtqKT_E,1074
-puda_drivers-0.0.2.dist-info/RECORD,,
+puda_drivers/transfer/liquid/sartorius/sartorius.py,sha256=iW3v-YHjj4ZAfGv0x0J-XV-Y0fAAhS6xmSg2ozQm4UI,13803
+puda_drivers-0.0.3.dist-info/METADATA,sha256=and-Tnldz1Er_yVN76nJdmDDCsqoiEEJmyIovzaXNMI,5153
+puda_drivers-0.0.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+puda_drivers-0.0.3.dist-info/licenses/LICENSE,sha256=7EI8xVBu6h_7_JlVw-yPhhOZlpY9hP8wal7kHtqKT_E,1074
+puda_drivers-0.0.3.dist-info/RECORD,,