opentrons 8.7.0a1__py3-none-any.whl → 8.7.0a2__py3-none-any.whl

opentrons/protocol_api/core/protocol.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from abc import abstractmethod, ABC
-from typing import Generic, List, Optional, Union, Tuple, Dict, TYPE_CHECKING
+from typing import Generic, List, Optional, Union, Tuple, Dict, TYPE_CHECKING, Sequence
 
 from opentrons_shared_data.deck.types import DeckDefinitionV5, SlotDefV3
 from opentrons_shared_data.pipette.types import PipetteNameType
@@ -24,6 +24,7 @@ from opentrons.protocols.api_support.util import AxisMaxSpeeds
 from .instrument import InstrumentCoreType
 from .labware import LabwareCoreType, LabwareLoadParams
 from .module import ModuleCoreType
+from .tasks import TaskCoreType
 from .._liquid import Liquid, LiquidClass
 from .robot import AbstractRobot
 from .._types import OffDeckType
@@ -34,7 +35,7 @@ if TYPE_CHECKING:
 
 
 class AbstractProtocol(
-    ABC, Generic[InstrumentCoreType, LabwareCoreType, ModuleCoreType]
+    ABC, Generic[InstrumentCoreType, LabwareCoreType, ModuleCoreType, TaskCoreType]
 ):
     @property
     @abstractmethod
@@ -192,6 +193,14 @@ class AbstractProtocol(
     def delay(self, seconds: float, msg: Optional[str]) -> None:
         ...
 
+    @abstractmethod
+    def wait_for_tasks(self, task_cores: Sequence[TaskCoreType]) -> None:
+        ...
+
+    @abstractmethod
+    def create_timer(self, seconds: float) -> TaskCoreType:
+        ...
+
     @abstractmethod
     def home(self) -> None:
         ...

opentrons/protocol_api/core/tasks.py

@@ -0,0 +1,31 @@
+from abc import abstractmethod, ABC
+from datetime import datetime
+from typing import TypeVar
+
+
+class AbstractTaskCore(ABC):
+    @abstractmethod
+    def get_created_at_timestamp(self) -> datetime:
+        """Get the createdAt timestamp of the task."""
+        ...
+
+    @abstractmethod
+    def is_done(self) -> bool:
+        """Returns ``True`` if the task is done."""
+        ...
+
+    @abstractmethod
+    def is_started(self) -> bool:
+        """Returns ``True`` if the task has started."""
+        ...
+
+    @abstractmethod
+    def get_finished_at_timestamp(self) -> datetime | None:
+        """The timestamp of the when the task finished.
+
+        Returns ``None`` if the task hasn't finished yet.
+        """
+        ...
+
+
+TaskCoreType = TypeVar("TaskCoreType", bound=AbstractTaskCore)

opentrons/protocol_api/module_contexts.py

@@ -686,6 +686,7 @@ class ThermocyclerContext(ModuleContext):
             celsius=temperature,
             hold_time_seconds=seconds,
             block_max_volume=block_max_volume,
+            ramp_rate=ramp_rate,
         )
         self._core.wait_for_block_temperature()
 

opentrons/protocol_api/protocol_context.py

@@ -89,6 +89,7 @@ from .module_contexts import (
     FlexStackerContext,
     ModuleContext,
 )
+from .tasks import Task
 from ._parameters import Parameters
 
 
@@ -234,10 +235,7 @@ class ProtocolContext(CommandPublisher):
     @property
     @requires_version(2, 22)
     def robot(self) -> RobotContext:
-        """The :py:class:`.RobotContext` for the protocol.
-
-        :meta private:
-        """
+        """The :py:class:`.RobotContext` for the protocol."""
         if self._core.robot_type != "OT-3 Standard" or not self._robot:
             raise RobotTypeError("The RobotContext is only available on Flex robots.")
         return self._robot
@@ -1289,6 +1287,30 @@ class ProtocolContext(CommandPublisher):
         delay_time = seconds + minutes * 60
         self._core.delay(seconds=delay_time, msg=msg)
 
