puda-drivers 0.0.3__tar.gz → 0.0.5__tar.gz

{puda_drivers-0.0.3 → puda_drivers-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: puda-drivers
-Version: 0.0.3
+Version: 0.0.5
 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
@@ -56,13 +56,19 @@ from puda_drivers.move import GCodeController
 gantry = GCodeController(port_name="/dev/ttyACM0", feed=3000)
 gantry.connect()
 
+# Configure axis limits for safety (recommended)
+gantry.set_axis_limits("X", 0, 200)
+gantry.set_axis_limits("Y", -200, 0)
+gantry.set_axis_limits("Z", -100, 0)
+gantry.set_axis_limits("A", -180, 180)
+
 # Home the gantry
 gantry.home()
 
-# Move to absolute position
+# Move to absolute position (validated against limits)
 gantry.move_absolute(x=50.0, y=-100.0, z=-10.0)
 
-# Move relative to current position
+# Move relative to current position (validated after conversion to absolute)
 gantry.move_relative(x=20.0, y=-10.0)
 
 # Query current position
@@ -73,6 +79,8 @@ print(f"Current position: {position}")
 gantry.disconnect()
 ```
 
+**Axis Limits and Validation**: The `move_absolute()` and `move_relative()` methods automatically validate that target positions are within configured axis limits. If a position is outside the limits, a `ValueError` is raised before any movement is executed. Use `set_axis_limits()` to configure limits for each axis.
+
 ### Liquid Handling (Sartorius)
 
 ```python
@@ -134,6 +142,7 @@ pipette.disconnect()
   - Supports X, Y, Z, and A axes
   - Configurable feed rates
   - Position synchronization and homing
+  - Automatic axis limit validation for safe operation
 
 ### Liquid Handling
 
@@ -142,6 +151,38 @@ pipette.disconnect()
   - Tip attachment and ejection
   - Configurable speeds and volumes
 
+## Error Handling
+
+### Axis Limit Validation
+
+Both `move_absolute()` and `move_relative()` validate positions against configured axis limits before executing any movement. If a position is outside the limits, a `ValueError` is raised:
+
+```python
+from puda_drivers.move import GCodeController
+
+gantry = GCodeController(port_name="/dev/ttyACM0")
+gantry.connect()
+
+# Set axis limits
+gantry.set_axis_limits("X", 0, 200)
+gantry.set_axis_limits("Y", -200, 0)
+
+try:
+    # This will raise ValueError: Value 250 outside axis limits [0, 200]
+    gantry.move_absolute(x=250.0, y=-50.0)
+except ValueError as e:
+    print(f"Move rejected: {e}")
+
+# Relative moves are also validated after conversion to absolute positions
+try:
+    # If current X is 150, moving 100 more would exceed the limit
+    gantry.move_relative(x=100.0)
+except ValueError as e:
+    print(f"Move rejected: {e}")
+```
+
+Validation errors are automatically logged at the ERROR level before the exception is raised.
+
 ## Finding Serial Ports
 
 To discover available serial ports on your system:
@@ -158,8 +199,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.3 → puda_drivers-0.0.5}/README.md

@@ -36,13 +36,19 @@ from puda_drivers.move import GCodeController
 gantry = GCodeController(port_name="/dev/ttyACM0", feed=3000)
 gantry.connect()
 
+# Configure axis limits for safety (recommended)
+gantry.set_axis_limits("X", 0, 200)
+gantry.set_axis_limits("Y", -200, 0)
+gantry.set_axis_limits("Z", -100, 0)
+gantry.set_axis_limits("A", -180, 180)
+
 # Home the gantry
 gantry.home()
 
-# Move to absolute position
+# Move to absolute position (validated against limits)
 gantry.move_absolute(x=50.0, y=-100.0, z=-10.0)
 
-# Move relative to current position
+# Move relative to current position (validated after conversion to absolute)
 gantry.move_relative(x=20.0, y=-10.0)
 
 # Query current position
@@ -53,6 +59,8 @@ print(f"Current position: {position}")
 gantry.disconnect()
 ```
 
+**Axis Limits and Validation**: The `move_absolute()` and `move_relative()` methods automatically validate that target positions are within configured axis limits. If a position is outside the limits, a `ValueError` is raised before any movement is executed. Use `set_axis_limits()` to configure limits for each axis.
+
 ### Liquid Handling (Sartorius)
 
 ```python
