opentrons 8.6.0__py3-none-any.whl

opentrons/protocol_engine/commands/load_module.py

@@ -0,0 +1,223 @@
+"""Implementation, request models, and response models for the load module command."""
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional, Type, Any
+from typing_extensions import Literal
+from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+
+from opentrons.protocol_engine.state.update_types import StateUpdate
+
+from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ..errors.error_occurrence import ErrorOccurrence
+from ..types import (
+    DeckSlotLocation,
+    AddressableAreaLocation,
+    ModuleType,
+    ModuleModel,
+)
+from opentrons.types import DeckSlotName
+
+from opentrons.protocol_engine.resources import deck_configuration_provider
+
+
+if TYPE_CHECKING:
+    from ..state.state import StateView
+    from ..execution import EquipmentHandler
+
+
+LoadModuleCommandType = Literal["loadModule"]
+
+
+def _remove_default(s: dict[str, Any]) -> None:
+    s.pop("default", None)
+
+
+class LoadModuleParams(BaseModel):
+    """Payload required to load a module."""
+
+    model: ModuleModel = Field(
+        ...,
+        description=(
+            "The model name of the module to load."
+            "\n\n"
+            "Protocol Engine will look for a connected module that either"
+            " exactly matches this one, or is compatible."
+            "\n\n"
+            " For example, if you request a `temperatureModuleV1` here,"
+            " Protocol Engine might load a `temperatureModuleV1` or a `temperatureModuleV2`."
+            "\n\n"
+            " The model that it finds connected will be available through `result.model`."
+        ),
+    )
+
+    # Note: Our assumption here that a module's position can be boiled down to a
+    # single deck slot precludes loading a Thermocycler in its special "shifted slightly
+    # to the left" position. This is okay for now because neither the Python Protocol
+    # API nor Protocol Designer attempt to support it, either.
+    location: DeckSlotLocation = Field(
+        ...,
+        description=(
+            "The location into which this module should be loaded."
+            "\n\n"
+            "For the Thermocycler Module, which occupies multiple deck slots,"
+            " this should be the front-most occupied slot (normally slot 7)."
+        ),
+    )
+
+    moduleId: str | SkipJsonSchema[None] = Field(
+        None,
+        description=(
+            "An optional ID to assign to this module."
+            " If None, an ID will be generated."
+        ),
+        json_schema_extra=_remove_default,
+    )
+
+
+class LoadModuleResult(BaseModel):
+    """The results of loading a module."""
+
+    # The `definition` used to exist here, but we intentionally removed it. See #18639.
+
+    moduleId: str = Field(
+        description="An ID to reference this module in subsequent commands."
+    )
+
+    model: ModuleModel = Field(
+        ...,
+        description=(
+            "The hardware model of the connected module."
+            " This can be different from the exact model that this command requested."
+            " See `params.model`."
+            "\n\n"
+            "This field is only meaningful in the run's actual execution,"
+            " not in the protocol's analysis."
+            " In analysis, it will be an arbitrary placeholder."
+        ),
+    )
+
+    serialNumber: Optional[str] = Field(
+        None,
+        description="Hardware serial number of the connected module. "
+        "Will be `None` if a module is not electrically connected to the robot (like the Magnetic Block).",
+    )
+
+
+class LoadModuleImplementation(
+    AbstractCommandImpl[LoadModuleParams, SuccessData[LoadModuleResult]]
+):
+    """The implementation of the load module command."""
+
+    def __init__(
+        self, equipment: EquipmentHandler, state_view: StateView, **kwargs: object
+    ) -> None:
+        self._equipment = equipment
+        self._state_view = state_view
+
+    async def execute(self, params: LoadModuleParams) -> SuccessData[LoadModuleResult]:
+        """Check that the requested module is attached and assign its identifier."""
+        state_update = StateUpdate()
+
+        module_type = params.model.as_type()
+        self._ensure_module_location(params.location.slotName, module_type)
+
+        if self._state_view.modules.get_deck_supports_module_fixtures():
+            addressable_area_module_reference = (
+                self._state_view.modules.ensure_and_convert_module_fixture_location(
+                    deck_slot=params.location.slotName,
+                    model=params.model,
+                )
+            )
+        else:
+            addressable_area_module_reference = params.location.slotName.id
+            state_update.set_addressable_area_used(
+                addressable_area_name=addressable_area_module_reference
+            )
+
+        self._state_view.addressable_areas.raise_if_area_not_in_deck_configuration(
+            addressable_area_module_reference
+        )
+
+        self._state_view.geometry.ensure_location_not_occupied(
+            params.location, addressable_area_module_reference
+        )
+
+        if params.model == ModuleModel.MAGNETIC_BLOCK_V1:
+            loaded_module = await self._equipment.load_magnetic_block(
+                model=params.model,
+                location=AddressableAreaLocation(
+                    addressableAreaName=addressable_area_module_reference
+                ),
+                module_id=params.moduleId,
+            )
+        else:
+            loaded_module = await self._equipment.load_module(
+                model=params.model,
+                location=AddressableAreaLocation(
+                    addressableAreaName=addressable_area_module_reference
+                ),
+                module_id=params.moduleId,
+            )
+
+        state_update.set_load_module(
+            module_id=loaded_module.module_id,
+            definition=loaded_module.definition,
+            requested_model=params.model,
+            serial_number=loaded_module.serial_number,
+            slot_name=params.location.slotName,
+        )
+
+        return SuccessData(
+            public=LoadModuleResult(
+                moduleId=loaded_module.module_id,
+                serialNumber=loaded_module.serial_number,
+                model=loaded_module.definition.model,
+            ),
+            state_update=state_update,
+        )
+
+    def _ensure_module_location(
+        self, slot: DeckSlotName, module_type: ModuleType
+    ) -> None:
+        # todo(mm, 2024-12-03): Theoretically, we should be able to deal with
+        # addressable areas and deck configurations the same way between OT-2 and Flex.
+        # Can this be simplified?
+        if self._state_view.config.robot_type == "OT-2 Standard":
+            slot_def = self._state_view.addressable_areas.get_slot_definition(slot.id)
+            compatible_modules = slot_def["compatibleModuleTypes"]
+            if module_type.value not in compatible_modules:
+                raise ValueError(
+                    f"A {module_type.value} cannot be loaded into slot {slot}"
+                )
+        else:
+            cutout_fixture_id = ModuleType.to_module_fixture_id(module_type)
+            module_fixture = deck_configuration_provider.get_cutout_fixture(
+                cutout_fixture_id,
+                self._state_view.labware.get_deck_definition(),
+            )
+            cutout_id = (
+                self._state_view.addressable_areas.get_cutout_id_by_deck_slot_name(slot)
+            )
+            if cutout_id not in module_fixture["mayMountTo"]:
+                raise ValueError(
+                    f"A {module_type.value} cannot be loaded into slot {slot}"
+                )
+
+
+class LoadModule(BaseCommand[LoadModuleParams, LoadModuleResult, ErrorOccurrence]):
+    """The model for a load module command."""
+
+    commandType: LoadModuleCommandType = "loadModule"
+    params: LoadModuleParams
+    result: Optional[LoadModuleResult] = None
+
+    _ImplementationCls: Type[LoadModuleImplementation] = LoadModuleImplementation
+
+
+class LoadModuleCreate(BaseCommandCreate[LoadModuleParams]):
+    """The model for a creation request for a load module command."""
+
+    commandType: LoadModuleCommandType = "loadModule"
+    params: LoadModuleParams
+
+    _CommandCls: Type[LoadModule] = LoadModule

