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

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: puda-drivers
-Version: 0.0.17
+Version: 0.0.19
 Summary: Hardware drivers for the PUDA platform.
-Project-URL: Homepage, https://github.com/PUDAP/puda-drivers
-Project-URL: Issues, https://github.com/PUDAP/puda-drivers/issues
+Project-URL: Homepage, https://github.com/PUDAP/puda
+Project-URL: Issues, https://github.com/PUDAP/puda/issues
 Author-email: zhao <20024592+agentzhao@users.noreply.github.com>
 License-Expression: MIT
 License-File: LICENSE
@@ -18,7 +18,6 @@ Requires-Python: >=3.10
 Requires-Dist: nats-py>=2.12.0
 Requires-Dist: opencv-python>=4.12.0.88
 Requires-Dist: pyserial~=3.5
-Requires-Dist: pytest>=9.0.2
 Description-Content-Type: text/markdown
 
 # puda-drivers
@@ -260,6 +259,9 @@ uv run pytest tests/ --cov=puda_drivers --cov-report=html
 # Build distribution packages
 uv build
 
+# cd to puda project root
+cd ...
+
 # Publish to PyPI
 uv publish
 # Username: __token__

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

@@ -237,6 +237,9 @@ uv run pytest tests/ --cov=puda_drivers --cov-report=html
 # Build distribution packages
 uv build
 
+# cd to puda project root
+cd ...
+
 # Publish to PyPI
 uv publish
 # Username: __token__

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

@@ -1,6 +1,6 @@
 [project]
 name = "puda-drivers"
