opentrons 8.6.0a1__py3-none-any.whl

opentrons/hardware_control/protocols/gripper_controller.py

@@ -0,0 +1,55 @@
+"""Protocol specifying API gripper control."""
+from typing import Optional
+from typing_extensions import Protocol
+
+from opentrons.hardware_control.dev_types import GripperDict
+from opentrons.hardware_control.instruments.ot3.gripper import Gripper
+
+
+class GripperController(Protocol):
+    """A protocol specifying gripper API functions."""
+
+    async def grip(
+        self, force_newtons: Optional[float] = None, stay_engaged: bool = True
+    ) -> None:
+        ...
+
+    async def home_gripper_jaw(self, recalibrate_jaw_width: bool = False) -> None:
+        ...
+
+    async def ungrip(self, force_newtons: Optional[float] = None) -> None:
+        """Release gripped object.
+
+        To simply open the jaw, use `home_gripper_jaw` instead.
+        """
+        ...
+
+    async def idle_gripper(self) -> None:
+        """Move gripper to its idle, gripped position."""
+        ...
+
+    def gripper_jaw_can_home(self) -> bool:
+        """Check if it is valid to home the gripper jaw.
+
+        This should return False if the API believes that the gripper is
+        currently holding something.
+        """
+        ...
+
+    def raise_error_if_gripper_pickup_failed(
+        self,
+        expected_grip_width: float,
+        grip_width_uncertainty_wider: float,
+        grip_width_uncertainty_narrower: float,
+    ) -> None:
+        """Ensure that a gripper pickup succeeded."""
+
+    @property
+    def attached_gripper(self) -> Optional[GripperDict]:
+        """Get a dict of all attached grippers."""
+        ...
+
+    @property
+    def hardware_gripper(self) -> Optional[Gripper]:
+        """Get attached gripper, if present."""
+        ...

opentrons/hardware_control/protocols/hardware_manager.py

@@ -0,0 +1,51 @@
+from typing import Dict, Optional
+from typing_extensions import Protocol
+
+from ..types import SubSystem, SubSystemState, Axis
+
+
+class HardwareManager(Protocol):
+    """Protocol specifying access to configuration plane elements of hardware."""
+
+    def get_fw_version(self) -> str:
+        """
+        Return the firmware version of the connected hardware.
+        """
+        ...
+
+    @property
+    def fw_version(self) -> str:
+        """
+        Return the firmware version of the connected hardware.
+
+        The version is a string retrieved directly from the attached hardware
+        (or possibly simulator).
+        """
+        ...
+
+    @property
+    def board_revision(self) -> str:
+        """
+        Return the revision of the central hardware.
+        """
+        ...
+
+    @property
+    def attached_subsystems(self) -> Dict[SubSystem, SubSystemState]:
+        """
+        Get a view of the hardware subsystems currently attached to the machine.
+
+        These subsystems are the programmable parts that underly and provide things like motion
+        control and instruments. Depending on the machine, different subsystems may be available.
+        In general, callers should not use the presence or absence of a specific subsystem to decide
+        whether or not the hardware is operating properly.
+        """
+        ...
+
+    async def get_serial_number(self) -> Optional[str]:
+        """Get the robot serial number, if provisioned. If not provisioned, will be None."""
+        ...
+
+    def axis_is_present(self, axis: Axis) -> bool:
+        """Get whether a motor axis is present on the machine."""
+        ...

opentrons/hardware_control/protocols/identifiable.py

@@ -0,0 +1,16 @@
+from typing_extensions import Protocol
+
+from .types import ProtocolRobotType
+
+
+class Identifiable(Protocol[ProtocolRobotType]):
+    """Protocol specifying support for hardware identification."""
+
+    def get_robot_type(self) -> ProtocolRobotType:
+        """Return the enumerated robot type that this API controls.
+
+        When a caller needs to determine whether an API function is expected
+        to be present on a hardware_control instance, it is preferable to check
+        with this function rather than check the exact type via `isinstance`.
+        """
+        ...

opentrons/hardware_control/protocols/instrument_configurer.py