opentrons/protocol_engine/commands/load_pipette.py

@@ -0,0 +1,167 @@
+"""Load pipette command request, result, and implementation models."""
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional, Type, Any
+
+from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+from typing_extensions import Literal
+
+from opentrons_shared_data.pipette.pipette_load_name_conversions import (
+    convert_to_pipette_name_type,
+)
+from opentrons_shared_data.pipette.types import PipetteGenerationType
+from opentrons_shared_data.robot import user_facing_robot_type
+from opentrons_shared_data.robot.types import RobotTypeEnum
+
+
+from opentrons_shared_data.pipette.types import PipetteNameType
+from opentrons.types import MountType
+
+from opentrons.protocol_engine.state.update_types import StateUpdate
+from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ..errors.error_occurrence import ErrorOccurrence
+from ..errors import InvalidSpecificationForRobotTypeError, InvalidLoadPipetteSpecsError
+
+if TYPE_CHECKING:
+    from ..execution import EquipmentHandler
+    from ..state.state import StateView
+
+
+LoadPipetteCommandType = Literal["loadPipette"]
+
+
+def _remove_default(s: dict[str, Any]) -> None:
+    s.pop("default", None)
+
+
+class LoadPipetteParams(BaseModel):
+    """Payload needed to load a pipette on to a mount."""
+
+    pipetteName: PipetteNameType = Field(
+        ...,
+        description="The load name of the pipette to be required.",
+    )
+    mount: MountType = Field(
+        ...,
+        description="The mount the pipette should be present on.",
+    )
+    pipetteId: str | SkipJsonSchema[None] = Field(
+        None,
+        description="An optional ID to assign to this pipette. If None, an ID "
+        "will be generated.",
+        json_schema_extra=_remove_default,
+    )
+    tipOverlapNotAfterVersion: str | SkipJsonSchema[None] = Field(
+        None,
+        description="A version of tip overlap data to not exceed. The highest-versioned "
+        "tip overlap data that does not exceed this version will be used. Versions are "
+        "expressed as vN where N is an integer, counting up from v0. If None, the current "
+        "highest version will be used.",
+        json_schema_extra=_remove_default,
+    )
+    liquidPresenceDetection: bool | SkipJsonSchema[None] = Field(
+        None,
+        description="Enable liquid presence detection for this pipette. Defaults to False.",
+        json_schema_extra=_remove_default,
+    )
+
+
+class LoadPipetteResult(BaseModel):
+    """Result data for executing a LoadPipette."""
+
+    pipetteId: str = Field(
+        ...,
+        description="An ID to reference this pipette in subsequent commands.",
+    )
+
+
+class LoadPipetteImplementation(
+    AbstractCommandImpl[LoadPipetteParams, SuccessData[LoadPipetteResult]]
+):
+    """Load pipette command implementation."""
+
+    def __init__(
+        self, equipment: EquipmentHandler, state_view: StateView, **kwargs: object
+    ) -> None:
+        self._equipment = equipment
+        self._state_view = state_view
+
+    async def execute(
+        self, params: LoadPipetteParams
+    ) -> SuccessData[LoadPipetteResult]:
+        """Check that requested pipette is attached and assign its identifier."""
+        pipette_generation = convert_to_pipette_name_type(
+            params.pipetteName.value
+        ).pipette_generation
+        robot_type = RobotTypeEnum.robot_literal_to_enum(
+            self._state_view.config.robot_type
+        )
+        if (
+            (
+                robot_type == RobotTypeEnum.FLEX
+                and pipette_generation != PipetteGenerationType.FLEX
+            )
+        ) or (
+            (
+                robot_type == RobotTypeEnum.OT2
+                and pipette_generation
+                not in [PipetteGenerationType.GEN1, PipetteGenerationType.GEN2]
+            )
+        ):
+            raise InvalidSpecificationForRobotTypeError(
+                f"Cannot load a {pipette_generation.value.capitalize()} pipette on "
+                f"{user_facing_robot_type(robot_type=self._state_view.config.robot_type, include_article=True)}."
+            )
+
+        if params.mount == MountType.EXTENSION:
+            raise InvalidLoadPipetteSpecsError(
+                "Cannot load a pipette on the EXTENSION mount. Use mount LEFT or RIGHT."
+            )
+
+        loaded_pipette = await self._equipment.load_pipette(
+            pipette_name=params.pipetteName,
+            mount=params.mount,
+            pipette_id=params.pipetteId,
+            tip_overlap_version=params.tipOverlapNotAfterVersion,
+        )
+
+        state_update = StateUpdate()
+        state_update.set_load_pipette(
+            pipette_id=loaded_pipette.pipette_id,
+            pipette_name=params.pipetteName,
+            mount=params.mount,
+            liquid_presence_detection=params.liquidPresenceDetection,
+        )
+        state_update.update_pipette_config(
+            pipette_id=loaded_pipette.pipette_id,
+            serial_number=loaded_pipette.serial_number,
+            config=loaded_pipette.static_config,
+        )
+        state_update.set_fluid_unknown(pipette_id=loaded_pipette.pipette_id)
+        state_update.set_pipette_ready_to_aspirate(
+            pipette_id=loaded_pipette.pipette_id, ready_to_aspirate=False
+        ),
+
+        return SuccessData(
+            public=LoadPipetteResult(pipetteId=loaded_pipette.pipette_id),
+            state_update=state_update,
+        )
+
+
+class LoadPipette(BaseCommand[LoadPipetteParams, LoadPipetteResult, ErrorOccurrence]):
+    """Load pipette command model."""
+
+    commandType: LoadPipetteCommandType = "loadPipette"
+    params: LoadPipetteParams
+    result: Optional[LoadPipetteResult] = None
+
+    _ImplementationCls: Type[LoadPipetteImplementation] = LoadPipetteImplementation
+
+
+class LoadPipetteCreate(BaseCommandCreate[LoadPipetteParams]):
+    """Load pipette command creation request model."""
+
+    commandType: LoadPipetteCommandType = "loadPipette"
+    params: LoadPipetteParams
+
+    _CommandCls: Type[LoadPipette] = LoadPipette

