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

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.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: puda-drivers
-Version: 0.0.2
+Version: 0.0.4
 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
@@ -158,8 +158,6 @@ for port, desc, hwid in ports:
 sartorius_ports = list_serial_ports(filter_desc="Sartorius")
 ```
 
-**Note:** The `list_ports()` method is also available as a static method on `SerialController` for backward compatibility, but the module-level `list_serial_ports()` function is the recommended approach.
-
 ## Requirements
 
 - Python >= 3.14

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

@@ -1,17 +1,17 @@
 puda_drivers/__init__.py,sha256=rcF5xCkMgyLlJLN3gWwJnUoW0ShPyISeyENvaqwg4Ik,503
 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/core/serialcontroller.py,sha256=c-_kMLKxz9hLhpG-54wENkLeN0bNzY1rP9zML1RV9uc,7660
 puda_drivers/move/__init__.py,sha256=i7G5VKD5FgnmC21TLxoASVtC88IrPUTLDJrTnp99u-0,35
-puda_drivers/move/gcode.py,sha256=DjXxLO5UVaL7-BffRlvC1MQI21bX14zTTwXymLAEugc,13390
+puda_drivers/move/gcode.py,sha256=hgI5YzvSABJBlz5QlaNoUysB_7m9dhqXXkNm-zguYqQ,21504
 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.4.dist-info/METADATA,sha256=Kx3TqzraU6R_AxNW8kPRK5F9GntTiBDqk8Z7HEFDhDs,4948
+puda_drivers-0.0.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+puda_drivers-0.0.4.dist-info/licenses/LICENSE,sha256=7EI8xVBu6h_7_JlVw-yPhhOZlpY9hP8wal7kHtqKT_E,1074
+puda_drivers-0.0.4.dist-info/RECORD,,