@opentrons/shared-data 0.0.0-alpha.14

package/protocol/types/schemaV6/index.ts

@@ -0,0 +1,122 @@
+import {
+  LoadedPipette,
+  LoadedLabware,
+  LoadedModule,
+  Liquid,
+  PipetteName,
+} from '../../../js'
+import type { CreateCommand, RunTimeCommand } from './command'
+import type {
+  LabwareDefinition2,
+  ModuleModel,
+  RobotType,
+} from '../../../js/types'
+
+export * from './command'
+
+// NOTE: must be kept in sync with '../schemas/6.json'
+export interface ProtocolFile<DesignerApplicationData = {}> {
+  $otSharedSchema: '#/protocol/schemas/6'
+  schemaVersion: 6
+  metadata: {
+    protocolName?: string
+    author?: string
+    description?: string | null | undefined
+    created?: number
+    lastModified?: number | null | undefined
+    category?: string | null | undefined
+    subcategory?: string | null | undefined
+    tags?: string[]
+  }
+  designerApplication?: {
+    name?: string
+    version?: string
+    data?: DesignerApplicationData
+  }
+  robot: {
+    model: 'OT-2 Standard' | 'OT-3 Standard'
+    deckId: 'ot2_standard' | 'ot2_short_trash' | 'ot3_standard'
+  }
+  pipettes: {
+    [pipetteId: string]: { name: PipetteName }
+  }
+  labwareDefinitions: {
+    [definitionId: string]: LabwareDefinition2
+  }
+  labware: {
+    [labwareId: string]: {
+      definitionId: string
+      displayName?: string
+    }
+  }
+  modules: {
+    [moduleId: string]: {
+      model: ModuleModel
+    }
+  }
+  liquids: {
+    [liquidId: string]: {
+      displayName: string
+      description: string
+      displayColor?: string
+    }
+  }
+  commands: CreateCommand[]
+  commandAnnotations?: {
+    commandIds: string[]
+    annotationType: string
+    params?: { [key: string]: any }
+  }
+}
+
+/**
+ * This type should not be used, any time you want a function/hook/component to take in
+ * a protocol file with run time commands, split your function signature to take in each param
+ * separately, and import the RunTimeCommand type separately. RunTimeCommand is a server concept
+ * and should not be mixed with our Protocol types
+ * @deprecated Use {@link ProtocolFile}
+ */
+export interface ProtocolAnalysisFile<DesignerApplicationData = {}>
+  extends Omit<ProtocolFile<DesignerApplicationData>, 'commands'> {
+  commands: RunTimeCommand[]
+}
+
+/**
+ * This type interface is represents the output of the opentrons analyze cli tool
+ * which contains the protocol analysis engine
+ * TODO: reconcile this type with that of the analysis returned from
+ * the protocols record endpoints on the robot-server
+ */
+export interface ProtocolAnalysisOutput {
+  createdAt: string
+  files: AnalysisSourceFile[]
+  config: JsonConfig | PythonConfig
+  metadata: { [key: string]: any }
+  commands: RunTimeCommand[]
+  labware: LoadedLabware[]
+  pipettes: LoadedPipette[]
+  modules: LoadedModule[]
+  liquids: Liquid[]
+  errors: AnalysisError[]
+  robotType?: RobotType
+}
+
+interface AnalysisSourceFile {
+  name: string
+  role: 'main' | 'labware'
+}
+export interface JsonConfig {
+  protocolType: 'json'
+  schemaVersion: number
+}
+export interface PythonConfig {
+  protocolType: 'python'
+  apiVersion: [major: number, minor: number]
+}
+
+interface AnalysisError {
+  id: string
+  errorType: string
+  createdAt: string
+  detail: string
+}

package/protocol/types/schemaV7/command/annotation.ts