+    @publish(command=cmds.wait_for_tasks)
+    @requires_version(2, 27)
+    def wait_for_tasks(self, tasks: list[Task]) -> None:
+        """Wait for a list of tasks to complete before executing subsequent commands.
+
+        :param list Task: tasks: A list of Task objects to wait for.
+
+        Task objects can be commands that are allowed to run concurrently.
+        """
+        task_cores = [task._core for task in tasks]
+        self._core.wait_for_tasks(task_cores)
+
+    @publish(command=cmds.create_timer)
+    @requires_version(2, 27)
+    def create_timer(self, seconds: float) -> Task:
+        """Create a timer task that runs in the background.
+
+        :param float seconds: The time to delay in seconds.
+
+        This timer will continue to run until it is complete and will not block subsequent commands.
+        """
+        task_core = self._core.create_timer(seconds=seconds)
+        return Task(core=task_core, api_version=self._api_version)
+
     @requires_version(2, 0)
     def home(self) -> None:
         """Home the movement system of the robot."""

opentrons/protocol_api/robot_context.py

@@ -46,7 +46,7 @@ class RobotContext(publisher.CommandPublisher):
     Objects in this class should not be instantiated directly. Instead, instances are
     returned by :py:meth:`ProtocolContext.robot`.
 
-    .. versionadded:: 2.20
+    .. versionadded:: 2.22
 
     """
 
@@ -83,15 +83,19 @@ class RobotContext(publisher.CommandPublisher):
         speed: Optional[float] = None,
     ) -> None:
         """
-        Move a specified mount to a destination location on the deck.
+        Move a specified mount to a location on the deck.
 
         :param mount: The mount of the instrument you wish to move.
                       This can either be an instance of :py:class:`.types.Mount` or one
                       of the strings ``"left"``, ``"right"``, ``"extension"``, ``"gripper"``. Note
                       that the gripper mount can be referred to either as ``"extension"`` or ``"gripper"``.
         :type mount: types.Mount or str
-        :param Location destination:
-        :param speed:
+        :param destination: Any location on the deck, specified as:
+
+              -  a slot, like ``"A1"``
+              -  a defined location, like labware in a deck slot
+              -  an absolute location, like a point {x=10 , y=10, z=10} or a deck location and point ("A1" + point {x=10 , y=10, z=10})
+        :param speed: The absolute speed in mm/s.
         """
         mount = validation.ensure_instrument_mount(mount)
         with publisher.publish_context(
@@ -116,10 +120,9 @@ class RobotContext(publisher.CommandPublisher):
         Move a set of axes to an absolute position on the deck.
 
         :param axis_map: A dictionary mapping axes to an absolute position on the deck in mm.
-        :param critical_point: The critical point to move the axes with. It should only
-        specify the gantry axes (i.e. `x`, `y`, `z`).
-        :param float speed: The maximum speed with which you want to move all the axes
-        in the axis map.
+        :param critical_point: The critical point, or specific point on the object being moved, to move the axes with. It should only specify the gantry axes (i.e. `x`, `y`, `z`). When you specify a critical point, you're specifying the object on the gantry to be moved. If not specified, the critical point defaults to the center of the carriage attached to the gantry.
+        :param float speed: The maximum speed with which to move all axes in mm/s.
+
         """
         instrument_on_left = self._core.get_pipette_type_from_engine(Mount.LEFT)
         is_96_channel = instrument_on_left == PipetteNameType.P1000_96
@@ -154,11 +157,9 @@ class RobotContext(publisher.CommandPublisher):
         """
         Move a set of axes to a relative position on the deck.
 
-        :param axis_map: A dictionary mapping axes to relative movements in mm.
-        :type mount: types.Mount or str
+        :param axis_map: A dictionary mapping axes to relative movements from the current position in mm.
 
-        :param float speed: The maximum speed with which you want to move all the axes
-        in the axis map.
+        :param float speed: The maximum speed with which to move all axes in mm/s.
         """
         instrument_on_left = self._core.get_pipette_type_from_engine(Mount.LEFT)
         is_96_channel = instrument_on_left == PipetteNameType.P1000_96
@@ -177,7 +178,10 @@ class RobotContext(publisher.CommandPublisher):
             self._core.move_axes_relative(axis_map, speed)
 
     def close_gripper_jaw(self, force: Optional[float] = None) -> None:
