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

puda_drivers/cv/__init__.py

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

puda_drivers/cv/camera.py

@@ -0,0 +1,434 @@
+"""
+Camera controller for image and video capture.
+
+This module provides a Python interface for controlling cameras and webcams
+to capture images and videos for laboratory automation applications using OpenCV.
+"""
+
+import logging
+import time
+import threading
+from datetime import datetime
+from typing import Optional, Union, List, Tuple
+from pathlib import Path
+import cv2
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+def list_cameras(max_index: int = 10) -> List[Tuple[int, bool, Optional[tuple[int, int]]]]:
+    """
+    Lists available cameras on the system by testing camera indices.
+    
+    This is a utility function that can be used independently of any controller instance.
+    It's useful for discovering available cameras before initializing a controller.
+    
+    Args:
+        max_index: Maximum camera index to test (default: 10). The function will test
+                  indices from 0 to max_index-1.
+    
+    Returns:
+        List of tuples, where each tuple contains (index, is_available, resolution).
+        resolution is a (width, height) tuple if available, None otherwise.
+    """
+    available_cameras = []
+    
+    for index in range(max_index):
+        cap = cv2.VideoCapture(index)
+        if cap.isOpened():
+            # Try to read a frame to confirm it's actually working
+            ret, _ = cap.read()
+            if ret:
+                # Get resolution
+                width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+                height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+                resolution = (width, height) if width > 0 and height > 0 else None
+                available_cameras.append((index, resolution))
+            cap.release()
+        else:
+            cap.release()
+    
+    return available_cameras
+
+
+class CameraController:
+    """
+    Controller for cameras and webcams using OpenCV.
+    
+    This class provides methods for capturing images and videos from cameras.
+    Images can be returned as numpy arrays and optionally saved to the captures folder.
+    Videos can be recorded for a specified duration or controlled manually with start/stop.
+    
+    Attributes:
+        camera_index: Index or identifier for the camera device
+        resolution: Camera resolution as (width, height) tuple
+        captures_folder: Path to the folder where captured images and videos are saved
+    """
+    
+    DEFAULT_CAPTURES_FOLDER = "captures"
+    
+    def __init__(
+        self,
+        camera_index: Union[int, str] = 0,
+        resolution: Optional[tuple[int, int]] = None,
+        captures_folder: Union[str, Path, None] = None,
+    ):
+        """
+        Initialize the camera controller.
+        
+        Args:
+            camera_index: Camera device index (0 for default) or device path/identifier
+            resolution: Optional resolution as (width, height) tuple
+            captures_folder: Path to folder for saving captured images. 
+                            Defaults to "captures" in the current working directory.
+        """
+        self.camera_index = camera_index
+        self.resolution = resolution
+        self.captures_folder = Path(captures_folder) if captures_folder else Path(self.DEFAULT_CAPTURES_FOLDER)
+        self._logger = logging.getLogger(__name__)
+        self._camera: Optional[cv2.VideoCapture] = None
+        self._is_connected = False
+        
+        # Video recording state
+        self._video_writer: Optional[cv2.VideoWriter] = None
+        self._is_recording = False
+        self._video_file_path: Optional[Path] = None
+        self._fps: float = 30.0  # Default FPS for video recording
+        self._recording_thread: Optional[threading.Thread] = None
+        self._stop_recording_event: Optional[threading.Event] = None
+        
+        # Create captures folder if it doesn't exist
+        self.captures_folder.mkdir(parents=True, exist_ok=True)
+        
+        self._logger.info(
+            "Camera Controller initialized with camera_index='%s', resolution=%s, captures_folder='%s'",
+            camera_index,
+            resolution,
+            self.captures_folder,
+        )
+    
+    def connect(self) -> None:
+        """
+        Connect to the camera device.
+        
+        Raises:
+            IOError: If camera connection fails
+        """
+        if self._is_connected:
+            self._logger.warning("Camera already connected. Disconnecting and reconnecting...")
+            self.disconnect()
+        
+        self._logger.info("Connecting to camera %s...", self.camera_index)
+        
+        try:
+            self._camera = cv2.VideoCapture(self.camera_index)
+            
+            if not self._camera.isOpened():
+                raise IOError(f"Could not open camera {self.camera_index}")
+            
+            # Set resolution if specified
+            if self.resolution:
+                width, height = self.resolution
+                self._camera.set(cv2.CAP_PROP_FRAME_WIDTH, width)
+                self._camera.set(cv2.CAP_PROP_FRAME_HEIGHT, height)
+                self._logger.info("Resolution set to %dx%d", width, height)
+            
+            self._is_connected = True
+            self._logger.info("Successfully connected to camera %s", self.camera_index)
+            
+        except Exception as e:
+            self._camera = None
+            self._is_connected = False
+            self._logger.error("Error connecting to camera %s: %s", self.camera_index, e)
+            raise IOError(f"Error connecting to camera {self.camera_index}: {e}") from e
+    
+    def disconnect(self) -> None:
+        """
+        Disconnect from the camera device.
+        """
+        # Stop any ongoing video recording before disconnecting
+        if self._is_recording:
+            self._logger.warning("Stopping video recording before disconnecting...")
+            self.stop_video_recording()
+        
+        if self._camera is not None:
+            self._logger.info("Disconnecting from camera %s...", self.camera_index)
+            self._camera.release()
+            self._camera = None
+            self._is_connected = False
+            self._logger.info("Camera disconnected")
+        else:
+            self._logger.warning("Camera already disconnected or was never connected")
+    
+    @property
+    def is_connected(self) -> bool:
+        """
+        Check if the camera is currently connected.
+        
+        Returns:
+            True if connected, False otherwise
+        """
+        return self._is_connected and self._camera is not None and self._camera.isOpened()
+    
+    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
+        """
+        if not self.is_connected:
+            raise IOError("Camera is not connected. Call connect() first.")
+        
+        self._logger.info("Capturing image...")
+        
+        ret, frame = self._camera.read()
+        
+        if not ret or frame is None:
+            self._logger.error("Failed to capture frame from camera")
+            raise IOError("Failed to capture frame from camera")
+        
+        self._logger.info("Image captured successfully (shape: %s)", frame.shape)
+        
+        # Save image if requested
+        if save:
+            if filename is None:
+                timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+                filename = f"capture_{timestamp}.jpg"
+            
+            file_path = Path(filename)
+            # If filename doesn't have an extension, add .jpg
+            if not file_path.suffix:
+                file_path = file_path.with_suffix(".jpg")
+            
+            # If filename is not absolute, save to captures folder
+            if not file_path.is_absolute():
+                file_path = self.captures_folder / file_path
+            
+            # Ensure parent directory exists
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+            
+            cv2.imwrite(str(file_path), frame)
+            self._logger.info("Image saved to %s", file_path)
+        
+        return frame
+    
+    def set_resolution(self, width: int, height: int) -> None:
+        """
+        Set the camera resolution.
+        
+        Args:
+            width: Image width in pixels
+            height: Image height in pixels
+        """
+        self.resolution = (width, height)
+        self._logger.info("Resolution set to %dx%d", width, height)
+        
+        # Apply resolution to camera if connected
+        if self.is_connected:
+            self._camera.set(cv2.CAP_PROP_FRAME_WIDTH, width)
+            self._camera.set(cv2.CAP_PROP_FRAME_HEIGHT, height)
+            self._logger.info("Resolution applied to camera")
+    
+    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
+        """
+        if not self.is_connected:
+            raise IOError("Camera is not connected. Call connect() first.")
+        
+        if self._is_recording:
+            raise ValueError("Video recording is already in progress. Call stop_video_recording() first.")
+        
+        # Generate filename if not provided
+        if filename is None:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            filename = f"video_{timestamp}.mp4"
+        
+        file_path = Path(filename)
+        # If filename doesn't have an extension, add .mp4
+        if not file_path.suffix:
+            file_path = file_path.with_suffix(".mp4")
+        
+        # If filename is not absolute, save to captures folder
+        if not file_path.is_absolute():
+            file_path = self.captures_folder / file_path
+        
+        # Ensure parent directory exists
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        
+        # Get current camera resolution
+        width = int(self._camera.get(cv2.CAP_PROP_FRAME_WIDTH))
+        height = int(self._camera.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        
+        # Use provided FPS or default
+        fps = fps if fps is not None else self._fps
+        
+        # Define codec and create VideoWriter
+        fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+        self._video_writer = cv2.VideoWriter(str(file_path), fourcc, fps, (width, height))
+        
+        if not self._video_writer.isOpened():
+            self._video_writer = None
+            raise IOError(f"Failed to initialize video writer for {file_path}")
+        
+        self._is_recording = True
+        self._video_file_path = file_path
+        self._fps = fps
+        
+        # Start background thread to continuously capture frames
+        self._stop_recording_event = threading.Event()
+        self._recording_thread = threading.Thread(target=self._capture_frames_loop, daemon=True)
+        self._recording_thread.start()
+        
+        self._logger.info("Started video recording to %s (FPS: %.1f, Resolution: %dx%d)", 
+                         file_path, fps, width, height)
+        
+        return file_path
+    
+    def _capture_frames_loop(self) -> None:
+        """
+        Internal method that continuously captures frames and writes them to the video.
+        Runs in a background thread while recording is active.
+        """
+        frame_interval = 1.0 / self._fps if self._fps > 0 else 0.033  # Default to ~30 FPS
+        
+        while self._is_recording and not self._stop_recording_event.is_set():
+            if self._video_writer is None or self._camera is None:
+                break
+            
+            ret, frame = self._camera.read()
+            if ret and frame is not None:
+                self._video_writer.write(frame)
+            
+            time.sleep(frame_interval)
+        
+        self._logger.debug("Frame capture loop stopped")
+    
+    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
+        """
+        if not self._is_recording:
+            self._logger.warning("No video recording in progress")
+            return None
+        
+        self._logger.info("Stopping video recording...")
+        
+        # Signal the recording thread to stop
+        self._is_recording = False
+        if self._stop_recording_event is not None:
+            self._stop_recording_event.set()
+        
+        # Wait for the recording thread to finish
+        if self._recording_thread is not None and self._recording_thread.is_alive():
+            self._recording_thread.join(timeout=2.0)
+        
+        # Release video writer
+        if self._video_writer is not None:
+            self._video_writer.release()
+            self._video_writer = None
+        
+        file_path = self._video_file_path
+        self._video_file_path = None
+        self._recording_thread = None
+        self._stop_recording_event = None
+        
+        if file_path and file_path.exists():
+            self._logger.info("Video saved to %s", file_path)
+        else:
+            self._logger.warning("Video file may not have been saved correctly")
+        
+        return file_path
+    
+    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
+            ValueError: If duration is not positive
+        """
+        if not self.is_connected:
+            raise IOError("Camera is not connected. Call connect() first.")
+        
+        if duration_seconds <= 0:
+            raise ValueError(f"Duration must be positive, got {duration_seconds}")
+        
+        # Start recording
+        file_path = self.start_video_recording(filename=filename, fps=fps)
+        
+        self._logger.info("Recording video for %.2f seconds...", duration_seconds)
+        
+        start_time = time.time()
+        frame_count = 0
+        
+        try:
+            while time.time() - start_time < duration_seconds:
+                ret, frame = self._camera.read()
+                if ret and frame is not None:
+                    self._video_writer.write(frame)
+                    frame_count += 1
+                else:
+                    self._logger.warning("Failed to read frame during video recording")
+                    break
+        finally:
+            # Always stop recording, even if there was an error
+            self.stop_video_recording()
+        
+        actual_duration = time.time() - start_time
+        self._logger.info("Video recording completed: %.2f seconds, %d frames (%.1f FPS actual)", 
+                         actual_duration, frame_count, frame_count / actual_duration if actual_duration > 0 else 0)
+        
+        return file_path
+

puda_drivers/machines/first.py

@@ -7,17 +7,19 @@ This class demonstrates the integration of:
 - SartoriusController: Handles liquid handling operations
 """
 
+import logging
 import time
-from typing import Optional, Dict, Tuple, Type
+from typing import Optional, Dict, Tuple, Type, Union
 from puda_drivers.move import GCodeController, Deck
 from puda_drivers.core import Position
 from puda_drivers.transfer.liquid.sartorius import SartoriusController
 from puda_drivers.labware import StandardLabware
+from puda_drivers.cv import CameraController
 
 
 class First:
     """
-    First machine class integrating motion control, deck management, and liquid handling.
+    First machine class integrating motion control, deck management, liquid handling, and camera.
     
     The deck has 16 slots arranged in a 4x4 grid (A1-D4).
     Each slot's origin location is stored for absolute movement calculation.
@@ -31,6 +33,8 @@ class First:
     DEFAULT_SARTORIUS_PORT = "/dev/ttyUSB0"
     DEFAULT_SARTORIUS_BAUDRATE = 9600
     
+    DEFAULT_CAMERA_INDEX = 0
+    
     # origin position of Z and A axes
     Z_ORIGIN = Position(x=0, y=0, z=0)
     A_ORIGIN = Position(x=60, y=0, a=0)
@@ -69,6 +73,7 @@ class First:
         self,
         qubot_port: Optional[str] = None,
         sartorius_port: Optional[str] = None,
+        camera_index: Optional[Union[int, str]] = None,
         axis_limits: Optional[Dict[str, Tuple[float, float]]] = None,
     ):
         """
@@ -77,6 +82,8 @@ class First:
         Args:
             qubot_port: Serial port for GCodeController (e.g., '/dev/ttyACM0')
             sartorius_port: Serial port for SartoriusController (e.g., '/dev/ttyUSB0')
+            camera_index: Camera device index (0 for default) or device path/identifier.
+                         Defaults to 0.
             axis_limits: Dictionary mapping axis names to (min, max) limits.
                         Defaults to DEFAULT_AXIS_LIMITS.
         """
