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

puda_drivers/core/serialcontroller.py

@@ -2,12 +2,12 @@
 Generic Serial Controller for communicating with devices over serial ports.
 """
 
-import serial
 import time
-import serial.tools.list_ports
 import logging
 from typing import Optional, List, Tuple
 from abc import ABC
+import serial
+import serial.tools.list_ports
 
 logger = logging.getLogger(__name__)
 
@@ -45,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):
@@ -127,8 +127,8 @@ class SerialController(ABC):
         try:
             self._serial.reset_input_buffer()  # clear input buffer
             self._serial.reset_output_buffer()  # clear output buffer
-            self._serial.write(bytes(command, "utf-8"))
             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)

puda_drivers/move/gcode.py

@@ -55,7 +55,9 @@ class GCodeController(SerialController):
 
     DEFAULT_FEEDRATE = 3000  # mm/min
     MAX_FEEDRATE = 3000  # mm/min
+    MAX_Z_FEED_RATE = 1000 # mm/min
     TOLERANCE = 0.01  # tolerance for position sync in mm
+    SAFE_MOVE_HEIGHT = -5 # safe height for Z and A axes in mm
 
     PROTOCOL_TERMINATOR = "\r"
     VALID_AXES = "XYZA"
@@ -66,6 +68,7 @@ class GCodeController(SerialController):
         baudrate: int = SerialController.DEFAULT_BAUDRATE,
         timeout: int = SerialController.DEFAULT_TIMEOUT,
         feed: int = DEFAULT_FEEDRATE,
+        z_feed: int = MAX_Z_FEED_RATE,
     ):
         """
         Initialize the G-code controller.
@@ -87,13 +90,14 @@ class GCodeController(SerialController):
         )
 
         # Tracks internal position state
-        self.current_position: Dict[str, float] = {
+        self._current_position: Dict[str, float] = {
             "X": 0.0,
             "Y": 0.0,
             "Z": 0.0,
             "A": 0.0,
         }
         self._feed: int = feed
+        self._z_feed: int = z_feed
 
         # Initialize axis limits with default values
         self._axis_limits: Dict[str, AxisLimits] = {
@@ -151,6 +155,15 @@ class GCodeController(SerialController):
         """
         return f"{command}{self.PROTOCOL_TERMINATOR}"
 
+    def wait_for_move(self) -> None:
+        """
+        Wait for the current move to complete (M400 command).
+        
+        This sends the M400 command which waits for all moves in the queue to complete
+        before continuing. This ensures that position updates are accurate.
+        """
+        self.execute(self._build_command("M400"))
+
     def _validate_axis(self, axis: str) -> str:
         """
         Validate and normalize an axis name.
@@ -292,19 +305,19 @@ class GCodeController(SerialController):
             home_target = "All"
 
         self._logger.info("[%s] homing axis/axes: %s **", cmd, home_target)
-        self._send_command(self._build_command(cmd))
+        self.execute(self._build_command(cmd))
         self._logger.info("Homing of %s completed.", home_target)
 
         # Update internal position (optimistic zeroing)
         if axis:
-            self.current_position[axis] = 0.0
+            self._current_position[axis] = 0.0
         else:
-            for key in self.current_position:
-                self.current_position[key] = 0.0
+            for key in self._current_position:
+                self._current_position[key] = 0.0
 
         self._logger.debug(
             "Internal position updated (optimistically zeroed) to %s",
-            self.current_position,
+            self._current_position,
         )
 
     def move_absolute(
@@ -314,7 +327,7 @@ class GCodeController(SerialController):
         z: Optional[float] = None,
         a: Optional[float] = None,
         feed: Optional[int] = None,
-    ) -> None:
+    ) -> Dict[str, float]:
         """
         Move to an absolute position (G90 + G1 command).
 
@@ -331,17 +344,26 @@ class GCodeController(SerialController):
         # Validate positions before executing move
         self._validate_move_positions(x=x, y=y, z=z, a=a)
 
+        # Fill in missing axes with current positions
+        target_x = x if x is not None else self._current_position["X"]
+        target_y = y if y is not None else self._current_position["Y"]
+        target_z = z if z is not None else self._current_position["Z"]
+        target_a = a if a is not None else self._current_position["A"]
+
         feed_rate = feed if feed is not None else self._feed
         self._logger.info(
             "Preparing absolute move to X:%s, Y:%s, Z:%s, A:%s at F:%s",
-            x,
-            y,
-            z,
-            a,
+            target_x,
+            target_y,
+            target_z,
+            target_a,
             feed_rate,
         )
 
-        self._execute_move(x=x, y=y, z=z, a=a, feed=feed)
+        return self._execute_move(
+            position={"X": target_x, "Y": target_y, "Z": target_z, "A": target_a},
+            feed=feed_rate
+        )
 
     def move_relative(
         self,
@@ -350,7 +372,7 @@ class GCodeController(SerialController):
         z: Optional[float] = None,
         a: Optional[float] = None,
         feed: Optional[int] = None,
-    ) -> None:
+    ) -> Dict[str, float]:
         """
         Move relative to the current position (converted to absolute move internally).
 
@@ -374,133 +396,111 @@ class GCodeController(SerialController):
             feed_rate,
         )
 