opentrons/protocol_engine/commands/magnetic_module/__init__.py

@@ -0,0 +1,32 @@
+"""Magnetic Module protocol commands."""
+
+from .disengage import (
+    Disengage,
+    DisengageCreate,
+    DisengageParams,
+    DisengageResult,
+    DisengageCommandType,
+)
+from .engage import (
+    Engage,
+    EngageCreate,
+    EngageParams,
+    EngageResult,
+    EngageCommandType,
+)
+
+
+__all__ = [
+    # magneticModule/disengageMagnet
+    "Disengage",
+    "DisengageCreate",
+    "DisengageParams",
+    "DisengageResult",
+    "DisengageCommandType",
+    # magneticModule/engageMagnet
+    "Engage",
+    "EngageCreate",
+    "EngageParams",
+    "EngageResult",
+    "EngageCommandType",
+]

opentrons/protocol_engine/commands/magnetic_module/disengage.py

@@ -0,0 +1,97 @@
+"""Magnetic Module disengage command request, result, and implementation models."""
+
+
+from __future__ import annotations
+
+from typing import Optional, TYPE_CHECKING
+from typing_extensions import Literal, Type
+
+from pydantic import BaseModel, Field
+
+from ..command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ...errors.error_occurrence import ErrorOccurrence
+
+if TYPE_CHECKING:
+    from opentrons.protocol_engine.execution import EquipmentHandler
+    from opentrons.protocol_engine.state.state import StateView
+
+
+DisengageCommandType = Literal["magneticModule/disengage"]
+
+
+class DisengageParams(BaseModel):
+    """Input data to disengage a Magnetic Module's magnets."""
+
+    moduleId: str = Field(
+        ...,
+        description=(
+            "The ID of the Magnetic Module whose magnets you want to disengage,"
+            " from a prior `loadModule` command."
+        ),
+    )
+
+
+class DisengageResult(BaseModel):
+    """The result of a Magnetic Module disengage command."""
+
+    pass
+
+
+class DisengageImplementation(
+    AbstractCommandImpl[DisengageParams, SuccessData[DisengageResult]]
+):
+    """The implementation of a Magnetic Module disengage command."""
+
+    def __init__(
+        self,
+        state_view: StateView,
+        equipment: EquipmentHandler,
+        **unused_dependencies: object,
+    ) -> None:
+        self._state_view = state_view
+        self._equipment = equipment
+
+    async def execute(self, params: DisengageParams) -> SuccessData[DisengageResult]:
+        """Execute a Magnetic Module disengage command.
+
+        Raises:
+            ModuleNotLoadedError: If the given module ID has not been loaded.
+            WrongModuleTypeError: If the given module ID has been loaded,
+                but it's not a Magnetic Module.
+            ModuleNotAttachedError: If the given module ID points to a valid loaded
+                Magnetic Module, but that module's hardware wasn't found attached.
+        """
+        # Allow propagation of ModuleNotLoadedError and WrongModuleTypeError.
+        mag_module_substate = self._state_view.modules.get_magnetic_module_substate(
+            module_id=params.moduleId
+        )
+        # Allow propagation of ModuleNotAttachedError.
+        hardware_module = self._equipment.get_module_hardware_api(
+            mag_module_substate.module_id
+        )
+
+        if hardware_module is not None:  # Not virtualizing modules.
+            await hardware_module.deactivate()
+
+        return SuccessData(
+            public=DisengageResult(),
+        )
+
+
+class Disengage(BaseCommand[DisengageParams, DisengageResult, ErrorOccurrence]):
+    """A command to disengage a Magnetic Module's magnets."""
+
+    commandType: DisengageCommandType = "magneticModule/disengage"
+    params: DisengageParams
+    result: Optional[DisengageResult] = None
+
+    _ImplementationCls: Type[DisengageImplementation] = DisengageImplementation
+
+
+class DisengageCreate(BaseCommandCreate[DisengageParams]):
+    """A request to create a Magnetic Module disengage command."""
+
+    commandType: DisengageCommandType = "magneticModule/disengage"
+    params: DisengageParams
+
+    _CommandCls: Type[Disengage] = Disengage

