puda-drivers 0.0.15__tar.gz → 0.0.17__tar.gz

{puda_drivers-0.0.15 → puda_drivers-0.0.17}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: puda-drivers
-Version: 0.0.15
+Version: 0.0.17
 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
+Project-URL: Homepage, https://github.com/PUDAP/puda-drivers
+Project-URL: Issues, https://github.com/PUDAP/puda-drivers/issues
 Author-email: zhao <20024592+agentzhao@users.noreply.github.com>
 License-Expression: MIT
 License-File: LICENSE
@@ -18,6 +18,7 @@ Requires-Python: >=3.10
 Requires-Dist: nats-py>=2.12.0
 Requires-Dist: opencv-python>=4.12.0.88
 Requires-Dist: pyserial~=3.5
+Requires-Dist: pytest>=9.0.2
 Description-Content-Type: text/markdown
 
 # puda-drivers
@@ -40,14 +41,6 @@ Hardware drivers for the PUDA (Physical Unified Device Architecture) platform. T
 pip install puda-drivers
 ```
 
-### From Source
-
-```bash
-git clone https://github.com/zhao-bears/puda-drivers.git
-cd puda-drivers
-pip install -e .
-```
-
 ## Quick Start
 
 ### Logging Configuration
@@ -197,22 +190,70 @@ sartorius_ports = list_serial_ports(filter_desc="Sartorius")
 
 ### Setup Development Environment
 
-First, install `uv` if you haven't already. See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for platform-specific instructions.
+This package is part of a UV workspace monorepo. First, install `uv` if you haven't already. See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for platform-specific instructions.
+
+**From the repository root:**
 
 ```bash
-# Create virtual environment
-uv venv
+# Or install dependencies for all workspace packages
+uv sync --all-packages
+```
+
+This will:
+- Create a virtual environment at the repository root (`.venv/`)
+- Install all dependencies for all workspace packages
+- Install `puda-drivers` and other workspace packages in editable mode automatically
 
-# Activate virtual environment
+**Using the package:**
+
+```bash
+# Run Python scripts with workspace context (recommended, works from anywhere in the workspace)
+uv run python your_script.py
+
+# Or activate the virtual environment (from repository root where .venv is located)
 source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+python your_script.py
+```
+
+**Adding dependencies:**
 
-# Install dependencies
-uv sync
+```bash
+# From the package directory
+cd libs/drivers
+uv add some-package
 
-# Install package in editable mode
-pip install -e .
+# Or from repository root
+uv add --package puda-drivers some-package
 ```
 
+**Note:** Workspace packages are automatically installed in editable mode, so code changes are immediately available without reinstalling.
+
+### Testing
+
+Run tests using pytest with `uv run`:
+
+```bash
+# Run all tests
+uv run pytest tests/
+
+# Run a specific test file
+uv run pytest tests/test_deck.py
+
+# Run a specific test class
+uv run pytest tests/test_deck.py::TestDeckToDict
+
+# Run a specific test function
+uv run pytest tests/test_deck.py::TestDeckToDict::test_to_dict_empty_deck
+
+# Run with verbose output
+uv run pytest tests/ -v
+
+# Run with coverage report
+uv run pytest tests/ --cov=puda_drivers --cov-report=html
+```
+
+**Note:** Make sure you're in the `libs/drivers` directory or use the full path to the tests directory when running pytest commands.
+
 ### Building and Publishing
 
 ```bash

{puda_drivers-0.0.15 → puda_drivers-0.0.17}/README.md

@@ -18,14 +18,6 @@ Hardware drivers for the PUDA (Physical Unified Device Architecture) platform. T
 pip install puda-drivers
 ```
 
-### From Source
-
-```bash
-git clone https://github.com/zhao-bears/puda-drivers.git
-cd puda-drivers
-pip install -e .
-```
-
 ## Quick Start
 
 ### Logging Configuration
@@ -175,22 +167,70 @@ sartorius_ports = list_serial_ports(filter_desc="Sartorius")
 
 ### Setup Development Environment
 
-First, install `uv` if you haven't already. See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for platform-specific instructions.
+This package is part of a UV workspace monorepo. First, install `uv` if you haven't already. See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for platform-specific instructions.
+
+**From the repository root:**
 
 ```bash