-        # Convert relative movements to absolute positions
-        abs_x = (self.current_position["X"] + x) if x is not None else None
-        abs_y = (self.current_position["Y"] + y) if y is not None else None
-        abs_z = (self.current_position["Z"] + z) if z is not None else None
-        abs_a = (self.current_position["A"] + a) if a is not None else None
+        # Convert relative movements to absolute positions, filling in missing axes with current position
+        abs_x = (self._current_position["X"] + x) if x is not None else self._current_position["X"]
+        abs_y = (self._current_position["Y"] + y) if y is not None else self._current_position["Y"]
+        abs_z = (self._current_position["Z"] + z) if z is not None else self._current_position["Z"]
+        abs_a = (self._current_position["A"] + a) if a is not None else self._current_position["A"]
 
         # Validate absolute positions before executing move
         self._validate_move_positions(x=abs_x, y=abs_y, z=abs_z, a=abs_a)
 
-        self._execute_move(x=abs_x, y=abs_y, z=abs_z, a=abs_a, feed=feed)
+        return self._execute_move(
+            position={"X": abs_x, "Y": abs_y, "Z": abs_z, "A": abs_a},
+            feed=feed_rate
+        )
 
     def _execute_move(
         self,
-        x: Optional[float] = None,
-        y: Optional[float] = None,
-        z: Optional[float] = None,
-        a: Optional[float] = None,
-        feed: Optional[int] = None,
-    ) -> None:
+        position: Dict[str, float],
+        feed: int,
+    ) -> Dict[str, float]:
         """
         Internal helper for executing G1 move commands with safe movement pattern.
         All coordinates are treated as absolute positions.
 
         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)
+        2. Then move X, Y to target
+        3. Finally move Z and A back to original position (or target if specified)
 
         Args:
-            x: Absolute X position (optional)
-            y: Absolute Y position (optional)
-            z: Absolute Z position (optional)
-            a: Absolute A position (optional)
-            feed: Feed rate (optional)
-        """
-        # Calculate target positions (all absolute)
-        target_pos = self.current_position.copy()
-        has_x = x is not None
-        has_y = y is not None
-        has_z = z is not None
-        has_a = a is not None
-
-        if not (has_x or has_y or has_z or has_a):
+            position: Dictionary with absolute positions for X, Y, Z, A axes
+            feed: Feed rate for the move
+        """
+        # Check if any movement is needed
+        needs_x_move = abs(position["X"] - self._current_position["X"]) > self.TOLERANCE
+        needs_y_move = abs(position["Y"] - self._current_position["Y"]) > self.TOLERANCE
+        needs_z_move = abs(position["Z"] - self._current_position["Z"]) > self.TOLERANCE
+        needs_a_move = abs(position["A"] - self._current_position["A"]) > self.TOLERANCE
+
+        if not (needs_x_move or needs_y_move or needs_z_move or needs_a_move):
             self._logger.warning(
                 "Move command issued without any axis movement. Skipping transmission."
             )
             return
+        
+        if needs_z_move and needs_a_move:
+            self._logger.warning(
+                "Move command issued with both Z and A movement. This is not supported. Skipping transmission."
+            )
+            raise ValueError("Move command issued with both Z and A movement. This is not supported.")
 
-        # Set target positions (all absolute)
-        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
-
-        feed_rate = feed if feed is not None else self._feed
-        if feed_rate > self.MAX_FEEDRATE:
-            feed_rate = self.MAX_FEEDRATE
-
-        # Ensure absolute mode is active
-        self._send_command(self._build_command("G90"))
-
-        # 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
+        # Step 0: Ensure absolute mode is active
+        self.execute(self._build_command("G90"))
+        needs_xy_move = needs_x_move or needs_y_move
 
-        # 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
-            # Validate safe height (Z=0) is within limits
-            self._validate_move_positions(z=0.0)
+        # Step 1: Move Z and A to SAFE_MOVE_HEIGHT if XY movement is needed
+        if needs_xy_move:
             self._logger.info(
-                "Safe move: Raising Z to safe height (0) before XY movement"
+                "Safe move: Raising Z and A to safe height (%s) before XY movement", self.SAFE_MOVE_HEIGHT
             )
-            move_cmd = f"G1 Z0 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 = f"G1 Z-5 A-5 F{self._z_feed}"
+            self.execute(self._build_command(move_cmd))
+            self.wait_for_move()
+            self._current_position["Z"] = self.SAFE_MOVE_HEIGHT
+            self._current_position["A"] = self.SAFE_MOVE_HEIGHT
+            self._logger.debug("Z and A moved to safe height (%s)", self.SAFE_MOVE_HEIGHT)
+
+        # Step 2: Move X, Y to target
+        if needs_xy_move:
             move_cmd = "G1"
-            if has_x:
-                move_cmd += f" X{target_pos['X']}"
-            if has_y:
-                move_cmd += f" Y{target_pos['Y']}"
-            if has_a:
-                move_cmd += f" A{target_pos['A']}"
-            move_cmd += f" F{feed_rate}"
+            if needs_x_move:
+                move_cmd += f" X{position['X']}"
+            if needs_y_move:
+                move_cmd += f" Y{position['Y']}"
+            move_cmd += f" F{feed}"
 
             self._logger.info("Executing XY move command: %s", move_cmd)
-            self._send_command(self._build_command(move_cmd))
+            self.execute(self._build_command(move_cmd))
+            self.wait_for_move()
 
             # 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:
-                move_cmd = f"G1 Z{target_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
+            if needs_x_move:
+                self._current_position["X"] = position['X']
+            if needs_y_move:
+                self._current_position["Y"] = position['Y']
+
+        # Step 3: Move Z and A back to original position (or target if specified)
+        if needs_z_move:
+            move_cmd = f"G1 Z{position['Z']} F{self._z_feed}"
+            self.execute(self._build_command(move_cmd))
+            self._current_position["Z"] = position['Z']
+        elif needs_a_move:
+            move_cmd = f"G1 A{position['A']} F{self._z_feed}"
+            self.execute(self._build_command(move_cmd))
+            self._current_position["A"] = position['A']
+        self.wait_for_move()
 
         self._logger.info(
-            "Move complete. Final position: %s", self.current_position
+            "Move complete. Final position: %s", self._current_position
         )
-        self._logger.debug("New internal position: %s", self.current_position)
+        self._logger.debug("New internal position: %s", self._current_position)
 
-        # Post-move position synchronization check
+        # Step 4: Post-move position synchronization check
         self.sync_position()
+        
+        return self._current_position
 
     def query_position(self) -> Dict[str, float]:
         """
