puda-drivers 0.0.10__tar.gz → 0.0.12__tar.gz

{puda_drivers-0.0.10 → puda_drivers-0.0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: puda-drivers
-Version: 0.0.10
+Version: 0.0.12
 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
@@ -85,6 +85,7 @@ When file logging is enabled, logs are saved to timestamped files (unless a cust
 The `First` machine integrates motion control, deck management, liquid handling, and camera capabilities:
 
 ```python
+import time
 import logging
 from puda_drivers.machines import First
 from puda_drivers.core.logging import setup_logging
@@ -102,14 +103,8 @@ machine = First(
     camera_index=0,
 )
 
-# Connect all devices
-machine.connect()
-
-# Home the gantry
-machine.qubot.home()
-
-# Initialize the pipette
-machine.pipette.initialize()
+# Start up the machine (connects all controllers, homes gantry, and initializes pipette)
+machine.startup()
 
 # Load labware onto the deck
 machine.load_deck({
@@ -119,19 +114,19 @@ machine.load_deck({
 })
 
 # Start video recording
-machine.camera.start_video_recording()
+machine.start_video_recording()
 
 # Perform liquid handling operations
 machine.attach_tip(slot="A3", well="G8")
-machine.aspirate_from(slot="C2", well="A1", amount=100)
-machine.dispense_to(slot="C2", well="B4", amount=100)
-machine.drop_tip(slot="C1", well="A1")
+machine.aspirate_from(slot="C2", well="A1", amount=100, height_from_bottom=10.0)
+machine.dispense_to(slot="C2", well="B4", amount=100, height_from_bottom=30.0)
+machine.drop_tip(slot="C1", well="A1", height_from_bottom=10)
 
 # Stop video recording
-machine.camera.stop_video_recording()
+machine.stop_video_recording()
 
-# Disconnect all devices
-machine.disconnect()
+# Shutdown the machine (gracefully disconnects all controllers)
+machine.shutdown()
 ```
 
 **Discovering Available Methods**: To explore what methods are available on any class instance, you can use Python's built-in `help()` function:

{puda_drivers-0.0.10 → puda_drivers-0.0.12}/README.md

@@ -64,6 +64,7 @@ When file logging is enabled, logs are saved to timestamped files (unless a cust
 The `First` machine integrates motion control, deck management, liquid handling, and camera capabilities:
 
 ```python
+import time
 import logging
 from puda_drivers.machines import First
 from puda_drivers.core.logging import setup_logging
@@ -81,14 +82,8 @@ machine = First(
     camera_index=0,
 )
 
-# Connect all devices
-machine.connect()
-
-# Home the gantry
-machine.qubot.home()
-
-# Initialize the pipette
-machine.pipette.initialize()
+# Start up the machine (connects all controllers, homes gantry, and initializes pipette)
+machine.startup()
 
 # Load labware onto the deck
 machine.load_deck({
@@ -98,19 +93,19 @@ machine.load_deck({
 })
 
 # Start video recording
-machine.camera.start_video_recording()
+machine.start_video_recording()
 
 # Perform liquid handling operations
 machine.attach_tip(slot="A3", well="G8")
-machine.aspirate_from(slot="C2", well="A1", amount=100)
-machine.dispense_to(slot="C2", well="B4", amount=100)
-machine.drop_tip(slot="C1", well="A1")
+machine.aspirate_from(slot="C2", well="A1", amount=100, height_from_bottom=10.0)
+machine.dispense_to(slot="C2", well="B4", amount=100, height_from_bottom=30.0)
+machine.drop_tip(slot="C1", well="A1", height_from_bottom=10)
 
 # Stop video recording
-machine.camera.stop_video_recording()
+machine.stop_video_recording()
 
-# Disconnect all devices
-machine.disconnect()
+# Shutdown the machine (gracefully disconnects all controllers)
+machine.shutdown()
 ```
 
 **Discovering Available Methods**: To explore what methods are available on any class instance, you can use Python's built-in `help()` function:

{puda_drivers-0.0.10 → puda_drivers-0.0.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "puda-drivers"
-version = "0.0.10"
+version = "0.0.12"
 description = "Hardware drivers for the PUDA platform."
 readme = "README.md"
 authors = [

{puda_drivers-0.0.10 → puda_drivers-0.0.12}/src/puda_drivers/labware/polyelectric_8_wellplate_30000ul.json

@@ -30,7 +30,7 @@
     "dimensions": {
         "xDimension": 128,
         "yDimension": 85.5,
-        "zDimension": 74
+        "zDimension": 54
     },
     "wells": {
         "A1": {

{puda_drivers-0.0.10 → puda_drivers-0.0.12}/src/puda_drivers/labware/trash_bin.json

@@ -11,7 +11,7 @@
   "dimensions": {
     "xDimension": 127.76,
     "yDimension": 85.48,
-    "zDimension": 20
+    "zDimension": 0
   },
   "wells": {
     "A1": {

{puda_drivers-0.0.10 → puda_drivers-0.0.12}/src/puda_drivers/machines/first.py

@@ -9,7 +9,9 @@ This class demonstrates the integration of:
 
 import logging
 import time
+from pathlib import Path
 from typing import Optional, Dict, Tuple, Type, Union
+import numpy as np
 from puda_drivers.move import GCodeController, Deck
 from puda_drivers.core import Position
 from puda_drivers.transfer.liquid.sartorius import SartoriusController
@@ -118,21 +120,44 @@ class First:
             camera_index if camera_index is not None else self.DEFAULT_CAMERA_INDEX,
         )
         
-    def connect(self):
-        """Connect all controllers."""
-        self._logger.info("Connecting all controllers")
+    def startup(self):
+        """
+        Start up the machine by connecting all controllers and initializing subsystems.
+        
+        This method:
+        - Connects to all controllers (gantry, pipette, camera)
+        - Homes the gantry to establish a known position
+        - Initializes the pipette to reset it to a known state
+        
+        The machine is ready for operations after this method completes.
+        """
+        self._logger.info("Starting up machine and connecting all controllers")
         self.qubot.connect()
         self.pipette.connect()
         self.camera.connect()
         self._logger.info("All controllers connected successfully")
         
-    def disconnect(self):
-        """Disconnect all controllers."""
-        self._logger.info("Disconnecting all controllers")
+        # Home the gantry to establish known position
+        self._logger.info("Homing gantry...")
+        self.qubot.home()
+        
+        # Initialize the pipette (all pipette operations need to wait 5 seconds for completion)
+        self._logger.info("Initializing pipette...")
+        self.pipette.initialize()
+        time.sleep(5)
+        self._logger.info("Machine startup complete - ready for operations")
+        
+    def shutdown(self):
+        """
+        Gracefully shut down the machine by disconnecting all controllers.
+        
+        This method ensures all connections are properly closed and resources are released.
+        """
+        self._logger.info("Shutting down machine and disconnecting all controllers")
         self.qubot.disconnect()
         self.pipette.disconnect()
         self.camera.disconnect()
-        self._logger.info("All controllers disconnected successfully")
+        self._logger.info("Machine shutdown complete")
         
     def load_labware(self, slot: str, labware_name: str):
         """Load a labware object into a slot."""
@@ -185,14 +210,30 @@ class First:
         self.qubot.home(axis="Z")
         self._logger.debug("Z axis homed after tip attachment")
         
-    def drop_tip(self, slot: str, well: str):
-        """Drop a tip into a slot."""
+    def drop_tip(self, slot: str, well: str, height_from_bottom: float = 0.0):
+        """
+        Drop a tip into a slot.
+        
+        Args:
+            slot: Slot name (e.g., 'A1', 'B2')
+            well: Well name within the slot (e.g., 'A1' for a well in a tiprack)
+            height_from_bottom: Height from the bottom of the well in mm. Defaults to 0.0.
+                               Positive values move up from the bottom. Negative values
+                               may cause a ValueError if the resulting position is outside
+                               the Z axis limits.
+        
+        Raises:
+            ValueError: If no tip is attached, or if the resulting position is outside
+                       the Z axis limits.
+        """
         if not self.pipette.is_tip_attached():
             self._logger.error("Cannot drop tip: no tip attached")
             raise ValueError("Tip not attached")
         
         self._logger.info("Dropping tip into slot '%s', well '%s'", slot, well)
         pos = self.get_absolute_z_position(slot, well)
+        # add height from bottom
+        pos += Position(z=height_from_bottom)
         # move up by the tip length
         pos += Position(z=self.TIP_LENGTH)
         self._logger.debug("Moving to position %s (adjusted for tip length) for tip drop", pos)
@@ -204,31 +245,67 @@ class First:
         self.pipette.set_tip_attached(attached=False)
         self._logger.info("Tip dropped successfully")
         
-    def aspirate_from(self, slot:str, well:str, amount:int):
-        """Aspirate a volume of liquid from a slot."""
+    def aspirate_from(self, slot:str, well:str, amount:int, height_from_bottom: float = 0.0):
+        """
+        Aspirate a volume of liquid from a slot.
+        
+        Args:
+            slot: Slot name (e.g., 'A1', 'B2')
+            well: Well name within the slot (e.g., 'A1')
+            amount: Volume to aspirate in µL
+            height_from_bottom: Height from the bottom of the well in mm. Defaults to 0.0.
+                               Positive values move up from the bottom. Negative values
+                               may cause a ValueError if the resulting position is outside
+                               the Z axis limits.
+        
+        Raises:
+            ValueError: If no tip is attached, or if the resulting position is outside
+                       the Z axis limits.
+        """
         if not self.pipette.is_tip_attached():
             self._logger.error("Cannot aspirate: no tip attached")
             raise ValueError("Tip not attached")
         
         self._logger.info("Aspirating %d µL from slot '%s', well '%s'", amount, slot, well)
         pos = self.get_absolute_z_position(slot, well)
+        # add height from bottom
+        pos += Position(z=height_from_bottom)
         self._logger.debug("Moving Z axis to position %s", pos)
         self.qubot.move_absolute(position=pos)
+
         self._logger.debug("Aspirating %d µL", amount)
         self.pipette.aspirate(amount=amount)
         time.sleep(5)
         self._logger.info("Aspiration completed: %d µL from slot '%s', well '%s'", amount, slot, well)
         
-    def dispense_to(self, slot:str, well:str, amount:int):
-        """Dispense a volume of liquid to a slot."""
+    def dispense_to(self, slot:str, well:str, amount:int, height_from_bottom: float = 0.0):
+        """
+        Dispense a volume of liquid to a slot.
+        
+        Args:
+            slot: Slot name (e.g., 'A1', 'B2')
+            well: Well name within the slot (e.g., 'A1')
+            amount: Volume to dispense in µL
+            height_from_bottom: Height from the bottom of the well in mm. Defaults to 0.0.
+                               Positive values move up from the bottom. Negative values
+                               may cause a ValueError if the resulting position is outside
+                               the Z axis limits.
+        
+        Raises:
+            ValueError: If no tip is attached, or if the resulting position is outside
+                       the Z axis limits.
+        """
         if not self.pipette.is_tip_attached():
             self._logger.error("Cannot dispense: no tip attached")
             raise ValueError("Tip not attached")
         
         self._logger.info("Dispensing %d µL to slot '%s', well '%s'", amount, slot, well)
         pos = self.get_absolute_z_position(slot, well)
+        # add height from bottom
+        pos += Position(z=height_from_bottom)
         self._logger.debug("Moving Z axis to position %s", pos)
         self.qubot.move_absolute(position=pos)
+
         self._logger.debug("Dispensing %d µL", amount)
         self.pipette.dispense(amount=amount)
         time.sleep(5)
@@ -275,8 +352,7 @@ class First:
             # the deck is rotated 90 degrees clockwise for this machine
             pos += well_pos.swap_xy()
             # get z
-            z = Position(z=self.deck[slot].get_height() - self.CEILING_HEIGHT)
-            pos += z
+            pos += Position(z=self.deck[slot].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)
@@ -299,3 +375,86 @@ class First:
         else:
             self._logger.debug("Absolute A position for slot '%s': %s", slot, pos)
         return pos
+    
+    def start_video_recording(
+        self,
+        filename: Optional[Union[str, Path]] = None,
+        fps: Optional[float] = None
+    ) -> Path:
+        """
+        Start recording a video.
+        
+        Args:
+            filename: Optional filename for the video. If not provided, a timestamped
+                    filename will be generated. If provided without extension, .mp4 will be added.
+            fps: Optional frames per second for the video. Defaults to 30.0 if not specified.
+        
+        Returns:
+            Path to the video file where recording is being saved
+            
+        Raises:
+            IOError: If camera is not connected or recording fails to start
+            ValueError: If already recording
+        """
+        return self.camera.start_video_recording(filename=filename, fps=fps)
+    
+    def stop_video_recording(self) -> Optional[Path]:
+        """
+        Stop recording a video.
+        
+        Returns:
+            Path to the saved video file, or None if no recording was in progress
+            
+        Raises:
+            IOError: If video writer fails to release
+        """
+        return self.camera.stop_video_recording()
+    
+    def record_video(
+        self,
+        duration_seconds: float,
+        filename: Optional[Union[str, Path]] = None,
+        fps: Optional[float] = None
+    ) -> Path:
+        """
+        Record a video for a specified duration.
+        
+        Args:
+            duration_seconds: Duration of the video in seconds
+            filename: Optional filename for the video. If not provided, a timestamped
+                    filename will be generated. If provided without extension, .mp4 will be added.
+            fps: Optional frames per second for the video. Defaults to 30.0 if not specified.
+        
+        Returns:
+            Path to the saved video file
+            
+        Raises:
+            IOError: If camera is not connected or recording fails
+        """
+        return self.camera.record_video(
+            duration_seconds=duration_seconds,
+            filename=filename,
+            fps=fps
+        )
+    
+    def capture_image(
+        self, 
+        save: bool = False, 
+        filename: Optional[Union[str, Path]] = None
+    ) -> np.ndarray:
+        """
+        Capture a single image from the camera.
+        
+        Args:
+            save: If True, save the image to the captures folder
+            filename: Optional filename for the saved image. If not provided and save=True,
+                     a timestamped filename will be generated. If provided without extension,
+                     .jpg will be added.
+        
+        Returns:
+            Captured image as a numpy array (BGR format)
+            
+        Raises:
+            IOError: If camera is not connected or capture fails
+        """
+        return self.camera.capture_image(save=save, filename=filename)

{puda_drivers-0.0.10 → puda_drivers-0.0.12}/tests/first.py

@@ -1,6 +1,7 @@
 """Test script for the First machine driver."""
 
 import random
+import time
 import logging
 from puda_drivers.machines import First
 from puda_drivers.labware import get_available_labware
@@ -8,7 +9,7 @@ from puda_drivers.core import setup_logging
 
 setup_logging(
     enable_file_logging=False,
-    log_level=logging.DEBUG,  # Use logging.DEBUG to see all (DEBUG, INFO, WARNING, ERROR, CRITICAL) logs
+    log_level=logging.INFO,  # Use logging.DEBUG to see all (DEBUG, INFO, WARNING, ERROR, CRITICAL) logs
 )
 
 if __name__ == "__main__":
@@ -34,15 +35,15 @@ if __name__ == "__main__":
     print(machine.deck)
     print(machine.deck["C2"])
 
-    machine.connect()
-    machine.qubot.home()
-    machine.pipette.initialize()
+    machine.startup()  # Connects all controllers, homes gantry, and initializes pipette
     
-    machine.camera.start_video_recording()
+    # machine.record_video(duration_seconds=10, filename="test.mp4")
+    machine.start_video_recording()
     machine.attach_tip(slot="A3", well="G8")
-    machine.aspirate_from(slot="C2", well="A1", amount=100)
-    machine.dispense_to(slot="C2", well="B4", amount=100)
-    machine.drop_tip(slot="C1", well="A1")
+    machine.aspirate_from(slot="C2", well="A1", amount=100, height_from_bottom=10)
+    # machine.capture_image()
+    machine.dispense_to(slot="C2", well="B4", amount=100, height_from_bottom=50)
+    machine.drop_tip(slot="C1", well="A1", height_from_bottom=10)
     
     # tiprack_wells = machine.deck["A3"].wells
     # # get pick up pipette one by one and drop it in the trash bin
@@ -58,7 +59,7 @@ if __name__ == "__main__":
     #     machine.drop_tip("C1", "A1")
 
 
-    machine.camera.stop_video_recording()
+    machine.stop_video_recording()
     
-    # Disconnect machine
-    machine.disconnect()
+    # Shutdown machine
+    machine.shutdown()

{puda_drivers-0.0.10 → puda_drivers-0.0.12}/uv.lock

@@ -186,7 +186,7 @@ wheels = [
 
 [[package]]
 name = "puda-drivers"
-version = "0.0.10"
+version = "0.0.12"
 source = { editable = "." }
 dependencies = [
     { name = "opencv-python" },