-version = "0.0.17"
+version = "0.0.19"
 description = "Hardware drivers for the PUDA platform."
 readme = "README.md"
 authors = [
@@ -18,10 +18,14 @@ classifiers = [
 ]
 license = "MIT"
 license-files = ["LICEN[CS]E*"]
+
 dependencies = [
     "nats-py>=2.12.0",
     "opencv-python>=4.12.0.88",
     "pyserial~=3.5",
+]
+[dependency-groups]
+dev = [
     "pytest>=9.0.2",
 ]
 
@@ -30,5 +34,5 @@ requires = ["hatchling >= 1.26"]
 build-backend = "hatchling.build"
 
 [project.urls]
-Homepage = "https://github.com/PUDAP/puda-drivers"
-Issues = "https://github.com/PUDAP/puda-drivers/issues"
+Homepage = "https://github.com/PUDAP/puda"
+Issues = "https://github.com/PUDAP/puda/issues"

puda_drivers-0.0.19/src/puda_drivers/labware/MEA_cell_MTP.json

@@ -0,0 +1,56 @@
+{
+    
+    "ordering": [
+        [
+            "A1"
+        ]
+
+    ],
+    "brand": {
+        "brand": "Custom",
+        "brandId": []
+    },
+    "metadata": {
+        "displayName": "MEA cell MTP",
+        "displayCategory": "functionalLabware",
+        "tags": []
+    },
+    "dimensions": {
+        "xDimension": 127,
+        "yDimension": 85,
+        "zDimension": 28
+    },
+    "wells": {
+        "A1": {
+            "shape": "square",
+            "x": 63.5,
+            "y": 42.5,
+            "z": 25
+        }
+    },
+    "groups": [
+        {
+            "metadata": {
+                "wellBottomShape": "flat"
+            },
+            "wells": [
+                "A1"
+            ]
+        }
+    ],
+    "parameters": {
+        "format": "irregular",
+        "quirks": [],
+        "isTiprack": false,
+        "isMagneticModuleCompatible": false,
+        "loadName": "MEA_cell_MTP"
+    },
+    "namespace": "custom_beta",
+    "version": 1,
+    "schemaVersion": 2,
+    "cornerOffsetFromSlot": {
+        "x": 0,
+        "y": 0,
+        "z": 0
+    }
+}

{puda_drivers-0.0.17 → puda_drivers-0.0.19}/src/puda_drivers/labware/labware.py

@@ -3,15 +3,14 @@
 import json
 import inspect
 from pathlib import Path
-from typing import Dict, Any
+from typing import Dict, Any, List, Optional
 from abc import ABC
-from typing import List
 from puda_drivers.core import Position
 
 
 class StandardLabware(ABC):
     """
-    Generic Parent Class for all Labware on a microplate 
+    Generic Parent Class for all Labware on a microplate
     """
     def __init__(self, labware_name: str):
         """
@@ -64,7 +63,7 @@ class StandardLabware(ABC):
         
         with open(definition_path, "r", encoding="utf-8") as f:
             return json.load(f)
-        
+
     def __str__(self):
         """
         Return a string representation of the labware.
@@ -93,7 +92,7 @@ class StandardLabware(ABC):
             List of well identifiers (e.g., ["A1", "A2", "B1", ...])
         """
         return list(self._wells.keys())
-    
+
     def get_well_position(self, well_id: str) -> Position:
         """
         Get the position of a well from definition.json.
@@ -111,39 +110,65 @@ class StandardLabware(ABC):
         well_id_upper = well_id.upper()
         if well_id_upper not in self._wells:
             raise KeyError(f"Well '{well_id}' not found in tip rack definition")
-        
+
         # Get the well data from the definition
         well_data = self._wells.get(well_id_upper, {})
-        
+
         # Return position of the well (x, y are already center coordinates)
         return Position(
             x=well_data.get("x", 0.0),
             y=well_data.get("y", 0.0),
-            z=well_data.get("z", 0.0), 
+            z=well_data.get("z", 0.0),
         )
-        
-    def get_height(self) -> float:
+
+    def get_height(self, well_name: Optional[str] = None) -> float:
         """
         Get the height of the labware.
-        
+
+        Args:
+            well_name: Optional well name within the labware (e.g., "A1" for a well in a tiprack)
+                If not provided, the height of the labware is returned (zDimension).
         Returns:
-            Height of the labware (zDimension)
+            Height of the labware (zDimension) or the height of the well (z)
             
         Raises:
-            KeyError: If dimensions or zDimension is not found in the definition
+            KeyError: If dimensions or zDimension is not found in the definition, or if well_name is not found in the labware
         """
         dimensions = self._definition.get("dimensions")
         if dimensions is None:
             raise KeyError("'dimensions' not found in labware definition")
         
-        if "zDimension" not in dimensions:
-            raise KeyError("'zDimension' not found in labware dimensions")
-        
-        return dimensions["zDimension"]
-        
+        if well_name:
+            well_data = self._wells.get(well_name.upper(), {})
+            if well_data is None:
+                raise KeyError(f"Well '{well_name}' not found in labware definition")
+            return well_data.get("z")
+        else:
+            if "zDimension" not in dimensions:
+                raise KeyError("'zDimension' not found in labware dimensions")
+            return dimensions["zDimension"]
+
     def get_insert_depth(self) -> float:
         """
-        Get the insert depth of the labware.
+        Get the insert depth of the labware. This should be added to all labware definitions.
+        
+        insert_depth represents the maximum internal Z-axis clearance of the
+        labware. It is calculated as the absolute difference between the Top
+        Plane (the highest point of the well opening) and the Internal Floor
+        (the physical bottom of the well).
+        
+        Top of Labware (Z = 0 reference)
+              │      │
+        ┌─────┴──────┴─────┐  <─── Opening
+        │                  │
+        │      SPACE       │  }
+        │    AVAILABLE     │  }
+        │       FOR        │  }  insert_depth
+        │    INSERTION     │  }  (e.g., 40mm)
+        │                  │  }
+        └──────┬───────────┘
+               │
+        Bottom of Well (Limit)
         
         Returns:
             Insert depth of the labware

{puda_drivers-0.0.17 → puda_drivers-0.0.19}/src/puda_drivers/labware/polyelectric_8_wellplate_30000ul.json

@@ -1,4 +1,5 @@
 {
+    "insert_depth": 70,
     "ordering": [
         [
             "A1",
@@ -30,7 +31,7 @@
     "dimensions": {
         "xDimension": 128,
         "yDimension": 85.5,
-        "zDimension": 54
+        "zDimension": 74
     },
     "wells": {
         "A1": {

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

@@ -1,4 +1,5 @@
 {
+  "insert_depth": 0,
   "ordering": [
     ["A1"]
   ],
@@ -11,7 +12,7 @@
   "dimensions": {
     "xDimension": 127.76,
     "yDimension": 85.48,
-    "zDimension": 0
+    "zDimension": 10
   },
   "wells": {
     "A1": {

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

@@ -29,12 +29,7 @@ class First:
     
     # Default configuration values
     DEFAULT_QUBOT_PORT = "/dev/ttyACM0"
-    DEFAULT_QUBOT_BAUDRATE = 9600
-    DEFAULT_QUBOT_FEEDRATE = 3000
-    
     DEFAULT_SARTORIUS_PORT = "/dev/ttyUSB0"
-    DEFAULT_SARTORIUS_BAUDRATE = 9600
-    
     DEFAULT_CAMERA_INDEX = 0
     
     # origin position of Z and A axes
@@ -52,8 +47,11 @@ class First:
     # Height from z and a origin to the deck
     CEILING_HEIGHT = 192.2
     
-    # Tip length
-    TIP_LENGTH = 59
+    # Pipette Tip length
+    TIP_LENGTH = 59 # mm
+    
+    # Electrode length
+    ELECTRODE_LENGTH = 2 # mm
     
     # Slot origins (the bottom left corner of the slot relative to the deck origin)
     SLOT_ORIGINS = {
@@ -141,11 +139,23 @@ class First:
         self._logger.info("Homing gantry...")
         self.qubot.home()
         
-        # Initialize the pipette (all pipette operations need to wait 5 seconds for completion)
+        # Initialize the pipette
         self._logger.info("Initializing pipette...")
         self.pipette.initialize()
-        time.sleep(5)
+        time.sleep(3) # need to wait for the pipette to initialize
         self._logger.info("Machine startup complete - ready for operations")
+    
+    def home(self):
+        """
+        Home the qubot gantry to establish a known position.
+        
+        This method homes the gantry to its reference position, which is useful
+        for establishing a known starting point before operations or after
+        potential position drift.
+        """
+        self._logger.info("Homing qubot gantry...")
+        self.qubot.home()
+        self._logger.info("Qubot gantry homing complete")
         
     def shutdown(self):
         """
@@ -158,7 +168,19 @@ class First:
         self.pipette.disconnect()
         self.camera.disconnect()
         self._logger.info("Machine shutdown complete")
+    
+    def wait(self, seconds: float):
+        """
+        Wait for a specified number of seconds.
         
+        Args:
+            seconds: Number of seconds to wait (can be a float for fractional seconds)
+        """
+        self._logger.debug("Waiting for %.2f seconds", seconds)
+        time.sleep(seconds)
+        self._logger.debug("Waited for %.2f seconds", seconds)
+        
+    ### Queue (public commands) ###
     async def get_position(self) -> Dict[str, Union[Dict[str, float], int]]:
         """
         Get the current position of the machine. Both QuBot and Sartorius are queried.
@@ -175,56 +197,53 @@ class First:
             "qubot": qubot_position.to_dict(),
             "pipette": sartorius_position,
         }
-        
-    ### Labware management ###
-        
-    def load_labware(self, slot: str, labware_name: str):
+    
+    def get_deck(self):
         """
-        Load a labware object into a slot.
+        Get the current deck layout.
         
-        Args:
-            slot: Slot name (e.g., 'A1', 'B2')
-            labware_name: Name of the labware class to load
+        Returns:
+            Dictionary mapping deck slot names (e.g., "A1") to labware classes.
         
         Raises:
-            KeyError: If slot is not found in deck
+            None
         """
-        self._logger.info("Loading labware '%s' into slot '%s'", labware_name, slot)
-        self.deck.load_labware(slot=slot, labware_name=labware_name)
-        self._logger.debug("Labware '%s' loaded into slot '%s'", labware_name, slot)
-
-    def remove_labware(self, slot: str):
+        return self.deck.to_dict()
+        
+    def load_labware(self, deck_slot: str, labware_name: str):
         """
-        Remove labware from a slot.
+        Load a labware object into a deck slot.
         
         Args:
-            slot: Slot name (e.g., 'A1', 'B2')
+            deck_slot: Deck slot name (e.g., 'A1', 'B2')
+            labware_name: Name of the labware class to load
         
         Raises:
-            KeyError: If slot is not found in deck
+            KeyError: If deck_slot is not found in deck
         """
-        self.deck.empty_slot(slot=slot)
-        self._logger.debug("Slot '%s' emptied", slot)
-    
-    def get_deck(self):
+        self._logger.info("Loading labware '%s' into deck slot '%s'", labware_name, deck_slot)
+        self.deck.load_labware(slot=deck_slot, labware_name=labware_name)
+        self._logger.debug("Labware '%s' loaded into deck slot '%s'", labware_name, deck_slot)
+
+    def remove_labware(self, deck_slot: str):
         """
-        Get the current deck layout.
+        Remove labware from a deck slot.
         
-        Returns:
-            Dictionary mapping slot names (e.g., "A1") to labware classes.
+        Args:
+            deck_slot: Deck slot name (e.g., 'A1', 'B2')
         
         Raises:
-            None
+            KeyError: If deck_slot is not found in deck
         """
-        return self.deck.to_dict()
-
+        self.deck.empty_slot(slot=deck_slot)
+        self._logger.debug("Deck slot '%s' emptied", deck_slot)
         
     def load_deck(self, deck_layout: Dict[str, Type[StandardLabware]]):
         """
         Load multiple labware into the deck at once.
         
         Args:
-            deck_layout: Dictionary mapping slot names (e.g., "A1") to labware classes.
+            deck_layout: Dictionary mapping deck slot names (e.g., "A1") to labware classes.
                         Each class will be instantiated automatically.
         
         Example:
@@ -235,19 +254,18 @@ class First:
             })
         """
         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)
+        for deck_slot, labware_name in deck_layout.items():
+            self.load_labware(deck_slot=deck_slot, labware_name=labware_name)
         self._logger.info("Deck layout loaded successfully")
         
-    ### Liquid handling ###
-        
-    def attach_tip(self, slot: str, well: Optional[str] = None):
+    ### Pipette operations ###
+    def attach_tip(self, deck_slot: str, well_name: Optional[str] = None):
         """
