opentrons-shared-data 8.8.0a10__py3-none-any.whl

opentrons_shared_data/deck/__init__.py

@@ -0,0 +1,108 @@
+"""
+opentrons_shared_data.deck: types and bindings for deck definitions
+"""
+from typing import Dict, List, NamedTuple, cast, overload, TYPE_CHECKING
+from typing_extensions import Final
+import json
+
+from .. import get_shared_data_root, load_shared_data
+
+if TYPE_CHECKING:
+    from .types import (
+        DeckSchema,
+        DeckDefinition,
+        DeckDefinitionV3,
+        DeckSchemaVersion3,
+        DeckDefinitionV4,
+        DeckSchemaVersion4,
+        DeckDefinitionV5,
+        DeckSchemaVersion5,
+    )
+
+DEFAULT_DECK_DEFINITION_VERSION: Final = 5
+
+
+class Offset(NamedTuple):
+    x: float = 0.0
+    y: float = 0.0
+    z: float = 0.0
+
+
+Z_PREP_OFFSET = Offset(x=13, y=13)
+CALIBRATION_PROBE_RADIUS: Final[float] = 2
+CALIBRATION_SQUARE_DEPTH: Final[float] = -0.25
+CALIBRATION_SQUARE_SIZE: Final[float] = 20
+CALIBRATION_SQUARE_EDGES: Dict[str, Offset] = {
+    "left": Offset(x=-CALIBRATION_SQUARE_SIZE * 0.5),
+    "right": Offset(x=CALIBRATION_SQUARE_SIZE * 0.5),
+    "top": Offset(y=CALIBRATION_SQUARE_SIZE * 0.5),
+    "bottom": Offset(y=-CALIBRATION_SQUARE_SIZE * 0.5),
+}
+
+
+@overload
+def load(name: str, version: "DeckSchemaVersion5") -> "DeckDefinitionV5":
+    ...
+
+
+@overload
+def load(name: str, version: "DeckSchemaVersion4") -> "DeckDefinitionV4":
+    ...
+
+
+@overload
+def load(name: str, version: "DeckSchemaVersion3") -> "DeckDefinitionV3":
+    ...
+
+
+@overload
+def load(name: str) -> "DeckDefinitionV5":
+    ...
+
+
+def load(name: str, version: int = DEFAULT_DECK_DEFINITION_VERSION) -> "DeckDefinition":
+    return json.loads(  # type: ignore[no-any-return]
+        load_shared_data(f"deck/definitions/{version}/{name}.json")
+    )
+
+
+def load_schema(version: int) -> "DeckSchema":
+    return cast(
+        "DeckSchema", json.loads(load_shared_data(f"deck/schemas/{version}.json"))
+    )
+
+
+def list_names(version: int) -> List[str]:
+    """Return all loadable deck definition names, for the given schema version."""
+    definitions_directory = (
+        get_shared_data_root() / "deck" / "definitions" / f"{version}"
+    )
+    return [file.stem for file in definitions_directory.iterdir()]
+
+
+def get_calibration_square_position_in_slot(slot: int) -> Offset:
+    """Get the position of an OT-3 deck slot's calibration square.
+
+    Params:
+        slot: The slot whose calibration square to retrieve, specified as an OT-2-style slot number.
+            For example, specify 5 to get slot C2.
+    """
+    deck = load("ot3_standard", version=3)
+    slots = deck["locations"]["orderedSlots"]
+
+    # Assume that the OT-3 deck definition has the same number of slots, and in the same order,
+    # as the OT-2.
+    # TODO(mm, 2023-05-22): This assumption will break down when the OT-3 has staging area slots.
+    # https://opentrons.atlassian.net/browse/RLAB-345
+    s = slots[slot - 1]
+
+    bottom_left = s["position"]
+    slot_size_x = s["boundingBox"]["xDimension"]
+    slot_size_y = s["boundingBox"]["yDimension"]
+    relative_center = [float(slot_size_x) * 0.5, float(slot_size_y) * 0.5, 0]
+    square_z = [0, 0, CALIBRATION_SQUARE_DEPTH]
+    # add up the elements of each list and return an Offset of the result
+    nominal_position = [
+        float(sum(x)) for x in zip(bottom_left, relative_center, square_z)
+    ]
+    return Offset(*nominal_position)

