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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: puda-drivers
-Version: 0.0.9
+Version: 0.0.10
 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
@@ -80,160 +80,96 @@ setup_logging(
 
 When file logging is enabled, logs are saved to timestamped files (unless a custom name is provided) in the `logs/` folder. The logs folder is created automatically if it doesn't exist.
 
-### Gantry Control (GCode)
+### First Machine Example
 
-```python
-from puda_drivers.move import GCodeController
-
-# Initialize and connect to a G-code device
-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()
+The `First` machine integrates motion control, deck management, liquid handling, and camera capabilities:
 
-# Move to absolute position (validated against limits)
-gantry.move_absolute(x=50.0, y=-100.0, z=-10.0)
-
-# Move relative to current position (validated after conversion to absolute)
-gantry.move_relative(x=20.0, y=-10.0)
-
-# Query current position
-position = gantry.query_position()
-print(f"Current position: {position}")
+```python
+import logging
+from puda_drivers.machines import First
+from puda_drivers.core.logging import setup_logging
 
-# Disconnect when done
-gantry.disconnect()
-```
+# Configure logging
+setup_logging(
+    enable_file_logging=False,
+    log_level=logging.DEBUG,
+)
 
-**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.
+# Initialize the First machine
+machine = First(
+    qubot_port="/dev/ttyACM0",
+    sartorius_port="/dev/ttyUSB0",
+    camera_index=0,
+)
 
-### Liquid Handling (Sartorius)
+# Connect all devices
+machine.connect()
 
-```python
-from puda_drivers.transfer.liquid.sartorius import SartoriusController
+# Home the gantry
+machine.qubot.home()
 
-# Initialize and connect to pipette
-pipette = SartoriusController(port_name="/dev/ttyUSB0")
-pipette.connect()
-pipette.initialize()
+# Initialize the pipette
+machine.pipette.initialize()
 
-# Attach tip
-pipette.attach_tip()
+# Load labware onto the deck
+machine.load_deck({
+    "C1": "trash_bin",
+    "C2": "polyelectric_8_wellplate_30000ul",
+    "A3": "opentrons_96_tiprack_300ul",
+})
 
-# Aspirate liquid
-pipette.aspirate(amount=50.0)  # 50 µL
+# Start video recording
+machine.camera.start_video_recording()
 
-# Dispense liquid
-pipette.dispense(amount=50.0)
+# 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")
 
-# Eject tip
-pipette.eject_tip()
+# Stop video recording
+machine.camera.stop_video_recording()
 
-# Disconnect when done
-pipette.disconnect()
+# Disconnect all devices
+machine.disconnect()
 ```
 
-### Combined Workflow
+**Discovering Available Methods**: To explore what methods are available on any class instance, you can use Python's built-in `help()` function:
 
 ```python
-from puda_drivers.move import GCodeController
-from puda_drivers.transfer.liquid.sartorius import SartoriusController
-
-# Initialize both devices
-gantry = GCodeController(port_name="/dev/ttyACM0")
-pipette = SartoriusController(port_name="/dev/ttyUSB0")
-
-gantry.connect()
-pipette.connect()
-
-# Move to source well
-gantry.move_absolute(x=50.0, y=-50.0, z=-20.0)
-pipette.aspirate(amount=50.0)
-
-# Move to destination well
-gantry.move_absolute(x=150.0, y=-150.0, z=-20.0)
-pipette.dispense(amount=50.0)
-
-# Cleanup
-pipette.eject_tip()
-gantry.disconnect()
-pipette.disconnect()
+machine = First()
+help(machine)  # See methods for the First machine
+help(machine.qubot)  # See GCodeController methods
+help(machine.pipette)  # See SartoriusController methods
+help(machine.camera)  # See CameraController methods
 ```
 
-## Device Support
-
-### Motion Systems
+Alternatively, you can read the source code directly in the `src/puda_drivers/` directory.
 
-- **QuBot** (GCode) - Multi-axis gantry systems compatible with G-code commands
-  - Supports X, Y, Z, and A axes
-  - Configurable feed rates
-  - Position synchronization and homing
-  - Automatic axis limit validation for safe operation
+## Device Support
 
-### Liquid Handling
+The following device types are supported:
 
+- **GCode** - G-code compatible motion systems (e.g., QuBot)
 - **Sartorius rLINE®** - Electronic pipettes and robotic dispensers
-  - Aspirate and dispense operations
-  - Tip attachment and ejection
-  - Configurable speeds and volumes
+- **Camera** - Webcams and USB cameras for image and video capture
 
-## 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.
-
-### Logging Best Practices
+## Logging Best Practices
 
 For production applications, configure logging at the start of your script:
 
 ```python
 import logging
 from puda_drivers.core.logging import setup_logging
-from puda_drivers.move import GCodeController
 
 # Configure logging first, before initializing devices
 setup_logging(
     enable_file_logging=True,
     log_level=logging.INFO,
-    log_file_name="gantry_operation"
+    log_file_name="experiment"
 )
 
 # Now all device operations will be logged
-gantry = GCodeController(port_name="/dev/ttyACM0")
 # ... rest of your code
 ```
 
@@ -265,6 +201,8 @@ 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.
+
 ```bash
 # Create virtual environment
 uv venv

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

@@ -59,160 +59,96 @@ setup_logging(
 
 When file logging is enabled, logs are saved to timestamped files (unless a custom name is provided) in the `logs/` folder. The logs folder is created automatically if it doesn't exist.
 
-### Gantry Control (GCode)
+### First Machine Example
 
-```python
-from puda_drivers.move import GCodeController
-
-# Initialize and connect to a G-code device
-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()
+The `First` machine integrates motion control, deck management, liquid handling, and camera capabilities:
 
-# Move to absolute position (validated against limits)
-gantry.move_absolute(x=50.0, y=-100.0, z=-10.0)
-
-# Move relative to current position (validated after conversion to absolute)
-gantry.move_relative(x=20.0, y=-10.0)
-
-# Query current position
-position = gantry.query_position()
-print(f"Current position: {position}")
+```python
+import logging
+from puda_drivers.machines import First
+from puda_drivers.core.logging import setup_logging
 
-# Disconnect when done
-gantry.disconnect()
-```
+# Configure logging
+setup_logging(
+    enable_file_logging=False,
+    log_level=logging.DEBUG,
+)
 
-**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.
+# Initialize the First machine
+machine = First(
+    qubot_port="/dev/ttyACM0",
+    sartorius_port="/dev/ttyUSB0",
+    camera_index=0,
+)
 
-### Liquid Handling (Sartorius)
+# Connect all devices
+machine.connect()
 
-```python
-from puda_drivers.transfer.liquid.sartorius import SartoriusController
+# Home the gantry
+machine.qubot.home()
 
-# Initialize and connect to pipette
-pipette = SartoriusController(port_name="/dev/ttyUSB0")
-pipette.connect()
-pipette.initialize()
+# Initialize the pipette
+machine.pipette.initialize()
 
-# Attach tip
-pipette.attach_tip()
+# Load labware onto the deck
+machine.load_deck({
+    "C1": "trash_bin",
+    "C2": "polyelectric_8_wellplate_30000ul",
+    "A3": "opentrons_96_tiprack_300ul",
+})
 
-# Aspirate liquid
-pipette.aspirate(amount=50.0)  # 50 µL
+# Start video recording
+machine.camera.start_video_recording()
 
-# Dispense liquid
-pipette.dispense(amount=50.0)
+# 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")
 
-# Eject tip
-pipette.eject_tip()
+# Stop video recording
+machine.camera.stop_video_recording()
 
-# Disconnect when done
-pipette.disconnect()
+# Disconnect all devices
+machine.disconnect()
 ```
 
-### Combined Workflow
+**Discovering Available Methods**: To explore what methods are available on any class instance, you can use Python's built-in `help()` function:
 
 ```python
-from puda_drivers.move import GCodeController
-from puda_drivers.transfer.liquid.sartorius import SartoriusController
-
-# Initialize both devices
-gantry = GCodeController(port_name="/dev/ttyACM0")
-pipette = SartoriusController(port_name="/dev/ttyUSB0")
-
-gantry.connect()
-pipette.connect()
-
-# Move to source well
-gantry.move_absolute(x=50.0, y=-50.0, z=-20.0)
-pipette.aspirate(amount=50.0)
-
-# Move to destination well
-gantry.move_absolute(x=150.0, y=-150.0, z=-20.0)
-pipette.dispense(amount=50.0)
-
-# Cleanup
-pipette.eject_tip()
-gantry.disconnect()
-pipette.disconnect()
+machine = First()
+help(machine)  # See methods for the First machine
+help(machine.qubot)  # See GCodeController methods
+help(machine.pipette)  # See SartoriusController methods
+help(machine.camera)  # See CameraController methods
 ```
 
-## Device Support
-
-### Motion Systems
+Alternatively, you can read the source code directly in the `src/puda_drivers/` directory.
 
-- **QuBot** (GCode) - Multi-axis gantry systems compatible with G-code commands
-  - Supports X, Y, Z, and A axes
-  - Configurable feed rates
-  - Position synchronization and homing
-  - Automatic axis limit validation for safe operation
+## Device Support
 
-### Liquid Handling
+The following device types are supported:
 
+- **GCode** - G-code compatible motion systems (e.g., QuBot)
 - **Sartorius rLINE®** - Electronic pipettes and robotic dispensers
-  - Aspirate and dispense operations
-  - Tip attachment and ejection
-  - Configurable speeds and volumes
+- **Camera** - Webcams and USB cameras for image and video capture
 
-## 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.
-
-### Logging Best Practices
+## Logging Best Practices
 
 For production applications, configure logging at the start of your script:
 
 ```python
 import logging
 from puda_drivers.core.logging import setup_logging
-from puda_drivers.move import GCodeController
 
 # Configure logging first, before initializing devices
 setup_logging(
     enable_file_logging=True,
     log_level=logging.INFO,
-    log_file_name="gantry_operation"
+    log_file_name="experiment"
 )
 
 # Now all device operations will be logged
-gantry = GCodeController(port_name="/dev/ttyACM0")
 # ... rest of your code
 ```
 
@@ -244,6 +180,8 @@ 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.
+
 ```bash
 # Create virtual environment
 uv venv

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

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

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

@@ -7,6 +7,7 @@ This class demonstrates the integration of:
 - SartoriusController: Handles liquid handling operations
 """
 
+import logging
 import time
 from typing import Optional, Dict, Tuple, Type, Union
 from puda_drivers.move import GCodeController, Deck
@@ -108,21 +109,36 @@ class First:
             camera_index=camera_index if camera_index is not None else self.DEFAULT_CAMERA_INDEX,
         )
         
+        # Initialize logger
+        self._logger = logging.getLogger(__name__)
+        self._logger.info(
+            "First machine initialized with qubot_port='%s', sartorius_port='%s', camera_index=%s",
+            qubot_port or self.DEFAULT_QUBOT_PORT,
+            sartorius_port or self.DEFAULT_SARTORIUS_PORT,
+            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")
         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")
         self.qubot.disconnect()
         self.pipette.disconnect()
         self.camera.disconnect()
+        self._logger.info("All controllers disconnected successfully")
         
     def load_labware(self, slot: str, labware_name: str):
         """Load a labware object into a slot."""
+        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 load_deck(self, deck_layout: Dict[str, Type[StandardLabware]]):
         """
@@ -139,63 +155,84 @@ class First:
                 "C1": Rubbish,
             })
         """
+        self._logger.info("Loading deck layout with %d labware items", len(deck_layout))
         for slot, labware_name in deck_layout.items():
             self.load_labware(slot=slot, labware_name=labware_name)
+        self._logger.info("Deck layout loaded successfully")
         
     def attach_tip(self, slot: str, well: Optional[str] = None):
         """Attach a tip from a slot."""
         if self.pipette.is_tip_attached():
+            self._logger.error("Cannot attach tip: tip already attached")
             raise ValueError("Tip already attached")
         
+        self._logger.info("Attaching tip from slot '%s'%s", slot, f", well '{well}'" if well else "")
         pos = self.get_absolute_z_position(slot, well)
+        self._logger.debug("Moving to position %s for tip attachment", pos)
         # return the offset from the origin
         self.qubot.move_absolute(position=pos)
         
         # attach tip (move slowly down)
+        insert_depth = self.deck[slot].get_insert_depth()
+        self._logger.debug("Moving down by %s mm to insert tip", insert_depth)
         self.qubot.move_relative(
-            position=Position(z=-self.deck[slot].get_insert_depth()),
+            position=Position(z=-insert_depth),
             feed=500
         )
         self.pipette.set_tip_attached(attached=True)
+        self._logger.info("Tip attached successfully, homing Z axis")
         # must home Z axis after, as pressing in tip might cause it to lose steps
         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."""
         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)
         # move up by the tip length
         pos += Position(z=self.TIP_LENGTH)