-        Attach a tip from a slot.
+        Attach a tip from a deck slot.
 
         Args:
-            slot: Slot name (e.g., 'A1', 'B2')
-            well: Optional well name within the slot (e.g., 'A1' for a well in a tiprack)
+            deck_slot: Deck slot name (e.g., 'A1', 'B2')
+            well_name: Optional well name within the deck slot (e.g., 'A1' for a well in a tiprack)
         
         Note:
             This method is idempotent - if a tip is already attached, it will
@@ -257,21 +275,20 @@ class First:
             self._logger.warning("Tip already attached - skipping attachment (idempotent operation)")
             return
         
-        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.info("Attaching tip from deck slot '%s'%s", deck_slot, f", well '{well_name}'" if well_name else "")
+        pos = self._get_absolute_z_position(deck_slot, well_name)
         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)
-        labware = self.deck[slot]
+        labware = self.deck[deck_slot]
         if labware is None:
-            self._logger.error("Cannot attach tip: no labware loaded in slot '%s'", slot)
-            raise ValueError(f"No labware loaded in slot '{slot}'. Load labware before attaching tips.")
-        insert_depth = labware.get_insert_depth()
-        self._logger.debug("Moving down by %s mm to insert tip", insert_depth)
+            self._logger.error("Cannot attach tip: no labware loaded in deck slot '%s'", deck_slot)
+            raise ValueError(f"No labware loaded in deck slot '{deck_slot}'. Load labware before attaching tips.")
+        self._logger.debug("Moving down by %s mm to insert tip", labware.get_insert_depth())
         self.qubot.move_relative(
-            position=Position(z=-insert_depth),
+            position=Position(z=-labware.get_insert_depth()),
             feed=500
         )
         self.pipette.set_tip_attached(attached=True)
