opentrons 8.3.2__py2.py3-none-any.whl → 8.4.0__py2.py3-none-any.whl

opentrons/protocol_engine/commands/flex_stacker/__init__.py

@@ -0,0 +1,106 @@
+"""Command models for Flex Stacker commands."""
+
+from .store import (
+    StoreCommandType,
+    StoreParams,
+    StoreResult,
+    Store,
+    StoreCreate,
+)
+
+from .retrieve import (
+    RetrieveCommandType,
+    RetrieveParams,
+    RetrieveResult,
+    Retrieve,
+    RetrieveCreate,
+)
+
+from .set_stored_labware import (
+    SetStoredLabwareCommandType,
+    SetStoredLabwareParams,
+    SetStoredLabwareResult,
+    SetStoredLabware,
+    SetStoredLabwareCreate,
+    StackerStoredLabwareDetails,
+)
+
+from .fill import FillCommandType, FillParams, FillResult, Fill, FillCreate
+
+from .empty import EmptyCommandType, EmptyParams, EmptyResult, Empty, EmptyCreate
+
+from .close_latch import (
+    CloseLatchCommandType,
+    CloseLatchParams,
+    CloseLatchResult,
+    CloseLatch,
+    CloseLatchCreate,
+)
+from .open_latch import (
+    OpenLatchCommandType,
+    OpenLatchParams,
+    OpenLatchResult,
+    OpenLatch,
+    OpenLatchCreate,
+)
+
+from .prepare_shuttle import (
+    PrepareShuttleCommandType,
+    PrepareShuttleParams,
+    PrepareShuttleResult,
+    PrepareShuttle,
+    PrepareShuttleCreate,
+)
+
+
+__all__ = [
+    # flexStacker/store
+    "StoreCommandType",
+    "StoreParams",
+    "StoreResult",
+    "Store",
+    "StoreCreate",
+    # flexStacker/retrieve
+    "RetrieveCommandType",
+    "RetrieveParams",
+    "RetrieveResult",
+    "Retrieve",
+    "RetrieveCreate",
+    # flexStacker/setStoredLabware
+    "SetStoredLabwareCommandType",
+    "SetStoredLabwareParams",
+    "SetStoredLabwareResult",
+    "SetStoredLabware",
+    "SetStoredLabwareCreate",
+    "StackerStoredLabwareDetails",
+    # flexStacker/fill
+    "FillCommandType",
+    "FillParams",
+    "FillResult",
+    "Fill",
+    "FillCreate",
+    # flexStacker/empty
+    "EmptyCommandType",
+    "EmptyParams",
+    "EmptyResult",
+    "Empty",
+    "EmptyCreate",
+    # flexStacker/closeLatch
+    "CloseLatchCommandType",
+    "CloseLatchParams",
+    "CloseLatchResult",
+    "CloseLatch",
+    "CloseLatchCreate",
+    # flexStacker/openLatch
+    "OpenLatchCommandType",
+    "OpenLatchParams",
+    "OpenLatchResult",
+    "OpenLatch",
+    "OpenLatchCreate",
+    # flexStacker/prepareShuttle
+    "PrepareShuttleCommandType",
+    "PrepareShuttleParams",
+    "PrepareShuttleResult",
+    "PrepareShuttle",
+    "PrepareShuttleCreate",
+]

opentrons/protocol_engine/commands/flex_stacker/close_latch.py

