puda-drivers 0.0.6__py3-none-any.whl → 0.0.8__py3-none-any.whl

puda_drivers/core/__init__.py

@@ -1,4 +1,5 @@
 from .serialcontroller import SerialController, list_serial_ports
 from .logging import setup_logging
+from .position import Position
 
-__all__ = ["SerialController", "list_serial_ports", "setup_logging"]
+__all__ = ["SerialController", "list_serial_ports", "setup_logging", "Position"]

puda_drivers/core/position.py

@@ -0,0 +1,378 @@
+"""
+Position class for handling multi-axis positions.
+
+Supports flexible axis definitions with default x, y, z, a axes.
+Provides JSON conversion, arithmetic operations, and dictionary/tuple compatibility.
+"""
+
+import json
+import copy
+from typing import Dict, Optional, Tuple, Union, Any
+
+
+class Position:
+    """
+    Represents a position in multi-axis space.
+    
+    Default axes are x, y, z, a, but can support any number of axes.
+    Supports addition, subtraction, JSON conversion, and dictionary/tuple access.
+    """
+    
+    def __init__(
+        self,
+        x: Optional[float] = None,
+        y: Optional[float] = None,
+        z: Optional[float] = None,
+        a: Optional[float] = None,
+        **kwargs: float
+    ):
+        """
+        Initialize a Position with axis values.
+        
+        Args:
+            x: X axis value (optional)
+            y: Y axis value (optional)
+            z: Z axis value (optional)
+            a: A axis value (optional)
+            **kwargs: Additional axis values (e.g., b=10.0, c=20.0)
+        
+        Examples:
+            >>> pos = Position(x=10, y=20, z=30, a=0)
+            >>> pos = Position(x=10, y=20, b=5.0, c=10.0)
+        """
+        self._axes: Dict[str, float] = {}
+        
+        # Set default axes if provided
+        if x is not None:
+            self._axes["x"] = float(x)
+        if y is not None:
+            self._axes["y"] = float(y)
+        if z is not None:
+            self._axes["z"] = float(z)
+        if a is not None:
+            self._axes["a"] = float(a)
+        
+        # Set additional axes
+        for axis_name, value in kwargs.items():
+            self._axes[axis_name.lower()] = float(value)
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, float], case_sensitive: bool = False) -> "Position":
+        """
+        Create a Position from a dictionary.
+        
+        Args:
+            data: Dictionary with axis names as keys and values as floats
+            case_sensitive: If False, converts keys to lowercase. Defaults to False.
+        
+        Returns:
+            Position instance
+        
+        Examples:
+            >>> pos = Position.from_dict({"X": 10, "Y": 20, "Z": 30})
+            >>> pos = Position.from_dict({"x": 10, "y": 20, "z": 30})
+        """
+        if case_sensitive:
+            return cls(**{k: v for k, v in data.items()})
+        else:
+            return cls(**{k.lower(): v for k, v in data.items()})
+    
+    @classmethod
+    def from_json(cls, json_str: str) -> "Position":
+        """
+        Create a Position from a JSON string.
+        
+        Args:
+            json_str: JSON string containing axis values
+        
+        Returns:
+            Position instance
+        
+        Examples:
+            >>> pos = Position.from_json('{"x": 10, "y": 20, "z": 30}')
+        """
+        data = json.loads(json_str)
+        return cls.from_dict(data)
+    
+    @classmethod
+    def from_tuple(cls, values: Tuple[float, ...], axes: Optional[Tuple[str, ...]] = None) -> "Position":
+        """
+        Create a Position from a tuple of values.
+        
+        Args:
+            values: Tuple of float values
+            axes: Optional tuple of axis names. Defaults to ("x", "y", "z", "a")
+        
+        Returns:
+            Position instance
+        
+        Examples:
+            >>> pos = Position.from_tuple((10, 20, 30))
+            >>> pos = Position.from_tuple((10, 20, 30, 0), ("x", "y", "z", "a"))
+        """
+        if axes is None:
+            default_axes = ("x", "y", "z", "a")
+            axes = default_axes[:len(values)]
+        
+        if len(values) != len(axes):
+            raise ValueError(f"Number of values ({len(values)}) must match number of axes ({len(axes)})")
+        
+        return cls(**{axis: val for axis, val in zip(axes, values)})
+    
+    def to_dict(self, uppercase: bool = False) -> Dict[str, float]:
+        """
+        Convert Position to a dictionary.
+        
+        Args:
+            uppercase: If True, returns uppercase keys (X, Y, Z, A). Defaults to False.
+        
+        Returns:
+            Dictionary with axis names as keys
+        
+        Examples:
+            >>> pos = Position(x=10, y=20)
+            >>> pos.to_dict()  # {"x": 10, "y": 20}
+            >>> pos.to_dict(uppercase=True)  # {"X": 10, "Y": 20}
+        """
+        if uppercase:
+            return {k.upper(): v for k, v in self._axes.items()}
+        return self._axes.copy()
+    
+    def to_json(self) -> str:
+        """
+        Convert Position to a JSON string.
+        
+        Returns:
+            JSON string representation
+        """
+        return json.dumps(self.to_dict())
+    
+    def to_tuple(self, axes: Optional[Tuple[str, ...]] = None) -> Tuple[float, ...]:
+        """
+        Convert Position to a tuple of values.
+        
+        Args:
+            axes: Optional tuple of axis names to include. Defaults to all axes in order.
+        
+        Returns:
+            Tuple of float values
+        
+        Examples:
+            >>> pos = Position(x=10, y=20, z=30)
+            >>> pos.to_tuple()  # (10.0, 20.0, 30.0)
+            >>> pos.to_tuple(("x", "y"))  # (10.0, 20.0)
+        """
+        if axes is None:
+            axes = tuple(self._axes.keys())
+        
+        return tuple(self._axes.get(axis, 0.0) for axis in axes)
+    
+    def __getitem__(self, axis: str) -> float:
+        """Get axis value by name (case-insensitive)."""
+        axis_lower = axis.lower()
+        return self._axes.get(axis_lower, 0.0)
+    
+    def __setitem__(self, axis: str, value: float) -> None:
+        """Set axis value by name (case-insensitive)."""
+        self._axes[axis.lower()] = float(value)
+    
+    def __getattr__(self, name: str) -> float:
+        """Get axis value as attribute (e.g., pos.x, pos.y)."""
+        if name.startswith("_"):
+            raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+        return self._axes.get(name.lower(), 0.0)
+    
+    def __setattr__(self, name: str, value: Any) -> None:
+        """Set axis value as attribute (e.g., pos.x = 10)."""
+        if name.startswith("_") or name in dir(self):
+            super().__setattr__(name, value)
+        else:
+            if "_axes" in self.__dict__:
+                self._axes[name.lower()] = float(value)
+            else:
+                super().__setattr__(name, value)
+    
+    def __add__(self, other: Union["Position", Dict[str, float], float]) -> "Position":
+        """
+        Add two positions or add a scalar to all axes.
+        
+        Args:
+            other: Position, dict, or float to add
+        
+        Returns:
+            New Position instance
+        
+        Examples:
+            >>> pos1 = Position(x=10, y=20)
+            >>> pos2 = Position(x=5, y=10)
+            >>> pos3 = pos1 + pos2  # Position(x=15, y=30)
+            >>> pos4 = pos1 + 5  # Position(x=15, y=25)
+        """
+        if isinstance(other, Position):
+            result = Position()
+            all_axes = set(self._axes.keys()) | set(other._axes.keys())
+            for axis in all_axes:
+                result._axes[axis] = self[axis] + other[axis]
+            return result
+        elif isinstance(other, dict):
+            other_pos = Position.from_dict(other)
+            return self + other_pos
+        elif isinstance(other, (int, float)):
+            result = Position()
+            for axis, value in self._axes.items():
+                result._axes[axis] = value + other
+            return result
+        else:
+            return NotImplemented
+    
+    def __radd__(self, other: Union[Dict[str, float], float]) -> "Position":
+        """Right-side addition."""
+        return self + other
+    
+    def __sub__(self, other: Union["Position", Dict[str, float], float]) -> "Position":
+        """
+        Subtract two positions or subtract a scalar from all axes.
+        
+        Args:
+            other: Position, dict, or float to subtract
+        
+        Returns:
+            New Position instance
+        
+        Examples:
+            >>> pos1 = Position(x=10, y=20)
+            >>> pos2 = Position(x=5, y=10)
+            >>> pos3 = pos1 - pos2  # Position(x=5, y=10)
+            >>> pos4 = pos1 - 5  # Position(x=5, y=15)
+        """
+        if isinstance(other, Position):
+            result = Position()
+            all_axes = set(self._axes.keys()) | set(other._axes.keys())
+            for axis in all_axes:
+                result._axes[axis] = self[axis] - other[axis]
+            return result
+        elif isinstance(other, dict):
+            other_pos = Position.from_dict(other)
+            return self - other_pos
+        elif isinstance(other, (int, float)):
+            result = Position()
+            for axis, value in self._axes.items():
+                result._axes[axis] = value - other
+            return result
+        else:
+            return NotImplemented
+    
+    def __rsub__(self, other: Union[Dict[str, float], float]) -> "Position":
+        """Right-side subtraction."""
+        if isinstance(other, dict):
+            other_pos = Position.from_dict(other)
+            return other_pos - self
+        elif isinstance(other, (int, float)):
+            result = Position()
+            for axis, value in self._axes.items():
+                result._axes[axis] = other - value
+            return result
+        else:
+            return NotImplemented
+    
+    def __mul__(self, scalar: float) -> "Position":
+        """
+        Multiply all axes by a scalar.
+        
+        Args:
+            scalar: Scalar value to multiply
+        
+        Returns:
+            New Position instance
+        
+        Examples:
+            >>> pos = Position(x=10, y=20)
+            >>> pos2 = pos * 2  # Position(x=20, y=40)
+        """
+        if isinstance(scalar, (int, float)):
+            result = Position()
+            for axis, value in self._axes.items():
+                result._axes[axis] = value * scalar
+            return result
+        return NotImplemented
+    
+    def __rmul__(self, scalar: float) -> "Position":
+        """Right-side multiplication."""
+        return self * scalar
+    
+    def __truediv__(self, scalar: float) -> "Position":
+        """
+        Divide all axes by a scalar.
+        
+        Args:
+            scalar: Scalar value to divide by
+        
+        Returns:
+            New Position instance
+        
+        Examples:
+            >>> pos = Position(x=10, y=20)
+            >>> pos2 = pos / 2  # Position(x=5, y=10)
+        """
+        if isinstance(scalar, (int, float)):
+            if scalar == 0:
+                raise ZeroDivisionError("Cannot divide Position by zero")
+            result = Position()
+            for axis, value in self._axes.items():
+                result._axes[axis] = value / scalar
+            return result
+        return NotImplemented
+    
+    def __neg__(self) -> "Position":
+        """Negate all axes."""
+        result = Position()
+        for axis, value in self._axes.items():
+            result._axes[axis] = -value
+        return result
+    
+    def __abs__(self) -> "Position":
+        """Absolute value of all axes."""
+        result = Position()
+        for axis, value in self._axes.items():
+            result._axes[axis] = abs(value)
+        return result
+    
+    def __eq__(self, other: object) -> bool:
+        """Check equality with another Position."""
+        if not isinstance(other, Position):
+            return False
+        return self._axes == other._axes
+    
+    def __repr__(self) -> str:
+        """String representation of Position."""
+        if not self._axes:
+            return "Position()"
+        axis_strs = [f"{k}={v}" for k, v in sorted(self._axes.items())]
+        return f"Position({', '.join(axis_strs)})"
+    
+    def __str__(self) -> str:
+        """Human-readable string representation."""
+        return self.__repr__()
+    
+    def get_axes(self) -> Tuple[str, ...]:
+        """Get tuple of all axis names."""
+        return tuple(sorted(self._axes.keys()))
+    
+    def has_axis(self, axis: str) -> bool:
+        """Check if position has a specific axis."""
+        return axis.lower() in self._axes
+    
+    def copy(self) -> "Position":
+        """Create a copy of this Position."""
+        return copy.copy(self)
+
+    # swap x and y axes
+    def swap_xy(self) -> "Position":
+        """Swap x and y axes."""
+        self._axes["x"], self._axes["y"] = self._axes["y"], self._axes["x"]
+        return self
+    
+    # get x and y coordinates only
+    def get_xy(self) -> "Position":
+        """Get x and y coordinates only."""
+        return Position(x=self._axes["x"], y=self._axes["y"])

