chore(step-generation): state update for FlexStacker in getNextRobotStateAndWarningsSingleCommand

api/src/opentrons/protocol_engine/commands/flex_stacker/fill.py

@@ -1,4 +1,4 @@
-"""Command models to engage a user to empty a Flex Stacker."""
+"""Command models to engage a user to fill a Flex Stacker."""
 
 from __future__ import annotations
 from typing import Optional, Literal, TYPE_CHECKING, Annotated

api/src/opentrons/protocol_engine/commands/flex_stacker/store.py

@@ -1,4 +1,4 @@
-"""Command models to retrieve a labware from a Flex Stacker."""
+"""Command models to store a labware in a Flex Stacker."""
 
 from __future__ import annotations
 from typing import Optional, Literal, TYPE_CHECKING, Type, Union, cast

protocol-designer/src/step-forms/selectors/index.ts

@@ -230,6 +230,14 @@ const ABSORBANCE_READER_INITIAL_STATE: AbsorbanceReaderState = {
 }
 const FLEX_STACKER_INITIAL_STATE: FlexStackerModuleState = {
   type: FLEX_STACKER_MODULE_TYPE,
+  latchOpen: null,
+  maxPoolCount: 0,
+  storedLabwareDetails: null,
+  shuttlePosition: 'home',
+  labwareInStacker: null,
+  labwareInShuttle: null,
+  labwareRetrieved: null,
+  labwareStored: null,
 }
 
 const MODULE_INITIAL_STATES_MAP: Record<

protocol-designer/src/step-forms/types.ts

