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

opentrons/protocol_engine/execution/labware_movement.py

@@ -1,7 +1,9 @@
 """Labware movement command handling."""
 from __future__ import annotations
 
-from typing import Optional, TYPE_CHECKING
+from typing import Optional, TYPE_CHECKING, overload
+
+from opentrons_shared_data.labware.labware_definition import LabwareDefinition
 
 from opentrons.types import Point
 
@@ -9,7 +11,7 @@ from opentrons.hardware_control import HardwareControlAPI
 from opentrons.hardware_control.types import OT3Mount, Axis
 from opentrons.motion_planning import get_gripper_labware_movement_waypoints
 
-from opentrons.protocol_engine.state import StateStore
+from opentrons.protocol_engine.state.state import StateStore
 from opentrons.protocol_engine.resources.ot3_validation import ensure_ot3_hardware
 
 from .thermocycler_movement_flagger import ThermocyclerMovementFlagger
@@ -37,8 +39,6 @@ if TYPE_CHECKING:
 _GRIPPER_HOMED_POSITION_Z = 166.125  # Height of the center of the gripper critical point from the deck when homed
 
 
-# TODO (spp, 2022-10-20): name this GripperMovementHandler if it doesn't handle
-#  any non-gripper implementations
 class LabwareMovementHandler:
     """Implementation logic for labware movement."""
 
@@ -81,24 +81,64 @@ class LabwareMovementHandler:
             )
         )
 
+    @overload
     async def move_labware_with_gripper(
         self,
+        *,
         labware_id: str,
         current_location: OnDeckLabwareLocation,
         new_location: OnDeckLabwareLocation,
         user_offset_data: LabwareMovementOffsetData,
         post_drop_slide_offset: Optional[Point],
     ) -> None:
-        """Move a loaded labware from one location to another using gripper."""
+        ...
+
+    @overload
+    async def move_labware_with_gripper(
+        self,
+        *,
+        labware_definition: LabwareDefinition,
+        current_location: OnDeckLabwareLocation,
+        new_location: OnDeckLabwareLocation,
+        user_offset_data: LabwareMovementOffsetData,
+        post_drop_slide_offset: Optional[Point],
+    ) -> None:
+        ...
+
+    async def move_labware_with_gripper(  # noqa: C901
+        self,
+        *,
+        labware_id: str | None = None,
+        labware_definition: LabwareDefinition | None = None,
+        current_location: OnDeckLabwareLocation,
+        new_location: OnDeckLabwareLocation,
+        user_offset_data: LabwareMovementOffsetData,
+        post_drop_slide_offset: Optional[Point],
+    ) -> None:
+        """Physically move a labware from one location to another using the gripper.
+
+        Generally, provide the `labware_id` of a loaded labware, and this method will
+        automatically look up its labware definition. If you're physically moving
+        something that has not been loaded as a labware (this is not common),
+        provide the `labware_definition` yourself instead.
+        """
         use_virtual_gripper = self._state_store.config.use_virtual_gripper
 
+        if labware_definition is None:
+            assert labware_id is not None  # From this method's @typing.overloads.
+            labware_definition = self._state_store.labware.get_definition(labware_id)
+
         if use_virtual_gripper:
-            # During Analysis we will pass in hard coded estimates for certain positions only accessible during execution
-            self._state_store.geometry.check_gripper_labware_tip_collision(
-                gripper_homed_position_z=_GRIPPER_HOMED_POSITION_Z,
-                labware_id=labware_id,
-                current_location=current_location,
-            )
+            # todo(mm, 2024-11-07): We should do this collision checking even when we
+            # only have a `labware_definition`, not a `labware_id`. Resolve when
+            # `check_gripper_labware_tip_collision()` can be made independent of `labware_id`.
+            if labware_id is not None:
+                self._state_store.geometry.check_gripper_labware_tip_collision(
+                    # During Analysis we will pass in hard coded estimates for certain positions only accessible during execution
+                    gripper_homed_position_z=_GRIPPER_HOMED_POSITION_Z,
+                    labware_id=labware_id,
+                    current_location=current_location,
+                )
             return
 
         ot3api = ensure_ot3_hardware(
@@ -121,12 +161,15 @@ class LabwareMovementHandler:
         await ot3api.home(axes=[Axis.Z_L, Axis.Z_R, Axis.Z_G])
         gripper_homed_position = await ot3api.gantry_position(mount=gripper_mount)
 
-        # Verify that no tip collisions will occur during the move
-        self._state_store.geometry.check_gripper_labware_tip_collision(
-            gripper_homed_position_z=gripper_homed_position.z,
-            labware_id=labware_id,
-            current_location=current_location,
-        )
+        # todo(mm, 2024-11-07): We should do this collision checking even when we
+        # only have a `labware_definition`, not a `labware_id`. Resolve when
+        # `check_gripper_labware_tip_collision()` can be made independent of `labware_id`.
+        if labware_id is not None:
+            self._state_store.geometry.check_gripper_labware_tip_collision(
+                gripper_homed_position_z=gripper_homed_position.z,
+                labware_id=labware_id,
+                current_location=current_location,
+            )
 
         async with self._thermocycler_plate_lifter.lift_plate_for_labware_movement(
             labware_location=current_location
@@ -136,13 +179,14 @@ class LabwareMovementHandler:
                     from_location=current_location,
                     to_location=new_location,
                     additional_offset_vector=user_offset_data,
+                    current_labware=labware_definition,
                 )
             )
             from_labware_center = self._state_store.geometry.get_labware_grip_point(
-                labware_id=labware_id, location=current_location
+                labware_definition=labware_definition, location=current_location
             )
             to_labware_center = self._state_store.geometry.get_labware_grip_point(
-                labware_id=labware_id, location=new_location
+                labware_definition=labware_definition, location=new_location
             )
             movement_waypoints = get_gripper_labware_movement_waypoints(
                 from_labware_center=from_labware_center,
@@ -151,7 +195,9 @@ class LabwareMovementHandler:
                 offset_data=final_offsets,
                 post_drop_slide_offset=post_drop_slide_offset,
             )
-            labware_grip_force = self._state_store.labware.get_grip_force(labware_id)
+            labware_grip_force = self._state_store.labware.get_grip_force(
+                labware_definition
+            )
             holding_labware = False
             for waypoint_data in movement_waypoints:
                 if waypoint_data.jaw_open:
@@ -174,9 +220,14 @@ class LabwareMovementHandler:
                     # should be holding labware
                     if holding_labware:
                         labware_bbox = self._state_store.labware.get_dimensions(
-                            labware_id
+                            labware_definition=labware_definition
+                        )
+                        well_bbox = self._state_store.labware.get_well_bbox(
+                            labware_definition=labware_definition
                         )