@@ -0,0 +1,206 @@
+from typing import Dict, Optional
+from typing_extensions import Protocol
+
+from opentrons_shared_data.pipette.types import PipetteName
+from opentrons.types import Mount
+from .types import MountArgType
+
+# TODO (lc 12-05-2022) This protocol has deviated from the OT3 api. We
+# need to figure out how to combine them again in follow-up refactors.
+from opentrons.hardware_control.instruments.ot2.pipette import Pipette
+from ..dev_types import PipetteDict
+from ..types import CriticalPoint
+
+
+class InstrumentConfigurer(Protocol[MountArgType]):
+    """A protocol specifying how to interact with instrument presence and detection."""
+
+    def reset_instrument(self, mount: Optional[MountArgType] = None) -> None:
+        """
+        Reset the internal state of a pipette by its mount, without doing
+        any lower level reconfiguration. This is useful to make sure that no
+        settings changes from a protocol persist.
+
+        mount: If specified, reset that mount. If not specified, reset both
+        """
+        ...
+
+    async def cache_instruments(
+        self,
+        require: Optional[Dict[Mount, PipetteName]] = None,
+        skip_if_would_block: bool = False,
+    ) -> None:
+        """
+        Scan the attached instruments, take necessary configuration actions,
+        and set up hardware controller internal state if necessary.
+
+        require: If specified, the require should be a dict of mounts to
+                 instrument names describing the instruments expected to be
+                 present. This can save a subsequent call of attached_instruments
+                 and also serves as the hook for the hardware simulator to decide
+                 what is attached.
+        raises RuntimeError: If an instrument is expected but not found.
+
+        This function will only change the things that need to be changed.
+        If the same pipette (by serial) or the same lack of pipette is
+        observed on a mount before and after the scan, no action will be
+        taken. That makes this function appropriate for setting up the
+        robot for operation, but not for making sure that any previous
+        settings changes have been reset. For the latter use case, use
+        reset_instrument.
+        """
+        ...
+
+    def get_attached_instruments(self) -> Dict[Mount, PipetteDict]:
+        """Get the status dicts of the cached attached instruments.
+
+        Also available as :py:meth:`get_attached_instruments`.
+
+        This returns a dictified version of the
+        hardware_control.instruments.pipette.Pipette as a dict keyed by
+        the Mount to which the pipette is attached.
+        If no pipette is attached on a given mount, the mount key will
+        still be present but will have the value ``None``.
+
+        Note that on the OT-2 this is only a query of a cached value;
+        to actively scan for changes, use cache_instruments`. This process
+        deactivates the OT-2's motors and should be used sparingly.
+        """
+        ...
+
+    def get_attached_instrument(self, mount: MountArgType) -> PipetteDict:
+        """Get the status dict of a single cached instrument.
+
+        Return values and caveats are as get_attached_instruments.
+        """
+        ...
+
+    @property
+    def attached_instruments(self) -> Dict[Mount, PipetteDict]:
+        return self.get_attached_instruments()
+
+    def get_attached_pipettes(self) -> Dict[Mount, PipetteDict]:
+        """Get the status dicts of cached attached pipettes.
+
+        Works like get_attached_instruments but for pipettes only - on the Flex,
+        there will be no gripper information here.
+        """
+        ...
+
+    @property
+    def attached_pipettes(self) -> Dict[Mount, PipetteDict]:
+        return self.get_attached_pipettes()
+
+    def calibrate_plunger(
+        self,
+        mount: MountArgType,
+        top: Optional[float] = None,
+        bottom: Optional[float] = None,
+        blow_out: Optional[float] = None,
+        drop_tip: Optional[float] = None,
+    ) -> None:
+        """
+        Set calibration values for the pipette plunger.
+        This can be called multiple times as the user sets each value,
+        or you can set them all at once.
+        :param top: Touching but not engaging the plunger.
+        :param bottom: Must be above the pipette's physical hard-stop, while
+        still leaving enough room for 'blow_out'
+        :param blow_out: Plunger is pushed down enough to expel all liquids.
+        :param drop_tip: Position that causes the tip to be released from the
+        pipette
+        """
+        ...
+
+    def set_flow_rate(
+        self,
+        mount: MountArgType,
+        aspirate: Optional[float] = None,
+        dispense: Optional[float] = None,
+        blow_out: Optional[float] = None,
+    ) -> None:
+        """Set a pipette's rate of liquid handling in flow rate units"""
+        ...
+
+    def set_pipette_speed(
+        self,
+        mount: MountArgType,
+        aspirate: Optional[float] = None,
+        dispense: Optional[float] = None,
+        blow_out: Optional[float] = None,
+    ) -> None:
+        """Set a pipette's rate of liquid handling in linear speed units."""
+        ...
+
+    def get_instrument_max_height(
+        self,
+        mount: MountArgType,
+        critical_point: Optional[CriticalPoint] = None,
+    ) -> float:
+        """Return max achievable height of the attached instrument
+        based on the current critical point
+        """
+        ...
+
+    # todo(mm, 2024-10-17): Consider deleting this in favor of cache_tip()
+    # if we can do so without breaking anything.
+    def add_tip(self, mount: MountArgType, tip_length: float) -> None:
+        """Inform the hardware that a tip is now attached to a pipette.
+
+        If a tip is already attached, this no-ops.
+
+        This changes the critical point of the pipette to make sure that
+        the end of the tip is what moves around, and allows liquid handling.
+        """
+        ...
+
+    def cache_tip(self, mount: MountArgType, tip_length: float) -> None:
+        """Inform the hardware that a tip is now attached to a pipette.
+
+        This is like `add_tip()`, except that if a tip is already attached,
+        this replaces it instead of no-opping.
+        """
+        ...
+
+    def remove_tip(self, mount: MountArgType) -> None:
+        """Inform the hardware that a tip is no longer attached to a pipette.
+
+        This changes the critical point of the system to the end of the
+        nozzle and prevents further liquid handling commands.
+        """
+        ...
+
+    def set_current_tiprack_diameter(
+        self, mount: MountArgType, tiprack_diameter: float
+    ) -> None:
+        """Inform the hardware of the diameter of the tiprack.
+
+        This drives the magnitude of the shake commanded for pipettes that need
+        a shake after dropping or picking up tips.
+        """
+        ...
+
+    def set_working_volume(self, mount: MountArgType, tip_volume: float) -> None:
+        """Inform the hardware how much volume a pipette can aspirate.
+
+        This will set the limit of aspiration for the pipette, and is
+        necessary for backcompatibility.
+        """
+        ...
+
+    @property
+    def hardware_instruments(self) -> Dict[Mount, Optional[Pipette]]:
+        """Return the underlying hardware representation of the instruments.
+
+        This should rarely be used. Do not write new code that uses it.
+        """
+        ...
+
+    def has_gripper(self) -> bool:
+        """Return whether there is a gripper attached to this instance.
+
+         - On robots that do not support a gripper, this will always return False.
+         - On robots that support a gripper, this will return based on the current
+        presence of a gripper.
+        """
+        ...