-        """Command the gripper closed with some force."""
+        """Closes the Flex Gripper jaws with a specified force.
+
+        :param force: Force with which to close the gripper jaws in newtons.
+        """
         with publisher.publish_context(
             broker=self.broker,
             command=cmds.close_gripper(
@@ -187,7 +191,10 @@ class RobotContext(publisher.CommandPublisher):
             self._core.close_gripper(force)
 
     def open_gripper_jaw(self) -> None:
-        """Command the gripper open."""
+        """Opens the Flex Gripper jaws with a specified force.
+
+        :param force: Force with which to open the gripper jaws in newtons.
+        """
         with publisher.publish_context(
             broker=self.broker,
             command=cmds.open_gripper(),
@@ -200,9 +207,9 @@ class RobotContext(publisher.CommandPublisher):
         location: Union[Location, ModuleContext, DeckLocation],
     ) -> AxisMapType:
         """
-        Build a :py:class:`.types.AxisMapType` from a location to be compatible with
+        Build an axis map from a location to provide to
         either :py:meth:`.RobotContext.move_axes_to` or :py:meth:`.RobotContext.move_axes_relative`.
-        You must provide only one of `location`, `slot`, or `module` to build
+        You must provide only one of either a `location`, `slot`, or `module` to build
         the axis map.
 
         :param mount: The mount of the instrument you wish create an axis map for.
@@ -210,7 +217,10 @@ class RobotContext(publisher.CommandPublisher):
                       of the strings ``"left"``, ``"right"``, ``"extension"``, ``"gripper"``. Note
                       that the gripper mount can be referred to either as ``"extension"`` or ``"gripper"``.
         :type mount: types.Mount or str
-        :param location: The location to format an axis map for.
+        :param location: Any location on the deck, specified as:
+
+              -  a deck location, like slot ``"A1"``.
+              -  a defined location, like a module on the deck.
         :type location: `Well`, `ModuleContext`, `DeckLocation` or `OffDeckType`
         """
         mount = validation.ensure_instrument_mount(mount)
@@ -248,7 +258,11 @@ class RobotContext(publisher.CommandPublisher):
         self, mount: Union[Mount, str], volume: float, action: PipetteActionTypes
     ) -> AxisMapType:
         """
-        Build a :py:class:`.types.AxisMapType` for a pipette plunger motor from volume.
+        Build an axis map to move a pipette plunger motor to complete liquid handling actions.
+
+        :mount: The left or right instrument mount the pipette is attached to.
+        :param volume: A volume to convert to an axis map for linear plunger displacement.
+        :param action: Choose to ``aspirate`` or ``dispense``.
 
         """
         pipette_name = self._core.get_pipette_type_from_engine(mount)
@@ -268,7 +282,9 @@ class RobotContext(publisher.CommandPublisher):
         self, mount: Union[Mount, str], position_name: PlungerPositionTypes
     ) -> AxisMapType:
         """
-        Build a :py:class:`.types.AxisMapType` for a pipette plunger motor from position_name.
+        Build an axis map to move a pipette plunger motor to a named position.
+
+        :param position_name: A named position to move the pipette plunger to. Choose from ``top``, ``bottom``, ``blowout``, or ``drop`` plunger positions.
 
         """
         pipette_name = self._core.get_pipette_type_from_engine(mount)
@@ -284,8 +300,9 @@ class RobotContext(publisher.CommandPublisher):
         return {pipette_axis: pipette_position}
 
     def build_axis_map(self, axis_map: StringAxisMap) -> AxisMapType:
-        """Take in a :py:class:`.types.StringAxisMap` and output a :py:class:`.types.AxisMapType`.
-        A :py:class:`.types.StringAxisMap` is allowed to contain any of the following strings:
+        """Take in a :py:class:`.types.StringAxisMap` and output an axis map.
+
+        The :py:class:`.types.StringAxisMap` is allowed to contain any of the following strings:
         ``"x"``, ``"y"``, "``z_l"``, "``z_r"``, "``z_g"``, ``"q"``.
 
         An example of a valid axis map could be:

opentrons/protocol_api/tasks.py