opentrons_shared_data/deck/types.py

@@ -0,0 +1,216 @@
+"""
+opentrons_shared_data.deck.types: types for deck defs
+
+This should only be imported if typing.TYPE_CHECKING is True
+"""
+
+from typing import Any, Dict, List, NewType, Union
+from typing_extensions import Literal, TypedDict
+
+from ..module.types import ModuleType, ModuleOrientation
+from opentrons_shared_data.labware.types import LocatingFeatures
+
+
+DeckSchemaVersion5 = Literal[5]
+DeckSchemaVersion4 = Literal[4]
+DeckSchemaVersion3 = Literal[3]
+DeckSchemaVersion2 = Literal[2]
+DeckSchemaVersion1 = Literal[1]
+
+DeckSchema = NewType("DeckSchema", Dict[str, Any])
+
+DeckSchemaId = Literal["opentronsDeckSchemaV3", "opentronsDeckSchemaV4"]
+RobotModel = Union[Literal["OT-2 Standard"], Literal["OT-3 Standard"]]
+
+
+class Metadata(TypedDict, total=False):
+    displayName: str
+    tags: List[str]
+
+
+class Robot(TypedDict):
+    model: RobotModel
+
+
+class BoundingBox(TypedDict):
+    xDimension: float
+    yDimension: float
+    zDimension: float
+
+
+class SlotDefV3(TypedDict, total=False):
+    id: str
+    position: List[float]
+    boundingBox: BoundingBox
+    displayName: str
+    compatibleModuleTypes: List[ModuleType]
+    matingSurfaceUnitVector: List[Union[Literal[1], Literal[-1]]]
+    features: LocatingFeatures
+    orientation: ModuleOrientation
+
+
+class CalibrationPoint(TypedDict):
+    id: str
+    position: List[float]
+    displayName: str
+
+
+class INode(TypedDict):
+    name: str
+    type: str
+    value: str
+    attributes: Dict[str, str]
+    # this should be a recursive call to INode but we need to upgrade mypy
+    children: List[Dict[str, Any]]
+
+
+class FixedLabwareBySlot(TypedDict):
+    id: str
+    displayName: str
+    labware: str
+    slot: str
+
+
+class FixedLabwareByPosition(TypedDict):
+    id: str
+    displayName: str
+    labware: str
+    position: List[float]
+
+
+class FixedVolumeBySlot(TypedDict):
+    id: str
+    displayName: str
+    boundingBox: BoundingBox
+    slot: str
+
+
+class FixedVolumeByPosition(TypedDict):
+    id: str
+    displayName: str
+    boundingBox: BoundingBox
+    position: List[float]
+
+
+class _RequiredAddressableArea(TypedDict):
+    id: str
+    areaType: str
+    offsetFromCutoutFixture: List[float]
+    boundingBox: BoundingBox
+    displayName: str
+
+
+class AddressableArea(_RequiredAddressableArea, total=False):
+    compatibleModuleTypes: List[ModuleType]
+    matingSurfaceUnitVector: List[Union[Literal[1], Literal[-1]]]
+    ableToDropTips: bool
+    ableToDropLabware: bool
+
+
+class AddressableAreaV5(_RequiredAddressableArea, total=False):
+    compatibleModuleTypes: List[ModuleType]
+    matingSurfaceUnitVector: List[Union[Literal[1], Literal[-1]]]
+    ableToDropTips: bool
+    ableToDropLabware: bool
+    features: LocatingFeatures
+    orientation: Union[ModuleOrientation, None]
+
+
+class Cutout(TypedDict):
+    id: str
+    position: List[float]
+    displayName: str
+
+
+class CutoutFixture(TypedDict):
+    id: str
+    expectOpentronsModuleSerialNumber: bool
+    mayMountTo: List[str]
+    displayName: str
+    providesAddressableAreas: Dict[str, List[str]]
+    fixtureGroup: Dict[str, List[Dict[str, str]]]
+    height: float
+
+
+Fixture = Union[
+    FixedLabwareBySlot, FixedLabwareByPosition, FixedVolumeBySlot, FixedVolumeByPosition
+]
+
+
+class LocationsV3(TypedDict):
+    orderedSlots: List[SlotDefV3]
+    calibrationPoints: List[CalibrationPoint]
+    fixtures: List[Fixture]
+
+
+class LocationsV4(TypedDict):
+    addressableAreas: List[AddressableArea]
+    calibrationPoints: List[CalibrationPoint]
+    cutouts: List[Cutout]
+    legacyFixtures: List[Fixture]
+
+
+class LocationsV5(TypedDict):
+    addressableAreas: List[AddressableAreaV5]
+    calibrationPoints: List[CalibrationPoint]
+    cutouts: List[Cutout]
+    legacyFixtures: List[Fixture]
+
+
+class NamedOffset(TypedDict):
+    x: float
+    y: float
+    z: float
+
+
+class GripperOffsets(TypedDict):
+    pickUpOffset: NamedOffset
+    dropOffset: NamedOffset
+
+
+class _RequiredDeckDefinitionV3(TypedDict):
+    otId: str
+    schemaVersion: Literal[3]
+    cornerOffsetFromOrigin: List[float]
+    dimensions: List[float]
+    metadata: Metadata
+    robot: Robot
+    locations: LocationsV3
+    layers: List[INode]
+
+
+class DeckDefinitionV3(_RequiredDeckDefinitionV3, total=False):
+    gripperOffsets: Dict[str, GripperOffsets]
+
+
+class _RequiredDeckDefinitionV4(TypedDict):
+    otId: str
+    schemaVersion: Literal[4]
+    cornerOffsetFromOrigin: List[float]
+    dimensions: List[float]
+    metadata: Metadata
+    robot: Robot
+    locations: LocationsV4
+    cutoutFixtures: List[CutoutFixture]
+
+
+class DeckDefinitionV4(_RequiredDeckDefinitionV4, total=False):
+    gripperOffsets: Dict[str, GripperOffsets]
+
+
+class _RequiredDeckDefinitionV5(TypedDict):
+    otId: str
+    schemaVersion: Literal[5]
+    cornerOffsetFromOrigin: List[float]
+    dimensions: List[float]
+    metadata: Metadata
+    robot: Robot
+    locations: LocationsV5
+    cutoutFixtures: List[CutoutFixture]
+
+
+class DeckDefinitionV5(_RequiredDeckDefinitionV5, total=False):
+    gripperOffsets: Dict[str, GripperOffsets]
+
+
+DeckDefinition = Union[DeckDefinitionV3, DeckDefinitionV4, DeckDefinitionV5]

