@opentrons/shared-data 0.1.7-alpha.0 → 0.1.7-alpha.1

package/command/types/annotation.ts

@@ -1,4 +1,4 @@
-import type { CommonCommandRunTimeInfo, CommonCommandCreateInfo } from '.'
+import type { CommonCommandCreateInfo, CommonCommandRunTimeInfo } from '.'
 
 export type AnnotationCreateCommand = CommentCreateCommand | CustomCreateCommand
 

package/command/types/calibration.ts

@@ -1,10 +1,11 @@
-import type { CommonCommandRunTimeInfo, CommonCommandCreateInfo } from '.'
+import type { CommonCommandCreateInfo, CommonCommandRunTimeInfo } from '.'
 import type {
-  PipetteMount,
   GantryMount,
   LabwareOffset,
-  Coordinates,
+  PipetteMount,
+  Vector3D,
 } 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'
@@ -62,7 +63,7 @@ interface CalibratePipetteParams {
 }
 interface CalibrateGripperParams {
   jaw: 'front' | 'rear'
-  otherJawOffset?: Coordinates
+  otherJawOffset?: Vector3D
 }
 interface CalibrateModuleParams {
   moduleId: string
@@ -73,12 +74,12 @@ interface CalibratePipetteResult {
   pipetteOffset: LabwareOffset
 }
 interface CalibrateGripperResult {
-  jawOffset: Coordinates
+  jawOffset: Vector3D
 }
 interface MoveToMaintenancePositionParams {
   mount: GantryMount
   maintenancePosition?: 'attachPlate' | 'attachInstrument'
 }
 interface CalibrateModuleResult {
-  moduleOffset: Coordinates
+  moduleOffset: Vector3D
 }

package/command/types/gantry.ts

@@ -1,12 +1,12 @@
-import type { CommonCommandRunTimeInfo, CommonCommandCreateInfo } from '.'
+import type { CommonCommandCreateInfo, CommonCommandRunTimeInfo } from '.'
 import type { AddressableAreaName } from '../../deck'
-import type { WellLocation } from './support'
 import type {
-  Coordinates,
+  GantryMount,
   MotorAxes,
   MotorAxis,
-  GantryMount,
+  Vector3D,
 } from '../../js/types'
+import type { WellLocation } from './support'
 
 export interface MoveToSlotCreateCommand extends CommonCommandCreateInfo {
   commandType: 'moveToSlot'
@@ -44,7 +44,7 @@ export interface MoveRelativeRunTimeCommand
   extends CommonCommandRunTimeInfo,
     MoveRelativeCreateCommand {
   result?: {
-    position: Coordinates
+    position: Vector3D
   }
 }
 export interface SavePositionCreateCommand extends CommonCommandCreateInfo {
@@ -56,7 +56,7 @@ export interface SavePositionRunTimeCommand
     SavePositionCreateCommand {
   result?: {
     positionId: string
-    position: Coordinates
+    position: Vector3D
   }
 }
 export interface HomeCreateCommand extends CommonCommandCreateInfo {
@@ -129,6 +129,7 @@ export interface MoveToWellParams {
   wellLocation?: WellLocation
   minimumZHeight?: number
   forceDirect?: boolean
+  speed?: number
 }
 
 interface MoveToCoordinatesParams {

package/command/types/incidental.ts

@@ -1,4 +1,4 @@
-import type { CommonCommandRunTimeInfo, CommonCommandCreateInfo } from '.'
+import type { CommonCommandCreateInfo, CommonCommandRunTimeInfo } from '.'
 import type { StatusBarAnimation } from '../../js/types'
 
 export type IncidentalCreateCommand =

package/command/types/index.ts

@@ -1,25 +1,26 @@
 import type { ErrorCodes } from '../../errors'
 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,
+  AnnotationRunTimeCommand,
 } from './annotation'
 import type {
-  CalibrationRunTimeCommand,
   CalibrationCreateCommand,
+  CalibrationRunTimeCommand,
 } from './calibration'
-import type { UnsafeRunTimeCommand, UnsafeCreateCommand } from './unsafe'
+import type { GantryCreateCommand, GantryRunTimeCommand } from './gantry'
+import type {
+  IncidentalCreateCommand,
+  IncidentalRunTimeCommand,
+} from './incidental'
+import type { ModuleCreateCommand, ModuleRunTimeCommand } from './module'
+import type {
+  PipettingCreateCommand,
+  PipettingRunTimeCommand,
+} from './pipetting'
+import type { RobotCreateCommand, RobotRunTimeCommand } from './robot'
+import type { SetupCreateCommand, SetupRunTimeCommand } from './setup'
+import type { TimingCreateCommand, TimingRunTimeCommand } from './timing'
+import type { UnsafeCreateCommand, UnsafeRunTimeCommand } from './unsafe'
 
 export * from './annotation'
 export * from './calibration'
@@ -31,6 +32,7 @@ export * from './setup'
 export * from './timing'
 export * from './unsafe'
 export * from './support'
+export * from './robot'
 // 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
@@ -42,11 +44,13 @@ export interface CommandNote {
 }
 export type CommandStatus = 'queued' | 'running' | 'succeeded' | 'failed'
 export type CommandIntent = 'protocol' | 'setup' | 'fixit'
-export interface CommonCommandRunTimeInfo {
+export interface CommonCommandRunTimeInfo<
+  DefinedErrorsT extends DefinedRunCommandError = DefinedRunCommandError
+> {
   key?: string
   id: string
   status: CommandStatus
-  error?: RunCommandError | null
+  error?: RunCommandErrorUndefined | DefinedErrorsT | null
   createdAt: string
   startedAt: string | null
   completedAt: string | null
@@ -70,6 +74,7 @@ export type CreateCommand =
   | AnnotationCreateCommand // annotating command execution
   | IncidentalCreateCommand // command with only incidental effects (status bar animations)
   | UnsafeCreateCommand // command providing capabilities that are not safe for scientific uses
+  | RobotCreateCommand // command providing underlying robot capabilities outside the normal model
 
 // commands will be required to have a key, but will not be created with one
 export type RunTimeCommand =
@@ -82,10 +87,19 @@ export type RunTimeCommand =
   | AnnotationRunTimeCommand // annotating command execution
   | IncidentalRunTimeCommand // command with only incidental effects (status bar animations)
   | UnsafeRunTimeCommand // command providing capabilities that are not safe for scientific uses
+  | RobotRunTimeCommand // command providing underlying robot capabilities outside the normal model
+
+export type RunCommandError = RunCommandErrorUndefined | DefinedRunCommandError
+
+export type DefinedRunCommandError =
+  | RunCommandRobotActionError
+  | RunCommandFlexStackerError
 
-export type RunCommandError =
-  | RunCommandErrorUndefined
+export type RunCommandRobotActionError =
   | RunCommandErrorOverpressure
+  | RunCommandErrorTipPhysicallyAttached
+
+export type Failed<CommandT extends RunTimeCommand> = Omit<CommandT, 'result'>
 
 // TODO(jh, 05-24-24): Update when some of these newer properties become more finalized.
 export interface RunCommandErrorBase {
@@ -98,7 +112,7 @@ export interface RunCommandErrorBase {
 export interface RunCommandErrorUndefined extends RunCommandErrorBase {
   errorCode: ErrorCodes
   errorType: string
-  isDefined: false
+  isDefined: boolean
   errorInfo?: Record<string, unknown>
 }
 
@@ -108,3 +122,37 @@ export interface RunCommandErrorOverpressure extends RunCommandErrorBase {
   isDefined: true
   errorInfo: { retryLocation: [number, number, number] }
 }
+
+export interface RunCommandErrorTipPhysicallyAttached
+  extends RunCommandErrorBase {
+  errorCode: '3004'
+  errorType: 'tipPhysicallyAttached'
+  isDefined: true
+  errorInfo: { retryLocation: [number, number, number] }
+}
+
+export interface RunCommandErrorFlexStackerStall extends RunCommandErrorBase {
+  errorCode: '2019'
+  errorType: 'flexStackerStallOrCollision'
+  isDefined: true
+  errorInfo: { labwareId?: string }
+}
+
+export interface RunCommandErrorFlexStackerShuttle extends RunCommandErrorBase {
+  errorCode: '3020'
+  errorType: 'flexStackerShuttleMissing'
+  isDefined: true
+  errorInfo: { labwareId?: string }
+}
+
+export interface RunCommandErrorFlexStackerHopper extends RunCommandErrorBase {
+  errorCode: '3022'
+  errorType: 'flexStackerHopperLabwareFailed'
+  isDefined: true
+  errorInfo: { labwareId?: string }
+}
+
+export type RunCommandFlexStackerError =
+  | RunCommandErrorFlexStackerStall
+  | RunCommandErrorFlexStackerShuttle
+  | RunCommandErrorFlexStackerHopper

package/command/types/module.ts

@@ -1,6 +1,10 @@
-import type { CommonCommandRunTimeInfo, CommonCommandCreateInfo } from '.'
-import type { LabwareLocationSequence } from './setup'
+import type {
+  CommonCommandCreateInfo,
+  CommonCommandRunTimeInfo,
+  RunCommandFlexStackerError,
+} from '.'
 import type { LabwareDefinition2 } from '../../js'
+import type { LabwareLocationSequence } from './setup'
 
 export type ModuleRunTimeCommand =
   | MagneticModuleEngageMagnetRunTimeCommand
@@ -69,6 +73,9 @@ export type ModuleCreateCommand =
   | FlexStackerStoreCreateCommand
   | FlexStackerFillCreateCommand
   | FlexStackerEmptyCreateCommand
+  | FlexStackerPrepareShuttleCreateCommand
+  | FlexStackerOpenLatch
+  | FlexStackerCloseLatch
 
 export interface MagneticModuleEngageMagnetCreateCommand
   extends CommonCommandCreateInfo {
@@ -399,12 +406,34 @@ export interface FlexStackerStoredLabwareDetails {
   version: number
 }
 
+export interface FlexStackerStoredLabwareGroup {
+  primaryLabwareId: string
+  adapterLabwareId: string | null
+  lidLabwareId: string | null
+}
+
+interface StackerStoredLabwareLocationSequences {
+  originalPrimaryLabwareLocationSequences?: LabwareLocationSequence[] | null
+  originalAdapterLabwareLocationSequences?: LabwareLocationSequence[] | null
+  originalLidLabwareLocationSequences?: LabwareLocationSequence[] | null
+  newPrimaryLabwareLocationSequences?: LabwareLocationSequence[] | null
+  newAdapterLabwareLocationSequences?: LabwareLocationSequence[] | null
+  newLidLabwareLocationSequences?: LabwareLocationSequence[] | null
+}
+
+interface StackerStoredLabwareDefinitionURIs {
+  primaryLabwareURI: string
+  adapterLabwareURI?: string | null
+  lidLabwareURI?: string | null
+}
+
 export interface FlexStackerSetStoredLabwareCreateCommand
   extends CommonCommandCreateInfo {
   commandType: 'flexStacker/setStoredLabware'
   params: {
     moduleId: string
-    initialCount: number
+    initialCount?: number | null
+    initialStoredLabware?: FlexStackerStoredLabwareGroup[] | null
     primaryLabware: FlexStackerStoredLabwareDetails
     lidLabware: FlexStackerStoredLabwareDetails | null
     adapterLabware: FlexStackerStoredLabwareDetails | null
@@ -419,7 +448,8 @@ export interface FlexStackerSetStoredLabwareRunTimeCommand
     lidLabwareDefinition?: LabwareDefinition2 | null
     adapterLabwareDefinition?: LabwareDefinition2 | null
     count: number
-  }
+    storedLabware: FlexStackerStoredLabwareGroup[]
+  } & StackerStoredLabwareLocationSequences
 }
 
 export interface FlexStackerRetrieveCreateCommand
@@ -442,6 +472,7 @@ export interface FlexStackerFillCreateCommand extends CommonCommandCreateInfo {
     strategy: 'manualWithPause' | 'logical'
     message?: string
     count?: number
+    labwareToStore?: FlexStackerStoredLabwareGroup[]
   }
 }
 
@@ -454,39 +485,69 @@ export interface FlexStackerEmptyCreateCommand extends CommonCommandCreateInfo {
     count?: number
   }
 }
+
+export interface FlexStackerPrepareShuttleCreateCommand
+  extends CommonCommandCreateInfo {
+  commandType: 'flexStacker/prepareShuttle'
+  params: {
+    moduleId: string
+    ignoreLatch?: boolean
+  }
+}
+
+// TODO(tz, 4-17-2025): move under unsafe domain when BE has moved as well
+export interface FlexStackerOpenLatch extends CommonCommandCreateInfo {
+  commandType: 'flexStacker/openLatch'
+  params: {
+    moduleId: string
+  }
+}
+
+export interface FlexStackerCloseLatch extends CommonCommandCreateInfo {
+  commandType: 'flexStacker/closeLatch'
+  params: {
+    moduleId: string
+  }
+}
+
 interface RetrieveResultPrimary {
   labwareId: string
   primaryLocationSequence: LabwareLocationSequence
+  originalPrimaryLocationSequence: LabwareLocationSequence
   primaryLabwareURI: string
 }
 
 interface RetrieveResultNoLid {
   lidId?: null
   lidLocationSequence?: null
+  originalLidLocationSequence?: null
   lidLabwareURI?: null
 }
 
 interface RetrieveResultLid {
   lidId: string
   lidLocationSequence: LabwareLocationSequence
+  originalLidLocationSequence: LabwareLocationSequence
   lidLabwareURI: string
 }
 
 interface RetrieveResultAdapter {
   adapterId: string
   adapterLocationSequence: LabwareLocationSequence
+  originalAdapterLocationSequence: LabwareLocationSequence
   adapterLabwareURI: string
 }
 
 interface RetrieveResultNoAdapter {
   adapterId?: null
   adapterLocationSequence?: null
+  originalAdapterLocationSequence?: null
   adapterLabwareURI?: null
 }
 
 export interface FlexStackerRetrieveRunTimeCommand
   extends FlexStackerRetrieveCreateCommand,
-    CommonCommandRunTimeInfo {
+    CommonCommandRunTimeInfo<RunCommandFlexStackerError> {
   result?:
     | (RetrieveResultPrimary & RetrieveResultNoLid & RetrieveResultNoAdapter)
     | (RetrieveResultPrimary & RetrieveResultLid & RetrieveResultNoAdapter)
@@ -496,7 +557,7 @@ export interface FlexStackerRetrieveRunTimeCommand
 
 export interface FlexStackerStoreRunTimeCommand
   extends FlexStackerStoreCreateCommand,
-    CommonCommandRunTimeInfo {
+    CommonCommandRunTimeInfo<RunCommandFlexStackerError> {
   result?: {
     eventualDestinationLocationSequence?: LabwareLocationSequence
     primaryOriginLocationSequence?: LabwareLocationSequence
@@ -505,7 +566,7 @@ export interface FlexStackerStoreRunTimeCommand
     adapterLabwareId?: string
     lidOriginLocationSequence?: LabwareLocationSequence
     lidLabwareId?: LabwareLocationSequence
-  }
+  } & StackerStoredLabwareDefinitionURIs
 }
 
 export interface FlexStackerFillRunTimeCommand
@@ -513,7 +574,10 @@ export interface FlexStackerFillRunTimeCommand
     CommonCommandRunTimeInfo {
   result?: {
     count: number
-  }
+    storedLabware?: FlexStackerStoredLabwareGroup[] | null
+    addedLabware?: FlexStackerStoredLabwareGroup[] | null
+  } & StackerStoredLabwareLocationSequences &
+    StackerStoredLabwareDefinitionURIs
 }
 
 export interface FlexStackerEmptyRunTimeCommand
@@ -521,5 +585,8 @@ export interface FlexStackerEmptyRunTimeCommand
     CommonCommandRunTimeInfo {
   result?: {
     count: number
-  }
+    storedLabware?: FlexStackerStoredLabwareGroup[] | null
+    removedLabware?: FlexStackerStoredLabwareGroup[] | null
+  } & StackerStoredLabwareLocationSequences &
+    StackerStoredLabwareDefinitionURIs
 }

package/command/types/pipetting.ts

@@ -1,6 +1,7 @@
+import type { CommonCommandCreateInfo, CommonCommandRunTimeInfo } from '.'
 import type { AddressableAreaName } from '../../deck'
-import type { CommonCommandRunTimeInfo, CommonCommandCreateInfo } from '.'
 import type { DropTipWellLocation, WellLocation } from './support'
+
 export type PipettingRunTimeCommand =
   | AspirateInPlaceRunTimeCommand
   | AspirateInPlaceRunTimeCommand
@@ -68,7 +69,9 @@ export interface ConfigureForVolumeRunTimeCommand
 
 export type AirGapInPlaceParams = FlowRateParams &
   PipetteIdentityParams &
-  VolumeParams
+  VolumeParams & {
+    correctionVolume?: number
+  }
 
 export interface AirGapInPlaceCreateCommand extends CommonCommandCreateInfo {
   commandType: 'airGapInPlace'
@@ -235,9 +238,10 @@ export interface VerifyTipPresenceRunTimeCommand
   result?: any
 }
 
+export type LiquidProbeParams = WellLocationParam & PipetteAccessParams
 export interface LiquidProbeCreateCommand extends CommonCommandCreateInfo {
   commandType: 'liquidProbe'
-  params: WellLocationParam & PipetteAccessParams
+  params: LiquidProbeParams
 }
 export interface LiquidProbeRunTimeCommand
   extends CommonCommandRunTimeInfo,
@@ -342,12 +346,14 @@ export interface DispenseInPlaceParams {
   volume: number
   flowRate: number // µL/s
   pushOut?: number
+  correctionVolume?: number
 }
 
 export interface AspirateInPlaceParams {
   pipetteId: string
   volume: number
   flowRate: number // µL/s
+  correctionVolume?: number
 }
 interface FlowRateParams {
   flowRate: number // µL/s

package/command/types/robot.ts

@@ -0,0 +1,98 @@
+import type { CommonCommandCreateInfo, CommonCommandRunTimeInfo } from '.'
+import type { GantryMount, MotorAxis } from '../../js/types'
+
+export type RobotRunTimeCommand =
+  | RobotMoveToRunTimeCommand
+  | RobotMoveAxesToRunTimeCommand
+  | RobotMoveAxesRelativeRunTimeCommand
+  | RobotOpenGripperJawRunTimeCommand
+  | RobotCloseGripperJawRunTimeCommand
+export type RobotCreateCommand =
+  | RobotMoveToCreateCommand
+  | RobotMoveAxesToCreateCommand
+  | RobotMoveAxesRelativeCreateCommand
+  | RobotOpenGripperJawCreateCommand
+  | RobotCloseGripperJawCreateCommand
+
+export type RobotMotorAxisMap = Record<MotorAxis, number>
+export type GantryAxisMap =
+  | { x: number; y: number; leftZ: number }
+  | { x: number; y: number; rightZ: number }
+
+export interface RobotMoveToParams {
+  mount: GantryMount
+  destination: { x: number; y: number; z: number }
+  speed?: number
+}
+
+export interface RobotMoveToCreateCommand extends CommonCommandCreateInfo {
+  commandType: 'robot/moveTo'
+  params: RobotMoveToParams
+}
+export interface RobotMoveToRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    RobotMoveToCreateCommand {
+  result?: any
+}
+
+export interface RobotMoveAxesToParams {
+  axis_map: RobotMotorAxisMap
+  critical_point?: GantryAxisMap
+  speed?: number
+}
+
+export interface RobotMoveAxesToCreateCommand extends CommonCommandCreateInfo {
+  commandType: 'robot/moveAxesTo'
+  params: RobotMoveAxesToParams
+}
+
+export interface RobotMoveAxesToRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    RobotMoveAxesToCreateCommand {
+  result?: {
+    position: RobotMotorAxisMap
+  }
+}
+
+export interface RobotMoveAxesRelativeParams {
+  axis_map: RobotMotorAxisMap
+  speed?: number
+}
+
+export interface RobotMoveAxesRelativeCreateCommand
+  extends CommonCommandCreateInfo {
+  commandType: 'robot/moveAxesRelative'
+  params: RobotMoveAxesRelativeParams
+}
+
+export interface RobotMoveAxesRelativeRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    RobotMoveAxesRelativeCreateCommand {
+  result?: {
+    position: RobotMotorAxisMap
+  }
+}
+
+export interface RobotOpenGripperJawCreateCommand
+  extends CommonCommandCreateInfo {
+  commandType: 'robot/openGripperJaw'
+  params: {}
+}
+
+export interface RobotOpenGripperJawRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    RobotOpenGripperJawCreateCommand {
+  result?: any
+}
+
+export interface RobotCloseGripperJawCreateCommand
+  extends CommonCommandCreateInfo {
+  commandType: 'robot/closeGripperJaw'
+  params: {}
+}
+
+export interface RobotCloseGripperJawRunTimeCommand
+  extends CommonCommandRunTimeInfo,
+    RobotCloseGripperJawCreateCommand {
+  result?: any
+}

package/command/types/setup.ts

@@ -1,13 +1,13 @@
 import type {
   AddressableAreaName,
-  CommonCommandRunTimeInfo,
+  AspirateProperties,
   CommonCommandCreateInfo,
+  CommonCommandRunTimeInfo,
   LabwareDefinition2,
   LabwareOffset,
-  PipetteName,
   ModuleModel,
-  AspirateProperties,
   MultiDispenseProperties,
+  PipetteName,
   SingleDispenseProperties,
 } from '../../js'
 

package/command/types/support.ts

@@ -1,5 +1,16 @@
-type BaseWellOrigin = 'top' | 'bottom' | 'center'
-export type WellOrigin = BaseWellOrigin | 'meniscus'
+import type {
+  WELL_ORIGIN_BOTTOM,
+  WELL_ORIGIN_CENTER,
+  WELL_ORIGIN_MENISCUS,
+  WELL_ORIGIN_TOP,
+} from '../../js/constants'
+
+type BaseWellOrigin =
+  | typeof WELL_ORIGIN_TOP
+  | typeof WELL_ORIGIN_BOTTOM
+  | typeof WELL_ORIGIN_CENTER
+
+export type WellOrigin = BaseWellOrigin | typeof WELL_ORIGIN_MENISCUS
 export interface WellOffset {
   x?: number
   y?: number

package/command/types/timing.ts

@@ -1,4 +1,4 @@
-import type { CommonCommandRunTimeInfo, CommonCommandCreateInfo } from '.'
+import type { CommonCommandCreateInfo, CommonCommandRunTimeInfo } from '.'
 
 export type TimingCreateCommand =
   | WaitForResumeCreateCommand