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

{puda_drivers-0.0.8 → puda_drivers-0.0.10}/.gitignore

@@ -133,3 +133,6 @@ dmypy.json
 # Log files
 logs/
 *.log
+
+# captures
+captures/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: puda-drivers
-Version: 0.0.8
+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
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Hardware
 Requires-Python: >=3.8
+Requires-Dist: opencv-python>=4.12.0.88
 Requires-Dist: pyserial~=3.5
 Description-Content-Type: text/markdown
 
@@ -79,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
 ```
 
@@ -264,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.8 → 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.8 → puda_drivers-0.0.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "puda-drivers"
-version = "0.0.8"
+version = "0.0.10"
 description = "Hardware drivers for the PUDA platform."
 readme = "README.md"
 authors = [
@@ -19,6 +19,7 @@ classifiers = [
 license = "MIT"
 license-files = ["LICEN[CS]E*"]
 dependencies = [
+    "opencv-python>=4.12.0.88",
     "pyserial~=3.5",
 ]
 

puda_drivers-0.0.10/src/puda_drivers/cv/__init__.py

@@ -0,0 +1,4 @@
+from .camera import CameraController, list_cameras
+
+__all__ = ["CameraController", "list_cameras"]
+