@@ -280,33 +297,33 @@ class First:
         self.qubot.home(axis="Z")
         self._logger.debug("Z axis homed after tip attachment")
         
-    def drop_tip(self, slot: str, well: str, height_from_bottom: float = 0.0):
+    def drop_tip(self, *, deck_slot: str, well_name: str, height_from_bottom: float = 0.0):
         """
-        Drop a tip into a slot.
+        Drop a tip into a deck slot.
         
         Args:
-            slot: Slot name (e.g., 'A1', 'B2')
-            well: Well name within the slot (e.g., 'A1' for a well in a tiprack)
+            deck_slot: Deck slot name (e.g., 'A1', 'B2')
+            well_name: Well name within the deck 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.
+                               Must be non-negative. Positive values move up from the bottom.
         
         Raises:
-            ValueError: If no tip is attached, or if the resulting position is outside
-                       the Z axis limits.
+            ValueError: If no tip is attached, if height_from_bottom is negative, or if
+                       the resulting position is outside the Z axis limits.
         """
+        if height_from_bottom < 0:
+            self._logger.error("height_from_bottom must be non-negative, got %f", height_from_bottom)
+            raise ValueError(f"height_from_bottom must be non-negative, got {height_from_bottom}")
+        
         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)
+        self._logger.info("Dropping tip into deck slot '%s', well '%s'", deck_slot, well_name)
+        pos = self._get_absolute_z_position(deck_slot, well_name)
         # 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)