@@ -0,0 +1,37 @@
+import type { CommonCommandRunTimeInfo, CommonCommandCreateInfo } from '.'
+
+export type AnnotationCreateCommand = CommentCreateCommand | CustomCreateCommand
+
+export type AnnotationRunTimeCommand =
+  | CommentRunTimeCommand
+  | CustomRunTimeCommand
+
+export interface CommentCreateCommand extends CommonCommandCreateInfo {
+  commandType: 'comment'
+  params: CommentParams
+}
+
+export interface CommentRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    CommentCreateCommand {
+  result?: any
+}
+
+interface CommentParams {
+  message: string
+}
+
+export interface CustomCreateCommand extends CommonCommandCreateInfo {
+  commandType: 'custom'
+  params: CustomParams
+}
+
+export interface CustomRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    CustomCreateCommand {
+  result?: any
+}
+
+interface CustomParams {
+  [key: string]: any
+}

package/protocol/types/schemaV7/command/calibration.ts

@@ -0,0 +1,84 @@
+import type { CommonCommandRunTimeInfo, CommonCommandCreateInfo } from '.'
+import type {
+  PipetteMount,
+  GantryMount,
+  LabwareOffset,
+  Coordinates,
+} from '../../../../js/types'
+// TODO (sb 10/26/22): Separate out calibration commands from protocol schema in RAUT-272
+export interface CalibratePipetteCreateCommand extends CommonCommandCreateInfo {
+  commandType: 'calibration/calibratePipette'
+  params: CalibratePipetteParams
+}
+export interface CalibrateGripperCreateCommand extends CommonCommandCreateInfo {
+  commandType: 'calibration/calibrateGripper'
+  params: CalibrateGripperParams
+}
+export interface CalibrateModuleCreateCommand extends CommonCommandCreateInfo {
+  commandType: 'calibration/calibrateModule'
+  params: CalibrateModuleParams
+}
+export interface MoveToMaintenancePositionCreateCommand
+  extends CommonCommandCreateInfo {
+  commandType: 'calibration/moveToMaintenancePosition'
+  params: MoveToMaintenancePositionParams
+}
+
+export interface CalibratePipetteRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    CalibratePipetteCreateCommand {
+  result?: CalibratePipetteResult
+}
+export interface CalibrateGripperRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    CalibrateGripperCreateCommand {
+  result?: CalibrateGripperResult
+}
+export interface CalibrateModuleRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    CalibrateModuleCreateCommand {
+  result?: CalibrateModuleResult
+}
+export interface MoveToMaintenancePositionRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    MoveToMaintenancePositionCreateCommand {
+  result?: {}
+}
+
+export type CalibrationRunTimeCommand =
+  | CalibratePipetteRunTimeCommand
+  | CalibrateGripperRunTimeCommand
+  | CalibrateModuleRunTimeCommand
+  | MoveToMaintenancePositionRunTimeCommand
+
+export type CalibrationCreateCommand =
+  | CalibratePipetteCreateCommand
+  | CalibrateGripperCreateCommand
+  | CalibrateModuleCreateCommand
+  | MoveToMaintenancePositionCreateCommand
+
+interface CalibratePipetteParams {
+  mount: PipetteMount
+}
+interface CalibrateGripperParams {
+  jaw: 'front' | 'rear'
+  otherJawOffset?: Coordinates
+}
+interface CalibrateModuleParams {
+  moduleId: string
+  labwareId: string
+  mount: PipetteMount
+}
+interface CalibratePipetteResult {
+  pipetteOffset: LabwareOffset
+}
+interface CalibrateGripperResult {
+  jawOffset: Coordinates
+}
+interface MoveToMaintenancePositionParams {
+  mount: GantryMount
+  maintenancePosition?: 'attachPlate' | 'attachInstrument'
+}
+interface CalibrateModuleResult {
+  moduleOffset: Coordinates
+}

package/protocol/types/schemaV7/command/gantry.ts

