opentrons 8.6.0__py3-none-any.whl

opentrons/protocol_engine/commands/calibration/__init__.py

@@ -0,0 +1,60 @@
+"""Calibration commands."""
+from .calibrate_gripper import (
+    CalibrateGripperParams,
+    CalibrateGripperResult,
+    CalibrateGripperCreate,
+    CalibrateGripperCommandType,
+    CalibrateGripper,
+)
+
+from .calibrate_pipette import (
+    CalibratePipetteParams,
+    CalibratePipetteResult,
+    CalibratePipetteCreate,
+    CalibratePipetteCommandType,
+    CalibratePipette,
+)
+
+from .calibrate_module import (
+    CalibrateModuleParams,
+    CalibrateModuleResult,
+    CalibrateModuleCreate,
+    CalibrateModuleCommandType,
+    CalibrateModule,
+)
+
+from .move_to_maintenance_position import (
+    MoveToMaintenancePositionParams,
+    MoveToMaintenancePositionResult,
+    MoveToMaintenancePositionCreate,
+    MoveToMaintenancePositionCommandType,
+    MoveToMaintenancePosition,
+)
+
+__all__ = [
+    # calibration/calibrateModule
+    "CalibrateModule",
+    "CalibrateModuleCreate",
+    "CalibrateModuleParams",
+    "CalibrateModuleResult",
+    "CalibrateModuleCommandType",
+    # calibration/calibrateGripper
+    "CalibrateGripper",
+    "CalibrateGripperCreate",
+    "CalibrateGripperParams",
+    "CalibrateGripperParamsProbe",
+    "CalibrateGripperResult",
+    "CalibrateGripperCommandType",
+    # calibration/calibratePipette
+    "CalibratePipette",
+    "CalibratePipetteCreate",
+    "CalibratePipetteParams",
+    "CalibratePipetteResult",
+    "CalibratePipetteCommandType",
+    # calibration/moveToMaintenancePosition
+    "MoveToMaintenancePosition",
+    "MoveToMaintenancePositionCreate",
+    "MoveToMaintenancePositionParams",
+    "MoveToMaintenancePositionResult",
+    "MoveToMaintenancePositionCommandType",
+]

opentrons/protocol_engine/commands/calibration/calibrate_gripper.py