-# Create virtual environment
-uv venv
+# Or install dependencies for all workspace packages
+uv sync --all-packages
+```
+
+This will:
+- Create a virtual environment at the repository root (`.venv/`)
+- Install all dependencies for all workspace packages
+- Install `puda-drivers` and other workspace packages in editable mode automatically
 
-# Activate virtual environment
+**Using the package:**
+
+```bash
+# Run Python scripts with workspace context (recommended, works from anywhere in the workspace)
+uv run python your_script.py
+
+# Or activate the virtual environment (from repository root where .venv is located)
 source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+python your_script.py
+```
+
+**Adding dependencies:**
 
-# Install dependencies
-uv sync
+```bash
+# From the package directory
+cd libs/drivers
+uv add some-package
 
-# Install package in editable mode
-pip install -e .
+# Or from repository root
+uv add --package puda-drivers some-package
 ```
 
+**Note:** Workspace packages are automatically installed in editable mode, so code changes are immediately available without reinstalling.
+
+### Testing
+
+Run tests using pytest with `uv run`:
+
+```bash
+# Run all tests
+uv run pytest tests/
+
+# Run a specific test file
+uv run pytest tests/test_deck.py
+
+# Run a specific test class
+uv run pytest tests/test_deck.py::TestDeckToDict
+
+# Run a specific test function
+uv run pytest tests/test_deck.py::TestDeckToDict::test_to_dict_empty_deck
+
+# Run with verbose output
+uv run pytest tests/ -v
+
+# Run with coverage report
+uv run pytest tests/ --cov=puda_drivers --cov-report=html
+```
+
+**Note:** Make sure you're in the `libs/drivers` directory or use the full path to the tests directory when running pytest commands.
+
 ### Building and Publishing
 
 ```bash