opentrons/hardware_control/protocols/liquid_handler.py

@@ -0,0 +1,266 @@
+from typing import Optional
+from typing_extensions import Protocol
+
+from opentrons.types import Point
+from opentrons.hardware_control.types import CriticalPoint, TipScrapeType
+from .types import MountArgType, CalibrationType, ConfigType
+
+from .instrument_configurer import InstrumentConfigurer
+from .motion_controller import MotionController
+from .configurable import Configurable
+from .calibratable import Calibratable
+
+
+class LiquidHandler(
+    InstrumentConfigurer[MountArgType],
+    MotionController[MountArgType],
+    Configurable[ConfigType],
+    Calibratable[CalibrationType],
+    Protocol[CalibrationType, MountArgType, ConfigType],
+):
+    def critical_point_for(
+        self,
+        mount: MountArgType,
+        cp_override: Optional[CriticalPoint] = None,
+    ) -> Point:
+        """
+        Determine the current critical point for the specified mount.
+
+        :param mount: A robot mount that the instrument is on.
+        :param cp_override: The critical point override to use.
+
+        If no critical point override is specified, the robot defaults to nozzle location `A1` or the mount critical point.
+        :return: Point.
+        """
+        ...
+
+    async def update_nozzle_configuration_for_mount(
+        self,
+        mount: MountArgType,
+        back_left_nozzle: Optional[str],
+        front_right_nozzle: Optional[str],
+        starting_nozzle: Optional[str] = None,
+    ) -> None:
+        """
+        The expectation of this function is that the back_left_nozzle/front_right_nozzle are the two corners
+        of a rectangle of nozzles. A call to this function that does not follow that schema will result
+        in an error.
+
+        :param mount: A robot mount that the instrument is on.
+        :param back_left_nozzle: A string representing a nozzle name of the form <LETTER><NUMBER> such as 'A1'.
+        :param front_right_nozzle: A string representing a nozzle name of the form <LETTER><NUMBER> such as 'A1'.
+        :param starting_nozzle: A string representing the starting nozzle which will be used as the critical point
+        of the pipette nozzle configuration. By default, the back left nozzle will be the starting nozzle if
+        none is provided.
+
+        If none of the nozzle parameters are provided, the nozzle configuration will be reset to default.
+        :return: None.
+        """
+        ...
+
+    async def configure_for_volume(self, mount: MountArgType, volume: float) -> None:
+        """
+        Configure a pipette to handle the specified volume.
+
+        Some pipettes need to switch modes to handle different volumes of liquid. Calling
+        this ensures they do so. If the pipette does not need to switch modes, or the pipette
+        is already in the specified mode, nothing will happen.
+
+        If the pipette does need to switch modes, it will likely be unready for aspiration and
+        you will need to call :py:meth:`prepare_for_aspirate` afterwards.
+        """
+        ...
+
+    async def prepare_for_aspirate(
+        self, mount: MountArgType, rate: float = 1.0
+    ) -> None:
+        """
+        Prepare the pipette for aspiration.
+
+        This must happen after every :py:meth:`blow_out` and should probably be
+        called before every :py:meth:`aspirate`, while the pipette tip is not
+        immersed in a well. It ensures that the plunger is at the 0-volume
+        position of the pipette if necessary (if not necessary, it does
+        nothing).
+
+        If :py:meth:`aspirate` is called immediately after :py:meth:`blow_out`,
+        the plunger is left at the ``blow_out`` position, below the ``bottom``
+        position, and moving the plunger up during :py:meth:`aspirate` is
+        expected to aspirate liquid - :py:meth:`aspirate` is called once the
+        pipette tip is already in the well. This will cause a subtle over
+        aspiration. To make the problem more obvious, :py:meth:`aspirate` will
+        raise an exception if this method has not previously been called.
+        """
+        ...
+
+    async def aspirate(
+        self,
+        mount: MountArgType,
+        volume: Optional[float] = None,
+        rate: float = 1.0,
+        correction_volume: float = 0.0,
+    ) -> None:
+        """
+        Aspirate a volume of liquid (in microliters/uL) using this pipette
+        from the *current location*. If no volume is passed, `aspirate` will
+        default to max available volume (after taking into account the volume
+        already present in the tip).
+
+        The function :py:meth:`prepare_for_aspirate` must be called prior to
+        calling this function, while the tip is above the well. This ensures
+        that the pipette tip is in the proper position at the bottom of the
+        pipette to begin aspiration, and prevents subtle over-aspiration if
+        an aspirate is done immediately after :py:meth:`blow_out`. If
+        :py:meth:`prepare_for_aspirate` has not been called since the last
+        call to :py:meth:`aspirate`, an exception will be raised.
+
+        mount : Mount.LEFT or Mount.RIGHT
+        volume : [float] The number of microliters to aspirate
+        rate : [float] Set plunger speed for this aspirate, where
+            speed = rate * aspirate_speed
+        correction_volume : Correction volume in uL for the specified aspirate volume
+        """
+        ...
+
+    async def aspirate_while_tracking(
+        self,
+        mount: MountArgType,
+        z_distance: float,
+        volume: float,
+        flow_rate: float = 1.0,
+    ) -> None:
+        """
+        Aspirate a volume of liquid (in microliters/uL) while moving the z axis synchronously.
+
+        :param mount: A robot mount that the instrument is on.
+        :param z_distance: The distance the z axis will move during apsiration.
+        :param volume: The volume of liquid to be aspirated.
+        :param flow_rate: The flow rate to aspirate with.
+        """
+        ...
+
+    async def dispense(
+        self,
+        mount: MountArgType,
+        volume: Optional[float] = None,
+        rate: float = 1.0,
+        push_out: Optional[float] = None,
+        correction_volume: float = 0.0,
+        is_full_dispense: bool = False,
+    ) -> None:
+        """
+        Dispense a volume of liquid in microliters(uL) using this pipette
+        at the current location. If no volume is specified, `dispense` will
+        dispense all volume currently present in pipette
+
+        mount : Mount.LEFT or Mount.RIGHT
+        volume : [float] The number of microliters to dispense
+        rate : [float] Set plunger speed for this dispense, where
+            speed = rate * dispense_speed
+        correction_volume : Correction volume in uL for the specified dispense volume
+        """
+        ...
+
+    async def dispense_while_tracking(
+        self,
+        mount: MountArgType,
+        z_distance: float,
+        volume: float,
+        push_out: Optional[float],
+        flow_rate: float = 1.0,
+        is_full_dispense: bool = False,
+    ) -> None:
+        """
+        Dispense a volume of liquid (in microliters/uL) while moving the z axis synchronously.
+
+        :param mount: A robot mount that the instrument is on.
+        :param z_distance: The distance the z axis will move during dispensing.
+        :param volume: The volume of liquid to be dispensed.
+        :param flow_rate: The flow rate to dispense with.
+        """
+        ...
+
+    async def blow_out(
+        self, mount: MountArgType, volume: Optional[float] = None
+    ) -> None:
+        """
+        Force any remaining liquid to dispense. The liquid will be dispensed at
+        the current location of pipette
+        """
+        ...
+
+    async def tip_pickup_moves(
+        self,
+        mount: MountArgType,
+        presses: Optional[int] = None,
+        increment: Optional[float] = None,
+    ) -> None:
+        ...
+
+    async def pick_up_tip(
+        self,
+        mount: MountArgType,
+        tip_length: float,
+        presses: Optional[int] = None,
+        increment: Optional[float] = None,
+        prep_after: bool = True,
+    ) -> None:
+        """
+        Pick up tip from current location.
+
+        This is achieved by attempting to move the instrument down by its
+        `pick_up_distance`, in a series of presses. This distance is larger
+        than the space available in the tip, so the stepper motor will
+        eventually skip steps, which is resolved by homing afterwards. The
+        pick up operation is done at a current specified in the pipette config,
+        which is experimentally determined to skip steps at a level of force
+        sufficient to provide a good seal between the pipette nozzle and tip
+        while also avoiding attaching the tip so firmly that it can't be
+        dropped later.
+
+        If ``presses`` or ``increment`` is not specified (or is ``None``),
+        their value is taken from the pipette configuration.
+        """
+        ...
+
+    async def tip_drop_moves(
+        self,
+        mount: MountArgType,
+        home_after: bool = True,
+        ignore_plunger: bool = False,
+        scrape_type: TipScrapeType = TipScrapeType.NONE,
+    ) -> None:
+        ...
+
+    async def drop_tip(
+        self,
+        mount: MountArgType,
+        home_after: bool = True,
+    ) -> None:
+        """
+        Drop tip at the current location
+
+        :param Mount mount: The mount to drop a tip from
+        :param bool home_after: Home the plunger motor after dropping tip. This
+                                is used in case the plunger motor skipped while
+                                dropping the tip, and is also used to recover
+                                the ejector shroud after a drop.
+        """
+        ...
+
+    async def liquid_probe(
+        self,
+        mount: MountArgType,
+        max_z_dist: float,
+    ) -> float:
+        """Search for and return liquid level height using this pipette
+        at the current location.
+
+        mount : Mount.LEFT or Mount.RIGHT
+        max_z_dist : maximum depth to probe for liquid
+        """
+        ...
+
+    async def increase_evo_disp_count(self, mount: MountArgType) -> None:
+        """Tell a pipette to increase it's evo-tip-dispense-count in eeprom."""
+        ...

opentrons/hardware_control/protocols/module_provider.py

@@ -0,0 +1,16 @@
+from typing import List
+from typing_extensions import Protocol
+
+from ..modules import AbstractModule, ModuleModel
+
+
+class ModuleProvider(Protocol):
+    """A protocol specifying access to modules."""
+
+    @property
+    def attached_modules(self) -> List[AbstractModule]:
+        """Return a list of currently-attached modules."""
+        ...
+
+    async def create_simulating_module(self, model: ModuleModel) -> AbstractModule:
+        """Create a simulating module hardware interface."""