@@ -4,6 +4,7 @@ import type {
   CutoutId,
   FLEX_STACKER_MODULE_TYPE,
   FlexModuleCutoutFixtureId,
+  FlexStackerSetStoredLabwareParams,
   HEATERSHAKER_MODULE_TYPE,
   MAGNETIC_BLOCK_TYPE,
   MAGNETIC_MODULE_TYPE,
@@ -71,7 +72,14 @@ export interface MagneticBlockState {
 
 export interface FlexStackerModuleState {
   type: typeof FLEX_STACKER_MODULE_TYPE
-  // TODO: extend this state
+  latchOpen: boolean | null
+  maxPoolCount: number
+  storedLabwareDetails: FlexStackerSetStoredLabwareParams | null
+  shuttlePosition: 'home' | 'retrieved' | 'stored'
+  labwareInStacker: string[] | null
+  labwareInShuttle: number | null
+  labwareRetrieved: number | null
+  labwareStored: number | null
 }
 export type InitializationMode = 'single' | 'multi'
 export interface Initialization {

shared-data/command/types/module.ts

@@ -461,17 +461,19 @@ interface StackerStoredLabwareDefinitionURIs {
   lidLabwareURI?: string | null
 }
 
+export interface FlexStackerSetStoredLabwareParams {
+  moduleId: string
+  initialCount?: number | null
+  initialStoredLabware?: FlexStackerStoredLabwareGroup[] | null
+  primaryLabware: FlexStackerStoredLabwareDetails
+  lidLabware: FlexStackerStoredLabwareDetails | null
+  adapterLabware: FlexStackerStoredLabwareDetails | null
+}
+
 export interface FlexStackerSetStoredLabwareCreateCommand
   extends CommonCommandCreateInfo {
   commandType: 'flexStacker/setStoredLabware'
-  params: {
-    moduleId: string
-    initialCount?: number | null
-    initialStoredLabware?: FlexStackerStoredLabwareGroup[] | null
-    primaryLabware: FlexStackerStoredLabwareDetails
-    lidLabware: FlexStackerStoredLabwareDetails | null
-    adapterLabware: FlexStackerStoredLabwareDetails | null
-  }
+  params: FlexStackerSetStoredLabwareParams
 }
 
 export interface FlexStackerSetStoredLabwareRunTimeCommand
@@ -502,25 +504,29 @@ export interface FlexStackerStoreCreateCommand extends CommonCommandCreateInfo {
   }
 }
 
+export interface FlexStackerFillParams {
+  moduleId: string
+  strategy: 'manualWithPause' | 'logical'
+  message?: string
+  count?: number
+  labwareToStore?: FlexStackerStoredLabwareGroup[]
+}
+
 export interface FlexStackerFillCreateCommand extends CommonCommandCreateInfo {
   commandType: 'flexStacker/fill'
-  params: {
-    moduleId: string
-    strategy: 'manualWithPause' | 'logical'
-    message?: string
-    count?: number
-    labwareToStore?: FlexStackerStoredLabwareGroup[]
-  }
+  params: FlexStackerFillParams
+}
+
+export interface FlexStackerEmptyParams {
+  moduleId: string
+  strategy: 'manualWithPause' | 'logical'
+  message?: string
+  count?: number
 }
 
 export interface FlexStackerEmptyCreateCommand extends CommonCommandCreateInfo {
   commandType: 'flexStacker/empty'
-  params: {
-    moduleId: string
-    strategy: 'manualWithPause' | 'logical'
-    message?: string
-    count?: number
-  }
+  params: FlexStackerEmptyParams
 }
 
 export interface FlexStackerPrepareShuttleCreateCommand

shared-data/js/fixtures.ts

@@ -868,6 +868,7 @@ export function getFixtureDisplayName(
   }
 }
 
+// TODO: Move to helpers/deckDeclarationHelpers.ts
 export const STANDARD_OT2_SLOTS: AddressableAreaName[] = [
   ADDRESSABLE_AREA_1,
   ADDRESSABLE_AREA_2,
@@ -882,6 +883,7 @@ export const STANDARD_OT2_SLOTS: AddressableAreaName[] = [
   ADDRESSABLE_AREA_11,
 ]
 
+// TODO: Move to helpers
 export const STANDARD_FLEX_SLOTS: AddressableAreaName[] = [
   A1_ADDRESSABLE_AREA,
   A2_ADDRESSABLE_AREA,

shared-data/js/helpers/__tests__/getFlexStackerHardwareProps.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  fixtureTiprack1000ul,
+  FLEX_STACKER_MODULE_V1,
+  getSchema2Dimensions,
+  MAGNETIC_MODULE_V1,
+} from '../..'
+import {
+  getHeightOfLabwareStackFromDefinitions,
+  getLabwareOverlapOffset,
+  getModuleMaxFillHeight,
+  getStackerMaxPoolCountByHeight,
+} from '../getFlexStackerHardwareProps'
+
+import type { LabwareDefinition2 } from '../..'
+
+describe('getModuleMaxFillHeight()', () => {
+  it('should return the max fill height for a given module model', () => {
+    expect(getModuleMaxFillHeight(FLEX_STACKER_MODULE_V1)).toBe(612.75)
+  })
+})
+
+describe('getStackerMaxPoolCountByHeight()', () => {
+  it('should return the max pool count by height for a given module model', () => {
+    expect(getStackerMaxPoolCountByHeight(FLEX_STACKER_MODULE_V1, 100, 0)).toBe(
+      6
+    )
+  })
+
+  it('should throw an error if the module model is invalid', () => {
+    expect(() =>
+      getStackerMaxPoolCountByHeight(MAGNETIC_MODULE_V1, 100, 0)
+    ).toThrow(
+      'Invalid module model for max pool count by height: magneticModuleV1'
+    )
+  })
+})
+
+describe('getLabwareOverlapOffset()', () => {
+  const mockLabwareDefinition = fixtureTiprack1000ul as LabwareDefinition2
+
+  it('should return the labware overlap offset for a given module model', () => {
+    const result = getLabwareOverlapOffset(
+      FLEX_STACKER_MODULE_V1,
+      mockLabwareDefinition,
+      'labware-name'
+    )
+    expect(result).toStrictEqual({ x: 0, y: 0, z: 0 })
+  })
+
+  it('should throw an error if the module model is invalid', () => {
+    expect(() =>
+      getLabwareOverlapOffset(
+        MAGNETIC_MODULE_V1,
+        mockLabwareDefinition,
+        'labware-name'
+      )
+    ).toThrow(
+      'Invalid module model for labware overlap offset: magneticModuleV1'
+    )
+  })
+})
+
+describe('getHeightOfLabwareStackFromDefinitions()', () => {
+  it('should return the height of a stack of labware from definitions', () => {
+    const mockLabwareDefinition = fixtureTiprack1000ul as LabwareDefinition2
+    const result = getHeightOfLabwareStackFromDefinitions([
+      mockLabwareDefinition,
+    ])
+    expect(result).toBe(getSchema2Dimensions(mockLabwareDefinition).zDimension)
+  })
+
+  it('should return 0 if the definitions are empty', () => {
+    const result = getHeightOfLabwareStackFromDefinitions([])
+    expect(result).toBe(0)
+  })
+
+  it('should return the height of a stack of labware from definitions', () => {
+    const mockLabwareDefinition = fixtureTiprack1000ul as LabwareDefinition2
+    const result = getHeightOfLabwareStackFromDefinitions([
+      mockLabwareDefinition,
+      mockLabwareDefinition,
+    ])
+    expect(result).toBe(
+      getSchema2Dimensions(mockLabwareDefinition).zDimension * 2
+    )
+  })
+})

shared-data/js/helpers/__tests__/symbolicPositionHelpers.test.ts

@@ -0,0 +1,23 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import { STANDARD_FLEX_SLOTS, STANDARD_OT2_SLOTS } from '../../fixtures'
+import { getIsValidSlotName } from '../symbolicPositionHelpers'
+
+describe('getIsSlotValid', () => {
+  beforeEach(() => {})
+
+  it('returns true for a valid slot', () => {
+    STANDARD_FLEX_SLOTS.forEach(slot => {
+      expect(getIsValidSlotName(slot)).toBe(true)
+    })
+    STANDARD_OT2_SLOTS.forEach(slot => {
+      expect(getIsValidSlotName(slot)).toBe(true)
+    })
+  })
+  it('returns false for an invalid slot', () => {
+    expect(getIsValidSlotName('13')).toBe(false)
+  })
+  it('returns false for an invalid slot', () => {
+    expect(getIsValidSlotName('A5')).toBe(false)
+  })
+})

shared-data/js/helpers/getFlexStackerHardwareProps.ts

@@ -0,0 +1,77 @@
+import { FLEX_STACKER_MODULE_V1 } from '../constants'
+import { getModuleDef } from '../modules'
+import { getSchema2Dimensions } from './positionMath'
+
+import type { LabwareDefinition, ModuleModel, Vector3D } from '../types'
+
+export const getModuleMaxFillHeight = (model: ModuleModel): number => {
+  if (model === FLEX_STACKER_MODULE_V1) {
+    return (
+      getModuleDef(FLEX_STACKER_MODULE_V1).dimensions.maxStackerFillHeight ?? 0
+    )
+  }
+  throw new Error(`Invalid module model for max fill height: ${model}`)
+}
+
+export const getStackerMaxPoolCountByHeight = (
+  model: ModuleModel,
+  poolHeight: number,
+  poolOverlap: number
+): number => {
+  if (model === FLEX_STACKER_MODULE_V1) {
+    const maxFillHeight = getModuleMaxFillHeight(model)
+    if (maxFillHeight <= 0) {
+      throw new Error(
+        `Invalid max fill height for ${model}: ${maxFillHeight} must be greater than 0`
+      )
+    }
+    return Math.floor(
+      (maxFillHeight - poolOverlap) / (poolHeight - poolOverlap)
+    )
+  }
+  throw new Error(`Invalid module model for max pool count by height: ${model}`)
+}
+
+export const getLabwareOverlapOffset = (
+  model: ModuleModel,
+  definition: LabwareDefinition,
+  belowLabwareName: string
+): Vector3D => {
+  if (model !== FLEX_STACKER_MODULE_V1) {
+    throw new Error(`Invalid module model for labware overlap offset: ${model}`)
+  }
+  if (
+    belowLabwareName in Object.keys(definition.stackingOffsetWithLabware ?? {})
+  ) {
+    return (
+      definition.stackingOffsetWithLabware?.[belowLabwareName] ?? {
+        x: 0,
+        y: 0,
+        z: 0,
+      }
+    )
+  }
+  return definition.stackingOffsetWithLabware?.default ?? { x: 0, y: 0, z: 0 }
+}
+
+export const getHeightOfLabwareStackFromDefinitions = (
+  definitions: LabwareDefinition[]
+): number => {
+  if (definitions.length === 0) {
+    return 0
+  }
+  let total_height = 0.0
+  let upper_def: LabwareDefinition = definitions[0]
+  for (const lower_def of definitions.slice(1)) {
+    const overlap = getLabwareOverlapOffset(
+      FLEX_STACKER_MODULE_V1,
+      upper_def,
+      lower_def.parameters.loadName
+    ).z
+    total_height += getSchema2Dimensions(upper_def).zDimension - overlap
+    upper_def = lower_def
+  }
+  return total_height + getSchema2Dimensions(upper_def).zDimension
+}
+// export const getModuleMaxRetrievableHeight = (model: ModuleModel): number =>
+//   getModuleDef(model).dimensions.maxStackerRetrievableHeight ?? 0

shared-data/js/helpers/index.ts

@@ -36,6 +36,7 @@ export * from './matrixMath'
 export * from './getLoadedLabwareDefinitionsByUri'
 export * from './getFixedTrashLabwareDefinition'
 export * from './getOccludedSlotCountForModule'
+export * from './getFlexStackerHardwareProps'
 export * from './labwareInference'
 export * from './linearInterpolate'
 export * from './liquidClasses'

shared-data/js/helpers/symbolicPositionHelpers.ts

@@ -1,8 +1,10 @@
+import { STANDARD_FLEX_SLOTS, STANDARD_OT2_SLOTS } from '../fixtures'
+
 import type {
   LabwareLocation,
   OnDeckLabwareLocation,
 } from '../../command/types/setup'
-import type { AddressableAreaName } from '../../js'
+import type { AddressableAreaName } from '../../deck'
 
 export const changeAnyUseOfMeToPreserveStructure_thisIsAnOffDeckLocationInASlotName =
   (quoteUnquoteSlotName: string): boolean =>
@@ -41,3 +43,14 @@ export const locationIsOnAddressableArea = (
   labwareLocation: LabwareLocation
 ): labwareLocation is { addressableAreaName: AddressableAreaName } =>
   locationIsOnDeck(labwareLocation) && 'addressableAreaName' in labwareLocation
+
+export const getIsValidSlotName = (slot: string): boolean => {
+  return (
+    STANDARD_OT2_SLOTS.includes(slot as AddressableAreaName) ||
+    STANDARD_FLEX_SLOTS.includes(slot as AddressableAreaName) ||
+    slot === 'A4' ||
+    slot === 'B4' ||
+    slot === 'C4' ||
+    slot === 'D4'
+  )
+}

shared-data/js/types.ts

@@ -566,6 +566,8 @@ export interface ModuleDimensions {
   labwareInterfaceXDimension?: number
   labwareInterfaceYDimension?: number
   lidHeight?: number
+  maxStackerFillHeight?: number
+  maxStackerRetrievableHeight?: number
 }
 
 export interface ModuleCalibrationPoint {