opentrons 8.3.1a1__py2.py3-none-any.whl → 8.4.0a1__py2.py3-none-any.whl

opentrons/protocol_engine/commands/flex_stacker/set_stored_labware.py

@@ -0,0 +1,190 @@
+"""Command models to configure the stored labware pool of a Flex Stacker.."""
+
+from __future__ import annotations
+from typing import Optional, Literal, TYPE_CHECKING
+from typing_extensions import Type
+
+from pydantic import BaseModel, Field
+
+from opentrons_shared_data.labware.labware_definition import LabwareDefinition
+
+from ..command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ...errors import (
+    ErrorOccurrence,
+)
+from ...errors.exceptions import FlexStackerNotLogicallyEmptyError
+from ...state import update_types
+
+if TYPE_CHECKING:
+    from opentrons.protocol_engine.state.state import StateView
+    from opentrons.protocol_engine.execution import EquipmentHandler
+
+SetStoredLabwareCommandType = Literal["flexStacker/setStoredLabware"]
+
+
+class StackerStoredLabwareDetails(BaseModel):
+    """The parameters defining a labware to be stored in the stacker."""
+
+    loadName: str = Field(
+        ..., description="Name used to reference the definition of this labware."
+    )
+    namespace: str = Field(
+        ..., description="Namespace of the definition of this labware."
+    )
+    version: int = Field(..., description="Version of the definition of this labware.")
+
+
+class SetStoredLabwareParams(BaseModel):
+    """Input parameters for a setStoredLabware command."""
+
+    moduleId: str = Field(
+        ...,
+        description="Unique ID of the Flex Stacker.",
+    )
+    primaryLabware: StackerStoredLabwareDetails = Field(
+        ...,
+        description="The details of the primary labware (i.e. not the lid or adapter, if any) stored in the stacker.",
+    )
+    lidLabware: StackerStoredLabwareDetails | None = Field(
+        default=None,
+        description="The details of the lid on the primary labware, if any.",
+    )
+    adapterLabware: StackerStoredLabwareDetails | None = Field(
+        default=None,
+        description="The details of the adapter under the primary labware, if any.",
+    )
+    initialCount: int | None = Field(
+        None,
+        description=(
+            "The number of labware that should be initially stored in the stacker. This number will be silently clamped to "
+            "the maximum number of labware that will fit; do not rely on the parameter to know how many labware are in the stacker."
+        ),
+        ge=0,
+    )
+
+
+class SetStoredLabwareResult(BaseModel):
+    """Result data from a setstoredlabware command."""
+
+    primaryLabwareDefinition: LabwareDefinition = Field(
+        ..., description="The definition of the primary labware."
+    )
+    lidLabwareDefinition: LabwareDefinition | None = Field(
+        ..., description="The definition of the lid on the primary labware, if any."
+    )
+    adapterLabwareDefinition: LabwareDefinition | None = Field(
+        ...,
+        description="The definition of the adapter under the primary labware, if any.",
+    )
+    count: int = Field(
+        ..., description="The number of labware loaded into the stacker labware pool."
+    )
+
+
+class SetStoredLabwareImpl(
+    AbstractCommandImpl[SetStoredLabwareParams, SuccessData[SetStoredLabwareResult]]
+):
+    """Implementation of a setstoredlabware command."""
+
+    def __init__(
+        self,
+        state_view: StateView,
+        equipment: EquipmentHandler,
+        **kwargs: object,
+    ) -> None:
+        self._state_view = state_view
+        self._equipment = equipment
+
+    async def execute(
+        self, params: SetStoredLabwareParams
+    ) -> SuccessData[SetStoredLabwareResult]:
+        """Execute the setstoredlabwarecommand."""
+        stacker_state = self._state_view.modules.get_flex_stacker_substate(
+            params.moduleId
+        )
+
+        if stacker_state.pool_count != 0:
+            # Note: this error catches if the protocol tells us the stacker is not empty, making this command
+            # invalid at this point in the protocol. This error is not recoverable and should occur during
+            # analysis; the protocol must be changed.
+
+            raise FlexStackerNotLogicallyEmptyError(
+                message=(
+                    "The Flex Stacker must be known to be empty before reconfiguring its labware pool, but it has "
+                    f"a pool of {stacker_state.pool_count} labware"
+                )
+            )
+
+        labware_def, _ = await self._equipment.load_definition_for_details(
+            load_name=params.primaryLabware.loadName,
+            namespace=params.primaryLabware.namespace,
+            version=params.primaryLabware.version,
+        )
+        lid_def: LabwareDefinition | None = None
+        if params.lidLabware:
+            lid_def, _ = await self._equipment.load_definition_for_details(
+                load_name=params.lidLabware.loadName,
+                namespace=params.lidLabware.namespace,
+                version=params.lidLabware.version,
+            )
+        adapter_def: LabwareDefinition | None = None
+        if params.adapterLabware:
+            adapter_def, _ = await self._equipment.load_definition_for_details(
+                load_name=params.adapterLabware.loadName,
+                namespace=params.adapterLabware.namespace,
+                version=params.adapterLabware.version,
+            )
+
+        self._state_view.labware.raise_if_stacker_labware_pool_is_not_valid(
+            labware_def, lid_def, adapter_def
+        )
+
+        pool_height = self._state_view.geometry.get_height_of_labware_stack(
+            [x for x in [lid_def, labware_def, adapter_def] if x is not None]
+        )
+        max_pool_count = self._state_view.modules.stacker_max_pool_count_by_height(
+            params.moduleId, pool_height
+        )
+
+        initial_count = (
+            params.initialCount if params.initialCount is not None else max_pool_count
+        )
+        count = min(initial_count, max_pool_count)
+
+        state_update = (
+            update_types.StateUpdate()
+            .update_flex_stacker_labware_pool_definition(
+                params.moduleId, max_pool_count, labware_def, adapter_def, lid_def
+            )
+            .update_flex_stacker_labware_pool_count(params.moduleId, count)
+        )
+        return SuccessData(
+            public=SetStoredLabwareResult.model_construct(
+                primaryLabwareDefinition=labware_def,
+                lidLabwareDefinition=lid_def,
+                adapterLabwareDefinition=adapter_def,
+                count=count,
+            ),
+            state_update=state_update,
+        )
+
+
+class SetStoredLabware(
+    BaseCommand[SetStoredLabwareParams, SetStoredLabwareResult, ErrorOccurrence]
+):
+    """A command to setstoredlabware the Flex Stacker."""
+
+    commandType: SetStoredLabwareCommandType = "flexStacker/setStoredLabware"
+    params: SetStoredLabwareParams
+    result: Optional[SetStoredLabwareResult] = None
+
+    _ImplementationCls: Type[SetStoredLabwareImpl] = SetStoredLabwareImpl
+
+
+class SetStoredLabwareCreate(BaseCommandCreate[SetStoredLabwareParams]):
+    """A request to execute a Flex Stacker SetStoredLabware command."""
+
+    commandType: SetStoredLabwareCommandType = "flexStacker/setStoredLabware"
+    params: SetStoredLabwareParams
+
+    _CommandCls: Type[SetStoredLabware] = SetStoredLabware