@@ -97,19 +104,41 @@ class First:
             port_name=sartorius_port or self.DEFAULT_SARTORIUS_PORT,
         )
         
+        # Initialize camera
+        self.camera = CameraController(
+            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]]):
         """
@@ -126,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:
         """
@@ -199,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:
         """
@@ -224,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:
@@ -239,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.8.dist-info → puda_drivers-0.0.10.dist-info}/METADATA

@@ -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.dist-info → puda_drivers-0.0.10.dist-info}/RECORD

@@ -4,13 +4,15 @@ puda_drivers/core/__init__.py,sha256=XbCdXsU6NMDsmEAtavAGiSZZPla5d7zc2L7Qx9qKHdY
 puda_drivers/core/logging.py,sha256=prOeJ3CGEbm37TtMRyAOTQQiMU5_ImZTRXmcUJxkenc,2892
 puda_drivers/core/position.py,sha256=f4efmDSrKKCtqrR-GUJxVitPG20MiuGSDOWt-9TVISk,12628
 puda_drivers/core/serialcontroller.py,sha256=38mKas1iJaOkAE0_V4tmqgZz7RxMMEWfGqA0Ma_Dt2A,8604
+puda_drivers/cv/__init__.py,sha256=DYiPwYOLSUsZ9ivWiHoMGGD3MZ3Ygu9qLYja_OiUodU,100
+puda_drivers/cv/camera.py,sha256=Tzxt1h3W5Z8XFanud_z-PhhJ2UYsC4OEhcak9TVu8jM,16490
 puda_drivers/labware/__init__.py,sha256=RlRxrJn2zyzyxv4c1KGt8Gmxv2cRO8V4zZVnnyL-I00,288
 puda_drivers/labware/labware.py,sha256=hZhOzSyb1GP_bm1LvQsREx4YSqLCWBTKNWDgDqfFavI,5317
 puda_drivers/labware/opentrons_96_tiprack_300ul.json,sha256=jmNaworu688GEgFdxMxNRSaEp4ZOg9IumFk8bVHSzYY,19796
 puda_drivers/labware/polyelectric_8_wellplate_30000ul.json,sha256=NwXMgHBYnIIFasmrthTDTTV7n1M5DYQBDWh-KYsq1gI,3104
 puda_drivers/labware/trash_bin.json,sha256=X4TDNDzGbCtJSWlYgGYHUzdnVKj62SggGDNf7z5S0OE,581
 puda_drivers/machines/__init__.py,sha256=zmIk_r2T8nbPA68h3Cko8N6oL7ncoBpmvhNcAqzHmc4,45
-puda_drivers/machines/first.py,sha256=McnZ4q_ykv56aWFqphoZFqXqbhDGZAWCk40CPblgPsw,8492
+puda_drivers/machines/first.py,sha256=9Im7jiw2duOBbBQEOxVkqFApPDRlGfI87OoyJ-M4SJE,12122
 puda_drivers/move/__init__.py,sha256=NKIKckcqgyviPM0EGFcmIoaqkJM4qekR4babfdddRzM,96
 puda_drivers/move/deck.py,sha256=yq2B4WMqj0hQvHt8HoJskP10u1DUyKwUnjP2c9gJ174,1397
 puda_drivers/move/gcode.py,sha256=Aw7la4RkPw737hW5sKl6WiPCmmTnsjLvG4mOb-RwVSc,22592
@@ -21,7 +23,7 @@ puda_drivers/transfer/liquid/sartorius/__init__.py,sha256=QGpKz5YUwa8xCdSMXeZ0iR
 puda_drivers/transfer/liquid/sartorius/api.py,sha256=jxwIJmY2k1K2ts6NC2ZgFTe4MOiH8TGnJeqYOqNa3rE,28250
 puda_drivers/transfer/liquid/sartorius/constants.py,sha256=mcsjLrVBH-RSodH-pszstwcEL9wwbV0vOgHbGNxZz9w,2770
 puda_drivers/transfer/liquid/sartorius/sartorius.py,sha256=bW838jYOAfLlbUqtsKRipZ-RLjrNTcZ7riYV6I4w8G8,13728
-puda_drivers-0.0.8.dist-info/METADATA,sha256=_dQYo29lMIclzyd3HGZBvmOidliS92UWTQPPO0g79V0,8597
-puda_drivers-0.0.8.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-puda_drivers-0.0.8.dist-info/licenses/LICENSE,sha256=7EI8xVBu6h_7_JlVw-yPhhOZlpY9hP8wal7kHtqKT_E,1074
-puda_drivers-0.0.8.dist-info/RECORD,,
+puda_drivers-0.0.10.dist-info/METADATA,sha256=oEbn6NvV9bXfJZusYV49ri1V1aPFR3n2qjKTp3vJ5R0,6991
+puda_drivers-0.0.10.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+puda_drivers-0.0.10.dist-info/licenses/LICENSE,sha256=7EI8xVBu6h_7_JlVw-yPhhOZlpY9hP8wal7kHtqKT_E,1074
+puda_drivers-0.0.10.dist-info/RECORD,,