+        self._logger.debug("Moving to position %s for tip drop", pos)
         self.qubot.move_absolute(position=pos)
 
         self._logger.debug("Ejecting tip")
@@ -315,157 +332,204 @@ 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, height_from_bottom: float = 0.0):
+    def aspirate_from(self, *, deck_slot: str, well_name: str, amount: int, height_from_bottom: float = 0.0):
         """
-        Aspirate a volume of liquid from a slot.
+        Aspirate a volume of liquid from a deck slot.
         
         Args:
-            slot: Slot name (e.g., 'A1', 'B2')
-            well: Well name within the slot (e.g., 'A1')
+            deck_slot: Deck slot name (e.g., 'A1', 'B2')
+            well_name: Well name within the deck 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.
+                               Must be non-negative. Positive values move up from the bottom.
         
         Raises:
-            ValueError: If no tip is attached, or if the resulting position is outside
-                       the Z axis limits.
+            ValueError: If no tip is attached, if height_from_bottom is negative, or if
+                       the resulting position is outside the Z axis limits.
         """
+        if height_from_bottom < 0:
+            self._logger.error("height_from_bottom must be non-negative, got %f", height_from_bottom)
+            raise ValueError(f"height_from_bottom must be non-negative, got {height_from_bottom}")
+        
         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)
+        self._logger.info("Aspirating %d µL from deck slot '%s', well '%s'", amount, deck_slot, well_name)
+
+        pos = self._get_absolute_z_position(deck_slot, well_name)
         # add height from bottom
         pos += Position(z=height_from_bottom)
+        # subtract insert depth to get the bottom of the well
+        pos -= Position(z=self.deck[deck_slot].get_insert_depth())
+
         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)
+        self._logger.info("Aspiration completed: %d µL from deck slot '%s', well '%s'", amount, deck_slot, well_name)
         
-    def dispense_to(self, slot:str, well:str, amount:int, height_from_bottom: float = 0.0):
+    def dispense_to(self, *, deck_slot: str, well_name: str, amount: int, height_from_bottom: float = 0.0):
         """
-        Dispense a volume of liquid to a slot.
+        Dispense a volume of liquid to a deck slot.
         
         Args:
-            slot: Slot name (e.g., 'A1', 'B2')
-            well: Well name within the slot (e.g., 'A1')
+            deck_slot: Deck slot name (e.g., 'A1', 'B2')
+            well_name: Well name within the deck 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.
+                               Must be non-negative. Positive values move up from the bottom.
         
         Raises:
-            ValueError: If no tip is attached, or if the resulting position is outside
-                       the Z axis limits.
+            ValueError: If no tip is attached, if height_from_bottom is negative, or if
+                       the resulting position is outside the Z axis limits.
         """
+        if height_from_bottom < 0:
+            self._logger.error("height_from_bottom must be non-negative, got %f", height_from_bottom)
+            raise ValueError(f"height_from_bottom must be non-negative, got {height_from_bottom}")
+        
         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)
+        self._logger.info("Dispensing %d µL to deck slot '%s', well '%s'", amount, deck_slot, well_name)
+
+        pos = self._get_absolute_z_position(deck_slot, well_name)
         # add height from bottom
         pos += Position(z=height_from_bottom)
+        # subtract insert depth to get the bottom of the well
+        pos -= Position(z=self.deck[deck_slot].get_insert_depth())
+
         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)
+        self._logger.info("Dispense completed: %d µL to deck slot '%s', well '%s'", amount, deck_slot, well_name)
         