@@ -0,0 +1,72 @@
+"""Command models to close the latch of a Flex Stacker."""
+
+from __future__ import annotations
+
+from __future__ import annotations
+from typing import Optional, Literal, TYPE_CHECKING
+from typing_extensions import Type
+
+from pydantic import BaseModel, Field
+
+from ..command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ...errors import (
+    ErrorOccurrence,
+)
+
+if TYPE_CHECKING:
+    from ...state.state import StateView
+    from opentrons.protocol_engine.execution import EquipmentHandler
+
+CloseLatchCommandType = Literal["flexStacker/closeLatch"]
+
+
+class CloseLatchParams(BaseModel):
+    """The parameters defining how a stacker should close its latch."""
+
+    moduleId: str = Field(..., description="Unique ID of the Flex Stacker")
+
+
+class CloseLatchResult(BaseModel):
+    """Result data from a stacker CloseLatch command."""
+
+
+class CloseLatchImpl(
+    AbstractCommandImpl[CloseLatchParams, SuccessData[CloseLatchResult]]
+):
+    """Implementation of a stacker CloseLatch 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: CloseLatchParams) -> SuccessData[CloseLatchResult]:
+        """Execute the stacker CloseLatch command."""
+        stacker_state = self._state_view.modules.get_flex_stacker_substate(
+            params.moduleId
+        )
+        stacker_hw = self._equipment.get_module_hardware_api(stacker_state.module_id)
+
+        if stacker_hw is not None:
+            await stacker_hw.close_latch()
+        return SuccessData(public=CloseLatchResult())
+
+
+class CloseLatch(BaseCommand[CloseLatchParams, CloseLatchResult, ErrorOccurrence]):
+    """A command to CloseLatch the Flex Stacker of labware."""
+
+    commandType: CloseLatchCommandType = "flexStacker/closeLatch"
+    params: CloseLatchParams
+    result: Optional[CloseLatchResult] = None
+
+    _ImplementationCls: Type[CloseLatchImpl] = CloseLatchImpl
+
+
+class CloseLatchCreate(BaseCommandCreate[CloseLatchParams]):
+    """A request to execute a Flex Stacker CloseLatch command."""
+
+    commandType: CloseLatchCommandType = "flexStacker/closeLatch"
+    params: CloseLatchParams
+
+    _CommandCls: Type[CloseLatch] = CloseLatch

opentrons/protocol_engine/commands/flex_stacker/common.py

@@ -0,0 +1,15 @@
+"""Common flex stacker base models."""
+from typing import Literal
+
+from ...errors import ErrorOccurrence
+from opentrons_shared_data.errors import ErrorCodes
+
+
+class FlexStackerStallOrCollisionError(ErrorOccurrence):
+    """Returned when the motor driver detects a stall."""
+
+    isDefined: bool = True
+    errorType: Literal["flexStackerStallOrCollision"] = "flexStackerStallOrCollision"
+
+    errorCode: str = ErrorCodes.FLEX_STACKER_STALL_OR_COLLISION_DETECTED.value.code
+    detail: str = ErrorCodes.FLEX_STACKER_STALL_OR_COLLISION_DETECTED.value.detail

opentrons/protocol_engine/commands/flex_stacker/empty.py

@@ -0,0 +1,161 @@
+"""Command models to engage a user to empty a Flex Stacker."""
+
+from __future__ import annotations
+
+from __future__ import annotations
+from typing import Optional, Literal, TYPE_CHECKING, Annotated
+from typing_extensions import Type
+
+from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+
+from ..command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ...errors import (
+    ErrorOccurrence,
+)
+from ...errors.exceptions import FlexStackerLabwarePoolNotYetDefinedError
+from ...state import update_types
+from ...types import StackerFillEmptyStrategy
+from opentrons.calibration_storage.helpers import uri_from_details
+
+if TYPE_CHECKING:
+    from ...state.state import StateView
+    from ...execution import RunControlHandler
+
+EmptyCommandType = Literal["flexStacker/empty"]
+
+
+class EmptyParams(BaseModel):
+    """The parameters defining how a stacker should be emptied."""
+
+    moduleId: str = Field(..., description="Unique ID of the Flex Stacker")
+
+    strategy: StackerFillEmptyStrategy = Field(
+        ...,
+        description=(
+            "How to empty the stacker. "
+            "If manualWithPause, pause the protocol until the client sends an interaction, and mark "
+            "the labware pool as empty thereafter. If logical, do not pause but immediately apply the "
+            "specified count."
+        ),
+    )
+
+    message: str | SkipJsonSchema[None] = Field(
+        None,
+        description="The message to display on connected clients during a manualWithPause strategy empty.",
+    )
+
+    count: Optional[Annotated[int, Field(ge=0)]] = Field(
+        None,
+        description=(
+            "The new count of labware in the pool. If None, default to an empty pool. If this number is "
+            "larger than the amount of labware currently in the pool, default to the smaller amount. "
+            "Do not use the value in the parameters as an outside observer; instead, use the count value "
+            "from the results."
+        ),
+    )
+
+
+class EmptyResult(BaseModel):
+    """Result data from a stacker empty command."""
+
+    count: int = Field(
+        ..., description="The new amount of labware stored in the stacker labware pool."
+    )
+    primaryLabwareURI: str = Field(
+        ...,
+        description="The labware definition URI of the primary labware.",
+    )
+    adapterLabwareURI: str | SkipJsonSchema[None] = Field(
+        None,
+        description="The labware definition URI of the adapter labware.",
+    )
+    lidLabwareURI: str | SkipJsonSchema[None] = Field(
+        None,
+        description="The labware definition URI of the lid labware.",
+    )
+
+
+class EmptyImpl(AbstractCommandImpl[EmptyParams, SuccessData[EmptyResult]]):
+    """Implementation of a stacker empty command."""
+
+    def __init__(
+        self, state_view: StateView, run_control: RunControlHandler, **kwargs: object
+    ) -> None:
+        self._state_view = state_view
+        self._run_control = run_control
+
+    async def execute(self, params: EmptyParams) -> SuccessData[EmptyResult]:
+        """Execute the stacker empty command."""
+        stacker_state = self._state_view.modules.get_flex_stacker_substate(
+            params.moduleId
+        )
+
+        if stacker_state.pool_primary_definition is None:
+            location = self._state_view.modules.get_location(params.moduleId)
+            raise FlexStackerLabwarePoolNotYetDefinedError(
+                message=f"The Flex Stacker in {location} has not been configured yet and cannot be emptied."
+            )
+
+        count = params.count if params.count is not None else 0
+
+        new_count = min(stacker_state.pool_count, count)
+
+        state_update = (
+            update_types.StateUpdate().update_flex_stacker_labware_pool_count(
+                params.moduleId, new_count
+            )
+        )
+
+        if params.strategy == StackerFillEmptyStrategy.MANUAL_WITH_PAUSE:
+            await self._run_control.wait_for_resume()
+
+        if stacker_state.pool_primary_definition is None:
+            raise FlexStackerLabwarePoolNotYetDefinedError(
+                "The Primary Labware must be defined in the stacker pool."
+            )
+
+        return SuccessData(
+            public=EmptyResult(
+                count=new_count,
+                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 Empty(BaseCommand[EmptyParams, EmptyResult, ErrorOccurrence]):
+    """A command to empty the Flex Stacker of labware."""
+
+    commandType: EmptyCommandType = "flexStacker/empty"
+    params: EmptyParams
+    result: Optional[EmptyResult] = None
+
+    _ImplementationCls: Type[EmptyImpl] = EmptyImpl
+
+
+class EmptyCreate(BaseCommandCreate[EmptyParams]):
+    """A request to execute a Flex Stacker empty command."""
+
+    commandType: EmptyCommandType = "flexStacker/empty"
+    params: EmptyParams
+
+    _CommandCls: Type[Empty] = Empty

opentrons/protocol_engine/commands/flex_stacker/fill.py

@@ -0,0 +1,164 @@
+"""Command models to engage a user to empty a Flex Stacker."""
+
+from __future__ import annotations
+from typing import Optional, Literal, TYPE_CHECKING, Annotated
+from typing_extensions import Type
+
+from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+
+from ..command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ...errors import (
+    ErrorOccurrence,
+)
+from ...errors.exceptions import FlexStackerLabwarePoolNotYetDefinedError
+from ...state import update_types
+from ...types import StackerFillEmptyStrategy
+from opentrons.calibration_storage.helpers import uri_from_details
+
+if TYPE_CHECKING:
+    from ...state.state import StateView
+    from ...execution import RunControlHandler
+
+FillCommandType = Literal["flexStacker/fill"]
+
+
+class FillParams(BaseModel):
+    """The parameters defining how a stacker should be filled."""
+
+    moduleId: str = Field(..., description="Unique ID of the Flex Stacker")
+
+    strategy: StackerFillEmptyStrategy = Field(
+        ...,
+        description=(
+            "How to fill the stacker. "
+            "If manualWithPause, pause the protocol until the client sends an interaction, and apply "
+            "the new specified count thereafter. If logical, do not pause but immediately apply the "
+            "specified count."
+        ),
+    )
+
+    message: str | SkipJsonSchema[None] = Field(
+        None,
+        description="The message to display on connected clients during a manualWithPause strategy fill.",
+    )
+
+    count: Optional[Annotated[int, Field(ge=1)]] = Field(
+        None,
+        description=(
+            "How full the labware pool should now be. If None, default to the maximum amount "
+            "of the currently-configured labware the pool can hold. "
+            "If this number is larger than the maximum the pool can hold, it will be clamped to "
+            "the maximum. If this number is smaller than the current amount of labware the pool "
+            "holds, it will be clamped to that minimum. Do not use the value in the parameters as "
+            "an outside observer; instead, use the count value from the results."
+        ),
+    )
+
+
+class FillResult(BaseModel):
+    """Result data from a stacker fill command."""
+
+    count: int = Field(
+        ..., description="The new amount of labware stored in the stacker labware pool."
+    )
+    primaryLabwareURI: str = Field(
+        ...,
+        description="The labware definition URI of the primary labware.",
+    )
+    adapterLabwareURI: str | SkipJsonSchema[None] = Field(
+        None,
+        description="The labware definition URI of the adapter labware.",
+    )
+    lidLabwareURI: str | SkipJsonSchema[None] = Field(
+        None,
+        description="The labware definition URI of the lid labware.",
+    )
+
+
+class FillImpl(AbstractCommandImpl[FillParams, SuccessData[FillResult]]):
+    """Implementation of a stacker fill command."""
+
+    def __init__(
+        self, state_view: StateView, run_control: RunControlHandler, **kwargs: object
+    ) -> None:
+        self._state_view = state_view
+        self._run_control = run_control
+
+    async def execute(self, params: FillParams) -> SuccessData[FillResult]:
+        """Execute the stacker fill command."""
+        stacker_state = self._state_view.modules.get_flex_stacker_substate(
+            params.moduleId
+        )
+
+        if stacker_state.pool_primary_definition is None:
+            location = self._state_view.modules.get_location(params.moduleId)
+            raise FlexStackerLabwarePoolNotYetDefinedError(
+                message=f"The Flex Stacker in {location} has not been configured yet and cannot be filled."
+            )
+
+        count = (
+            params.count if params.count is not None else stacker_state.max_pool_count
+        )
+        new_count = min(
+            stacker_state.max_pool_count, max(stacker_state.pool_count, count)
+        )
+
+        state_update = (
+            update_types.StateUpdate().update_flex_stacker_labware_pool_count(
+                params.moduleId, new_count
+            )
+        )
+
+        if params.strategy == StackerFillEmptyStrategy.MANUAL_WITH_PAUSE:
+            await self._run_control.wait_for_resume()
+
+        if stacker_state.pool_primary_definition is None:
+            raise FlexStackerLabwarePoolNotYetDefinedError(
+                "The Primary Labware must be defined in the stacker pool."
+            )
+
+        return SuccessData(
+            public=FillResult(
+                count=new_count,
+                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 Fill(BaseCommand[FillParams, FillResult, ErrorOccurrence]):
+    """A command to fill the Flex Stacker with labware."""
+
+    commandType: FillCommandType = "flexStacker/fill"
+    params: FillParams
+    result: Optional[FillResult] = None
+
+    _ImplementationCls: Type[FillImpl] = FillImpl
+
+
+class FillCreate(BaseCommandCreate[FillParams]):
+    """A request to execute a Flex Stacker fill command."""
+
+    commandType: FillCommandType = "flexStacker/fill"
+    params: FillParams
+
+    _CommandCls: Type[Fill] = Fill

opentrons/protocol_engine/commands/flex_stacker/open_latch.py

@@ -0,0 +1,70 @@
+"""Command models to open the latch of a Flex Stacker."""
+
+from __future__ import annotations
+
+from __future__ import annotations
+from typing import Optional, Literal, TYPE_CHECKING
+from typing_extensions import Type
+
+from pydantic import BaseModel, Field
+
+from ..command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ...errors import (
+    ErrorOccurrence,
+)
+
+if TYPE_CHECKING:
+    from ...state.state import StateView
+    from opentrons.protocol_engine.execution import EquipmentHandler
+
+OpenLatchCommandType = Literal["flexStacker/openLatch"]
+
+
+class OpenLatchParams(BaseModel):
+    """The parameters defining how a stacker should open its latch."""
+
+    moduleId: str = Field(..., description="Unique ID of the Flex Stacker")
+
+
+class OpenLatchResult(BaseModel):
+    """Result data from a stacker OpenLatch command."""
+
+
+class OpenLatchImpl(AbstractCommandImpl[OpenLatchParams, SuccessData[OpenLatchResult]]):
+    """Implementation of a stacker OpenLatch 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: OpenLatchParams) -> SuccessData[OpenLatchResult]:
+        """Execute the stacker OpenLatch command."""
+        stacker_state = self._state_view.modules.get_flex_stacker_substate(
+            params.moduleId
+        )
+        stacker_hw = self._equipment.get_module_hardware_api(stacker_state.module_id)
+
+        if stacker_hw is not None:
+            await stacker_hw.open_latch()
+        return SuccessData(public=OpenLatchResult())
+
+
+class OpenLatch(BaseCommand[OpenLatchParams, OpenLatchResult, ErrorOccurrence]):
+    """A command to OpenLatch the Flex Stacker of labware."""
+
+    commandType: OpenLatchCommandType = "flexStacker/openLatch"
+    params: OpenLatchParams
+    result: Optional[OpenLatchResult] = None
+
+    _ImplementationCls: Type[OpenLatchImpl] = OpenLatchImpl
+
+
+class OpenLatchCreate(BaseCommandCreate[OpenLatchParams]):
+    """A request to execute a Flex Stacker OpenLatch command."""
+
+    commandType: OpenLatchCommandType = "flexStacker/openLatch"
+    params: OpenLatchParams
+
+    _CommandCls: Type[OpenLatch] = OpenLatch