@@ -0,0 +1,166 @@
+"""Models and implementation for the calibrateGripper command."""
+
+from enum import Enum
+from typing import Optional, Type, Any
+from typing_extensions import Literal
+
+from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+
+from opentrons.types import Point
+from opentrons.hardware_control import HardwareControlAPI
+from opentrons.hardware_control import ot3_calibration
+from opentrons.hardware_control.types import OT3Mount, GripperProbe as HWAPIGripperProbe
+from opentrons.hardware_control.instruments.ot3.instrument_calibration import (
+    GripperCalibrationOffset,
+)
+from ..command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ...errors.error_occurrence import ErrorOccurrence
+from opentrons.protocol_engine.types import Vec3f
+from opentrons.protocol_engine.resources import ensure_ot3_hardware
+
+
+CalibrateGripperCommandType = Literal["calibration/calibrateGripper"]
+
+
+def _remove_default(s: dict[str, Any]) -> None:
+    s.pop("default", None)
+
+
+class CalibrateGripperParamsJaw(Enum):  # noqa: D101
+    FRONT = "front"
+    REAR = "rear"
+
+
+class CalibrateGripperParams(BaseModel):
+    """Parameters for a `calibrateGripper` command."""
+
+    jaw: CalibrateGripperParamsJaw = Field(
+        ...,
+        description=(
+            "Which of the gripper's jaws to use to measure its offset."
+            " The robot will assume that a human operator has already attached"
+            " the capacitive probe to the jaw and none is attached to the other jaw."
+        ),
+    )
+
+    otherJawOffset: Vec3f | SkipJsonSchema[None] = Field(
+        None,
+        description=(
+            "If an offset for the other probe is already found, then specifying it here"
+            " will enable the CalibrateGripper command to complete the calibration"
+            " process by calculating the total offset and saving it to disk."
+            " If this param is not specified then the command will only find and return"
+            " the offset for the specified probe."
+        ),
+        json_schema_extra=_remove_default,
+    )
+
+
+class CalibrateGripperResult(BaseModel):
+    """The result of a successful `calibrateGripper` command."""
+
+    jawOffset: Vec3f = Field(
+        ...,
+        description=(
+            "The offset from the probe's nominal position"
+            " to its actual measured position."
+        ),
+    )
+
+    savedCalibration: GripperCalibrationOffset | SkipJsonSchema[None] = Field(
+        None,
+        description=(
+            "Gripper calibration result data, when `otherJawOffset` is provided."
+        ),
+        json_schema_extra=_remove_default,
+    )
+
+
+class CalibrateGripperImplementation(
+    AbstractCommandImpl[CalibrateGripperParams, SuccessData[CalibrateGripperResult]]
+):
+    """The implementation of a `calibrateGripper` command."""
+
+    def __init__(
+        self,
+        hardware_api: HardwareControlAPI,
+        *args: object,
+        **kwargs: object,
+    ) -> None:
+        self._hardware_api = hardware_api
+
+    async def execute(
+        self, params: CalibrateGripperParams
+    ) -> SuccessData[CalibrateGripperResult]:
+        """Execute a `calibrateGripper` command.
+
+        1. Move from the current location to the calibration area on the deck.
+        2. Using the given probe, sense the gripper's offset from its ideal position.
+        3. Return the gripper's offset from its ideal position.
+        """
+        ot3_hardware_api = ensure_ot3_hardware(self._hardware_api)
+
+        probe_offset = await ot3_calibration.calibrate_gripper_jaw(
+            hcapi=ot3_hardware_api, probe=self._convert_to_hw_api_probe(params.jaw)
+        )
+        other_probe_offset = params.otherJawOffset
+        calibration_data: Optional[GripperCalibrationOffset] = None
+        if other_probe_offset is not None:
+            total_offset = 0.5 * (
+                probe_offset
+                + Point(
+                    x=other_probe_offset.x,
+                    y=other_probe_offset.y,
+                    z=other_probe_offset.z,
+                )
+            )
+            result = await ot3_hardware_api.save_instrument_offset(
+                mount=OT3Mount.GRIPPER, delta=total_offset
+            )
+            assert isinstance(result, GripperCalibrationOffset), (
+                f"Expected result to be GripperCalibrationOffset type, "
+                f"but received {type(result)}"
+            )
+            calibration_data = result
+
+        return SuccessData(
+            public=CalibrateGripperResult.model_construct(
+                jawOffset=Vec3f.model_construct(
+                    x=probe_offset.x, y=probe_offset.y, z=probe_offset.z
+                ),
+                savedCalibration=calibration_data,
+            ),
+        )
+
+    @staticmethod
+    def _convert_to_hw_api_probe(
+        probe_from_params: CalibrateGripperParamsJaw,
+    ) -> HWAPIGripperProbe:
+        if probe_from_params is CalibrateGripperParamsJaw.FRONT:
+            return HWAPIGripperProbe.FRONT
+        elif probe_from_params is CalibrateGripperParamsJaw.REAR:
+            return HWAPIGripperProbe.REAR
+
+
+class CalibrateGripper(
+    BaseCommand[CalibrateGripperParams, CalibrateGripperResult, ErrorOccurrence]
+):
+    """A `calibrateGripper` command."""
+
+    commandType: CalibrateGripperCommandType = "calibration/calibrateGripper"
+    params: CalibrateGripperParams
+    result: Optional[CalibrateGripperResult] = None
+
+    _ImplementationCls: Type[
+        CalibrateGripperImplementation
+    ] = CalibrateGripperImplementation
+
+
+class CalibrateGripperCreate(BaseCommandCreate[CalibrateGripperParams]):
+    """A request to create a `calibrateGripper` command."""
+
+    commandType: CalibrateGripperCommandType = "calibration/calibrateGripper"
+    params: CalibrateGripperParams
+
+    _CommandCls: Type[CalibrateGripper] = CalibrateGripper

opentrons/protocol_engine/commands/calibration/calibrate_module.py