-                        well_bbox = self._state_store.labware.get_well_bbox(labware_id)
+                        # todo(mm, 2024-09-26): This currently raises a lower-level 2015 FailedGripperPickupError.
+                        # Convert this to a higher-level 3001 LabwareDroppedError or 3002 LabwareNotPickedUpError,
+                        # depending on what waypoint we're at, to propagate a more specific error code to users.
                         ot3api.raise_error_if_gripper_pickup_failed(
                             expected_grip_width=labware_bbox.y,
                             grip_width_uncertainty_wider=abs(

opentrons/protocol_engine/execution/movement.py

@@ -2,21 +2,23 @@
 from __future__ import annotations
 
 import logging
-from typing import Optional, List
+from typing import Optional, List, Union
 
-from opentrons.types import Point, MountType
+from opentrons.types import Point, MountType, StagingSlotName
 from opentrons.hardware_control import HardwareControlAPI
 from opentrons_shared_data.errors.exceptions import PositionUnknownError
+from opentrons.protocol_engine.errors import LocationIsStagingSlotError
 
 from ..types import (
     WellLocation,
+    LiquidHandlingWellLocation,
     DeckPoint,
     MovementAxis,
     MotorAxis,
     CurrentWell,
     AddressableOffsetVector,
 )
-from ..state import StateStore
+from ..state.state import StateStore
 from ..resources import ModelUtils
 from .thermocycler_movement_flagger import ThermocyclerMovementFlagger
 from .heater_shaker_movement_flagger import HeaterShakerMovementFlagger
@@ -66,11 +68,12 @@ class MovementHandler:
         pipette_id: str,
         labware_id: str,
         well_name: str,
-        well_location: Optional[WellLocation] = None,
+        well_location: Optional[Union[WellLocation, LiquidHandlingWellLocation]] = None,
         current_well: Optional[CurrentWell] = None,
         force_direct: bool = False,
         minimum_z_height: Optional[float] = None,
         speed: Optional[float] = None,
+        operation_volume: Optional[float] = None,
     ) -> Point:
         """Move to a specific well."""
         self._state_store.labware.raise_if_labware_inaccessible_by_pipette(
@@ -91,9 +94,13 @@ class MovementHandler:
             self._state_store.modules.get_heater_shaker_movement_restrictors()
         )
 
-        dest_slot_int = self._state_store.geometry.get_ancestor_slot_name(
-            labware_id
-        ).as_int()
+        ancestor = self._state_store.geometry.get_ancestor_slot_name(labware_id)
+        if isinstance(ancestor, StagingSlotName):
+            raise LocationIsStagingSlotError(
+                "Cannot move to well on labware in Staging Area Slot."
+            )
+
+        dest_slot_int = ancestor.as_int()
 
         self._hs_movement_flagger.raise_if_movement_restricted(
             hs_movement_restrictors=hs_movement_restrictors,
@@ -129,6 +136,7 @@ class MovementHandler:
             current_well=current_well,
             force_direct=force_direct,
             minimum_z_height=minimum_z_height,
+            operation_volume=operation_volume,
         )
 
         speed = self._state_store.pipettes.get_movement_speed(
@@ -151,6 +159,7 @@ class MovementHandler:
         speed: Optional[float] = None,
         stay_at_highest_possible_z: bool = False,
         ignore_tip_configuration: Optional[bool] = True,
+        highest_possible_z_extra_offset: Optional[float] = None,
     ) -> Point:
         """Move to a specific addressable area."""
         # Check for presence of heater shakers on deck, and if planned
@@ -201,6 +210,7 @@ class MovementHandler:
             minimum_z_height=minimum_z_height,
             stay_at_max_travel_z=stay_at_highest_possible_z,
             ignore_tip_configuration=ignore_tip_configuration,
+            max_travel_z_extra_margin=highest_possible_z_extra_offset,
         )
 
         speed = self._state_store.pipettes.get_movement_speed(

opentrons/protocol_engine/execution/pipetting.py

@@ -5,7 +5,8 @@ from contextlib import contextmanager
 
 from opentrons.hardware_control import HardwareControlAPI
 
-from ..state import StateView, HardwarePipette
+from ..state.state import StateView
+from ..state.pipettes import HardwarePipette
 from ..notes import CommandNoteAdder, CommandNote
 from ..errors.exceptions import (
     TipNotAttachedError,
@@ -186,7 +187,9 @@ class HardwarePipettingHandler(PipettingHandler):
             mount=hw_pipette.mount,
             max_z_dist=well_depth - lld_min_height + well_location.offset.z,
         )
-        return float(z_pos)
+        labware_pos = self._state_view.geometry.get_labware_position(labware_id)
+        relative_height = z_pos - labware_pos.z - well_def.z
+        return float(relative_height)
 
     @contextmanager
     def _set_flow_rate(
@@ -285,8 +288,8 @@ class VirtualPipettingHandler(PipettingHandler):
         well_location: WellLocation,
     ) -> float:
         """Detect liquid level."""
-        # TODO (pm, 6-18-24): return a value of worth if needed
-        return 0.0
+        well_def = self._state_view.labware.get_well_definition(labware_id, well_name)
+        return well_def.depth
 
     def _validate_tip_attached(self, pipette_id: str, command_name: str) -> None:
         """Validate if there is a tip attached."""

opentrons/protocol_engine/execution/queue_worker.py

@@ -3,7 +3,7 @@ import asyncio
 from logging import getLogger
 from typing import Optional, AsyncGenerator, Callable
 
-from ..state import StateStore
+from ..state.state import StateStore
 from .command_executor import CommandExecutor
 
 log = getLogger(__name__)
@@ -69,7 +69,11 @@ class QueueWorker:
 
     async def _run_commands(self) -> None:
         async for command_id in self._command_generator():
-            await self._command_executor.execute(command_id=command_id)
+            try:
+                await self._command_executor.execute(command_id=command_id)
+            except BaseException:
+                log.exception("Unhandled failure in command executor")
+                raise
             # Yield to the event loop in case we're executing a long sequence of commands
             # that never yields internally. For example, a long sequence of comment commands.
             await asyncio.sleep(0)

opentrons/protocol_engine/execution/run_control.py

@@ -1,7 +1,7 @@
 """Run control command side-effect logic."""
 import asyncio
 
-from ..state import StateStore
+from ..state.state import StateStore
 from ..actions import ActionDispatcher, PauseAction, PauseSource
 
 

opentrons/protocol_engine/execution/thermocycler_movement_flagger.py

@@ -7,7 +7,7 @@ from opentrons.hardware_control import HardwareControlAPI
 from opentrons.hardware_control.modules import Thermocycler as HardwareThermocycler
 
 from ..types import ModuleLocation, LabwareLocation
-from ..state import StateStore
+from ..state.state import StateStore
 from ..errors import ThermocyclerNotOpenError, WrongModuleTypeError
 
 

opentrons/protocol_engine/execution/thermocycler_plate_lifter.py

@@ -5,7 +5,8 @@ import asyncio
 from typing import TYPE_CHECKING, AsyncGenerator, Optional
 from opentrons.hardware_control.modules.thermocycler import Thermocycler
 from opentrons.protocol_engine.types import LabwareLocation, ModuleLocation, ModuleModel
-from opentrons.protocol_engine.state import StateStore, ThermocyclerModuleId
+from opentrons.protocol_engine.state.state import StateStore
+from opentrons.protocol_engine.state.module_substates import ThermocyclerModuleId
 from contextlib import asynccontextmanager
 
 if TYPE_CHECKING:

opentrons/protocol_engine/execution/tip_handler.py

@@ -4,6 +4,9 @@ from typing_extensions import Protocol as TypingProtocol
 
 from opentrons.hardware_control import HardwareControlAPI
 from opentrons.hardware_control.types import FailedTipStateCheck, InstrumentProbeType
+from opentrons.protocol_engine.errors.exceptions import PickUpTipTipNotAttachedError
+from opentrons.types import Mount
+
 from opentrons_shared_data.errors.exceptions import (
     CommandPreconditionViolated,
     CommandParameterLimitViolated,
@@ -11,7 +14,7 @@ from opentrons_shared_data.errors.exceptions import (
 )
 
 from ..resources import LabwareDataProvider, ensure_ot3_hardware
-from ..state import StateView
+from ..state.state import StateView
 from ..types import TipGeometry, TipPresenceStatus
 from ..errors import (
     HardwareNotSupportedError,
@@ -68,18 +71,27 @@ class TipHandler(TypingProtocol):
 
         Returns:
             Tip geometry of the picked up tip.
+
+        Raises:
+            PickUpTipTipNotAttachedError
         """
         ...
 
     async def drop_tip(self, pipette_id: str, home_after: Optional[bool]) -> None:
-        """Drop the attached tip into the named location.
+        """Drop the attached tip into the current location.
 
         Pipette should be in place over the destination prior to calling this method.
+
+        Raises:
+            TipAttachedError
         """
 
-    async def add_tip(self, pipette_id: str, tip: TipGeometry) -> None:
+    def cache_tip(self, pipette_id: str, tip: TipGeometry) -> None:
         """Tell the Hardware API that a tip is attached."""
 
+    def remove_tip(self, pipette_id: str) -> None:
+        """Tell the hardware API that no tip is attached."""
+
     async def get_tip_presence(self, pipette_id: str) -> TipPresenceStatus:
         """Get tip presence status on the pipette."""
 
@@ -89,7 +101,12 @@ class TipHandler(TypingProtocol):
         expected: TipPresenceStatus,
         follow_singular_sensor: Optional[InstrumentProbeType] = None,
     ) -> None:
-        """Verify the expected tip presence status."""
+        """Use sensors to verify that a tip is or is not physically attached.
+
+        Raises:
+            TipNotAttachedError or TipAttachedError, as appropriate, if the physical
+            status doesn't match what was expected.
+        """
 
 
 async def _available_for_nozzle_layout(  # noqa: C901
@@ -187,6 +204,11 @@ class HardwareTipHandler(TipHandler):
         self._labware_data_provider = labware_data_provider or LabwareDataProvider()
         self._state_view = state_view
 
+        # WARNING: ErrorRecoveryHardwareStateSynchronizer can currently construct several
+        # instances of this class per run, in addition to the main instance used
+        # for command execution. We're therefore depending on this class being
+        # stateless, so consider that before adding additional attributes here.
+
     async def available_for_nozzle_layout(
         self,
         pipette_id: str,
@@ -195,7 +217,7 @@ class HardwareTipHandler(TipHandler):
         front_right_nozzle: Optional[str] = None,
         back_left_nozzle: Optional[str] = None,
     ) -> Dict[str, str]:
-        """Returns configuration for nozzle layout to pass to configure_nozzle_layout."""
+        """See documentation on abstract base class."""
         if self._state_view.pipettes.get_attached_tip(pipette_id):
             raise CommandPreconditionViolated(
                 message=f"Cannot configure nozzle layout of {str(self)} while it has tips attached."
@@ -211,8 +233,8 @@ class HardwareTipHandler(TipHandler):
         labware_id: str,
         well_name: str,
     ) -> TipGeometry:
-        """Pick up a tip at the current location using the Hardware API."""
-        hw_mount = self._state_view.pipettes.get_mount(pipette_id).to_hw_mount()
+        """See documentation on abstract base class."""
+        hw_mount = self._get_hw_mount(pipette_id)
 
         nominal_tip_geometry = self._state_view.geometry.get_nominal_tip_geometry(
             pipette_id=pipette_id, labware_id=labware_id, well_name=well_name
@@ -224,33 +246,29 @@ class HardwareTipHandler(TipHandler):
             nominal_fallback=nominal_tip_geometry.length,
         )
 
+        tip_geometry = TipGeometry(
+            length=actual_tip_length,
+            diameter=nominal_tip_geometry.diameter,
+            volume=nominal_tip_geometry.volume,
+        )
+
         await self._hardware_api.tip_pickup_moves(
             mount=hw_mount, presses=None, increment=None
         )
-        await self.verify_tip_presence(pipette_id, TipPresenceStatus.PRESENT)
+        try:
+            await self.verify_tip_presence(pipette_id, TipPresenceStatus.PRESENT)
+        except TipNotAttachedError as e:
+            raise PickUpTipTipNotAttachedError(tip_geometry=tip_geometry) from e
 
-        self._hardware_api.cache_tip(hw_mount, actual_tip_length)
-        await self._hardware_api.prepare_for_aspirate(hw_mount)
+        self.cache_tip(pipette_id, tip_geometry)
 
-        self._hardware_api.set_current_tiprack_diameter(
-            mount=hw_mount,
-            tiprack_diameter=nominal_tip_geometry.diameter,
-        )
-
-        self._hardware_api.set_working_volume(
-            mount=hw_mount,
-            tip_volume=nominal_tip_geometry.volume,
-        )
+        await self._hardware_api.prepare_for_aspirate(hw_mount)
 
-        return TipGeometry(
-            length=actual_tip_length,
-            diameter=nominal_tip_geometry.diameter,
-            volume=nominal_tip_geometry.volume,
-        )
+        return tip_geometry
 
     async def drop_tip(self, pipette_id: str, home_after: Optional[bool]) -> None:
-        """Drop a tip at the current location using the Hardware API."""
-        hw_mount = self._state_view.pipettes.get_mount(pipette_id).to_hw_mount()
+        """See documentation on abstract base class."""
+        hw_mount = self._get_hw_mount(pipette_id)
 
         # Let the hardware controller handle defaulting home_after since its behavior
         # differs between machines
@@ -259,14 +277,18 @@ class HardwareTipHandler(TipHandler):
         else:
             kwargs = {}
 
-        await self._hardware_api.drop_tip(mount=hw_mount, **kwargs)
+        await self._hardware_api.tip_drop_moves(mount=hw_mount, **kwargs)
+
+        # Allow TipNotAttachedError to propagate.
         await self.verify_tip_presence(pipette_id, TipPresenceStatus.ABSENT)
 
-    async def add_tip(self, pipette_id: str, tip: TipGeometry) -> None:
-        """Tell the Hardware API that a tip is attached."""
-        hw_mount = self._state_view.pipettes.get_mount(pipette_id).to_hw_mount()
+        self.remove_tip(pipette_id)
 
-        await self._hardware_api.add_tip(mount=hw_mount, tip_length=tip.length)
+    def cache_tip(self, pipette_id: str, tip: TipGeometry) -> None:
+        """See documentation on abstract base class."""
+        hw_mount = self._get_hw_mount(pipette_id)
+
+        self._hardware_api.cache_tip(mount=hw_mount, tip_length=tip.length)
 
         self._hardware_api.set_current_tiprack_diameter(
             mount=hw_mount,
@@ -278,12 +300,18 @@ class HardwareTipHandler(TipHandler):
             tip_volume=tip.volume,
         )
 
+    def remove_tip(self, pipette_id: str) -> None:
+        """See documentation on abstract base class."""
+        hw_mount = self._get_hw_mount(pipette_id)
+        self._hardware_api.remove_tip(hw_mount)
+        self._hardware_api.set_current_tiprack_diameter(hw_mount, 0)
+
     async def get_tip_presence(self, pipette_id: str) -> TipPresenceStatus:
-        """Get the tip presence status of the pipette."""
+        """See documentation on abstract base class."""
         try:
             ot3api = ensure_ot3_hardware(hardware_api=self._hardware_api)
 
-            hw_mount = self._state_view.pipettes.get_mount(pipette_id).to_hw_mount()
+            hw_mount = self._get_hw_mount(pipette_id)
 
             status = await ot3api.get_tip_presence_status(hw_mount)
             return TipPresenceStatus.from_hw_state(status)
@@ -297,11 +325,7 @@ class HardwareTipHandler(TipHandler):
         expected: TipPresenceStatus,
         follow_singular_sensor: Optional[InstrumentProbeType] = None,
     ) -> None:
-        """Verify the expecterd tip presence status of the pipette.
-
-        This function will raise an exception if the specified tip presence status
-        isn't matched.
-        """
+        """See documentation on abstract base class."""
         nozzle_configuration = (
             self._state_view.pipettes.state.nozzle_configuration_by_id[pipette_id]
         )
@@ -328,7 +352,7 @@ class HardwareTipHandler(TipHandler):
             return
         try:
             ot3api = ensure_ot3_hardware(hardware_api=self._hardware_api)
-            hw_mount = self._state_view.pipettes.get_mount(pipette_id).to_hw_mount()
+            hw_mount = self._get_hw_mount(pipette_id)
             await ot3api.verify_tip_presence(
                 hw_mount, expected.to_hw_state(), follow_singular_sensor
             )
@@ -346,6 +370,9 @@ class HardwareTipHandler(TipHandler):
                     wrapping=[PythonException(e)],
                 )
 
+    def _get_hw_mount(self, pipette_id: str) -> Mount:
+        return self._state_view.pipettes.get_mount(pipette_id).to_hw_mount()
+
 
 class VirtualTipHandler(TipHandler):
     """Pick up and drop tips, using a virtual pipette."""
@@ -385,7 +412,7 @@ class VirtualTipHandler(TipHandler):
         front_right_nozzle: Optional[str] = None,
         back_left_nozzle: Optional[str] = None,
     ) -> Dict[str, str]:
-        """Returns configuration for nozzle layout to pass to configure_nozzle_layout."""
+        """See documentation on abstract base class."""
         if self._state_view.pipettes.get_attached_tip(pipette_id):
             raise CommandPreconditionViolated(
                 message=f"Cannot configure nozzle layout of {str(self)} while it has tips attached."
@@ -409,12 +436,19 @@ class VirtualTipHandler(TipHandler):
             expected_has_tip=True,
         )
 
-    async def add_tip(self, pipette_id: str, tip: TipGeometry) -> None:
-        """Add a tip using a virtual pipette.
+    def cache_tip(self, pipette_id: str, tip: TipGeometry) -> None:
+        """See documentation on abstract base class.
+
+        This should not be called when using virtual pipettes.
+        """
+        assert False, "TipHandler.cache_tip should not be used with virtual pipettes"
+
+    def remove_tip(self, pipette_id: str) -> None:
+        """See documentation on abstract base class.
 
         This should not be called when using virtual pipettes.
         """
-        assert False, "TipHandler.add_tip should not be used with virtual pipettes"
+        assert False, "TipHandler.remove_tip should not be used with virtual pipettes"
 
     async def verify_tip_presence(
         self,

opentrons/protocol_engine/notes/__init__.py

@@ -1,5 +1,17 @@
 """Protocol engine notes module."""
 
-from .notes import NoteKind, CommandNote, CommandNoteAdder, CommandNoteTracker
+from .notes import (
+    NoteKind,
+    CommandNote,
+    CommandNoteAdder,
+    CommandNoteTracker,
+    make_error_recovery_debug_note,
+)
 
-__all__ = ["NoteKind", "CommandNote", "CommandNoteAdder", "CommandNoteTracker"]
+__all__ = [
+    "NoteKind",
+    "CommandNote",
+    "CommandNoteAdder",
+    "CommandNoteTracker",
+    "make_error_recovery_debug_note",
+]

opentrons/protocol_engine/notes/notes.py

@@ -1,7 +1,10 @@
 """Definitions of data and interface shapes for notes."""
-from typing import Union, Literal, Protocol, List
+from typing import Union, Literal, Protocol, List, TYPE_CHECKING
 from pydantic import BaseModel, Field
 
+if TYPE_CHECKING:
+    from opentrons.protocol_engine.error_recovery_policy import ErrorRecoveryType
+
 NoteKind = Union[Literal["warning", "information"], str]
 
 
@@ -26,6 +29,20 @@ class CommandNote(BaseModel):
     )
 
 
+def make_error_recovery_debug_note(type: "ErrorRecoveryType") -> CommandNote:
+    """Return a note for debugging error recovery.
+
+    This is intended to be read by developers and support people, not computers.
+    """
+    message = f"Handling this command failure with {type.name}."
+    return CommandNote.construct(
+        noteKind="debugErrorRecovery",
+        shortMessage=message,
+        longMessage=message,
+        source="execution",
+    )
+
+
 class CommandNoteAdder(Protocol):
     """The shape of a function that something can use to add a command note."""
 

opentrons/protocol_engine/plugins.py

@@ -5,7 +5,7 @@ from typing import List
 from typing_extensions import final
 
 from .actions import Action, ActionDispatcher, ActionHandler
-from .state import StateView
+from .state.state import StateView
 
 
 class AbstractPlugin(ActionHandler, ABC):