opentrons/protocol_engine/commands/flex_stacker/store.py

@@ -0,0 +1,288 @@
+"""Command models to retrieve a labware from a Flex Stacker."""
+
+from __future__ import annotations
+from typing import Optional, Literal, TYPE_CHECKING, Type, Union
+
+from pydantic import BaseModel, Field
+
+from ..command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    SuccessData,
+    DefinedErrorData,
+)
+from ..flex_stacker.common import FlexStackerStallOrCollisionError
+from ...errors import (
+    ErrorOccurrence,
+    CannotPerformModuleAction,
+    LabwareNotLoadedOnModuleError,
+    FlexStackerLabwarePoolNotYetDefinedError,
+)
+from ...resources import ModelUtils
+from ...state import update_types
+from ...types import (
+    LabwareLocationSequence,
+    InStackerHopperLocation,
+)
+
+from opentrons_shared_data.errors.exceptions import FlexStackerStallError
+from opentrons.calibration_storage.helpers import uri_from_details
+
+
+if TYPE_CHECKING:
+    from opentrons.protocol_engine.state.state import StateView
+    from opentrons.protocol_engine.state.module_substates import FlexStackerSubState
+    from opentrons.protocol_engine.execution import EquipmentHandler
+
+
+StoreCommandType = Literal["flexStacker/store"]
+
+
+class StoreParams(BaseModel):
+    """Input parameters for a labware storage command."""
+
+    moduleId: str = Field(
+        ...,
+        description="Unique ID of the flex stacker.",
+    )
+
+
+class StoreResult(BaseModel):
+    """Result data from a labware storage command."""
+
+    eventualDestinationLocationSequence: LabwareLocationSequence | None = Field(
+        None,
+        description=(
+            "The full location in which all labware moved by this command will eventually reside."
+        ),
+    )
+    primaryOriginLocationSequence: LabwareLocationSequence | None = Field(
+        None, description=("The origin location of the primary labware.")
+    )
+    primaryLabwareId: str | None = Field(
+        None, description="The primary labware in the stack that was stored."
+    )
+    adapterOriginLocationSequence: LabwareLocationSequence | None = Field(
+        None, description=("The origin location of the adapter labware, if any.")
+    )
+    adapterLabwareId: str | None = Field(
+        None, description="The adapter in the stack that was stored, if any."
+    )
+    lidOriginLocationSequence: LabwareLocationSequence | None = Field(
+        None, description=("The origin location of the lid labware, if any.")
+    )
+    lidLabwareId: str | None = Field(
+        None, description="The lid in the stack that was stored, if any."
+    )
+    primaryLabwareURI: str = Field(
+        ...,
+        description="The labware definition URI of the primary labware.",
+    )
+    adapterLabwareURI: str | None = Field(
+        None,
+        description="The labware definition URI of the adapter labware.",
+    )
+    lidLabwareURI: str | None = Field(
+        None,
+        description="The labware definition URI of the lid labware.",
+    )
+
+
+_ExecuteReturn = Union[
+    SuccessData[StoreResult],
+    DefinedErrorData[FlexStackerStallOrCollisionError],
+]
+
+
+class StoreImpl(AbstractCommandImpl[StoreParams, _ExecuteReturn]):
+    """Implementation of a labware storage command."""
+
+    def __init__(
+        self,
+        state_view: StateView,
+        equipment: EquipmentHandler,
+        model_utils: ModelUtils,
+        **kwargs: object,
+    ) -> None:
+        self._state_view = state_view
+        self._equipment = equipment
+        self._model_utils = model_utils
+
+    def _verify_labware_to_store(
+        self, params: StoreParams, stacker_state: FlexStackerSubState
+    ) -> tuple[str, str | None, str | None]:
+        try:
+            bottom_id = self._state_view.labware.get_id_by_module(params.moduleId)
+        except LabwareNotLoadedOnModuleError:
+            raise CannotPerformModuleAction(
+                "Cannot store labware if Flex Stacker carriage is empty"
+            )
+        labware_ids = self._state_view.labware.get_labware_stack_from_parent(bottom_id)
+        labware_defs = [
+            self._state_view.labware.get_definition(id) for id in labware_ids
+        ]
+
+        lid_id: str | None = None
+
+        pool_list = stacker_state.get_pool_definition_ordered_list()
+        assert pool_list is not None
+        if len(labware_ids) != len(pool_list):
+            raise CannotPerformModuleAction(
+                "Cannot store labware stack that does not correspond with Flex Stacker configuration"
+            )
+        if stacker_state.pool_lid_definition is not None:
+            if labware_defs[-1] != stacker_state.pool_lid_definition:
+                raise CannotPerformModuleAction(
+                    "Cannot store labware stack that does not correspond with Flex Stacker configuration"
+                )
+            lid_id = labware_ids[-1]
+
+        if stacker_state.pool_adapter_definition is not None:
+            if (
+                labware_defs[0] != stacker_state.pool_adapter_definition
+                or labware_defs[1] != stacker_state.pool_primary_definition
+            ):
+                raise CannotPerformModuleAction(
+                    "Cannot store labware stack that does not correspond with Flex Stacker configuration"
+                )
+            else:
+                return labware_ids[1], labware_ids[0], lid_id
+        else:
+            if labware_defs[0] != stacker_state.pool_primary_definition:
+                raise CannotPerformModuleAction(
+                    "Cannot store labware stack that does not correspond with Flex Stacker configuration"
+                )
+            return labware_ids[0], None, lid_id
+
+    async def execute(self, params: StoreParams) -> _ExecuteReturn:
+        """Execute the labware storage command."""
+        stacker_state = self._state_view.modules.get_flex_stacker_substate(
+            params.moduleId
+        )
+
+        if stacker_state.pool_count == stacker_state.max_pool_count:
+            raise CannotPerformModuleAction(
+                "Cannot store labware in Flex Stacker while it is full"
+            )
+
+        pool_definitions = stacker_state.get_pool_definition_ordered_list()
+        if pool_definitions is None:
+            raise FlexStackerLabwarePoolNotYetDefinedError(
+                message="The Flex Stacker has not been configured yet and cannot be filled."
+            )
+
+        primary_id, maybe_adapter_id, maybe_lid_id = self._verify_labware_to_store(
+            params, stacker_state
+        )
+
+        # Allow propagation of ModuleNotAttachedError.
+        stacker_hw = self._equipment.get_module_hardware_api(stacker_state.module_id)
+
+        eventual_target_location_sequence = (
+            self._state_view.geometry.get_predicted_location_sequence(
+                InStackerHopperLocation(moduleId=params.moduleId)
+            )
+        )
+        stack_height = self._state_view.geometry.get_height_of_labware_stack(
+            pool_definitions
+        )
+
+        state_update = update_types.StateUpdate()
+        try:
+            if stacker_hw is not None:
+                await stacker_hw.store_labware(labware_height=stack_height)
+        except FlexStackerStallError as e:
+            return DefinedErrorData(
+                public=FlexStackerStallOrCollisionError(
+                    id=self._model_utils.generate_id(),
+                    createdAt=self._model_utils.get_timestamp(),
+                    wrappedErrors=[
+                        ErrorOccurrence.from_failed(
+                            id=self._model_utils.generate_id(),
+                            createdAt=self._model_utils.get_timestamp(),
+                            error=e,
+                        )
+                    ],
+                ),
+            )
+
+        id_list = [
+            id for id in (primary_id, maybe_adapter_id, maybe_lid_id) if id is not None
+        ]
+
+        state_update.set_batch_labware_location(
+            new_locations_by_id={
+                id: InStackerHopperLocation(moduleId=params.moduleId) for id in id_list
+            },
+            new_offset_ids_by_id={id: None for id in id_list},
+        )
+
+        state_update.update_flex_stacker_labware_pool_count(
+            module_id=params.moduleId, count=stacker_state.pool_count + 1
+        )
+        if stacker_state.pool_primary_definition is None:
+            raise FlexStackerLabwarePoolNotYetDefinedError(
+                "The Primary Labware must be defined in the stacker pool."
+            )
+
+        return SuccessData(
+            public=StoreResult(
+                eventualDestinationLocationSequence=eventual_target_location_sequence,
+                primaryOriginLocationSequence=self._state_view.geometry.get_location_sequence(
+                    primary_id
+                ),
+                primaryLabwareId=primary_id,
+                adapterOriginLocationSequence=(
+                    self._state_view.geometry.get_location_sequence(maybe_adapter_id)
+                    if maybe_adapter_id is not None
+                    else None
+                ),
+                adapterLabwareId=maybe_adapter_id,
+                lidOriginLocationSequence=(
+                    self._state_view.geometry.get_location_sequence(maybe_lid_id)
+                    if maybe_lid_id is not None
+                    else None
+                ),
+                lidLabwareId=maybe_lid_id,
+                primaryLabwareURI=uri_from_details(
+                    stacker_state.pool_primary_definition.namespace,
+                    stacker_state.pool_primary_definition.parameters.loadName,
+                    stacker_state.pool_primary_definition.version,
+                ),
+                adapterLabwareURI=uri_from_details(
+                    stacker_state.pool_adapter_definition.namespace,
+                    stacker_state.pool_adapter_definition.parameters.loadName,
+                    stacker_state.pool_adapter_definition.version,
+                )
+                if stacker_state.pool_adapter_definition is not None
+                else None,
+                lidLabwareURI=uri_from_details(
+                    stacker_state.pool_lid_definition.namespace,
+                    stacker_state.pool_lid_definition.parameters.loadName,
+                    stacker_state.pool_lid_definition.version,
+                )
+                if stacker_state.pool_lid_definition is not None
+                else None,
+            ),
+            state_update=state_update,
+        )
+
+
+class Store(BaseCommand[StoreParams, StoreResult, ErrorOccurrence]):
+    """A command to store a labware in a Flex Stacker."""
+
+    commandType: StoreCommandType = "flexStacker/store"
+    params: StoreParams
+    result: Optional[StoreResult] = None
+
+    _ImplementationCls: Type[StoreImpl] = StoreImpl
+
+
+class StoreCreate(BaseCommandCreate[StoreParams]):
+    """A request to execute a Flex Stacker store command."""
+
+    commandType: StoreCommandType = "flexStacker/store"
+    params: StoreParams
+
+    _CommandCls: Type[Store] = Store