@@ -555,8 +555,8 @@ class GCodeController(SerialController):
         queried_position = self.query_position()
 
         if not queried_position:
-            self._logger.warning("Query position failed. Cannot synchronize.")
-            return False, self.current_position
+            self._logger.error("Query position failed. Cannot synchronize.")
+            raise ValueError("Query position failed. Cannot synchronize.")
 
         # Compare internal vs. queried position
         axis_keys = ["X", "Y", "Z", "A"]
@@ -564,36 +564,31 @@ class GCodeController(SerialController):
 
         for axis in axis_keys:
             if (
-                axis in self.current_position
+                axis in self._current_position
                 and axis in queried_position
-                and abs(self.current_position[axis] - queried_position[axis])
+                and abs(self._current_position[axis] - queried_position[axis])
                 > self.TOLERANCE
             ):
                 self._logger.warning(
                     "Position mismatch found on %s axis: Internal=%.3f, Queried=%.3f",
                     axis,
-                    self.current_position[axis],
+                    self._current_position[axis],
                     queried_position[axis],
                 )
                 adjustment_needed = True
             elif axis in queried_position:
                 # Update internal position with queried position if it differs slightly
-                self.current_position[axis] = queried_position[axis]
+                self._current_position[axis] = queried_position[axis]
 
         # Perform re-synchronization move if needed
         if adjustment_needed:
             self._logger.info(
-                "** DISCREPANCY DETECTED. Moving robot back to internal position: %s **",
-                self.current_position,
+                "** DISCREPANCY DETECTED. Moving robot to internal position: %s **",
+                self._current_position,
             )
 
             try:
-                target_x = self.current_position.get("X")
-                target_y = self.current_position.get("Y")
-                target_z = self.current_position.get("Z")
-                target_a = self.current_position.get("A")
-
-                self.move_absolute(x=target_x, y=target_y, z=target_z, a=target_a)
+                self.move_absolute(x=self._current_position["X"], y=self._current_position["Y"], z=self._current_position["Z"], a=self._current_position["A"])
                 self._logger.info("Synchronization move successfully completed.")
 
                 # Recursive call to verify position after move
@@ -609,7 +604,7 @@ class GCodeController(SerialController):
         else:
             self._logger.info("No adjustment was made.")
 
-        return adjustment_needed, self.current_position.copy()
+        return adjustment_needed, self._current_position.copy()
 
     def get_info(self) -> str:
         """
@@ -628,5 +623,5 @@ class GCodeController(SerialController):
         Returns:
             Dictionary containing the current internal position for all axes
         """
-        self._logger.debug("Returning internal position: %s", self.current_position)
-        return self.current_position.copy()
+        self._logger.debug("Returning internal position: %s", self._current_position)
+        return self._current_position.copy()

{puda_drivers-0.0.4.dist-info → puda_drivers-0.0.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: puda-drivers
-Version: 0.0.4
+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:

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

@@ -1,9 +1,9 @@
 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=c-_kMLKxz9hLhpG-54wENkLeN0bNzY1rP9zML1RV9uc,7660
+puda_drivers/core/serialcontroller.py,sha256=I7TsLNl45HPrO29LkhMRIQQ8fWdjdJUvIwQQ5swbMHM,7660
 puda_drivers/move/__init__.py,sha256=i7G5VKD5FgnmC21TLxoASVtC88IrPUTLDJrTnp99u-0,35
-puda_drivers/move/gcode.py,sha256=hgI5YzvSABJBlz5QlaNoUysB_7m9dhqXXkNm-zguYqQ,21504
+puda_drivers/move/gcode.py,sha256=egZw3D5m9d1R8P32L1wd3lDwiWcFMDGPHsFMFIYXkRA,22069
 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
@@ -11,7 +11,7 @@ puda_drivers/transfer/liquid/sartorius/__init__.py,sha256=QGpKz5YUwa8xCdSMXeZ0iR
 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=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,,
+puda_drivers-0.0.5.dist-info/METADATA,sha256=5VB_QiC_hcuV4-FEoXi-qEp637jAjQLiv5fipHX9QPg,6559
+puda_drivers-0.0.5.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+puda_drivers-0.0.5.dist-info/licenses/LICENSE,sha256=7EI8xVBu6h_7_JlVw-yPhhOZlpY9hP8wal7kHtqKT_E,1074
+puda_drivers-0.0.5.dist-info/RECORD,,