-    def get_slot_origin(self, slot: str) -> Position:
+    # Electrode operations
+    def move_electrode(self, deck_slot: str, well_name: str, height_from_bottom: float = 0.0):
         """
-        Get the origin coordinates of a slot.
+        Move the electrode to a deck slot.
         
         Args:
-            slot: Slot name (e.g., 'A1', 'B2')
+            deck_slot: Deck slot name (e.g., 'A1', 'B2')
+            well_name: Well name within the deck slot (e.g., 'A1')
+            height_from_bottom: Height from the bottom of the well in mm. Defaults to 0.0.
+                               Must be non-negative. Positive values move up from the bottom.
+        
+        Raises:
+            ValueError: If height_from_bottom is negative.
+        """
+        if height_from_bottom < 0:
+            self._logger.error("height_from_bottom must be non-negative, got %f", height_from_bottom)
+            raise ValueError(f"height_from_bottom must be non-negative, got {height_from_bottom}")
+        
+        pos = self._get_absolute_a_position(deck_slot, well_name)
+        pos += Position(a=height_from_bottom)
+        self.qubot.move_absolute(position=pos)
+        self._logger.info("Electrode moved to deck slot '%s', well '%s' at height %s mm from bottom", deck_slot, well_name, height_from_bottom)
+        
+    # Helper methods
+    def _get_slot_origin(self, deck_slot: str) -> Position:
+        """
+        Get the origin coordinates of a deck slot.
+        
+        Args:
+            deck_slot: Deck slot name (e.g., 'A1', 'B2')
             
         Returns:
-            Position for the slot origin
+            Position for the deck slot origin
             
         Raises:
-            KeyError: If slot name is invalid
-        """
-        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())}")
-        pos = self.SLOT_ORIGINS[slot]
-        self._logger.debug("Slot origin for '%s': %s", slot, pos)
+            KeyError: If deck_slot name is invalid
+        """
+        deck_slot = deck_slot.upper()
+        if deck_slot not in self.SLOT_ORIGINS:
+            self._logger.error("Invalid deck slot name: '%s'. Must be one of %s", deck_slot, list(self.SLOT_ORIGINS.keys()))
+            raise KeyError(f"Invalid deck slot name: {deck_slot}. Must be one of {list(self.SLOT_ORIGINS.keys())}")
+        pos = self.SLOT_ORIGINS[deck_slot]
+        self._logger.debug("Deck slot origin for '%s': %s", deck_slot, pos)
         return pos
     
-    def get_absolute_z_position(self, slot: str, well: Optional[str] = None) -> Position:
+    def _get_absolute_z_position(self, deck_slot: str, well_name: Optional[str] = None) -> Position:
         """
-        Get the absolute position for a slot (and optionally a well within that slot) based on the origin
+        Get the absolute position for a deck slot (and optionally a well within that deck slot) based on the origin
         
         Args:
-            slot: Slot name (e.g., 'A1', 'B2')
-            well: Optional well name within the slot (e.g., 'A1' for a well in a tiprack)
+            deck_slot: Deck slot name (e.g., 'A1', 'B2')
+            well_name: Optional well name within the deck slot (e.g., 'A1' for a well in a tiprack)
             
         Returns:
             Position with absolute coordinates
             
         Raises:
-            ValueError: If well is specified but no labware is loaded in the slot
+            ValueError: If well_name is specified but no labware is loaded in the deck slot
         """
-        # Get slot origin
-        pos = self.get_slot_origin(slot)
+        # Get deck slot origin
+        pos = self._get_slot_origin(deck_slot)
 
-        # relative well position from slot origin
-        if well:
-            labware = self.deck[slot]
+        # relative well position from deck slot origin
+        if well_name:
+            labware = self.deck[deck_slot]
             if labware is None:
-                self._logger.error("Cannot get well position: no labware loaded in slot '%s'", slot)
-                raise ValueError(f"No labware loaded in slot '{slot}'. Load labware before accessing wells.")
-            well_pos = labware.get_well_position(well).get_xy()
+                self._logger.error("Cannot get well position: no labware loaded in deck slot '%s'", deck_slot)
+                raise ValueError(f"No labware loaded in deck slot '{deck_slot}'. Load labware before accessing wells.")
+            well_pos = labware.get_well_position(well_name).get_xy()
             # the deck is rotated 90 degrees clockwise for this machine
             pos += well_pos.swap_xy()
             # get z
             pos += Position(z=labware.get_height() - self.CEILING_HEIGHT)
-            self._logger.debug("Absolute Z position for slot '%s', well '%s': %s", slot, well, pos)
+            # if tip attached, add tip length
+            if self.pipette.is_tip_attached():
+                pos += Position(z=self.TIP_LENGTH)
+            self._logger.debug("Absolute Z position for deck slot '%s', well '%s': %s", deck_slot, well_name, pos)
         else:
-            self._logger.debug("Absolute Z position for slot '%s': %s", slot, pos)
+            self._logger.debug("Absolute Z position for deck slot '%s': %s", deck_slot, pos)
         return pos
     
-    def get_absolute_a_position(self, slot: str, well: Optional[str] = None) -> Position:
+    def _get_absolute_a_position(self, deck_slot: str, well_name: Optional[str] = None) -> Position:
         """