{puda_drivers-0.0.15 → puda_drivers-0.0.17}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "puda-drivers"
-version = "0.0.15"
+version = "0.0.17"
 description = "Hardware drivers for the PUDA platform."
 readme = "README.md"
 authors = [
@@ -22,6 +22,7 @@ dependencies = [
     "nats-py>=2.12.0",
     "opencv-python>=4.12.0.88",
     "pyserial~=3.5",
+    "pytest>=9.0.2",
 ]
 
 [build-system]
@@ -29,5 +30,5 @@ requires = ["hatchling >= 1.26"]
 build-backend = "hatchling.build"
 
 [project.urls]
-Homepage = "https://github.com/zhao-bears/puda-drivers"
-Issues = "https://github.com/zhao-bears/puda-drivers/issues"
+Homepage = "https://github.com/PUDAP/puda-drivers"
+Issues = "https://github.com/PUDAP/puda-drivers/issues"

{puda_drivers-0.0.15 → puda_drivers-0.0.17}/src/puda_drivers/core/serialcontroller.py

@@ -4,6 +4,7 @@ Generic Serial Controller for communicating with devices over serial ports.
 
 import time
 import logging
+import threading
 from typing import Optional, List, Tuple
 from abc import ABC, abstractmethod
 import serial
@@ -47,8 +48,11 @@ class SerialController(ABC):
         self._serial = None
         self.port_name = port_name
         self.baudrate = baudrate
-        self.timeout = timeout
+        self._timeout = timeout
         self._logger = logger
+        
+        # lock to prevent concurrent access to the serial port
+        self._lock = threading.Lock()
 
     def connect(self) -> None:
         """
@@ -71,7 +75,7 @@ class SerialController(ABC):
             self._serial = serial.Serial(
                 port=self.port_name,
                 baudrate=self.baudrate,
-                timeout=self.timeout,
+                timeout=self._timeout,
             )
             self._serial.flush()
             self._logger.info("Successfully connected to %s.", self.port_name)
@@ -103,20 +107,20 @@ class SerialController(ABC):
 
     def _send_command(self, command: str) -> None:
         """
-        Sends a custom protocol command, reads, and returns the response.
-        If a timeout occurs, it logs the error and returns None instead of raising an exception.
+        Sends a command to the device.
+        Note: This method should be called while holding self._lock to ensure
+        atomic command/response pairing.
         """
+        self._logger.info("-> Sending: %r", command)
+
         if not self.is_connected or not self._serial:
             self._logger.error(
                 "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.")
+            raise serial.SerialException("Device disconnected. Call connect() first.")
 
-        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
@@ -130,13 +134,13 @@ class SerialController(ABC):
 
         except serial.SerialException as e:
             self._logger.error(
-                "Serial error writing or reading command '%s'. Error: %s",
+                "Serial error writing command '%s'. Error: %s",
                 command,
                 e,
             )
             return None
 
-    def _read_response(self) -> str:
+    def _read_response(self, timeout: int = None) -> str:
         """
         Generic, blocking read that respects timeout and returns
         all data that arrived within the timeout period.
@@ -144,10 +148,13 @@ class SerialController(ABC):
         if not self.is_connected or not self._serial:
             raise serial.SerialException("Device not connected.")
 
+        if timeout is None:
+            timeout = self._timeout
+
         start_time = time.time()
         response = b""
 
-        while time.time() - start_time < self.timeout:
+        while time.time() - start_time < timeout:
             if self._serial.in_waiting > 0:
                 # Read all available bytes
                 response += self._serial.read(self._serial.in_waiting)
@@ -164,14 +171,12 @@ class SerialController(ABC):
 
         # Timeout reached - check what we got
         if not response:
-            self._logger.error("No response within %s seconds.", self.timeout)
+            self._logger.error("No response within %s seconds.", timeout)
             raise serial.SerialTimeoutException(
-                f"No response received within {self.timeout} seconds."
+                f"No response received within {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():
@@ -189,20 +194,25 @@ class SerialController(ABC):
     def _build_command(self, command: str, value: Optional[str] = None) -> str:
         """
         Build a command string according to the device protocol.
+        
+        There might be special starting and ending characters for devices
         """
-        pass
+        raise NotImplementedError
 
-    def execute(self, command: str, value: Optional[str] = None) -> str:
+    def execute(self, command: str, value: Optional[str] = None, timeout: int = None) -> 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.
+        that was just sent. The entire operation is protected by a lock to prevent
+        concurrent commands from interfering with each other.
+        
+        This is the preferred method for commands that require a response.
         
         Args:
             command: Command string to send (should include protocol terminator if needed)
+            value: Optional value parameter for the command
             
         Returns:
             Response string from the device
@@ -211,20 +221,10 @@ 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(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
+        if timeout is None:
+            timeout = self._timeout
+        # Hold the lock for the entire send+read operation to ensure atomicity
+        # This prevents concurrent commands from mixing up responses
+        with self._lock:
+            self._send_command(self._build_command(command, value))
+            return self._read_response(timeout=timeout)

{puda_drivers-0.0.15 → puda_drivers-0.0.17}/src/puda_drivers/labware/trash_bin.json

@@ -20,7 +20,8 @@
       "width": 10.0,
       "height": 10.0,
       "x": 60.0,
-      "y": 42.0
+      "y": 42.0,
+      "z": 0.0
     }
   },
   "groups": [

{puda_drivers-0.0.15 → puda_drivers-0.0.17}/src/puda_drivers/machines/first.py

@@ -159,7 +159,7 @@ class First:
         self.camera.disconnect()
         self._logger.info("Machine shutdown complete")
         
-    async def get_position(self) -> Dict[str, float]:
+    async def get_position(self) -> Dict[str, Union[Dict[str, float], int]]:
         """
         Get the current position of the machine. Both QuBot and Sartorius are queried.
         
@@ -176,6 +176,8 @@ class First:
             "pipette": sartorius_position,
         }
         
+    ### Labware management ###
+        
     def load_labware(self, slot: str, labware_name: str):
         """
         Load a labware object into a slot.
@@ -190,7 +192,33 @@ class First:
         self._logger.info("Loading labware '%s' into slot '%s'", labware_name, slot)
         self.deck.load_labware(slot=slot, labware_name=labware_name)
         self._logger.debug("Labware '%s' loaded into slot '%s'", labware_name, slot)
+
+    def remove_labware(self, slot: str):
+        """
+        Remove labware from a slot.
+        
+        Args:
+            slot: Slot name (e.g., 'A1', 'B2')
+        
+        Raises:
+            KeyError: If slot is not found in deck
+        """
+        self.deck.empty_slot(slot=slot)
+        self._logger.debug("Slot '%s' emptied", slot)
     
+    def get_deck(self):
+        """
+        Get the current deck layout.
+        
+        Returns:
+            Dictionary mapping slot names (e.g., "A1") to labware classes.
+        
+        Raises:
+            None
+        """
+        return self.deck.to_dict()
+
+        
     def load_deck(self, deck_layout: Dict[str, Type[StandardLabware]]):
         """
         Load multiple labware into the deck at once.
@@ -211,6 +239,8 @@ class First:
             self.load_labware(slot=slot, labware_name=labware_name)
         self._logger.info("Deck layout loaded successfully")
         
+    ### Liquid handling ###
+        
     def attach_tip(self, slot: str, well: Optional[str] = None):
         """
         Attach a tip from a slot.
@@ -234,7 +264,11 @@ class First:
         self.qubot.move_absolute(position=pos)
         
         # attach tip (move slowly down)
-        insert_depth = self.deck[slot].get_insert_depth()
+        labware = self.deck[slot]
+        if labware is None:
+            self._logger.error("Cannot attach tip: no labware loaded in slot '%s'", slot)
+            raise ValueError(f"No labware loaded in slot '{slot}'. Load labware before attaching tips.")
+        insert_depth = labware.get_insert_depth()
         self._logger.debug("Moving down by %s mm to insert tip", insert_depth)
         self.qubot.move_relative(
             position=Position(z=-insert_depth),
@@ -378,17 +412,24 @@ class First:
             
         Returns:
             Position with absolute coordinates
+            
+        Raises:
+            ValueError: If well is specified but no labware is loaded in the slot
         """
         # Get slot origin
         pos = self.get_slot_origin(slot)
 
         # relative well position from slot origin
         if well:
-            well_pos = self.deck[slot].get_well_position(well).get_xy()
+            labware = self.deck[slot]
+            if labware is None:
+                self._logger.error("Cannot get well position: no labware loaded in slot '%s'", slot)
+                raise ValueError(f"No labware loaded in slot '{slot}'. Load labware before accessing wells.")
+            well_pos = labware.get_well_position(well).get_xy()
             # the deck is rotated 90 degrees clockwise for this machine
             pos += well_pos.swap_xy()
             # get z
-            pos += Position(z=self.deck[slot].get_height() - self.CEILING_HEIGHT)
+            pos += Position(z=labware.get_height() - self.CEILING_HEIGHT)
             self._logger.debug("Absolute Z position for slot '%s', well '%s': %s", slot, well, pos)
         else:
             self._logger.debug("Absolute Z position for slot '%s': %s", slot, pos)
@@ -404,15 +445,22 @@ class First:
             
         Returns:
             Position with absolute coordinates
+            
+        Raises:
+            ValueError: If well is specified but no labware is loaded in the slot
         """
         pos = self.get_slot_origin(slot)
         
         if well:
-            well_pos = self.deck[slot].get_well_position(well).get_xy()
+            labware = self.deck[slot]
+            if labware is None:
+                self._logger.error("Cannot get well position: no labware loaded in slot '%s'", slot)
+                raise ValueError(f"No labware loaded in slot '{slot}'. Load labware before accessing wells.")
+            well_pos = labware.get_well_position(well).get_xy()
             pos += well_pos.swap_xy()
             
             # get a
-            a = Position(a=self.deck[slot].get_height() - self.CEILING_HEIGHT)
+            a = Position(a=labware.get_height() - self.CEILING_HEIGHT)
             pos += a
             self._logger.debug("Absolute A position for slot '%s', well '%s': %s", slot, well, pos)
         else:

{puda_drivers-0.0.15 → puda_drivers-0.0.17}/src/puda_drivers/move/deck.py

@@ -1,5 +1,6 @@
 # src/puda_drivers/move/deck.py
 
+import json
 from puda_drivers.labware import StandardLabware
 
 
@@ -29,6 +30,20 @@ class Deck:
         if slot.upper() not in self.slots:
             raise KeyError(f"Slot {slot} not found in deck")
         self.slots[slot.upper()] = StandardLabware(labware_name=labware_name)
+    
+    def empty_slot(self, slot: str):
+        """
+        Empty a slot (remove labware from it).
+        
+        Args:
+            slot: Slot name (e.g., 'A1', 'B2')
+        
+        Raises:
+            KeyError: If slot is not found in deck
+        """
+        if slot.upper() not in self.slots:
+            raise KeyError(f"Slot {slot} not found in deck")
+        self.slots[slot.upper()] = None
         
     def __str__(self):
         """
@@ -44,4 +59,23 @@ class Deck:
 
     def __getitem__(self, key):
         """Allows syntax for: my_deck['B4']"""
-        return self.slots[key.upper()]
+        return self.slots[key.upper()]
+ 
+    def to_dict(self) -> dict:
+        """
+        Return the deck layout as a dictionary.
+        """
+        deck_data = {}
+        for slot, labware in self.slots.items():
+            if labware is None:
+                deck_data[slot] = None
+            else:
+                deck_data[slot] = labware.name
+        return deck_data
+
+    def to_json(self) -> str:
+        """
+        Return the deck layout as a JSON string.
+        """
+        # Re-use the logic from to_dict() so you don't have to update it in two places
+        return json.dumps(self.to_dict(), indent=2)

{puda_drivers-0.0.15 → puda_drivers-0.0.17}/src/puda_drivers/move/gcode.py

@@ -296,7 +296,7 @@ class GCodeController(SerialController):
             home_target = "All"
 
         self._logger.info("[%s] homing axis/axes: %s **", cmd, home_target)
-        self.execute(cmd)
+        self.execute(command=cmd, timeout=90) # 90 seconds timeout for homing
         self._logger.info("Homing of %s completed.\n", home_target)
 
         # Update internal position (optimistic zeroing)
@@ -514,6 +514,9 @@ class GCodeController(SerialController):
 
         This method can be called even when the machine is moving from other commands,
         as it runs the blocking serial communication in a separate thread.
+        
+        If the M114 command takes more than 1 second to respond, falls back to
+        returning the internally tracked position instead.
 
         Returns:
             Position containing X, Y, Z, and A positions
@@ -523,28 +526,38 @@ class GCodeController(SerialController):
         """
         self._logger.info("Querying current machine position (M114).")
         # Run the blocking execute call in a thread pool to allow concurrent operations
-        res: str = await asyncio.to_thread(self.execute, "M114")
-
-        # Extract position values using regex
-        pattern = re.compile(r"([XYZA]):(-?\d+\.\d+)")
-        matches = pattern.findall(res)
+        # with a 1 second timeout - if it takes longer, fall back to internal position
+        try:
+            res: str = await asyncio.wait_for(
+                asyncio.to_thread(self.execute, "M114"),
+                timeout=1.0
+            )
+            
+            # Extract position values using regex
+            pattern = re.compile(r"([XYZA]):(-?\d+\.\d+)")
+            matches = pattern.findall(res)
 
-        position_data: Dict[str, float] = {}
+            position_data: Dict[str, float] = {}
 
-        for axis, value_str in matches:
-            try:
-                position_data[axis.lower()] = float(value_str)
-            except ValueError:
-                self._logger.error(
-                    "Failed to convert position value '%s' for axis %s to float.",
-                    value_str,
-                    axis,
-                )
-                continue
-
-        position = Position.from_dict(position_data)
-        self._logger.info("Query position complete. Retrieved positions: %s", position)
-        return position
+            for axis, value_str in matches:
+                try:
+                    position_data[axis.lower()] = float(value_str)
+                except ValueError:
+                    self._logger.error(
+                        "Failed to convert position value '%s' for axis %s to float.",
+                        value_str,
+                        axis,
+                    )
+                    continue
+
+            position = Position.from_dict(position_data)
+            self._logger.info("Query position complete. Retrieved positions: %s", position)
+            return position
+        except asyncio.TimeoutError:
+            self._logger.info(
+                "M114 command timed out after 1 second. Falling back to internal position."
+            )
+            return self.get_internal_position()
 
     def _sync_position(self) -> Tuple[bool, Position]:
         """