opentrons/protocol_engine/commands/generate_command_schema.py

@@ -5,6 +5,9 @@ import argparse
 import sys
 from opentrons.protocol_engine.commands.command_unions import CommandCreateAdapter
 
+from opentrons_shared_data.command import get_newest_schema_version
+from opentrons_shared_data.load import get_shared_data_root
+
 
 def generate_command_schema(version: str) -> str:
     """Generate a JSON Schema that all valid create commands can validate against."""
@@ -14,6 +17,13 @@ def generate_command_schema(version: str) -> str:
     return json.dumps(schema_as_dict, indent=2, sort_keys=True)
 
 
+def write_command_schema(json_string: str, version: str) -> None:
+    """Write a JSON command schema to the shared-data command schema directory."""
+    path = get_shared_data_root() / "command" / "schemas" / f"{version}.json"
+    with open(path, "w") as schema_file:
+        schema_file.write(json_string)
+
+
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(
         prog="generate_command_schema",
@@ -22,10 +32,29 @@ if __name__ == "__main__":
     parser.add_argument(
         "version",
         type=str,
-        help="The command schema version. This is a single integer (e.g. 7) that will be used to name the generated schema file",
+        nargs="?",
+        help="The command schema version. This is a single integer (e.g. 7) that will be used to name the generated"
+        " schema file. If not included, it will automatically use the latest version in shared-data.",
+    )
+    parser.add_argument(
+        "--overwrite-shared-data",
+        action="store_true",
+        help="If used, overwrites the specified or automatically chosen command schema version in shared-data."
+        " If not included, the generated schema will be printed to stdout.",
     )
     args = parser.parse_args()
-    print(generate_command_schema(args.version))
+
+    if args.version is None:
+        version_string = get_newest_schema_version()
+    else:
+        version_string = args.version
+
+    command_schema = generate_command_schema(version_string)
+
+    if args.overwrite_shared_data:
+        write_command_schema(command_schema, version_string)
+    else:
+        print(command_schema)
 
     sys.exit()
 

opentrons/protocol_engine/commands/labware_handling_common.py

@@ -0,0 +1,24 @@
+"""Helpers for commands that alter the position of labware."""
+
+from pydantic import BaseModel, Field
+
+from ..types import LabwareLocationSequence
+
+
+class LabwareHandlingResultMixin(BaseModel):
+    """A result for commands that create a labware entity."""
+
+    labwareId: str = Field(..., description="The id of the labware.")
+    locationSequence: LabwareLocationSequence | None = Field(
+        None,
+        description="The full location down to the deck on which this labware exists.",
+    )
+
+
+class LabwarePositionResultMixin(LabwareHandlingResultMixin):
+    """A result for commands that create an offsetable labware entity."""
+
+    offsetId: str | None = Field(
+        None,
+        description="An ID referencing the labware offset that will apply to this labware in this location.",
+    )

opentrons/protocol_engine/commands/liquid_probe.py

@@ -23,6 +23,7 @@ from opentrons_shared_data.errors.exceptions import (
 )
 
 from ..types import DeckPoint
+from ..types.liquid_level_detection import LiquidTrackingType
 from .pipetting_common import (
     LiquidNotFoundError,
     PipetteIdMixin,
@@ -80,7 +81,7 @@ class TryLiquidProbeParams(_CommonParams):
 class LiquidProbeResult(DestinationPositionResult):
     """Result data from the execution of a `liquidProbe` command."""
 
-    z_position: float = Field(
+    z_position: LiquidTrackingType = Field(
         ..., description="The Z coordinate, in mm, of the found liquid in deck space."
     )
     # New fields should use camelCase. z_position is snake_case for historical reasons.
@@ -89,7 +90,7 @@ class LiquidProbeResult(DestinationPositionResult):
 class TryLiquidProbeResult(DestinationPositionResult):
     """Result data from the execution of a `tryLiquidProbe` command."""
 
-    z_position: float | SkipJsonSchema[None] = Field(
+    z_position: Union[LiquidTrackingType, SkipJsonSchema[None]] = Field(
         ...,
         description=(
             "The Z coordinate, in mm, of the found liquid in deck space."
@@ -116,8 +117,7 @@ class _ExecuteCommonResult(NamedTuple):
     # If the probe succeeded, the z_pos that it returned.
     # Or, if the probe found no liquid, the error representing that,
     # so calling code can propagate those details up.
-    z_pos_or_error: float | PipetteLiquidNotFoundError | PipetteOverpressureError
-
+    z_pos_or_error: LiquidTrackingType | PipetteLiquidNotFoundError | PipetteOverpressureError
     state_update: update_types.StateUpdate
     deck_point: DeckPoint
 
@@ -190,6 +190,9 @@ async def _execute_common(  # noqa: C901
             well_location=params.wellLocation,
         )
     except PipetteLiquidNotFoundError as exception:
+        move_result.state_update.set_pipette_ready_to_aspirate(
+            pipette_id=pipette_id, ready_to_aspirate=True
+        )
         return _ExecuteCommonResult(
             z_pos_or_error=exception,
             state_update=move_result.state_update,
@@ -223,6 +226,9 @@ async def _execute_common(  # noqa: C901
             ),
         )
     else:
+        move_result.state_update.set_pipette_ready_to_aspirate(
+            pipette_id=pipette_id, ready_to_aspirate=True
+        )
         return _ExecuteCommonResult(
             z_pos_or_error=z_pos,
             state_update=move_result.state_update,
@@ -303,12 +309,13 @@ class LiquidProbeImplementation(
             )
         else:
             try:
-                well_volume: float | update_types.ClearType = (
-                    self._state_view.geometry.get_well_volume_at_height(
-                        labware_id=params.labwareId,
-                        well_name=params.wellName,
-                        height=z_pos_or_error,
-                    )
+                well_volume: Union[
+                    LiquidTrackingType,
+                    update_types.ClearType,
+                ] = self._state_view.geometry.get_well_volume_at_height(
+                    labware_id=params.labwareId,
+                    well_name=params.wellName,
+                    height=z_pos_or_error,
                 )
             except IncompleteLabwareDefinitionError:
                 well_volume = update_types.CLEAR
@@ -370,7 +377,10 @@ class TryLiquidProbeImplementation(
             z_pos_or_error, (PipetteLiquidNotFoundError, PipetteOverpressureError)
         ):
             z_pos = None
-            well_volume: float | update_types.ClearType = update_types.CLEAR
+            well_volume: Union[
+                LiquidTrackingType,
+                update_types.ClearType,
+            ] = update_types.CLEAR
         else:
             z_pos = z_pos_or_error
             try:
@@ -387,7 +397,6 @@ class TryLiquidProbeImplementation(
             volume=well_volume,
             last_probed=self._model_utils.get_timestamp(),
         )
-
         return SuccessData(
             public=TryLiquidProbeResult(
                 z_position=z_pos,