-        print("moving Z to", pos)
+        self._logger.debug("Moving to position %s (adjusted for tip length) for tip drop", pos)
         self.qubot.move_absolute(position=pos)
 
+        self._logger.debug("Ejecting tip")
         self.pipette.eject_tip()
         time.sleep(5)
         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."""
         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)
-        print("moving Z to", pos)
+        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."""
         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)
-        print("moving Z to", pos)
+        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)
+        self._logger.info("Dispense completed: %d µL to slot '%s', well '%s'", amount, slot, well)
         
     def get_slot_origin(self, slot: str) -> Position:
         """
@@ -212,8 +249,11 @@ class First:
         """
         slot = slot.upper()
         if slot not in self.SLOT_ORIGINS:
+            self._logger.error("Invalid slot name: '%s'. Must be one of %s", slot, list(self.SLOT_ORIGINS.keys()))
             raise KeyError(f"Invalid slot name: {slot}. Must be one of {list(self.SLOT_ORIGINS.keys())}")
-        return self.SLOT_ORIGINS[slot]
+        pos = self.SLOT_ORIGINS[slot]
+        self._logger.debug("Slot origin for '%s': %s", slot, pos)
+        return pos
     
     def get_absolute_z_position(self, slot: str, well: Optional[str] = None) -> Position:
         """
@@ -237,6 +277,9 @@ class First:
             # get z
             z = Position(z=self.deck[slot].get_height() - self.CEILING_HEIGHT)
             pos += z
+            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)
         return pos
     
     def get_absolute_a_position(self, slot: str, well: Optional[str] = None) -> Position:
@@ -252,4 +295,7 @@ class First:
             # get a
             a = Position(a=self.deck[slot].get_height() - self.CEILING_HEIGHT)
             pos += a
+            self._logger.debug("Absolute A position for slot '%s', well '%s': %s", slot, well, pos)
+        else:
+            self._logger.debug("Absolute A position for slot '%s': %s", slot, pos)
         return pos

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

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