@@ -0,0 +1,154 @@
+import type { CommonCommandRunTimeInfo, CommonCommandCreateInfo } from '.'
+import type {
+  Coordinates,
+  MotorAxes,
+  MotorAxis,
+  GantryMount,
+} from '../../../../js/types'
+
+export interface MoveToSlotCreateCommand extends CommonCommandCreateInfo {
+  commandType: 'moveToSlot'
+  params: MoveToSlotParams
+}
+export interface MoveToSlotRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    MoveToSlotCreateCommand {
+  result?: {}
+}
+export interface MoveToWellCreateCommand extends CommonCommandCreateInfo {
+  commandType: 'moveToWell'
+  params: MoveToWellParams
+}
+export interface MoveToWellRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    MoveToWellCreateCommand {
+  result?: {}
+}
+export interface MoveToCoordinatesCreateCommand
+  extends CommonCommandCreateInfo {
+  commandType: 'moveToCoordinates'
+  params: MoveToCoordinatesParams
+}
+export interface MoveToCoordinatesRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    MoveToCoordinatesCreateCommand {
+  result?: {}
+}
+export interface MoveRelativeCreateCommand extends CommonCommandCreateInfo {
+  commandType: 'moveRelative'
+  params: MoveRelativeParams
+}
+export interface MoveRelativeRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    MoveRelativeCreateCommand {
+  result?: {
+    position: Coordinates
+  }
+}
+export interface SavePositionCreateCommand extends CommonCommandCreateInfo {
+  commandType: 'savePosition'
+  params: SavePositionParams
+}
+export interface SavePositionRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    SavePositionCreateCommand {
+  result?: {
+    positionId: string
+    position: Coordinates
+  }
+}
+export interface HomeCreateCommand extends CommonCommandCreateInfo {
+  commandType: 'home'
+  params: HomeParams
+}
+export interface HomeRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    HomeCreateCommand {
+  result?: {}
+}
+
+export interface RetractAxisCreateCommand extends CommonCommandCreateInfo {
+  commandType: 'retractAxis'
+  params: RetractAxisParams
+}
+export interface RetractAxisRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    RetractAxisCreateCommand {
+  result?: {}
+}
+
+export type GantryRunTimeCommand =
+  | MoveToSlotRunTimeCommand
+  | MoveToWellRunTimeCommand
+  | MoveToCoordinatesRunTimeCommand
+  | MoveRelativeRunTimeCommand
+  | SavePositionRunTimeCommand
+  | HomeRunTimeCommand
+  | RetractAxisRunTimeCommand
+
+export type GantryCreateCommand =
+  | MoveToSlotCreateCommand
+  | MoveToWellCreateCommand
+  | MoveToCoordinatesCreateCommand
+  | MoveRelativeCreateCommand
+  | SavePositionCreateCommand
+  | HomeCreateCommand
+  | RetractAxisCreateCommand
+interface MoveToSlotParams {
+  pipetteId: string
+  slotName: string
+  offset?: {
+    x: number
+    y: number
+    z: number
+  }
+  minimumZHeight?: number
+  forceDirect?: boolean
+}
+
+export interface MoveToWellParams {
+  pipetteId: string
+  labwareId: string
+  wellName: string
+  wellLocation?: {
+    origin?: 'top' | 'bottom'
+    offset?: {
+      x?: number
+      y?: number
+      z?: number
+    }
+  }
+  minimumZHeight?: number
+  forceDirect?: boolean
+}
+
+interface MoveToCoordinatesParams {
+  pipetteId: string
+  coordinates: {
+    x: number
+    y: number
+    z: number
+  }
+  minimumZHeight?: number
+  forceDirect?: boolean
+}
+
+interface MoveRelativeParams {
+  pipetteId: string
+  axis: 'x' | 'y' | 'z'
+  distance: number
+}
+
+interface SavePositionParams {
+  pipetteId: string // pipette to use in measurement
+  positionId?: string // position ID, auto-assigned if left blank
+}
+
+interface HomeParams {
+  axes?: MotorAxes
+  skipIfMountPositionOk?: GantryMount // If specified, only home if position invalid
+}
+
+interface RetractAxisParams {
+  axis: MotorAxis
+}

package/protocol/types/schemaV7/command/incidental.ts