-        Get the absolute position for a slot (and optionally a well within that slot) based on the origin
+        Get the absolute position for a deck slot (and optionally a well within that deck slot) based on the origin
         
         Args:
-            slot: Slot name (e.g., 'A1', 'B2')
-            well: Optional well name within the slot (e.g., 'A1' for a well in a tiprack)
+            deck_slot: Deck slot name (e.g., 'A1', 'B2')
+            well_name: Optional well name within the deck slot (e.g., 'A1' for a well in a tiprack)
             
         Returns:
             Position with absolute coordinates
             
         Raises:
-            ValueError: If well is specified but no labware is loaded in the slot
+            ValueError: If well_name is specified but no labware is loaded in the deck slot
         """
-        pos = self.get_slot_origin(slot)
+        # get x and y
+        pos = self._get_slot_origin(deck_slot)
+        pos -= self.A_ORIGIN # subtract the origin to get the absolute position
         
-        if well:
-            labware = self.deck[slot]
-            if labware is None:
-                self._logger.error("Cannot get well position: no labware loaded in slot '%s'", slot)
-                raise ValueError(f"No labware loaded in slot '{slot}'. Load labware before accessing wells.")
-            well_pos = labware.get_well_position(well).get_xy()
+        # Get labware for a-axis positioning
+        labware = self.deck[deck_slot]
+        if labware is None:
+            self._logger.error("Cannot get electrode position: no labware loaded in deck slot '%s'", deck_slot)
+            raise ValueError(f"No labware loaded in deck slot '{deck_slot}'. Load labware before moving electrode.")
+        
+        # get x and y for well if specified
+        if well_name:
+            well_pos = labware.get_well_position(well_name).get_xy()
             pos += well_pos.swap_xy()
-            
-            # get a
-            a = Position(a=labware.get_height() - self.CEILING_HEIGHT)
-            pos += a
-            self._logger.debug("Absolute A position for slot '%s', well '%s': %s", slot, well, pos)
+        
+        # get a (applies to both with and without well_name)
+        pos += Position(a=labware.get_height() - self.CEILING_HEIGHT)
+        pos += Position(a=self.ELECTRODE_LENGTH)
+        
+        if well_name:
+            self._logger.debug("Absolute A position for deck slot '%s', well '%s': %s", deck_slot, well_name, pos)
         else:
-            self._logger.debug("Absolute A position for slot '%s': %s", slot, pos)
+            self._logger.debug("Absolute A position for deck slot '%s': %s", deck_slot, pos)
+        
         return pos
+
+   ### Camera operations ###
     
     def start_video_recording(
         self,
@@ -529,8 +593,8 @@ class First:
         )
     
     def capture_image(
-        self, 
-        save: bool = False, 
+        self,
+        save: bool = False,
         filename: Optional[Union[str, Path]] = None
     ) -> np.ndarray:
         """
@@ -548,4 +612,24 @@ class First:
         Raises:
             IOError: If camera is not connected or capture fails
         """
-        return self.camera.capture_image(save=save, filename=filename)
+        return self.camera.capture_image(save=save, filename=filename)
+    
+    ### Control (immediate commands) ###
+    
+    def pause(self):
+        """
+        Pause the execution of queued commands.
+        """
+        print("Pausing machine")
+    
+    def resume(self):
+        """
+        Resume the execution of queued commands.
+        """
+        print("Resuming machine")
+
+    def cancel(self):
+        """
+        Cancel the execution of queued commands.
+        """
+        print("Cancelling machine")

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

@@ -332,30 +332,21 @@ class GCodeController(SerialController):
             >>> pos = Position(x=10, y=20)
             >>> controller.move_absolute(position=pos)  # z and a use current values
         """