@@ -0,0 +1,117 @@
+"""Calibrate-module command for OT3 hardware. request, result, and implementation models."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional, Type
+from typing_extensions import Literal
+from pydantic import BaseModel, Field
+
+from opentrons.types import MountType
+from opentrons.protocol_engine.resources.ot3_validation import ensure_ot3_hardware
+from ..command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ...errors.error_occurrence import ErrorOccurrence
+
+# Work around type-only circular dependencies.
+if TYPE_CHECKING:
+    from ...state.state import StateView
+
+from ...types import ModuleOffsetVector, DeckSlotLocation
+
+from opentrons.hardware_control import HardwareControlAPI
+from opentrons.hardware_control.types import OT3Mount
+from opentrons.hardware_control import ot3_calibration as calibration
+
+
+CalibrateModuleCommandType = Literal["calibration/calibrateModule"]
+
+
+class CalibrateModuleParams(BaseModel):
+    """Payload required to calibrate-module."""
+
+    moduleId: str = Field(..., description="The unique id of module to calibrate.")
+    labwareId: str = Field(
+        ..., description="The unique id of module calibration adapter labware."
+    )
+    mount: MountType = Field(
+        ..., description="The instrument mount used to calibrate the module."
+    )
+
+
+class CalibrateModuleResult(BaseModel):
+    """Result data from the execution of a calibrate-module command."""
+
+    moduleOffset: ModuleOffsetVector = Field(
+        ..., description="Offset of calibrated module."
+    )
+
+    location: DeckSlotLocation = Field(
+        ..., description="The deck slot this module was calibrated in."
+    )
+
+
+class CalibrateModuleImplementation(
+    AbstractCommandImpl[CalibrateModuleParams, SuccessData[CalibrateModuleResult]]
+):
+    """CalibrateModule command implementation."""
+
+    def __init__(
+        self,
+        state_view: StateView,
+        hardware_api: HardwareControlAPI,
+        **kwargs: object,
+    ) -> None:
+        self._state_view = state_view
+        self._hardware_api = hardware_api
+
+    async def execute(
+        self, params: CalibrateModuleParams
+    ) -> SuccessData[CalibrateModuleResult]:
+        """Execute calibrate-module command."""
+        ot3_api = ensure_ot3_hardware(
+            self._hardware_api,
+        )
+        ot3_mount = OT3Mount.from_mount(params.mount)
+        slot = self._state_view.modules.get_location(params.moduleId)
+        module_serial = self._state_view.modules.get_serial_number(params.moduleId)
+        # NOTE (ba, 2023-03-31): There are two wells for calibration labware definitions
+        # well A1 represents the location calibration square center relative to the adapters bottom-left corner
+        # well B1 represents the location of the calibration square probe point relative to the adapters bottom-left corner.
+        nominal_position = self._state_view.geometry.get_well_position(
+            labware_id=params.labwareId, well_name="B1"
+        )
+
+        # start the calibration
+        module_offset = await calibration.calibrate_module(
+            ot3_api, ot3_mount, slot.slotName.id, module_serial, nominal_position
+        )
+
+        return SuccessData(
+            public=CalibrateModuleResult(
+                moduleOffset=ModuleOffsetVector(
+                    x=module_offset.x, y=module_offset.y, z=module_offset.z
+                ),
+                location=slot,
+            ),
+        )
+
+
+class CalibrateModule(
+    BaseCommand[CalibrateModuleParams, CalibrateModuleResult, ErrorOccurrence]
+):
+    """Calibrate-module command model."""
+
+    commandType: CalibrateModuleCommandType = "calibration/calibrateModule"
+    params: CalibrateModuleParams
+    result: Optional[CalibrateModuleResult] = None
+
+    _ImplementationCls: Type[
+        CalibrateModuleImplementation
+    ] = CalibrateModuleImplementation
+
+
+class CalibrateModuleCreate(BaseCommandCreate[CalibrateModuleParams]):
+    """Create calibrate-module command request model."""
+
+    commandType: CalibrateModuleCommandType = "calibration/calibrateModule"
+    params: CalibrateModuleParams
+
+    _CommandCls: Type[CalibrateModule] = CalibrateModule

opentrons/protocol_engine/commands/calibration/calibrate_pipette.py

@@ -0,0 +1,96 @@
+"""Calibrate-pipette command for OT3 hardware. request, result, and implementation models."""
+from typing import Optional, Type
+from typing_extensions import Literal
+from pydantic import BaseModel, Field
+
+from ..command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ...errors.error_occurrence import ErrorOccurrence
+from ...types import InstrumentOffsetVector
+
+from opentrons.protocol_engine.resources.ot3_validation import ensure_ot3_hardware
+
+
+from opentrons.hardware_control import HardwareControlAPI
+from opentrons.hardware_control.types import OT3Mount
+from opentrons.hardware_control import ot3_calibration as calibration
+
+from opentrons.types import MountType
+
+CalibratePipetteCommandType = Literal["calibration/calibratePipette"]
+
+
+class CalibratePipetteParams(BaseModel):
+    """Payload required to calibrate-pipette."""
+
+    mount: MountType = Field(..., description="Instrument mount to calibrate.")
+
+
+class CalibratePipetteResult(BaseModel):
+    """Result data from the execution of a calibrate-pipette command."""
+
+    pipetteOffset: InstrumentOffsetVector = Field(
+        ..., description="Offset of calibrated pipette."
+    )
+
+
+class CalibratePipetteImplementation(
+    AbstractCommandImpl[CalibratePipetteParams, SuccessData[CalibratePipetteResult]]
+):
+    """CalibratePipette command implementation."""
+
+    def __init__(
+        self,
+        hardware_api: HardwareControlAPI,
+        **kwargs: object,
+    ) -> None:
+        self._hardware_api = hardware_api
+
+    async def execute(
+        self, params: CalibratePipetteParams
+    ) -> SuccessData[CalibratePipetteResult]:
+        """Execute calibrate-pipette command."""
+        # TODO (tz, 20-9-22): Add a better solution to determine if a command can be executed on an OT-3/OT-2
+        ot3_api = ensure_ot3_hardware(
+            self._hardware_api,
+        )
+        ot3_mount = OT3Mount.from_mount(params.mount)
+        assert (
+            ot3_mount is not OT3Mount.GRIPPER
+        ), "Expected a Pipette mount but Gripper mount was provided."
+
+        pipette_offset = await calibration.find_pipette_offset(
+            hcapi=ot3_api, mount=ot3_mount, slot=5
+        )
+
+        await ot3_api.save_instrument_offset(mount=ot3_mount, delta=pipette_offset)
+
+        return SuccessData(
+            public=CalibratePipetteResult.model_construct(
+                pipetteOffset=InstrumentOffsetVector.model_construct(
+                    x=pipette_offset.x, y=pipette_offset.y, z=pipette_offset.z
+                )
+            ),
+        )
+
+
+class CalibratePipette(
+    BaseCommand[CalibratePipetteParams, CalibratePipetteResult, ErrorOccurrence]
+):
+    """Calibrate-pipette command model."""
+
+    commandType: CalibratePipetteCommandType = "calibration/calibratePipette"
+    params: CalibratePipetteParams
+    result: Optional[CalibratePipetteResult] = None
+
+    _ImplementationCls: Type[
+        CalibratePipetteImplementation
+    ] = CalibratePipetteImplementation
+
+
+class CalibratePipetteCreate(BaseCommandCreate[CalibratePipetteParams]):
+    """Create calibrate-pipette command request model."""
+
+    commandType: CalibratePipetteCommandType = "calibration/calibratePipette"
+    params: CalibratePipetteParams
+
+    _CommandCls: Type[CalibratePipette] = CalibratePipette

opentrons/protocol_engine/commands/calibration/move_to_maintenance_position.py

@@ -0,0 +1,156 @@
+"""Calibration Move To Maintenance Location command payload, result, and implementation models."""
+from __future__ import annotations
+
+import enum
+from typing import TYPE_CHECKING, Type, Optional
+from typing_extensions import Literal
+
+from pydantic import BaseModel, Field
+
+from opentrons.types import MountType, Point, Mount
+from opentrons.hardware_control.types import Axis, CriticalPoint
+from ..command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ...errors.error_occurrence import ErrorOccurrence
+from opentrons.protocol_engine.resources.ot3_validation import ensure_ot3_hardware
+
+if TYPE_CHECKING:
+    from opentrons.hardware_control import HardwareControlAPI
+    from ...state.state import StateView
+
+# These offsets supplied from HW
+_ATTACH_POINT = Point(x=0, y=110)
+_MAX_Z_AXIS_MOTION_RANGE = 215
+# These offsets are by eye measuring
+_INSTRUMENT_ATTACH_Z_POINT = 400.0
+_LEFT_MOUNT_Z_MARGIN = 5
+# Move the right mount a bit higher than the left so the user won't forget to unscrew
+_RIGHT_MOUNT_Z_MARGIN = 20
+
+MoveToMaintenancePositionCommandType = Literal["calibration/moveToMaintenancePosition"]
+
+
+class MaintenancePosition(enum.Enum):
+    """Maintenance position options."""
+
+    ATTACH_PLATE = "attachPlate"
+    ATTACH_INSTRUMENT = "attachInstrument"
+
+
+class MoveToMaintenancePositionParams(BaseModel):
+    """Calibration set up position command parameters."""
+
+    mount: MountType = Field(
+        ...,
+        description="Gantry mount to move maintenance position.",
+    )
+
+    maintenancePosition: MaintenancePosition = Field(
+        MaintenancePosition.ATTACH_INSTRUMENT,
+        description="The position the gantry mount needs to move to.",
+    )
+
+
+class MoveToMaintenancePositionResult(BaseModel):
+    """Result data from the execution of a MoveToMaintenancePosition command."""
+
+
+class MoveToMaintenancePositionImplementation(
+    AbstractCommandImpl[
+        MoveToMaintenancePositionParams,
+        SuccessData[MoveToMaintenancePositionResult],
+    ]
+):
+    """Calibration set up position command implementation."""
+
+    def __init__(
+        self,
+        hardware_api: HardwareControlAPI,
+        state_view: StateView,
+        **kwargs: object,
+    ) -> None:
+        self._state_view = state_view
+        self._hardware_api = hardware_api
+
+    async def execute(
+        self, params: MoveToMaintenancePositionParams
+    ) -> SuccessData[MoveToMaintenancePositionResult]:
+        """Move the requested mount to a maintenance deck slot."""
+        ot3_api = ensure_ot3_hardware(
+            self._hardware_api,
+        )
+        max_height_z_tip = ot3_api.get_instrument_max_height(Mount.LEFT)
+        # disengage the gripper z mount if present and enabled
+        await ot3_api.prepare_for_mount_movement(Mount.LEFT)
+
+        await ot3_api.retract(Mount.LEFT)
+        current_pos = await ot3_api.gantry_position(
+            Mount.LEFT, critical_point=CriticalPoint.MOUNT
+        )
+        await ot3_api.move_to(
+            mount=Mount.LEFT,
+            abs_position=Point(x=_ATTACH_POINT.x, y=_ATTACH_POINT.y, z=current_pos.z),
+            critical_point=CriticalPoint.MOUNT,
+        )
+
+        if params.mount != MountType.EXTENSION:
+            if params.maintenancePosition == MaintenancePosition.ATTACH_INSTRUMENT:
+                mount = params.mount.to_hw_mount()
+                mount_to_axis = Axis.by_mount(mount)
+                await ot3_api.prepare_for_mount_movement(mount)
+                await ot3_api.move_axes(
+                    {
+                        mount_to_axis: _INSTRUMENT_ATTACH_Z_POINT,
+                    }
+                )
+                await ot3_api.disengage_axes([mount_to_axis])
+            else:
+                max_motion_range = max_height_z_tip - _MAX_Z_AXIS_MOTION_RANGE
+                await ot3_api.move_axes(
+                    {
+                        Axis.Z_L: max_motion_range + _LEFT_MOUNT_Z_MARGIN,
+                    }
+                )
+                await ot3_api.disengage_axes([Axis.Z_L])
+                await ot3_api.move_axes(
+                    {
+                        Axis.Z_R: max_motion_range + _RIGHT_MOUNT_Z_MARGIN,
+                    }
+                )
+                await ot3_api.disengage_axes([Axis.Z_R])
+
+        return SuccessData(
+            public=MoveToMaintenancePositionResult(),
+        )
+
+
+class MoveToMaintenancePosition(
+    BaseCommand[
+        MoveToMaintenancePositionParams,
+        MoveToMaintenancePositionResult,
+        ErrorOccurrence,
+    ]
+):
+    """Calibration set up position command model."""
+
+    commandType: MoveToMaintenancePositionCommandType = (
+        "calibration/moveToMaintenancePosition"
+    )
+    params: MoveToMaintenancePositionParams
+    result: Optional[MoveToMaintenancePositionResult] = None
+
+    _ImplementationCls: Type[
+        MoveToMaintenancePositionImplementation
+    ] = MoveToMaintenancePositionImplementation
+
+
+class MoveToMaintenancePositionCreate(
+    BaseCommandCreate[MoveToMaintenancePositionParams]
+):
+    """Calibration set up position command creation request model."""
+
+    commandType: MoveToMaintenancePositionCommandType = (
+        "calibration/moveToMaintenancePosition"
+    )
+    params: MoveToMaintenancePositionParams
+
+    _CommandCls: Type[MoveToMaintenancePosition] = MoveToMaintenancePosition