opentrons_shared_data/errors/__init__.py

@@ -0,0 +1,30 @@
+"""A python package implementing the errors in errors.json.
+
+A note on this package: it is not codegenned but written by hand, and has to be upkept
+by hand. It comes with tests to make sure this happens.
+
+This seems a little ridiculous and kind of is, but what it lets us do is really simplify
+our static analysis and dev setup.
+"""
+
+from .categories import ErrorCategories, ErrorCategory
+from .codes import ErrorCodes, ErrorCode
+from .exceptions import (
+    EnumeratedError,
+    PythonException,
+    GeneralError,
+    RoboticsControlError,
+    RoboticsInteractionError,
+)
+
+__all__ = [
+    "ErrorCategory",
+    "ErrorCategories",
+    "ErrorCode",
+    "ErrorCodes",
+    "EnumeratedError",
+    "PythonException",
+    "GeneralError",
+    "RoboticsControlError",
+    "RoboticsInteractionError",
+]

opentrons_shared_data/errors/categories.py

@@ -0,0 +1,60 @@
+"""Error categories."""
+
+from enum import Enum
+from dataclasses import dataclass
+import json
+from functools import lru_cache
+from typing import Dict
+
+from ..load import load_shared_data
+
+
+CATEGORIES: Dict[str, Dict[str, str]] = json.loads(
+    load_shared_data("errors/definitions/1/errors.json")
+)["categories"]
+
+
+@dataclass(frozen=True)
+class ErrorCategory:
+    """Individual error category data."""
+
+    name: str
+    detail: str
+    code_prefix: str
+
+
+def _category_from_dict_entry(entry_name: str) -> ErrorCategory:
+    return ErrorCategory(
+        name=entry_name,
+        detail=CATEGORIES[entry_name]["detail"],
+        code_prefix=CATEGORIES[entry_name]["codePrefix"],
+    )
+
+
+class ErrorCategories(Enum):
+    """All enuemrated error categories."""
+
+    HARDWARE_COMMUNICATION_ERROR = _category_from_dict_entry(
+        "hardwareCommunicationError"
+    )
+    ROBOTICS_CONTROL_ERROR = _category_from_dict_entry("roboticsControlError")
+    ROBOTICS_INTERACTION_ERROR = _category_from_dict_entry("roboticsInteractionError")
+    GENERAL_ERROR = _category_from_dict_entry("generalError")
+
+    @classmethod
+    @lru_cache(4)
+    def by_category_name(cls, category_name: str) -> "ErrorCategories":
+        """Get a subsystem by its category name."""
+        for entry in cls:
+            if entry.value.name == category_name:
+                return entry
+        raise KeyError(category_name)
+
+    @classmethod
+    @lru_cache(4)
+    def by_code_prefix(cls, prefix: str) -> "ErrorCategories":
+        """Get an error category by its code prefix."""
+        for entry in cls:
+            if entry.value.code_prefix == prefix:
+                return entry
+        raise KeyError(prefix)