@@ -114,6 +122,7 @@ pipette.disconnect()
   - Supports X, Y, Z, and A axes
   - Configurable feed rates
   - Position synchronization and homing
+  - Automatic axis limit validation for safe operation
 
 ### Liquid Handling
 
@@ -122,6 +131,38 @@ pipette.disconnect()
   - Tip attachment and ejection
   - Configurable speeds and volumes
 
+## Error Handling
+
+### Axis Limit Validation
+
+Both `move_absolute()` and `move_relative()` validate positions against configured axis limits before executing any movement. If a position is outside the limits, a `ValueError` is raised:
+
+```python
+from puda_drivers.move import GCodeController
+
+gantry = GCodeController(port_name="/dev/ttyACM0")
+gantry.connect()
+
+# Set axis limits
+gantry.set_axis_limits("X", 0, 200)
+gantry.set_axis_limits("Y", -200, 0)
+
+try:
+    # This will raise ValueError: Value 250 outside axis limits [0, 200]
+    gantry.move_absolute(x=250.0, y=-50.0)
+except ValueError as e:
+    print(f"Move rejected: {e}")
+
+# Relative moves are also validated after conversion to absolute positions
+try:
+    # If current X is 150, moving 100 more would exceed the limit
+    gantry.move_relative(x=100.0)
+except ValueError as e:
+    print(f"Move rejected: {e}")
+```
+
+Validation errors are automatically logged at the ERROR level before the exception is raised.
+
 ## Finding Serial Ports
 
 To discover available serial ports on your system:
@@ -138,8 +179,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.3 → puda_drivers-0.0.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "puda-drivers"
-version = "0.0.3"
+version = "0.0.5"
 description = "Hardware drivers for the PUDA platform."
 readme = "README.md"
 authors = [

{puda_drivers-0.0.3 → puda_drivers-0.0.5}/src/puda_drivers/core/serialcontroller.py

@@ -2,13 +2,12 @@
 Generic Serial Controller for communicating with devices over serial ports.
 """
 
-import serial
-import sys
 import time
-import serial.tools.list_ports
 import logging
 from typing import Optional, List, Tuple
-from abc import ABC, abstractmethod
+from abc import ABC
+import serial
+import serial.tools.list_ports
 
 logger = logging.getLogger(__name__)
 
@@ -46,7 +45,7 @@ def list_serial_ports(filter_desc: Optional[str] = None) -> List[Tuple[str, str,
 
 class SerialController(ABC):
     DEFAULT_BAUDRATE = 9600
-    DEFAULT_TIMEOUT = 20  # seconds
+    DEFAULT_TIMEOUT = 30  # seconds
     POLL_INTERVAL = 0.1  # seconds
 
     def __init__(self, port_name, baudrate=DEFAULT_BAUDRATE, timeout=DEFAULT_TIMEOUT):
@@ -58,23 +57,6 @@ class SerialController(ABC):
 
         self.connect()
 
-    @staticmethod
-    def list_ports(filter_desc: Optional[str] = None) -> List[Tuple[str, str, str]]:
-        """
-        Lists available serial ports on the system.
-
-        .. deprecated:: 0.0.1
-           Use the module-level function :func:`list_serial_ports` instead.
-           This method is kept for backward compatibility.
-
-        Args:
-            filter_desc: Optional string to filter ports by description (case-insensitive).
-
-        Returns:
-            List of tuples, where each tuple contains (port_name, description, hwid).
-        """
-        return list_serial_ports(filter_desc)
-
     def connect(self) -> None:
         """
         Establishes the serial connection to the port.
@@ -89,7 +71,9 @@ class SerialController(ABC):
 
         try:
             self._logger.info(
-                f"Attempting connection to {self.port_name} at {self.baudrate} baud."
+                "Attempting connection to %s at %s baud.",
+                self.port_name,
+                self.baudrate,
             )
             self._serial = serial.Serial(
                 port=self.port_name,
@@ -97,10 +81,10 @@ class SerialController(ABC):
                 timeout=self.timeout,
             )
             self._serial.flush()
-            self._logger.info(f"Successfully connected to {self.port_name}.")
+            self._logger.info("Successfully connected to %s.", self.port_name)
         except serial.SerialException as e:
             self._serial = None
-            self._logger.error(f"Error connecting to port {self.port_name}: {e}")
+            self._logger.error("Error connecting to port %s: %s", self.port_name, e)
             raise serial.SerialException(
                 f"Error connecting to port {self.port_name}: {e}"
             )
@@ -113,7 +97,7 @@ class SerialController(ABC):
             port_name = self._serial.port
             self._serial.close()
             self._serial = None
-            self._logger.info(f"Serial connection to {port_name} closed.")
+            self._logger.info("Serial connection to %s closed.", port_name)
         else:
             self._logger.warning(
                 "Serial port already disconnected or was never connected."
@@ -131,29 +115,31 @@ class SerialController(ABC):
         """
         if not self.is_connected or not self._serial:
             self._logger.error(
-                f"Attempt to send command '{command}' failed: Device not connected."
+                "Attempt to send command '%s' failed: Device not connected.",
+                command,
             )
             # Retain raising an error for being disconnected, as that's a connection state issue
             raise serial.SerialException("Device not connected. Call connect() first.")
 
-        command_bytes = bytes(command, "utf-8")
-        self._logger.info(f"-> Sending: {repr(command)}")
+        self._logger.info("-> Sending: %r", command)
 
         # Send the command
         try:
             self._serial.reset_input_buffer()  # clear input buffer
             self._serial.reset_output_buffer()  # clear output buffer
-            self._serial.write(command_bytes)
             self._serial.flush()
+            self._serial.write(bytes(command, "utf-8"))
 
         except serial.SerialTimeoutException as e:
             # Log the timeout error and return None as requested (no re-raise)
-            self._logger.error(f"Timeout on command '{command}'. Error: {e}")
+            self._logger.error("Timeout on command '%s'. Error: %s", command, e)
             return None
 
         except serial.SerialException as e:
             self._logger.error(
-                f"Serial error writing or reading command '{command}'. Error: {e}"
+                "Serial error writing or reading command '%s'. Error: %s",
+                command,
+                e,
             )
             return None
 
@@ -173,22 +159,51 @@ class SerialController(ABC):
                 # Read all available bytes
                 response += self._serial.read(self._serial.in_waiting)
 
-                # 5. Check if the 'ok' response is in the accumulated data
-                if b"ok" in response:
-                    self._logger.debug(f"<- Received response: {response!r}")
-                    return response.decode("utf-8", errors="ignore").strip()
-                if b"err" in response:
-                    self._logger.error(f"<- Received error: {response!r}")
-                    return response.decode("utf-8", errors="ignore").strip()
+                # Check for expected response markers for early return
+                if b"ok" in response or b"err" in response:
+                    break
             else:
                 time.sleep(0.1)
 
+        # Timeout reached - check what we got
         if not response:
-            self._logger.warning("<- Received no data (empty response).")
-            self._logger.error(f"No response within {self.timeout} seconds.")
-            sys.exit(124)  # Exit code for timeout
-
-        self._logger.info(
-            f"<- Received: {response.decode('utf-8', errors='ignore').strip()!r}"
-        )
-        return response.decode("utf-8", errors="ignore").strip()
+            self._logger.error("No response within %s seconds.", self.timeout)
+            raise serial.SerialTimeoutException(
+                f"No response received within {self.timeout} seconds."
+            )
+
+        # Decode once and check the decoded string
+        decoded_response = response.decode("utf-8", errors="ignore").strip()
+        
+        if "ok" in decoded_response.lower():
+            self._logger.debug("<- Received response: %r", decoded_response)
+        elif "err" in decoded_response.lower():
+            self._logger.error("<- Received error: %r", decoded_response)
+        else:
+            self._logger.warning(
+                "<- Received unexpected response (no 'ok' or 'err'): %r", decoded_response
+            )
+        
+        return decoded_response
+
+    def execute(self, command: str) -> str:
+        """
+        Send a command and read the response atomically.
+        
+        This method combines sending a command and reading its response into a
+        single atomic operation, ensuring the response corresponds to the command
+        that was just sent. This is the preferred method for commands that
+        require a response.
+        
+        Args:
+            command: Command string to send (should include protocol terminator if needed)
+            
+        Returns:
+            Response string from the device
+            
+        Raises:
+            serial.SerialException: If device is not connected or communication fails
+            serial.SerialTimeoutException: If no response is received within timeout
+        """
+        self._send_command(command)
+        return self._read_response()