puda_drivers/core/serialcontroller.py

@@ -5,7 +5,7 @@ Generic Serial Controller for communicating with devices over serial ports.
 import time
 import logging
 from typing import Optional, List, Tuple
-from abc import ABC
+from abc import ABC, abstractmethod
 import serial
 import serial.tools.list_ports
 
@@ -25,14 +25,6 @@ def list_serial_ports(filter_desc: Optional[str] = None) -> List[Tuple[str, str,
 
     Returns:
         List of tuples, where each tuple contains (port_name, description, hwid).
-
-    Example:
-        >>> from puda_drivers.core import list_serial_ports
-        >>> ports = list_serial_ports()
-        >>> for port, desc, hwid in ports:
-        ...     print(f"{port}: {desc}")
-        >>> # Filter for specific devices
-        >>> sartorius_ports = list_serial_ports(filter_desc="Sartorius")
     """
     all_ports = serial.tools.list_ports.comports()
     filtered_ports = []
@@ -44,6 +36,9 @@ def list_serial_ports(filter_desc: Optional[str] = None) -> List[Tuple[str, str,
 
 
 class SerialController(ABC):
+    """
+    Abstract base class for serial controllers.
+    """
     DEFAULT_BAUDRATE = 9600
     DEFAULT_TIMEOUT = 30  # seconds
     POLL_INTERVAL = 0.1  # seconds
@@ -55,8 +50,6 @@ class SerialController(ABC):
         self.timeout = timeout
         self._logger = logger
 
-        self.connect()
-
     def connect(self) -> None:
         """
         Establishes the serial connection to the port.
@@ -163,7 +156,7 @@ class SerialController(ABC):
                 if b"ok" in response or b"err" in response:
                     break
                 
-                # Check for expected response markers for early return for sartorius
+                # for sartorius since res not returning ok or err
                 if b"\xba\r" in response:
                     break
             else:
@@ -179,11 +172,11 @@ class SerialController(ABC):
         # Decode once and check the decoded string
         decoded_response = response.decode("utf-8", errors="ignore").strip()
         
-        if "ok" in decoded_response.lower(): # for qubot
+        if "ok" in decoded_response.lower():
             self._logger.debug("<- Received response: %r", decoded_response)
-        elif "err" in decoded_response.lower(): # for qubot
+        elif "err" in decoded_response.lower():
             self._logger.error("<- Received error: %r", decoded_response)
-        elif "º" in decoded_response: # for sartorius
+        elif "º" in decoded_response: # for sartorius (since res not returning ok or err)
             self._logger.debug("<- Received response: %r", decoded_response)
         else:
             self._logger.warning(
@@ -191,8 +184,15 @@ class SerialController(ABC):
             )
         
         return decoded_response
+    
+    @abstractmethod
+    def _build_command(self, command: str, value: Optional[str] = None) -> str:
+        """
+        Build a command string according to the device protocol.
+        """
+        pass
 
-    def execute(self, command: str) -> str:
+    def execute(self, command: str, value: Optional[str] = None) -> str:
         """
         Send a command and read the response atomically.
         
@@ -211,5 +211,20 @@ class SerialController(ABC):
             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()
+        self._send_command(self._build_command(command, value))
+        
+        # Increase timeout by 60 seconds for G28 (homing) command
+        original_timeout = self.timeout
+        if "G28" in command.upper():
+            self.timeout = original_timeout + 60
+            # Also update the serial connection's timeout if connected
+            if self.is_connected and self._serial:
+                self._serial.timeout = self.timeout
+        
+        try:
+            return self._read_response()
+        finally:
+            # Restore original timeout
+            self.timeout = original_timeout
+            if self.is_connected and self._serial:
+                self._serial.timeout = original_timeout

puda_drivers/labware/__init__.py

@@ -0,0 +1,9 @@
+# puda_drivers/labware/__init__.py
+
+# Import from the sub-packages (folders)
+from .labware import StandardLabware
+
+# Export get_available_labware as a standalone function
+get_available_labware = StandardLabware.get_available_labware
+
+__all__ = ["StandardLabware", "get_available_labware"]

puda_drivers/labware/labware.py

@@ -0,0 +1,157 @@
+# src/puda_drivers/labware/labware.py
+
+import json
+import inspect
+from pathlib import Path
+from typing import Dict, Any
+from abc import ABC
+from typing import List
+from puda_drivers.core import Position
+
+
+class StandardLabware(ABC):
+    """
+    Generic Parent Class for all Labware on a microplate 
+    """
+    def __init__(self, labware_name: str):
+        """
+        Initialize the labware.
+        Args:
+            name: The name of the labware.
+            rows: The number of rows in the labware.
+            cols: The number of columns in the labware.
+        """
+        self._definition = self.load_definition(file_name=labware_name + ".json")
+        self.name = self._definition.get("metadata", {}).get("displayName", "displayName not found")
+        self._wells = self._definition.get("wells", {})
+
+    @staticmethod
+    def get_available_labware() -> List[str]:
+        """
+        Get all available labware names from JSON definition files.
+        
+        Returns:
+            Sorted list of labware names (without .json extension) found in the labware directory.
+        """
+        labware_dir = Path(__file__).parent
+        json_files = sorted(labware_dir.glob("*.json"))
+        return [f.stem for f in json_files]
+
+    def load_definition(self, file_name: str = "definition.json") -> Dict[str, Any]:
+        """
+        Load a definition.json file from the class's module directory.
+        
+        This method automatically finds the definition.json file in the
+        same directory as the class that defines it.
+        
+        Args:
+            file_name: Name of the definition file (default: "definition.json")
+            
+        Returns:
+            Dictionary containing the labware definition
+            
+        Raises:
+            FileNotFoundError: If the definition file doesn't exist
+        """
+        # Get the file path of the class that defines this method
+        class_file = Path(inspect.getfile(self.__class__))
+        definition_path = class_file.parent / file_name
+        
+        if not definition_path.exists():
+            raise FileNotFoundError(
+                f"Definition file '{file_name}' not found in {class_file.parent}"
+            )
+        
+        with open(definition_path, "r", encoding="utf-8") as f:
+            return json.load(f)
+        
+    def __str__(self):
+        """
+        Return a string representation of the labware.
+        """
+        lines = [
+            f"Labware name: {self.name}",
+            f"Height in mm: {self.get_height()}",
+            "Distances away from origin (0,0) for each well in mm"
+        ]
+        
+        for well_id, well_data in self._wells.items():
+            x, y, z = well_data.get("x"), well_data.get("y"), well_data.get("z")
+
+            if x is None or y is None or z is None:
+                raise KeyError(f"Well '{well_id}' has missing coordinates in labware definition")
+
+            lines.append(f"Well {well_id}: x:{x}, y:{y}, z:{z}")
+        return "\n".join(lines)
+
+    @property
+    def wells(self) -> List[str]:
+        """
+        Get a list of all well IDs in the labware.
+        
+        Returns:
+            List of well identifiers (e.g., ["A1", "A2", "B1", ...])
+        """
+        return list(self._wells.keys())
+    
+    def get_well_position(self, well_id: str) -> Position:
+        """
+        Get the position of a well from definition.json.
+        
+        Args:
+            well_id: Well identifier (e.g., "A1", "H12")
+            
+        Returns:
+            Position with x, y, z coordinates
+            
+        Raises:
+            KeyError: If well_id doesn't exist in the tip rack
+        """
+        # Validate location exists in JSON definition
+        well_id_upper = well_id.upper()
+        if well_id_upper not in self._wells:
+            raise KeyError(f"Well '{well_id}' not found in tip rack definition")
+        
+        # Get the well data from the definition
+        well_data = self._wells.get(well_id_upper, {})
+        
+        # Return position of the well (x, y are already center coordinates)
+        return Position(
+            x=well_data.get("x", 0.0),
+            y=well_data.get("y", 0.0),
+            z=well_data.get("z", 0.0), 
+        )
+        
+    def get_height(self) -> float:
+        """
+        Get the height of the labware.
+        
+        Returns:
+            Height of the labware (zDimension)
+            
+        Raises:
+            KeyError: If dimensions or zDimension is not found in the definition
+        """
+        dimensions = self._definition.get("dimensions")
+        if dimensions is None:
+            raise KeyError("'dimensions' not found in labware definition")
+        
+        if "zDimension" not in dimensions:
+            raise KeyError("'zDimension' not found in labware dimensions")
+        
+        return dimensions["zDimension"]
+        
+    def get_insert_depth(self) -> float:
+        """
+        Get the insert depth of the labware.
+        
+        Returns:
+            Insert depth of the labware
+            
+        Raises:
+            KeyError: If insert_depth is not found in the definition
+        """
+        if "insert_depth" not in self._definition:
+            raise KeyError("'insert_depth' not found in labware definition")
+        
+        return self._definition["insert_depth"]