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

puda_drivers/core/serialcontroller.py

@@ -3,12 +3,11 @@ 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
 
 logger = logging.getLogger(__name__)
 
@@ -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.write(bytes(command, "utf-8"))
             self._serial.flush()
 
         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)
@@ -68,7 +94,14 @@ class GCodeController(SerialController):
             "A": 0.0,
         }
         self._feed: int = feed
-        self._is_absolute_mode: bool = True  # absolute mode by default
+
+        # 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:
@@ -143,6 +176,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).
@@ -195,7 +324,13 @@ 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)
+
         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",
@@ -206,12 +341,6 @@ class GCodeController(SerialController):
             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)
 
     def move_relative(
@@ -223,7 +352,7 @@ class GCodeController(SerialController):
         feed: Optional[int] = None,
     ) -> None:
         """
-        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 +360,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,13 +374,16 @@ 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
+        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
 
-        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)
+
+        self._execute_move(x=abs_x, y=abs_y, z=abs_z, a=abs_a, feed=feed)
 
     def _execute_move(
         self,
@@ -260,6 +395,7 @@ class GCodeController(SerialController):
     ) -> None:
         """
         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)
@@ -267,13 +403,13 @@ class GCodeController(SerialController):
         3. Finally move Z to target position (if specified)
 
         Args:
-            x: X axis value (optional)
-            y: Y axis value (optional)
-            z: Z axis value (optional)
-            a: A axis value (optional)
+            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
+        # Calculate target positions (all absolute)
         target_pos = self.current_position.copy()
         has_x = x is not None
         has_y = y is not None
@@ -286,30 +422,23 @@ class GCodeController(SerialController):
             )
             return
 
-        # 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
+        # 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"]
@@ -317,15 +446,12 @@ class GCodeController(SerialController):
 
         # 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)
             self._logger.info(
                 "Safe move: Raising Z to safe height (0) before XY movement"
             )
-            if self._is_absolute_mode:
-                move_cmd = "G1 Z0"
-            else:
-                # In relative mode, move by negative current_z to reach 0
-                move_cmd = f"G1 Z{-current_z}"
-            move_cmd += f" F{feed_rate}"
+            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)")
@@ -334,21 +460,11 @@ class GCodeController(SerialController):
         if needs_xy_move or has_a:
             move_cmd = "G1"
             if has_x:
-                # Use target position in absolute mode, relative value in relative mode
-                if self._is_absolute_mode:
-                    move_cmd += f" X{target_pos['X']}"
-                else:
-                    move_cmd += f" X{x}"
+                move_cmd += f" X{target_pos['X']}"
             if has_y:
-                if self._is_absolute_mode:
-                    move_cmd += f" Y{target_pos['Y']}"
-                else:
-                    move_cmd += f" Y{y}"
+                move_cmd += f" Y{target_pos['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" A{target_pos['A']}"
             move_cmd += f" F{feed_rate}"
 
             self._logger.info("Executing XY move command: %s", move_cmd)
@@ -366,11 +482,7 @@ class GCodeController(SerialController):
         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}"
+                move_cmd = f"G1 Z{target_z} F{feed_rate}"
                 
                 if needs_xy_move:
                     self._logger.info(
@@ -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+)")
@@ -491,8 +602,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 +609,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 +619,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]:
         """

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: puda-drivers
-Version: 0.0.3
+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.3.dist-info → puda_drivers-0.0.4.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=c-_kMLKxz9hLhpG-54wENkLeN0bNzY1rP9zML1RV9uc,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=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
@@ -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.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,,