-        # Fill in missing axes with current positions
-        final_x = position.x if position.has_axis("x") else self._current_position.x
-        final_y = position.y if position.has_axis("y") else self._current_position.y
-        final_z = position.z if position.has_axis("z") else self._current_position.z
-        final_a = position.a if position.has_axis("a") else self._current_position.a
-
-        # Create final position for validation and execution
-        final_position = Position(x=final_x, y=final_y, z=final_z, a=final_a)
-        
         # Validate positions before executing move
-        self._validate_move_positions(position=final_position)
+        self._validate_move_positions(position=position)
 
         feed_rate = feed if feed is not None else self._feed
         self._logger.info(
             "Preparing absolute move to X:%s, Y:%s, Z:%s, A:%s at F:%s",
-            final_x,
-            final_y,
-            final_z,
-            final_a,
+            position.x,
+            position.y,
+            position.z,
+            position.a,
             feed_rate,
         )
 
         return self._execute_move(
-            position=final_position,
+            position=position,
             feed=feed_rate
         )
 
@@ -429,9 +420,9 @@ class GCodeController(SerialController):
         All coordinates are treated as absolute positions.
 
         Safe move pattern:
-        1. If X or Y movement is needed, first move Z to 0 (safe height)
+        1. If X or Y movement is needed, first move Z and A to safe height
         2. Then move X, Y to target
-        3. Finally move Z and A back to original position (or target if specified)
+        3. Finally move Z or A to target (only the one that needs to move, the other stays where it is)
 
         Args:
             position: Position with absolute positions for X, Y, Z, A axes
@@ -440,8 +431,8 @@ class GCodeController(SerialController):
         # Check if any movement is needed
         needs_x_move = abs(position.x - self._current_position.x) > self.TOLERANCE
         needs_y_move = abs(position.y - self._current_position.y) > self.TOLERANCE
-        needs_z_move = abs(position.z - self._current_position.z) > self.TOLERANCE
-        needs_a_move = abs(position.a - self._current_position.a) > self.TOLERANCE
+        needs_z_move = abs(position.z - 0) > self.TOLERANCE
+        needs_a_move = abs(position.a - 0) > self.TOLERANCE
         
         if not (needs_x_move or needs_y_move or needs_z_move or needs_a_move):
             self._logger.warning(
@@ -450,7 +441,7 @@ class GCodeController(SerialController):
             return
         
         if needs_z_move and needs_a_move:
-            self._logger.warning(
+            self._logger.error(
                 "Move command issued with both Z and A movement. This is not supported. Skipping transmission."
             )
             raise ValueError("Move command issued with both Z and A movement. This is not supported.")
@@ -463,7 +454,7 @@ class GCodeController(SerialController):
             self._logger.debug(
                 "Safe move: Raising Z and A to safe height (%s) before XY movement", self.SAFE_MOVE_HEIGHT
             )
-            move_cmd = f"G1 Z-5 A-5 F{self._z_feed}"
+            move_cmd = f"G1 Z{self.SAFE_MOVE_HEIGHT} A{self.SAFE_MOVE_HEIGHT} F{self._z_feed}"
             self.execute(move_cmd)
             self._wait_for_move()
             self._current_position.z = self.SAFE_MOVE_HEIGHT
@@ -493,13 +484,13 @@ class GCodeController(SerialController):
             if needs_y_move:
                 self._current_position.y = position.y
 
-        # Step 3: Move Z and A back to original position (or target if specified)
+        # Step 3: Move Z or A to target (only the one that needs to move)
         if needs_z_move:
             move_cmd = f"G1 Z{position.z} F{self._z_feed}"
             self.execute(move_cmd)
             self._wait_for_move()
             self._current_position.z = position.z
-        elif needs_a_move:
+        if needs_a_move:
             move_cmd = f"G1 A{position.a} F{self._z_feed}"
             self.execute(move_cmd)
             self._wait_for_move()

{puda_drivers-0.0.17 → puda_drivers-0.0.19}/tests/first.py

@@ -37,6 +37,9 @@ if __name__ == "__main__":
 
     machine.startup()  # Connects all controllers, homes gantry, and initializes pipette
     
+    machine.get_absolute_a_position(slot="A3", well="A1")
+    # machine.move_electrode(slot="A3", well="A1", height_from_bottom=0)
+    
     # machine.record_video(duration_seconds=10, filename="test.mp4")
     machine.start_video_recording()
     machine.attach_tip(slot="A3", well="G8")