opentrons-shared-data 8.6.0a1__py3-none-any.whl

opentrons_shared_data/data/protocol/schemas/7.json

@@ -0,0 +1,290 @@
+{
+  "$id": "opentronsProtocolSchemaV7",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+
+  "definitions": {
+    "pipetteName": {
+      "description": "Name of a pipette. Does not contain info about specific model/version. Should match keys in pipetteNameSpecs.json file",
+      "type": "string",
+      "enum": [
+        "p10_single",
+        "p10_multi",
+        "p20_single_gen2",
+        "p20_multi_gen2",
+        "p50_single",
+        "p50_multi",
+        "p300_single",
+        "p300_multi",
+        "p300_single_gen2",
+        "p300_multi_gen2",
+        "p1000_single",
+        "p1000_single_gen2",
+        "p50_single_flex",
+        "p50_multi_flex",
+        "p1000_single_flex",
+        "p1000_multi_flex",
+        "p1000_96"
+      ]
+    },
+
+    "moduleOnlyParams": {
+      "required": ["moduleId"],
+      "additionalProperties": false,
+      "properties": {
+        "moduleId": {
+          "type": "string",
+          "description": "Unique identifier of module to target. Must be a key from the top level 'modules' object"
+        }
+      }
+    },
+
+    "offset": {
+      "description": "x, y, and z component of offset vector in mm",
+      "properties": {
+        "x": { "type": "number" },
+        "y": { "type": "number" },
+        "z": { "type": "number" }
+      }
+    },
+
+    "pipetteAccessParams": {
+      "required": ["pipetteId", "labwareId", "wellName"],
+      "properties": {
+        "pipetteId": {
+          "type": "string"
+        },
+        "labwareId": {
+          "type": "string"
+        },
+        "wellName": {
+          "type": "string"
+        }
+      }
+    },
+
+    "volumeParams": {
+      "required": ["volume"],
+      "volume": {
+        "type": "number"
+      }
+    },
+
+    "flowRate": {
+      "required": ["flowRate"],
+      "properties": {
+        "flowRate": {
+          "description": "flow rate in ul/sec",
+          "type": "number",
+          "exclusiveMinimum": 0
+        }
+      }
+    },
+
+    "wellLocation": {
+      "properties": {
+        "origin": {
+          "type": "string",
+          "description": "reference location with respect to a well from which to apply an offset if given (e.g. 'bottom' || 'top')"
+        },
+        "offset": {
+          "$ref": "#/definitions/offset",
+          "description": "X, Y, Z offset from the specified origin with respect to well"
+        }
+      }
+    },
+
+    "labwareLocation": {
+      "oneOf": [
+        {
+          "required": ["slotName"],
+          "properties": {
+            "slotName": {
+              "description": "Unique string identifier that corresponds to a slot in the referenced deck definition's locations",
+              "type": "string"
+            }
+          }
+        },
+        {
+          "required": ["moduleId"],
+          "properties": {
+            "moduleId": {
+              "description": "Unique identifier of destination module. Must be a key from the top level 'modules' object.",
+              "type": "string"
+            }
+          }
+        },
+        {
+          "const": "offDeck",
+          "description": "String literal 'offDeck'. Used to load a labware without placing it on the deck"
+        }
+      ]
+    }
+  },
+
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$otSharedSchema",
+    "schemaVersion",
+    "metadata",
+    "robot",
+    "labwareDefinitions",
+    "commands"
+  ],
+  "properties": {
+    "$otSharedSchema": {
+      "description": "The path to a valid Opentrons shared schema relative to the shared-data directory, without its extension.",
+      "enum": ["#/protocol/schemas/7"]
+    },
+
+    "schemaVersion": {
+      "description": "Schema version of a protocol is a single integer",
+      "enum": [7]
+    },
+
+    "metadata": {
+      "description": "Optional metadata about the protocol",
+      "type": "object",
+
+      "properties": {
+        "protocolName": {
+          "description": "A short, human-readable name for the protocol",
+          "type": "string"
+        },
+        "author": {
+          "description": "The author or organization who created the protocol",
+          "type": "string"
+        },
+        "description": {
+          "description": "A text description of the protocol.",
+          "type": ["string", "null"]
+        },
+
+        "created": {
+          "description": "UNIX timestamp when this file was created",
+          "type": "number"
+        },
+        "lastModified": {
+          "description": "UNIX timestamp when this file was last modified",
+          "type": ["number", "null"]
+        },
+
+        "category": {
+          "description": "Category of protocol (eg, \"Basic Pipetting\")",
+          "type": ["string", "null"]
+        },
+        "subcategory": {
+          "description": "Subcategory of protocol (eg, \"Cell Plating\")",
+          "type": ["string", "null"]
+        },
+        "tags": {
+          "description": "Tags to be used in searching for this protocol",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+
+    "designerApplication": {
+      "description": "Optional data & metadata not required to execute the protocol, used by the application that created this protocol",
+      "type": "object",
+      "properties": {
+        "name": {
+          "description": "Name of the application that created the protocol. Should be namespaced under the organization or individual who owns the organization, eg \"opentrons/protocol-designer\"",
+          "type": "string"
+        },
+        "version": {
+          "description": "Version of the application that created the protocol",
+          "type": "string"
+        },
+        "data": {
+          "description": "Any data used by the application that created this protocol",
+          "type": "object"
+        }
+      }
+    },
+
+    "robot": {
+      "required": ["model", "deckId"],
+      "properties": {
+        "model": {
+          "description": "Model of the robot this protocol is written for",
+          "type": "string",
+          "enum": ["OT-2 Standard", "OT-3 Standard"]
+        },
+        "deckId": {
+          "description": "Identifier of physical deck this protocol is written for. This should match a top-level key in shared-data/deck/definitions/3.json",
+          "type": "string"
+        }
+      }
+    },
+
+    "labwareDefinitions": {
+      "description": "All labware definitions used by labware in this protocol, keyed by a unique identifier (definitionId)",
+      "patternProperties": {
+        ".+": {
+          "$ref": "opentronsLabwareSchemaV2"
+        }
+      }
+    },
+
+    "liquids": {
+      "description": "All instances of liquid used in this protocol, keyed by a unique identifier (liquidId)",
+      "patternProperties": {
+        ".+": {
+          "description": "Fields describing a single liquid",
+          "type": "object",
+          "required": ["displayName", "description"],
+          "properties": {
+            "displayName": {
+              "description": "An human-readable name for this liquid.",
+              "type": "string"
+            },
+            "description": {
+              "description": "A description of this liquid.",
+              "type": "string"
+            },
+            "displayColor": {
+              "description": "Hex color code, with hash included, to represent the specified liquid. Standard three-value, four-value, six-value, and eight-value syntax are all acceptable.",
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+
+    "commands": {
+      "description": "An array of command objects representing steps to be executed on the robot.",
+      "type": "array",
+      "items": { "$ref": "opentronsCommandSchemaV7" }
+    },
+
+    "commandAnnotations": {
+      "type": "array",
+      "items": {
+        "description": "An optional object of annotations associated with commands.",
+        "type": "object",
+        "required": ["commandIds", "annotationType"],
+        "properties": {
+          "commandIds": {
+            "description": "An array of command ids that correspond to the targeted grouping of this annotation",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "annotationType": {
+            "description": "The type of annotation (e.g. 'transfer', 'initialSetup')",
+            "type": "string"
+          },
+          "params": {
+            "description": "The parameters used to create this grouping of atomic commands",
+            "type": "object"
+          }
+        }
+      }
+    }
+  }
+}

opentrons_shared_data/data/protocol/schemas/8.json

@@ -0,0 +1,157 @@
+{
+  "$id": "opentronsProtocolSchemaV8",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+
+  "definitions": {},
+
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$otSharedSchema",
+    "schemaVersion",
+    "metadata",
+    "robot",
+    "labwareDefinitions",
+    "labwareDefinitionSchemaId",
+    "commands",
+    "commandSchemaId",
+    "commandAnnotations",
+    "commandAnnotationSchemaId",
+    "liquids",
+    "liquidSchemaId"
+  ],
+  "properties": {
+    "$otSharedSchema": {
+      "description": "The path to a valid Opentrons shared schema relative to the shared-data directory, without its extension.",
+      "enum": ["#/protocol/schemas/8"]
+    },
+
+    "schemaVersion": {
+      "description": "Schema version of a protocol is a single integer",
+      "enum": [8]
+    },
+
+    "metadata": {
+      "description": "Optional metadata about the protocol",
+      "type": "object",
+
+      "properties": {
+        "protocolName": {
+          "description": "A short, human-readable name for the protocol",
+          "type": "string"
+        },
+        "author": {
+          "description": "The author or organization who created the protocol",
+          "type": "string"
+        },
+        "description": {
+          "description": "A text description of the protocol.",
+          "type": ["string", "null"]
+        },
+
+        "created": {
+          "description": "UNIX timestamp when this file was created",
+          "type": "number"
+        },
+        "lastModified": {
+          "description": "UNIX timestamp when this file was last modified",
+          "type": ["number", "null"]
+        },
+
+        "category": {
+          "description": "Category of protocol (eg, \"Basic Pipetting\")",
+          "type": ["string", "null"]
+        },
+        "subcategory": {
+          "description": "Subcategory of protocol (eg, \"Cell Plating\")",
+          "type": ["string", "null"]
+        },
+        "tags": {
+          "description": "Tags to be used in searching for this protocol",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+
+    "designerApplication": {
+      "description": "Optional data & metadata not required to execute the protocol, used by the application that created this protocol",
+      "type": "object",
+      "properties": {
+        "name": {
+          "description": "Name of the application that created the protocol. Should be namespaced under the organization or individual who owns the organization, eg \"opentrons/protocol-designer\"",
+          "type": "string"
+        },
+        "version": {
+          "description": "Version of the application that created the protocol",
+          "type": "string"
+        },
+        "data": {
+          "description": "Any data used by the application that created this protocol",
+          "type": "object"
+        }
+      }
+    },
+
+    "robot": {
+      "required": ["model", "deckId"],
+      "properties": {
+        "model": {
+          "description": "Model of the robot this protocol is written for",
+          "type": "string",
+          "enum": ["OT-2 Standard", "OT-3 Standard"]
+        },
+        "deckId": {
+          "description": "Identifier of physical deck this protocol is written for. This should match a definition in the shared-data directory matching the schema id",
+          "type": "string"
+        }
+      }
+    },
+
+    "labwareDefinitionSchemaId": {
+      "description": "The schema to use for labware definitions.",
+      "type": "string"
+    },
+
+    "labwareDefinitions": {
+      "description": "All labware definitions used by labware in this protocol, keyed by a unique identifier (definitionId)",
+      "patternProperties": {
+        ".+": { "type": "object" }
+      }
+    },
+
+    "liquidSchemaId": {
+      "description": "The schema to use for liquid definitions.",
+      "type": "string"
+    },
+
+    "liquids": {
+      "description": "All instances of liquid used in this protocol, keyed by a unique identifier (liquidId)",
+      "patternProperties": {
+        ".+": { "type": "object" }
+      }
+    },
+    "commandSchemaId": {
+      "description": "The schema to which the commands adhere.",
+      "type": "string"
+    },
+
+    "commands": {
+      "description": "An array of command objects representing steps to be executed on the robot.",
+      "type": "array",
+      "items": { "type": "object" }
+    },
+
+    "commandAnnotationSchemaId": {
+      "description": "The schema to which the command annotations adhere.",
+      "type": "string"
+    },
+
+    "commandAnnotations": {
+      "type": "array",
+      "items": { "type": "object" }
+    }
+  }
+}

opentrons_shared_data/data/robot/definitions/1/ot2.json

@@ -0,0 +1,16 @@
+{
+  "displayName": "OT-2",
+  "robotType": "OT-2 Standard",
+  "models": ["OT-2 Standard", "OT-2 Refresh"],
+  "extents": [446.75, 347.5, 0.0],
+  "paddingOffsets": {
+    "rear": -35.91,
+    "front": 31.89,
+    "leftSide": 0,
+    "rightSide": 0
+  },
+  "mountOffsets": {
+    "left": [-34.0, 0.0, 0.0],
+    "right": [0.0, 0.0, 0.0]
+  }
+}

opentrons_shared_data/data/robot/definitions/1/ot3.json

@@ -0,0 +1,17 @@
+{
+  "displayName": "OT-3",
+  "robotType": "OT-3 Standard",
+  "models": ["OT-3 Standard"],
+  "extents": [477.2, 493.8, 0.0],
+  "paddingOffsets": {
+    "rear": -169.42,
+    "front": 51.8,
+    "leftSide": 31.88,
+    "rightSide": -80.32
+  },
+  "mountOffsets": {
+    "left": [-13.5, -60.5, 255.675],
+    "right": [40.5, -60.5, 255.675],
+    "gripper": [84.55, -12.75, 93.85]
+  }
+}

opentrons_shared_data/data/robot/schemas/1.json

@@ -0,0 +1,83 @@
+{
+  "$id": "opentronsRobotSchemaV1",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "robotType": {
+      "type": "string",
+      "enum": ["OT-2 Standard", "OT-3 Standard"]
+    },
+    "xyzArray": {
+      "type": "array",
+      "description": "Array of 3 numbers, [x, y, z]",
+      "items": { "type": "number" },
+      "minItems": 3,
+      "maxItems": 3
+    }
+  },
+  "description": "Describes an Opentrons liquid handling robot.",
+  "type": "object",
+  "required": ["displayName", "robotType", "models", "extents", "mountOffsets"],
+  "properties": {
+    "displayName": {
+      "description": "A user-facing friendly name for the machine.",
+      "type": "string"
+    },
+    "robotType": {
+      "description": "A machine-readable but still printable name for the machine.",
+      "$ref": "#/definitions/robotType"
+    },
+    "models": {
+      "description": "A list of robot models.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "extents": {
+      "description": "The maximum addressable coordinates of the deck without instruments.",
+      "$ref": "#/definitions/xyzArray"
+    },
+    "paddingOffsets": {
+      "description": "The distance from a given edge of a deck extent by which the maximum amount of travel is limited.",
+      "type": "object",
+      "required": ["rear", "front", "leftSide", "rightSide"],
+      "properties": {
+        "rear": {
+          "description": "The padding distance from the rear edge of the deck extents which the front nozzles of a pipette must not exceed.",
+          "type": "number"
+        },
+        "front": {
+          "description": "The padding distance from the front edge of the deck extents which the rear nozzles of a pipette must not exceed.",
+          "type": "number"
+        },
+        "leftSide": {
+          "description": "The padding distance from the left edge of the deck extents which the right-most nozzles of a pipette must not exceed.",
+          "type": "number"
+        },
+        "rightSide": {
+          "description": "The padding distance from the right edge of the deck extents which the left-most nozzles of a pipette must not exceed.",
+          "type": "number"
+        }
+      }
+    },
+    "mountOffsets": {
+      "description": "The physical mount offsets from the center of the instrument carriage.",
+      "type": "object",
+      "required": ["left", "right"],
+      "properties": {
+        "left": {
+          "description": "The left mount offset from the center of the carriage to the center of the left mount",
+          "$ref": "#/definitions/xyzArray"
+        },
+        "right": {
+          "description": "The right mount offset from the center of the carriage to the center of the right mount",
+          "$ref": "#/definitions/xyzArray"
+        },
+        "gripper": {
+          "description": "The gripper mount offset from the center of the carriage to the center of the gripper, only on OT-3 Standard definitions",
+          "$ref": "#/definitions/xyzArray"
+        }
+      }
+    }
+  }
+}

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)