opentrons 8.1.0__py2.py3-none-any.whl → 8.2.0__py2.py3-none-any.whl

opentrons/protocol_engine/errors/__init__.py

@@ -8,6 +8,7 @@ from .exceptions import (
     InvalidSpecificationForRobotTypeError,
     InvalidLoadPipetteSpecsError,
     TipNotAttachedError,
+    PickUpTipTipNotAttachedError,
     TipAttachedError,
     CommandDoesNotExistError,
     LabwareNotLoadedError,
@@ -54,6 +55,7 @@ from .exceptions import (
     InvalidTargetTemperatureError,
     InvalidBlockVolumeError,
     InvalidHoldTimeError,
+    InvalidWavelengthError,
     CannotPerformModuleAction,
     PauseNotAllowedError,
     ResumeFromRecoveryNotAllowedError,
@@ -65,9 +67,17 @@ from .exceptions import (
     LocationIsOccupiedError,
     LocationNotAccessibleByPipetteError,
     LocationIsStagingSlotError,
+    LocationIsLidDockSlotError,
     InvalidAxisForRobotType,
     NotSupportedOnRobotType,
     CommandNotAllowedError,
+    InvalidLiquidHeightFound,
+    LiquidHeightUnknownError,
+    IncompleteLabwareDefinitionError,
+    IncompleteWellDefinitionError,
+    OperationLocationNotInWellError,
+    InvalidDispenseVolumeError,
+    StorageLimitReachedError,
 )
 
 from .error_occurrence import ErrorOccurrence, ProtocolCommandFailedError
@@ -81,6 +91,7 @@ __all__ = [
     "InvalidSpecificationForRobotTypeError",
     "InvalidLoadPipetteSpecsError",
     "TipNotAttachedError",
+    "PickUpTipTipNotAttachedError",
     "TipAttachedError",
     "CommandDoesNotExistError",
     "LabwareNotLoadedError",
@@ -127,6 +138,7 @@ __all__ = [
     "InvalidTargetSpeedError",
     "InvalidBlockVolumeError",
     "InvalidHoldTimeError",
+    "InvalidWavelengthError",
     "CannotPerformModuleAction",
     "ResumeFromRecoveryNotAllowedError",
     "PauseNotAllowedError",
@@ -139,9 +151,17 @@ __all__ = [
     "LocationIsOccupiedError",
     "LocationNotAccessibleByPipetteError",
     "LocationIsStagingSlotError",
+    "LocationIsLidDockSlotError",
     "InvalidAxisForRobotType",
     "NotSupportedOnRobotType",
     # error occurrence models
     "ErrorOccurrence",
     "CommandNotAllowedError",
+    "InvalidLiquidHeightFound",
+    "LiquidHeightUnknownError",
+    "IncompleteLabwareDefinitionError",
+    "IncompleteWellDefinitionError",
+    "OperationLocationNotInWellError",
+    "InvalidDispenseVolumeError",
+    "StorageLimitReachedError",
 ]

opentrons/protocol_engine/errors/error_occurrence.py

@@ -12,8 +12,6 @@ from opentrons_shared_data.errors.exceptions import EnumeratedError
 log = getLogger(__name__)
 
 
-# TODO(mc, 2021-11-12): flesh this model out with structured error data
-# for each error type so client may produce better error messages
 class ErrorOccurrence(BaseModel):
     """An occurrence of a specific error during protocol execution."""
 
@@ -44,8 +42,15 @@ class ErrorOccurrence(BaseModel):
     id: str = Field(..., description="Unique identifier of this error occurrence.")
     createdAt: datetime = Field(..., description="When the error occurred.")
 
+    # Our Python should probably always set this to False--if we want it to be True,
+    # we should probably be using a more specific subclass of ErrorOccurrence anyway.
+    # However, we can't make this Literal[False], because we want this class to be able
+    # to act as a catch-all for parsing defined errors that might be missing some
+    # `errorInfo` fields because they were serialized by older software.
     isDefined: bool = Field(
-        default=False,  # default=False for database backwards compatibility.
+        # default=False for database backwards compatibility, so we can parse objects
+        # serialized before isDefined existed.
+        default=False,
         description=dedent(
             """\
             Whether this error is *defined.*

opentrons/protocol_engine/errors/exceptions.py

@@ -1,11 +1,17 @@
 """Protocol engine exceptions."""
 
+from __future__ import annotations
+
 from logging import getLogger
-from typing import Any, Dict, Optional, Union, Iterator, Sequence
+from typing import Any, Dict, Final, Optional, Union, Iterator, Sequence, TYPE_CHECKING
 
 from opentrons_shared_data.errors import ErrorCodes
 from opentrons_shared_data.errors.exceptions import EnumeratedError, PythonException
 
+if TYPE_CHECKING:
+    from opentrons.protocol_engine.types import TipGeometry
+
+
 log = getLogger(__name__)
 
 
@@ -132,6 +138,21 @@ class TipNotAttachedError(ProtocolEngineError):
         super().__init__(ErrorCodes.UNEXPECTED_TIP_REMOVAL, message, details, wrapping)
 
 
+class PickUpTipTipNotAttachedError(TipNotAttachedError):
+    """Raised from TipHandler.pick_up_tip().
+
+    This is like TipNotAttachedError except that it carries some extra information
+    about the attempted operation.
+    """
+
+    tip_geometry: Final[TipGeometry]
+    """The tip geometry that would have been on the pipette, had the operation succeeded."""
+
+    def __init__(self, tip_geometry: TipGeometry) -> None:
+        super().__init__()
+        self.tip_geometry = tip_geometry
+
+
 class TipAttachedError(ProtocolEngineError):
     """Raised when a tip shouldn't be attached, but is."""
 
@@ -752,6 +773,19 @@ class InvalidBlockVolumeError(ProtocolEngineError):
         super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
 
 
+class InvalidWavelengthError(ProtocolEngineError):
+    """Raised when attempting to set an invalid absorbance wavelength."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build a InvalidWavelengthError."""
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
 class InvalidHoldTimeError(ProtocolEngineError):
     """An error raised when attempting to set an invalid temperature hold time."""
 
@@ -897,6 +931,19 @@ class LocationIsStagingSlotError(ProtocolEngineError):
         super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
 
 
+class LocationIsLidDockSlotError(ProtocolEngineError):
+    """Raised when referencing a labware on a lid dock slot when trying to get standard deck slot."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build a LocationIsLidDockSlotError."""
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
 class FirmwareUpdateRequired(ProtocolEngineError):
     """Raised when the firmware needs to be updated."""
 
@@ -939,7 +986,7 @@ class InvalidAspirateVolumeError(ProtocolEngineError):
         """Build a InvalidPipettingVolumeError."""
         message = (
             f"Cannot aspirate {attempted_aspirate_volume} µL when only"
-            f" {available_volume} is available."
+            f" {available_volume} is available in the tip."
         )
         details = {
             "attempted_aspirate_volume": attempted_aspirate_volume,
@@ -989,6 +1036,32 @@ class InvalidAxisForRobotType(ProtocolEngineError):
         super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
 
 
+class InvalidLiquidHeightFound(ProtocolEngineError):
+    """Raised when attempting to estimate liquid height based on volume fails."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build an InvalidLiquidHeightFound error."""
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
+class LiquidHeightUnknownError(ProtocolEngineError):
+    """Raised when attempting to specify WellOrigin.MENISCUS before liquid probing has been done."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build a LiquidHeightUnknownError."""
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
 class EStopActivatedError(ProtocolEngineError):
     """Represents an E-stop event."""
 
@@ -1030,3 +1103,55 @@ class TipNotEmptyError(ProtocolEngineError):
     ) -> None:
         """Build a TipNotEmptyError."""
         super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
+class IncompleteLabwareDefinitionError(ProtocolEngineError):
+    """Raised when a labware definition lacks innerLabwareGeometry in general or for a specific well_id."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build an IncompleteLabwareDefinitionError."""
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
+class IncompleteWellDefinitionError(ProtocolEngineError):
+    """Raised when a well definition lacks a geometryDefinitionId."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build an IncompleteWellDefinitionError."""
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
+class OperationLocationNotInWellError(ProtocolEngineError):
+    """Raised when a calculated operation location is not within a well."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build an OperationLocationNotInWellError."""
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
+class StorageLimitReachedError(ProtocolEngineError):
+    """Raised to indicate that a file cannot be created due to storage limitations."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        detail: Optional[Dict[str, str]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build an StorageLimitReached."""
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, detail, wrapping)

opentrons/protocol_engine/execution/__init__.py

@@ -21,6 +21,7 @@ from .run_control import RunControlHandler
 from .hardware_stopper import HardwareStopper
 from .door_watcher import DoorWatcher
 from .status_bar import StatusBarHandler
+from ..resources.file_provider import FileProvider
 
 # .thermocycler_movement_flagger omitted from package's public interface.
 
@@ -45,4 +46,5 @@ __all__ = [
     "DoorWatcher",
     "RailLightsHandler",
     "StatusBarHandler",
+    "FileProvider",
 ]

opentrons/protocol_engine/execution/command_executor.py

@@ -12,9 +12,10 @@ from opentrons_shared_data.errors.exceptions import (
 )
 
 from opentrons.protocol_engine.commands.command import SuccessData
+from opentrons.protocol_engine.notes import make_error_recovery_debug_note
 
-from ..state import StateStore
-from ..resources import ModelUtils
+from ..state.state import StateStore
+from ..resources import ModelUtils, FileProvider
 from ..commands import CommandStatus
 from ..actions import (
     ActionDispatcher,
@@ -72,6 +73,7 @@ class CommandExecutor:
     def __init__(
         self,
         hardware_api: HardwareControlAPI,
+        file_provider: FileProvider,
         state_store: StateStore,
         action_dispatcher: ActionDispatcher,
         equipment: EquipmentHandler,
@@ -88,6 +90,7 @@ class CommandExecutor:
     ) -> None:
         """Initialize the CommandExecutor with access to its dependencies."""
         self._hardware_api = hardware_api
+        self._file_provider = file_provider
         self._state_store = state_store
         self._action_dispatcher = action_dispatcher
         self._equipment = equipment
@@ -116,6 +119,7 @@ class CommandExecutor:
         command_impl = queued_command._ImplementationCls(
             state_view=self._state_store,
             hardware_api=self._hardware_api,
+            file_provider=self._file_provider,
             equipment=self._equipment,
             movement=self._movement,
             gantry_mover=self._gantry_mover,
@@ -158,6 +162,12 @@ class CommandExecutor:
             elif not isinstance(error, EnumeratedError):
                 error = PythonException(error)
 
+            error_recovery_type = error_recovery_policy(
+                self._state_store.config,
+                running_command,
+                None,
+            )
+            note_tracker(make_error_recovery_debug_note(error_recovery_type))
             self._action_dispatcher.dispatch(
                 FailCommandAction(
                     error=error,
@@ -166,11 +176,7 @@ class CommandExecutor:
                     error_id=self._model_utils.generate_id(),
                     failed_at=self._model_utils.get_timestamp(),
                     notes=note_tracker.get_notes(),
-                    type=error_recovery_policy(
-                        self._state_store.config,
-                        running_command,
-                        None,
-                    ),
+                    type=error_recovery_type,
                 )
             )
 
@@ -185,11 +191,18 @@ class CommandExecutor:
                 succeeded_command = running_command.copy(update=update)
                 self._action_dispatcher.dispatch(
                     SucceedCommandAction(
-                        command=succeeded_command, private_result=result.private
+                        command=succeeded_command,
+                        state_update=result.state_update,
                     ),
                 )
             else:
                 # The command encountered a defined error.
+                error_recovery_type = error_recovery_policy(
+                    self._state_store.config,
+                    running_command,
+                    result,
+                )
+                note_tracker(make_error_recovery_debug_note(error_recovery_type))
                 self._action_dispatcher.dispatch(
                     FailCommandAction(
                         error=result,
@@ -198,10 +211,6 @@ class CommandExecutor:
                         error_id=result.public.id,
                         failed_at=result.public.createdAt,
                         notes=note_tracker.get_notes(),
-                        type=error_recovery_policy(
-                            self._state_store.config,
-                            running_command,
-                            result,
-                        ),
+                        type=error_recovery_type,
                     )
                 )

opentrons/protocol_engine/execution/create_queue_worker.py

@@ -4,8 +4,9 @@ from typing import AsyncGenerator, Callable
 from opentrons.hardware_control import HardwareControlAPI
 from opentrons.protocol_engine.execution.rail_lights import RailLightsHandler
 
-from ..state import StateStore
+from ..state.state import StateStore
 from ..actions import ActionDispatcher
+from ..resources import FileProvider
 from .equipment import EquipmentHandler
 from .movement import MovementHandler
 from .gantry_mover import create_gantry_mover
@@ -20,6 +21,7 @@ from .status_bar import StatusBarHandler
 
 def create_queue_worker(
     hardware_api: HardwareControlAPI,
+    file_provider: FileProvider,
     state_store: StateStore,
     action_dispatcher: ActionDispatcher,
     command_generator: Callable[[], AsyncGenerator[str, None]],
@@ -28,6 +30,7 @@ def create_queue_worker(
 
     Arguments:
         hardware_api: Hardware control API to pass down to dependencies.
+        file_provider: Provides access to robot server file writing procedures for protocol output.
         state_store: StateStore to pass down to dependencies.
         action_dispatcher: ActionDispatcher to pass down to dependencies.
         error_recovery_policy: ErrorRecoveryPolicy to pass down to dependencies.
@@ -78,6 +81,7 @@ def create_queue_worker(
 
     command_executor = CommandExecutor(
         hardware_api=hardware_api,
+        file_provider=file_provider,
         state_store=state_store,
         action_dispatcher=action_dispatcher,
         equipment=equipment_handler,

opentrons/protocol_engine/execution/door_watcher.py

@@ -15,7 +15,7 @@ from opentrons.hardware_control.types import (
 
 from opentrons.protocol_engine.actions import ActionDispatcher, DoorChangeAction
 
-from ..state import StateStore
+from ..state.state import StateStore
 
 
 _UnsubscribeCallback = Callable[[], None]

opentrons/protocol_engine/execution/equipment.py

@@ -35,7 +35,8 @@ from ..resources import (
     ModelUtils,
     pipette_data_provider,
 )
-from ..state import StateStore, HardwareModule
+from ..state.state import StateStore
+from ..state.modules import HardwareModule
 from ..types import (
     LabwareLocation,
     DeckSlotLocation,

opentrons/protocol_engine/execution/error_recovery_hardware_state_synchronizer.py

@@ -0,0 +1,101 @@
+# noqa: D100
+
+
+from opentrons.hardware_control import HardwareControlAPI
+from opentrons.protocol_engine.actions.action_handler import ActionHandler
+from opentrons.protocol_engine.actions.actions import (
+    Action,
+    FailCommandAction,
+    ResumeFromRecoveryAction,
+)
+from opentrons.protocol_engine.commands.command import DefinedErrorData
+from opentrons.protocol_engine.error_recovery_policy import ErrorRecoveryType
+from opentrons.protocol_engine.execution.tip_handler import HardwareTipHandler
+from opentrons.protocol_engine.state import update_types
+from opentrons.protocol_engine.state.state import StateView
+
+
+class ErrorRecoveryHardwareStateSynchronizer(ActionHandler):
+    """A hack to keep the hardware API's state correct through certain error recovery flows.
+
+    BACKGROUND:
+
+    Certain parts of robot state are duplicated between `opentrons.protocol_engine` and
+    `opentrons.hardware_control`. Stuff like "is there a tip attached."
+
+    Normally, Protocol Engine command implementations (`opentrons.protocol_engine.commands`)
+    mutate hardware API state when they execute; and then when they finish executing,
+    the Protocol Engine state stores (`opentrons.protocol_engine.state`) update Protocol
+    Engine state accordingly. So both halves are accounted for. This generally works fine.
+
+    However, we need to go out of our way to support
+    `ProtocolEngine.resume_from_recovery(reconcile_false_positive=True)`.
+    It wants to apply a second set of state updates to "fix things up" with the
+    new knowledge that some error was a false positive. The Protocol Engine half of that
+    is easy for us to apply the normal way, through the state stores; but the
+    hardware API half of that cannot be applied the normal way, from the command
+    implementation, because the command in question is no longer running.
+
+    THE HACK:
+
+    This listens for the same error recovery state updates that the state stores do,
+    figures out what hardware API state mutations ought to go along with them,
+    and then does those mutations.
+
+    The problem is that hardware API state is now mutated from two different places
+    (sometimes the command implementations, and sometimes here), which are bound
+    to grow accidental differences.
+
+    TO FIX:
+
+    Make Protocol Engine's use of the hardware API less stateful. e.g. supply
+    tip geometry every time we call a hardware API movement method, instead of
+    just once when we pick up a tip. Use Protocol Engine state as the single source
+    of truth.
+    """
+
+    def __init__(self, hardware_api: HardwareControlAPI, state_view: StateView) -> None:
+        self._hardware_api = hardware_api
+        self._state_view = state_view
+
+    def handle_action(self, action: Action) -> None:
+        """Modify hardware API state in reaction to a Protocol Engine action."""
+        state_update = _get_state_update(action)
+        if state_update:
+            self._synchronize(state_update)
+
+    def _synchronize(self, state_update: update_types.StateUpdate) -> None:
+        tip_handler = HardwareTipHandler(self._state_view, self._hardware_api)
+
+        if state_update.pipette_tip_state != update_types.NO_CHANGE:
+            pipette_id = state_update.pipette_tip_state.pipette_id
+            tip_geometry = state_update.pipette_tip_state.tip_geometry
+            if tip_geometry is None:
+                tip_handler.remove_tip(pipette_id)
+            else:
+                tip_handler.cache_tip(pipette_id=pipette_id, tip=tip_geometry)
+
+
+def _get_state_update(action: Action) -> update_types.StateUpdate | None:
+    """Get the mutations that we need to do on the hardware API to stay in sync with an engine action.
+
+    The mutations are returned in Protocol Engine terms, as a StateUpdate.
+    They then need to be converted to hardware API terms.
+    """
+    match action:
+        case ResumeFromRecoveryAction(state_update=state_update):
+            return state_update
+
+        case FailCommandAction(
+            error=DefinedErrorData(
+                state_update_if_false_positive=state_update_if_false_positive
+            )
+        ):
+            return (
+                state_update_if_false_positive
+                if action.type == ErrorRecoveryType.ASSUME_FALSE_POSITIVE_AND_CONTINUE
+                else None
+            )
+
+        case _:
+            return None

opentrons/protocol_engine/execution/gantry_mover.py

@@ -10,7 +10,7 @@ from opentrons_shared_data.errors.exceptions import PositionUnknownError
 
 from opentrons.motion_planning import Waypoint
 
-from ..state import StateView
+from ..state.state import StateView
 from ..types import MotorAxis, CurrentWell
 from ..errors import MustHomeError, InvalidAxisForRobotType
 
@@ -273,7 +273,9 @@ class VirtualGantryMover(GantryMover):
             )
         else:
             instrument_height = VIRTUAL_MAX_OT3_HEIGHT
-        tip_length = self._state_view.tips.get_tip_length(pipette_id)
+
+        tip = self._state_view.pipettes.get_attached_tip(pipette_id=pipette_id)
+        tip_length = tip.length if tip is not None else 0
         return instrument_height - tip_length
 
     async def move_to(

opentrons/protocol_engine/execution/hardware_stopper.py

@@ -6,7 +6,7 @@ from opentrons.hardware_control import HardwareControlAPI
 from opentrons.types import PipetteNotAttachedError as HwPipetteNotAttachedError
 
 from ..resources.ot3_validation import ensure_ot3_hardware
-from ..state import StateStore
+from ..state.state import StateStore
 from ..types import MotorAxis, PostRunHardwareState
 from ..errors import HardwareNotSupportedError
 
@@ -78,7 +78,7 @@ class HardwareStopper:
                 try:
                     if self._state_store.labware.get_fixed_trash_id() == FIXED_TRASH_ID:
                         # OT-2 and Flex 2.15 protocols will default to the Fixed Trash Labware
-                        await self._tip_handler.add_tip(pipette_id=pipette_id, tip=tip)
+                        self._tip_handler.cache_tip(pipette_id=pipette_id, tip=tip)
                         await self._movement_handler.move_to_well(
                             pipette_id=pipette_id,
                             labware_id=FIXED_TRASH_ID,
@@ -90,7 +90,7 @@ class HardwareStopper:
                         )
                     elif self._state_store.config.robot_type == "OT-2 Standard":
                         # API 2.16 and above OT2 protocols use addressable areas
-                        await self._tip_handler.add_tip(pipette_id=pipette_id, tip=tip)
+                        self._tip_handler.cache_tip(pipette_id=pipette_id, tip=tip)
                         await self._movement_handler.move_to_addressable_area(
                             pipette_id=pipette_id,
                             addressable_area_name="fixedTrash",

opentrons/protocol_engine/execution/heater_shaker_movement_flagger.py

@@ -13,7 +13,7 @@ from ..errors import (
     HeaterShakerLabwareLatchStatusUnknown,
     WrongModuleTypeError,
 )
-from ..state import StateStore
+from ..state.state import StateStore
 from ..state.module_substates import HeaterShakerModuleSubState
 from ..types import (
     HeaterShakerMovementRestrictors,
@@ -61,9 +61,6 @@ class HeaterShakerMovementFlagger:
             return  # Labware on a module, but not a Heater-Shaker.
 
         if hs_substate.labware_latch_status == HeaterShakerLatchStatus.CLOSED:
-            # TODO (spp, 2022-10-27): This only raises if latch status is 'idle_closed'.
-            #  We need to update the flagger to raise if latch status is anything other
-            #  than 'idle_open'
             raise HeaterShakerLabwareLatchNotOpenError(
                 "Heater-Shaker labware latch must be open when moving labware to/from it."
             )