@@ -0,0 +1,21 @@
+import type { CommonCommandRunTimeInfo, CommonCommandCreateInfo } from '.'
+import type { StatusBarAnimation } from '../../../../js/types'
+
+export type IncidentalCreateCommand = SetStatusBarCreateCommand
+
+export type IncidentalRunTimeCommand = SetStatusBarRunTimeCommand
+
+export interface SetStatusBarCreateCommand extends CommonCommandCreateInfo {
+  commandType: 'setStatusBar'
+  params: SetStatusBarParams
+}
+
+export interface SetStatusBarRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    SetStatusBarCreateCommand {
+  result?: any
+}
+
+interface SetStatusBarParams {
+  animation: StatusBarAnimation
+}

package/protocol/types/schemaV7/command/index.ts

@@ -0,0 +1,76 @@
+import type {
+  PipettingRunTimeCommand,
+  PipettingCreateCommand,
+} from './pipetting'
+import type { GantryRunTimeCommand, GantryCreateCommand } from './gantry'
+import type { ModuleRunTimeCommand, ModuleCreateCommand } from './module'
+import type { SetupRunTimeCommand, SetupCreateCommand } from './setup'
+import type { TimingRunTimeCommand, TimingCreateCommand } from './timing'
+import type {
+  IncidentalCreateCommand,
+  IncidentalRunTimeCommand,
+} from './incidental'
+import type {
+  AnnotationRunTimeCommand,
+  AnnotationCreateCommand,
+} from './annotation'
+import type {
+  CalibrationRunTimeCommand,
+  CalibrationCreateCommand,
+} from './calibration'
+
+export * from './annotation'
+export * from './calibration'
+export * from './gantry'
+export * from './module'
+export * from './pipetting'
+export * from './setup'
+export * from './timing'
+
+// NOTE: these key/value pairs will only be present on commands at analysis/run time
+// they pertain only to the actual execution status of a command on hardware, as opposed to
+// the command's identity and parameters which can be known prior to runtime
+
+export type CommandStatus = 'queued' | 'running' | 'succeeded' | 'failed'
+export interface CommonCommandRunTimeInfo {
+  key?: string
+  id: string
+  status: CommandStatus
+  error?: RunCommandError | null
+  createdAt: string
+  startedAt: string | null
+  completedAt: string | null
+  intent?: 'protocol' | 'setup'
+}
+export interface CommonCommandCreateInfo {
+  key?: string
+  meta?: { [key: string]: any }
+}
+
+export type CreateCommand =
+  | PipettingCreateCommand // involves the pipettes plunger motor
+  | GantryCreateCommand // movement that only effects the x,y,z position of the gantry/pipette
+  | ModuleCreateCommand // directed at a hardware module
+  | SetupCreateCommand // only effecting robot's equipment setup (pipettes, labware, modules, liquid), no hardware side-effects
+  | TimingCreateCommand // effecting the timing of command execution
+  | CalibrationCreateCommand // for automatic pipette calibration
+  | AnnotationCreateCommand // annotating command execution
+  | IncidentalCreateCommand // command with only incidental effects (status bar animations)
+
+// commands will be required to have a key, but will not be created with one
+export type RunTimeCommand =
+  | PipettingRunTimeCommand // involves the pipettes plunger motor
+  | GantryRunTimeCommand // movement that only effects the x,y,z position of the gantry/pipette
+  | ModuleRunTimeCommand // directed at a hardware module
+  | SetupRunTimeCommand // only effecting robot's equipment setup (pipettes, labware, modules, liquid), no hardware side-effects
+  | TimingRunTimeCommand // effecting the timing of command execution
+  | CalibrationRunTimeCommand // for automatic pipette calibration
+  | AnnotationRunTimeCommand // annotating command execution
+  | IncidentalRunTimeCommand // command with only incidental effects (status bar animations)
+
+interface RunCommandError {
+  id: string
+  errorType: string
+  createdAt: string
+  detail: string
+}