opentrons/protocol_engine/commands/magnetic_module/engage.py

@@ -0,0 +1,119 @@
+"""Magnetic Module engage command request, result, and implementation models."""
+from __future__ import annotations
+from typing import Optional, TYPE_CHECKING
+from typing_extensions import Literal, Type
+
+from pydantic import BaseModel, Field
+
+from ..command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ...errors.error_occurrence import ErrorOccurrence
+
+if TYPE_CHECKING:
+    from opentrons.protocol_engine.execution import EquipmentHandler
+    from opentrons.protocol_engine.state.state import StateView
+
+
+EngageCommandType = Literal["magneticModule/engage"]
+
+
+class EngageParams(BaseModel):
+    """Input data to engage a Magnetic Module."""
+
+    moduleId: str = Field(
+        ...,
+        description=(
+            "The ID of the Magnetic Module whose magnets you want to raise,"
+            " from a prior `loadModule` command."
+        ),
+    )
+
+    height: float = Field(
+        ...,
+        description=(
+            "How high, in millimeters, to raise the magnets."
+            "\n\n"
+            "Zero means the tops of the magnets are level with the ledge"
+            " that the labware rests on."
+            " This will be slightly above the magnets' minimum height,"
+            " the hardware home position."
+            " Negative values are allowed, to put the magnets below the ledge."
+            "\n\n"
+            "Units are always true millimeters."
+            " This is unlike certain labware definitions,"
+            " engage commands in the Python Protocol API,"
+            " and engage commands in older versions of the JSON protocol schema."
+            " Take care to convert properly."
+        ),
+    )
+
+
+class EngageResult(BaseModel):
+    """The result of a Magnetic Module engage command."""
+
+    pass
+
+
+class EngageImplementation(
+    AbstractCommandImpl[EngageParams, SuccessData[EngageResult]]
+):
+    """The implementation of a Magnetic Module engage command."""
+
+    def __init__(
+        self,
+        state_view: StateView,
+        equipment: EquipmentHandler,
+        **unused_dependencies: object,
+    ) -> None:
+        self._state_view = state_view
+        self._equipment = equipment
+
+    async def execute(self, params: EngageParams) -> SuccessData[EngageResult]:
+        """Execute a Magnetic Module engage command.
+
+        Raises:
+            ModuleNotLoadedError: If the given module ID doesn't point to a
+                module that's already been loaded.
+            WrongModuleTypeError: If the given module ID points to a non-Magnetic
+                module.
+            ModuleNotAttachedError: If the given module ID points to a valid loaded
+                Magnetic Module, but that module's hardware wasn't found attached.
+            EngageHeightOutOfRangeError: If the given height is unreachable.
+        """
+        # Allow propagation of ModuleNotLoadedError and WrongModuleTypeError.
+        mag_module_substate = self._state_view.modules.get_magnetic_module_substate(
+            module_id=params.moduleId
+        )
+        # Allow propagation of EngageHeightOutOfRangeError.
+        hardware_height = mag_module_substate.calculate_magnet_hardware_height(
+            mm_from_base=params.height,
+        )
+        # Allow propagation of ModuleNotAttachedError.
+        hardware_module = self._equipment.get_module_hardware_api(
+            mag_module_substate.module_id
+        )
+
+        if hardware_module is not None:  # Not virtualizing modules.
+            await hardware_module.engage(height=hardware_height)
+
+        return SuccessData(
+            public=EngageResult(),
+        )
+
+
+class Engage(BaseCommand[EngageParams, EngageResult, ErrorOccurrence]):
+    """A command to engage a Magnetic Module's magnets."""
+
+    commandType: EngageCommandType = "magneticModule/engage"
+    params: EngageParams
+    result: Optional[EngageResult] = None
+
+    _ImplementationCls: Type[EngageImplementation] = EngageImplementation
+
+
+class EngageCreate(BaseCommandCreate[EngageParams]):
+    """A request to create a Magnetic Module engage command."""
+
+    commandType: EngageCommandType = "magneticModule/engage"
+    params: EngageParams
+
+    _CommandCls: Type[Engage] = Engage