opentrons_shared_data/errors/codes.py

@@ -0,0 +1,124 @@
+"""Error codes."""
+
+from enum import Enum
+from dataclasses import dataclass
+import json
+from typing import Tuple, Dict
+from functools import lru_cache
+
+from ..load import load_shared_data
+from .categories import ErrorCategories
+
+CODES: Dict[str, Dict[str, str]] = json.loads(
+    load_shared_data("errors/definitions/1/errors.json")
+)["codes"]
+
+
+@dataclass(frozen=True)
+class ErrorCode:
+    """Individual error code data."""
+
+    code: str
+    detail: str
+    category: ErrorCategories
+
+
+def _code_from_dict_entry(entry_code: str) -> ErrorCode:
+    return ErrorCode(
+        code=entry_code,
+        detail=CODES[entry_code]["detail"],
+        category=ErrorCategories.by_category_name(CODES[entry_code]["category"]),
+    )
+
+
+class ErrorCodes(Enum):
+    """All enumerated error codes."""
+
+    COMMUNICATION_ERROR = _code_from_dict_entry("1000")
+    CANBUS_COMMUNICATION_ERROR = _code_from_dict_entry("1001")
+    INTERNAL_USB_COMMUNICATION_ERROR = _code_from_dict_entry("1002")
+    MODULE_COMMUNICATION_ERROR = _code_from_dict_entry("1003")
+    COMMAND_TIMED_OUT = _code_from_dict_entry("1004")
+    FIRMWARE_UPDATE_FAILED = _code_from_dict_entry("1005")
+    INTERNAL_MESSAGE_FORMAT_ERROR = _code_from_dict_entry("1006")
+    CANBUS_CONFIGURATION_ERROR = _code_from_dict_entry("1007")
+    CANBUS_BUS_ERROR = _code_from_dict_entry("1008")
+    ROBOTICS_CONTROL_ERROR = _code_from_dict_entry("2000")
+    MOTION_FAILED = _code_from_dict_entry("2001")
+    HOMING_FAILED = _code_from_dict_entry("2002")
+    STALL_OR_COLLISION_DETECTED = _code_from_dict_entry("2003")
+    MOTION_PLANNING_FAILURE = _code_from_dict_entry("2004")
+    POSITION_ESTIMATION_INVALID = _code_from_dict_entry("2005")
+    MOVE_CONDITION_NOT_MET = _code_from_dict_entry("2006")
+    CALIBRATION_STRUCTURE_NOT_FOUND = _code_from_dict_entry("2007")
+    EDGE_NOT_FOUND = _code_from_dict_entry("2008")
+    EARLY_CAPACITIVE_SENSE_TRIGGER = _code_from_dict_entry("2009")
+    INACCURATE_NON_CONTACT_SWEEP = _code_from_dict_entry("2010")
+    MISALIGNED_GANTRY = _code_from_dict_entry("2011")
+    UNMATCHED_TIP_PRESENCE_STATES = _code_from_dict_entry("2012")
+    POSITION_UNKNOWN = _code_from_dict_entry("2013")
+    EXECUTION_CANCELLED = _code_from_dict_entry("2014")
+    FAILED_GRIPPER_PICKUP_ERROR = _code_from_dict_entry("2015")
+    MOTOR_DRIVER_ERROR = _code_from_dict_entry("2016")
+    PIPETTE_LIQUID_NOT_FOUND = _code_from_dict_entry("2017")
+    TIP_HIT_WELL_BOTTOM = _code_from_dict_entry("2018")
+    STACKER_STALL_OR_COLLISION_DETECTED = _code_from_dict_entry("2019")
+    ROBOTICS_INTERACTION_ERROR = _code_from_dict_entry("3000")
+    LABWARE_DROPPED = _code_from_dict_entry("3001")
+    LABWARE_NOT_PICKED_UP = _code_from_dict_entry("3002")
+    TIP_PICKUP_FAILED = _code_from_dict_entry("3003")
+    TIP_DROP_FAILED = _code_from_dict_entry("3004")
+    UNEXPECTED_TIP_REMOVAL = _code_from_dict_entry("3005")
+    PIPETTE_OVERPRESSURE = _code_from_dict_entry("3006")
+    E_STOP_ACTIVATED = _code_from_dict_entry("3008")
+    E_STOP_NOT_PRESENT = _code_from_dict_entry("3009")
+    PIPETTE_NOT_PRESENT = _code_from_dict_entry("3010")
+    GRIPPER_NOT_PRESENT = _code_from_dict_entry("3011")
+    UNEXPECTED_TIP_ATTACH = _code_from_dict_entry("3012")
+    FIRMWARE_UPDATE_REQUIRED = _code_from_dict_entry("3013")
+    INVALID_ACTUATOR = _code_from_dict_entry("3014")
+    MODULE_NOT_PRESENT = _code_from_dict_entry("3015")
+    INVALID_INSTRUMENT_DATA = _code_from_dict_entry("3016")
+    INVALID_LIQUID_CLASS_NAME = _code_from_dict_entry("3017")
+    TIP_DETECTOR_NOT_FOUND = _code_from_dict_entry("3018")
+    HEPA_UV_FAILED = _code_from_dict_entry("3019")
+    STACKER_SHUTTLE_MISSING = _code_from_dict_entry("3020")
+    STACKER_SHUTTLE_LABWARE_FAILED = _code_from_dict_entry("3021")
+    STACKER_HOPPER_LABWARE_FAILED = _code_from_dict_entry("3022")
+    STACKER_SHUTTLE_OCCUPIED = _code_from_dict_entry("3023")
+    GENERAL_ERROR = _code_from_dict_entry("4000")
+    ROBOT_IN_USE = _code_from_dict_entry("4001")
+    API_REMOVED = _code_from_dict_entry("4002")
+    NOT_SUPPORTED_ON_ROBOT_TYPE = _code_from_dict_entry("4003")
+    COMMAND_PRECONDITION_VIOLATED = _code_from_dict_entry("4004")
+    COMMAND_PARAMETER_LIMIT_VIOLATED = _code_from_dict_entry("4005")
+    INVALID_PROTOCOL_DATA = _code_from_dict_entry("4006")
+    API_MISCONFIGURATION = _code_from_dict_entry("4007")
+    INVALID_STORED_DATA = _code_from_dict_entry("4008")
+    MISSING_CONFIGURATION_DATA = _code_from_dict_entry("4009")
+    RUNTIME_PARAMETER_VALUE_REQUIRED = _code_from_dict_entry("4010")
+    INCORRECT_API_VERSION = _code_from_dict_entry("4011")
+    LABWARE_LOCATING_FEATURE_ERROR = _code_from_dict_entry("4012")
+    CAMERA_ERROR = _code_from_dict_entry("4013")
+
+    @classmethod
+    @lru_cache(25)
+    def by_error_code(cls, error_code: str) -> "ErrorCodes":
+        """Get an error by its code.
+
+        Note: this is a linear search because it makes life easier and also this is rare in python.
+        """
+        for error in cls:
+            if error.value.code == error_code:
+                return error
+        raise KeyError(error_code)
+
+    @classmethod
+    @lru_cache(len(ErrorCategories))
+    def of_category(cls, category: ErrorCategories) -> Tuple["ErrorCodes", ...]:
+        """Get all error codes by their category."""
+        return tuple(
+            error
+            for error in cls
+            if error.value.code.startswith(category.value.code_prefix)
+        )