@@ -0,0 +1,48 @@
+"""Data for concurrent protocol tasks."""
+from typing import TYPE_CHECKING
+from datetime import datetime
+from opentrons.protocols.api_support.util import requires_version
+from opentrons.protocols.api_support.types import APIVersion
+
+if TYPE_CHECKING:
+    from .core.common import TaskCore
+
+
+class Task:
+    """A concurrent protocol task created by a protocol API function.
+
+    .. versionadded:: 2.27
+    """
+
+    def __init__(self, core: "TaskCore", api_version: APIVersion) -> None:
+        """Initialize a Task."""
+        self._core = core
+        self._api_version = api_version
+
+    @property
+    @requires_version(2, 27)
+    def created_at(self) -> datetime:
+        """The timestamp of when the task was created."""
+        return self._core.get_created_at_timestamp()
+
+    @property
+    @requires_version(2, 27)
+    def done(self) -> bool:
+        """Returns ``True`` if the task is done."""
+        return self._core.is_done()
+
+    @property
+    @requires_version(2, 27)
+    def started(self) -> bool:
+        """Returns ``True`` if the task has started."""
+        return self._core.is_started()
+        ...
+
+    @property
+    @requires_version(2, 27)
+    def finished_at(self) -> datetime | None:
+        """The timestamp of the when the task finished.
+
+        Returns ``None`` if the task hasn't finished yet.
+        """
+        return self._core.get_finished_at_timestamp()

opentrons/protocol_api/validation.py

