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

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()

puda_drivers/move/gcode.py

@@ -2,24 +2,50 @@
 G-code controller for motion systems.
 
 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.
+systems (e.g., QuBot) via serial communication. All movements are executed in
+absolute coordinates, with relative moves converted to absolute internally.
+Supports homing and position synchronization.
 """
 
 import re
 import logging
-from typing import Optional, Dict, Tuple
+from dataclasses import dataclass
+from typing import Optional, Dict, Tuple, Union
 
 from puda_drivers.core.serialcontroller import SerialController
 
 
+@dataclass
+class AxisLimits:
+    """Holds min/max limits for an axis."""
+
+    min: float
+    max: float
+
+    def validate(self, value: float) -> None:
+        """
+        Validate that a value is within the axis limits.
+
+        Args:
+            value: Value to validate
+
+        Raises:
+            ValueError: If value is outside the limits
+        """
+        if not (self.min <= value <= self.max):
+            raise ValueError(
+                f"Value {value} outside axis limits [{self.min}, {self.max}]"
+            )
+
+
 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.
+    understand G-code commands. All movements are executed in absolute coordinates,
+    with relative moves converted to absolute internally. Supports homing and
+    position synchronization.
 
     Attributes:
         DEFAULT_FEEDRATE: Default feed rate in mm/min (3000)
@@ -29,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"
@@ -40,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.
@@ -61,14 +90,22 @@ 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._is_absolute_mode: bool = True  # absolute mode by default
+        self._z_feed: int = z_feed
+
+        # Initialize axis limits with default values
+        self._axis_limits: Dict[str, AxisLimits] = {
+            "X": AxisLimits(0, 0),
+            "Y": AxisLimits(0, 0),
+            "Z": AxisLimits(0, 0),
+            "A": AxisLimits(0, 0),
+        }
 
     @property
     def feed(self) -> int:
@@ -118,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.
@@ -143,6 +189,102 @@ class GCodeController(SerialController):
             )
         return axis_upper
 
+    def _validate_move_positions(
+        self,
+        x: Optional[float] = None,
+        y: Optional[float] = None,
+        z: Optional[float] = None,
+        a: Optional[float] = None,
+    ) -> None:
+        """
+        Validate that move positions are within axis limits.
+
+        Only validates axes that are being moved (not None). Raises ValueError
+        if any position is outside the configured limits.
+
+        Args:
+            x: Target X position (optional)
+            y: Target Y position (optional)
+            z: Target Z position (optional)
+            a: Target A position (optional)
+
+        Raises:
+            ValueError: If any position is outside the axis limits
+        """
+        if x is not None:
+            if "X" in self._axis_limits:
+                try:
+                    self._axis_limits["X"].validate(x)
+                except ValueError as e:
+                    self._logger.error("Move validation failed for X axis: %s", e)
+                    raise
+        if y is not None:
+            if "Y" in self._axis_limits:
+                try:
+                    self._axis_limits["Y"].validate(y)
+                except ValueError as e:
+                    self._logger.error("Move validation failed for Y axis: %s", e)
+                    raise
+        if z is not None:
+            if "Z" in self._axis_limits:
+                try:
+                    self._axis_limits["Z"].validate(z)
+                except ValueError as e:
+                    self._logger.error("Move validation failed for Z axis: %s", e)
+                    raise
+        if a is not None:
+            if "A" in self._axis_limits:
+                try:
+                    self._axis_limits["A"].validate(a)
+                except ValueError as e:
+                    self._logger.error("Move validation failed for A axis: %s", e)
+                    raise
+
+    def set_axis_limits(
+        self, axis: str, min_val: float, max_val: float
+    ) -> None:
+        """
+        Set the min/max limits for an axis.
+
+        Args:
+            axis: Axis name ('X', 'Y', 'Z', 'A')
+            min_val: Minimum allowed value
+            max_val: Maximum allowed value
+
+        Raises:
+            ValueError: If axis is unknown or min >= max
+        """
+        axis = self._validate_axis(axis)
+
+        if min_val >= max_val:
+            raise ValueError("min must be < max")
+
+        self._axis_limits[axis] = AxisLimits(min_val, max_val)
+        self._logger.info(
+            "Set limits for axis %s: [%s, %s]", axis, min_val, max_val
+        )
+
+    def get_axis_limits(
+        self, axis: Optional[str] = None
+    ) -> Union[AxisLimits, Dict[str, AxisLimits]]:
+        """
+        Get the current limits for an axis or all axes.
+
+        Args:
+            axis: Optional axis name ('X', 'Y', 'Z', 'A'). If None, returns all limits.
+
+        Returns:
+            If axis is specified: AxisLimits object with min and max values.
+            If axis is None: Dictionary of all axis limits.
+
+        Raises:
+            ValueError: If axis is unknown (only when axis is provided)
+        """
+        if axis is None:
+            return self._axis_limits.copy()
+        axis = self._validate_axis(axis)
+        return self._axis_limits[axis]
+
     def home(self, axis: Optional[str] = None) -> None:
         """
         Home one or all axes (G28 command).