@@ -489,6 +489,7 @@ def ensure_thermocycler_profile_steps(
         temperature = step.get("temperature")
         hold_mins = step.get("hold_time_minutes")
         hold_secs = step.get("hold_time_seconds")
+        ramp_rate = step.get("ramp_rate")
         if temperature is None:
             raise ValueError("temperature must be defined for each step in cycle")
         if hold_mins is None and hold_secs is None:
@@ -496,10 +497,14 @@ def ensure_thermocycler_profile_steps(
                 "either hold_time_minutes or hold_time_seconds must be"
                 "defined for each step in cycle"
             )
+        if ramp_rate is not None and ramp_rate <= 0:
+            raise ValueError("Ramp rate must be greater than 0.")
         validated_seconds = ensure_hold_time_seconds(hold_secs, hold_mins)
         validated_steps.append(
             ThermocyclerStep(
-                temperature=temperature, hold_time_seconds=validated_seconds
+                temperature=temperature,
+                hold_time_seconds=validated_seconds,
+                ramp_rate=ramp_rate,
             )
         )
     return validated_steps

opentrons/protocol_engine/actions/__init__.py

@@ -26,8 +26,9 @@ from .actions import (
     AddModuleAction,
     FinishErrorDetails,
     DoorChangeAction,
-    ResetTipsAction,
     SetPipetteMovementSpeedAction,
+    StartTaskAction,
+    FinishTaskAction,
 )
 from .get_state_update import get_state_updates
 
@@ -55,8 +56,9 @@ __all__ = [
     "AddAddressableAreaAction",
     "AddModuleAction",
     "DoorChangeAction",
-    "ResetTipsAction",
     "SetPipetteMovementSpeedAction",
+    "StartTaskAction",
+    "FinishTaskAction",
     # action payload values
     "PauseSource",
     "FinishErrorDetails",

opentrons/protocol_engine/actions/actions.py

@@ -3,6 +3,7 @@
 Actions can be passed to the ActionDispatcher, where they will trigger
 reactions in objects that subscribe to the pipeline, like the StateStore.
 """
+
 import dataclasses
 from datetime import datetime
 from enum import Enum
@@ -20,6 +21,7 @@ from ..commands import (
     CommandDefinedErrorData,
 )
 from ..error_recovery_policy import ErrorRecoveryPolicy, ErrorRecoveryType
+from ..errors import ErrorOccurrence
 from ..notes.notes import CommandNote
 from ..state.update_types import StateUpdate
 from ..types import (
@@ -27,6 +29,7 @@ from ..types import (
     ModuleDefinition,
     Liquid,
     DeckConfigurationType,
+    Task,
 )
 
 
@@ -60,7 +63,7 @@ class PauseAction:
 class StopAction:
     """Request engine execution to stop soon."""
 
-    from_estop: bool = False
+    from_asynchronous_error: bool = False
 
 
 @dataclasses.dataclass(frozen=True)
@@ -201,6 +204,22 @@ class FailCommandAction:
     """The command to fail, in its prior `running` state."""
 
 
+@dataclasses.dataclass(frozen=True)
+class StartTaskAction:
+    """Store new task in state."""
+
+    task: Task
+
+
+@dataclasses.dataclass(frozen=True)
+class FinishTaskAction:
+    """Mark task as finished in state."""
+
+    task_id: str
+    finished_at: datetime
+    error: ErrorOccurrence | None
+
+
 @dataclasses.dataclass(frozen=True)
 class AddLabwareOffsetAction:
     """Add a labware offset, to apply to subsequent `LoadLabwareCommand`s."""
@@ -253,13 +272,6 @@ class AddModuleAction:
     module_live_data: LiveData
 
 
-@dataclasses.dataclass(frozen=True)
-class ResetTipsAction:
-    """Reset the tip tracking state of a given tip rack."""
-
-    labware_id: str
-
-
 @dataclasses.dataclass(frozen=True)
 class SetPipetteMovementSpeedAction:
     """Set the speed of a pipette's X/Y/Z movements. Does not affect plunger speed.
@@ -296,7 +308,8 @@ Action = Union[
     SetDeckConfigurationAction,
     AddAddressableAreaAction,
     AddLiquidAction,
-    ResetTipsAction,
     SetPipetteMovementSpeedAction,
     SetErrorRecoveryPolicyAction,
+    StartTaskAction,
+    FinishTaskAction,
 ]

opentrons/protocol_engine/clients/sync_client.py

@@ -65,6 +65,12 @@ class SyncClient:
     ) -> commands.LoadLabwareResult:
         pass
 
+    @overload
+    def execute_command_without_recovery(
+        self, params: commands.CreateTimerParams
+    ) -> commands.CreateTimerResult:
+        pass
+
     @overload
     def execute_command_without_recovery(
         self, params: commands.LoadModuleParams
@@ -149,13 +155,6 @@ class SyncClient:
         """Add a liquid to the engine."""
         return self._transport.call_method("add_liquid", name=name, color=color, description=description)  # type: ignore[no-any-return]
 
-    def reset_tips(self, labware_id: str) -> None:
-        """Reset a labware's tip tracking state.."""
-        self._transport.call_method(
-            "reset_tips",
-            labware_id=labware_id,
-        )
-
     def add_labware_offset(self, request: LabwareOffsetCreate) -> None:
         """Add a labware offset."""
         self._transport.call_method("add_labware_offset", request=request)

opentrons/protocol_engine/commands/__init__.py

@@ -271,6 +271,22 @@ from .wait_for_duration import (
     WaitForDurationCommandType,
 )
 
+from .create_timer import (
+    CreateTimer,
+    CreateTimerCreate,
+    CreateTimerParams,
+    CreateTimerResult,
+    CreateTimerCommandType,
+)
+
+from .wait_for_tasks import (
+    WaitForTasks,
+    WaitForTasksCreate,
+    WaitForTasksParams,
+    WaitForTasksResult,
+    WaitForTasksCommandType,
+)
+
 from .pick_up_tip import (
     PickUpTip,
     PickUpTipParams,
@@ -384,6 +400,14 @@ from .get_next_tip import (
     GetNextTipCommandType,
 )
 
+from .set_tip_state import (
+    SetTipState,
+    SetTipStateCreate,
+    SetTipStateParams,
+    SetTipStateResult,
+    SetTipStateCommandType,
+)
+
 from .liquid_probe import (
     LiquidProbe,
     LiquidProbeParams,
@@ -619,6 +643,12 @@ __all__ = [
     "WaitForDurationCreate",
     "WaitForDurationResult",
     "WaitForDurationCommandType",
+    # Timer command models
+    "CreateTimer",
+    "CreateTimerCreate",
+    "CreateTimerParams",
+    "CreateTimerResult",
+    "CreateTimerCommandType",
     # pick up tip command models
     "PickUpTip",
     "PickUpTipCreate",
@@ -725,6 +755,12 @@ __all__ = [
     "GetNextTipParams",
     "GetNextTipResult",
     "GetNextTipCommandType",
+    # set tip state command bundle
+    "SetTipState",
+    "SetTipStateCreate",
+    "SetTipStateParams",
+    "SetTipStateResult",
+    "SetTipStateCommandType",
     # liquid probe command bundle
     "LiquidProbe",
     "LiquidProbeParams",
@@ -754,4 +790,10 @@ __all__ = [
     "PressureDispenseCreate",
     "PressureDispenseResult",
     "PressureDispenseCommandType",
+    # wait for tasks command bundle
+    "WaitForTasks",
+    "WaitForTasksCreate",
+    "WaitForTasksParams",
+    "WaitForTasksResult",
+    "WaitForTasksCommandType",
 ]

opentrons/protocol_engine/commands/absorbance_reader/close_lid.py

@@ -102,25 +102,12 @@ class CloseLidImpl(AbstractCommandImpl[CloseLidParams, SuccessData[CloseLidResul
                 )
             )
 
-            # The lid's labware definition stores gripper offsets for itself in the
-            # space normally meant for offsets for labware stacked atop it.
-            lid_gripper_offsets = self._state_view.labware.get_child_gripper_offsets(
-                labware_definition=lid_definition,
-                slot_name=None,
-            )
-            if lid_gripper_offsets is None:
-                raise ValueError(
-                    "Gripper Offset values for Absorbance Reader Lid labware must not be None."
-                )
-
             await self._labware_movement.move_labware_with_gripper(
                 labware_definition=lid_definition,
                 current_location=current_location,
                 new_location=new_location,
-                user_pick_up_offset=Point.from_xyz_attrs(
-                    lid_gripper_offsets.pickUpOffset
-                ),
-                user_drop_offset=Point.from_xyz_attrs(lid_gripper_offsets.dropOffset),
+                user_pick_up_offset=Point(),
+                user_drop_offset=Point(),
                 post_drop_slide_offset=None,
                 gripper_z_offset=LID_Z_CLEARANCE,
             )

opentrons/protocol_engine/commands/absorbance_reader/open_lid.py

@@ -103,25 +103,12 @@ class OpenLidImpl(AbstractCommandImpl[OpenLidParams, SuccessData[OpenLidResult]]
                 mod_substate.module_id
             )
 
-            # The lid's labware definition stores gripper offsets for itself in the
-            # space normally meant for offsets for labware stacked atop it.
-            lid_gripper_offsets = self._state_view.labware.get_child_gripper_offsets(
-                labware_definition=lid_definition,
-                slot_name=None,
-            )
-            if lid_gripper_offsets is None:
-                raise ValueError(
-                    "Gripper Offset values for Absorbance Reader Lid labware must not be None."
-                )
-
             await self._labware_movement.move_labware_with_gripper(
                 labware_definition=lid_definition,
                 current_location=current_location,
                 new_location=new_location,
-                user_pick_up_offset=Point.from_xyz_attrs(
-                    lid_gripper_offsets.pickUpOffset
-                ),
-                user_drop_offset=Point.from_xyz_attrs(lid_gripper_offsets.dropOffset),
+                user_pick_up_offset=Point(),
+                user_drop_offset=Point(),
                 post_drop_slide_offset=None,
                 gripper_z_offset=LID_Z_CLEARANCE,
             )

opentrons/protocol_engine/commands/aspirate.py

@@ -161,6 +161,7 @@ class AspirateImplementation(AbstractCommandImpl[AspirateParams, _ExecuteReturn]
             well_location=well_location,
             current_well=current_well,
             operation_volume=-params.volume,
+            offset_pipette_for_reservoir_subwells=False,
         )
         state_update.append(move_result.state_update)
         if isinstance(move_result, DefinedErrorData):

opentrons/protocol_engine/commands/command.py

@@ -185,6 +185,7 @@ class AbstractCommandImpl(
         tip_handler: execution.TipHandler,
         run_control: execution.RunControlHandler,
         rail_lights: execution.RailLightsHandler,
+        task_handler: execution.TaskHandler,
         model_utils: ModelUtils,
         status_bar: execution.StatusBarHandler,
         command_note_adder: CommandNoteAdder,