@@ -163,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(
@@ -185,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).
 
@@ -195,24 +337,33 @@ class GCodeController(SerialController):
             z: Target Z position (optional)
             a: Target A position (optional)
             feed: Feed rate for this move (optional, uses current feed if not specified)
+
+        Raises:
+            ValueError: If any position is outside the axis limits
         """
+        # 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,
         )
 
-        # Ensure absolute mode is active
-        if not self._is_absolute_mode:
-            self._logger.debug("Switching to absolute positioning mode (G90).")
-            self._send_command(self._build_command("G90"))
-            self._is_absolute_mode = True
-
-        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,
@@ -221,9 +372,9 @@ 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 (G91 + G1 command).
+        Move relative to the current position (converted to absolute move internally).
 
         Args:
             x: Relative X movement (optional)
@@ -231,6 +382,9 @@ class GCodeController(SerialController):
             z: Relative Z movement (optional)
             a: Relative A movement (optional)
             feed: Feed rate for this move (optional, uses current feed if not specified)
+
+        Raises:
+            ValueError: If any resulting absolute position is outside the axis limits
         """
         feed_rate = feed if feed is not None else self._feed
         self._logger.info(
@@ -242,153 +396,111 @@ class GCodeController(SerialController):
             feed_rate,
         )
 
-        # Ensure relative mode is active
-        if self._is_absolute_mode:
-            self._logger.debug("Switching to relative positioning mode (G91).")
-            self._send_command(self._build_command("G91"))
-            self._is_absolute_mode = False
+        # 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"]
 
-        self._execute_move(x=x, y=y, z=z, a=a, feed=feed)
+        # Validate absolute positions before executing move
+        self._validate_move_positions(x=abs_x, y=abs_y, z=abs_z, a=abs_a)
+
+        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: 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()
-        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.")
 
-        # 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
-
-        feed_rate = feed if feed is not None else self._feed
-        if feed_rate > self.MAX_FEEDRATE:
-            feed_rate = self.MAX_FEEDRATE
-
-        # 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
+        # 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
             )
-            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 = 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:
-                # 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}"
+            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:
-                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
+            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]:
         """
@@ -401,8 +513,7 @@ class GCodeController(SerialController):
             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()
+        res: str = self.execute(self._build_command("M114"))
 
         # Extract position values using regex
         pattern = re.compile(r"([XYZA]):(-?\d+\.\d+)")
@@ -444,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"]
@@ -453,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
@@ -491,8 +597,6 @@ class GCodeController(SerialController):
                 self._logger.error("Synchronization move failed: %s", e)
                 adjustment_needed = False
 
-        final_position = self.current_position.copy()
-
         if adjustment_needed:
             self._logger.info(
                 "Position check complete. Internal position is synchronized with machine."
@@ -500,7 +604,7 @@ class GCodeController(SerialController):
         else:
             self._logger.info("No adjustment was made.")
 
-        return adjustment_needed, final_position
+        return adjustment_needed, self._current_position.copy()
 
     def get_info(self) -> str:
         """
@@ -510,9 +614,7 @@ class GCodeController(SerialController):
             Machine information string from the device
         """
         self._logger.info("Querying machine information (M115).")
-        self._send_command(self._build_command("M115"))
-        res: str = self._read_response()
-        return res
+        return self.execute(self._build_command("M115"))
 
     def get_internal_position(self) -> Dict[str, float]:
         """
@@ -521,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.3.dist-info → puda_drivers-0.0.5.dist-info}/METADATA

@@ -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.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=-wdQqq30yb6dSsNwA2FQec5HUh0U3j71OOMt6pbQIpc,7230
+puda_drivers/core/serialcontroller.py,sha256=I7TsLNl45HPrO29LkhMRIQQ8fWdjdJUvIwQQ5swbMHM,7660
 puda_drivers/move/__init__.py,sha256=i7G5VKD5FgnmC21TLxoASVtC88IrPUTLDJrTnp99u-0,35
-puda_drivers/move/gcode.py,sha256=1KkpgwXBiNrcV4Ilc-6n-ADQwOVwVgK_9x08LKhbE5g,18106
+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.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,,
+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,,