feat(app): Implement Stacker Location Identify (#18721)

Covers EXEC-1417
Adds the "Identify" button to the "Add Module" step of the deck configuration flow that blinks a stacker LED when identified.

Author: CaseyBatten

app/src/assets/localization/en/device_details.json

@@ -6,7 +6,7 @@
   "abs_reader_lid_status": "Lid status: {{status}}",
   "abs_reader_status": "Absorbance Plate Reader Status",
   "add": "Add",
-  "add_fixture_description": "Add this hardware to your deck configuration. It will be referenced during protocol analysis.",
+  "add_fixture_description": "Choose an item below to add to your deck configuration. It will be referenced during protocol analysis.",
   "add_to_slot": "Add to slot {{slotName}}",
   "add_to": "Add to {{slotName}}",
   "an_error_occurred_while_updating": "An error occurred while updating your pipette's settings.",
@@ -74,6 +74,7 @@
   "heater": "Heater",
   "height_ranges": "{{gen}} Height Ranges",
   "hot_to_the_touch": "<block>Module is <bold>hot</bold> to the touch</block>",
+  "identify": "Identify",
   "input_out_of_range": "Input out of range",
   "instrument_attached": "Instrument attached",
   "instruments_and_modules": "Instruments and Modules",

app/src/organisms/DeviceDetailsDeckConfiguration/AddFixtureModal.tsx

@@ -30,8 +30,10 @@ import {
 import { OddModal } from '/app/molecules/OddModal'
 import { useNotifyDeckConfigurationQuery } from '/app/resources/deck_configuration/'
 
+import { useSendIdentifyStacker } from '../ModuleWizardFlows/hooks'
 import { getOptions } from './utils'
 
+import type { AttachedModule } from '@opentrons/api-client'
 import type { ModalProps } from '@opentrons/components'
 import type {
   AddressableAreaNamesWithFakes,
@@ -42,6 +44,9 @@ import type {
 } from '@opentrons/shared-data'
 import type { OddModalHeaderBaseProps } from '/app/molecules/OddModal/types'
 
+const FLEX_STACKER_FIXTURE = 'flexStackerModuleV1'
+const MODULE_IDENTIFY_TIME_MS = 10000
+
 interface AddFixtureModalProps {
   cutoutId: CutoutId
   addressableAreaId: AddressableAreaNamesWithFakes
@@ -161,7 +166,14 @@ export function AddFixtureModal({
     )
   }
 
-  const handleAddFixture = (addedCutoutConfigs: CutoutConfigMap[]): void => {
+  const sendIdentifyStacker = useSendIdentifyStacker()
+  const [identifyInUse, setIdentifyInUse] = useState<string | null>(null)
+  const [identifyTimeout, setTimeoutID] = useState<NodeJS.Timeout | null>(null)
+
+  const handleAddFixture = (
+    addedCutoutConfigs: CutoutConfigMap[],
+    fixtureSerialNumber?: string
+  ): void => {
     const addedCutoutConfigsWithCombo = replaceCutoutFixtureWithComboFixture(
       addedCutoutConfigs,
       deckConfigWithAA,
@@ -175,10 +187,54 @@ export function AddFixtureModal({
       )
     }) as CutoutConfig[] // we can do this bc we are mapping each aa to the proper fixture
 
+    if (fixtureSerialNumber) {
+      const module =
+        unconfiguredMods?.find(m => m.serialNumber === fixtureSerialNumber) ??
+        null
+      if (module !== null) {
+        sendIdentifyStacker(module, false)
+        if (identifyTimeout !== null) {
+          clearTimeout(identifyTimeout)
+        }
+      }
+    }
     updateDeckConfiguration(newDeckConfig)
     closeModal()
   }
 
+  const stackerIdentifyHandler = (module: AttachedModule): void => {
+    // Identify the stacker module
+    sendIdentifyStacker(module, true, 'blue')
+    // Ensure that the module reverts after a set time
+    setIdentifyInUse(module.serialNumber)
+    const timeoutID = setTimeout(() => {
+      sendIdentifyStacker(module, false)
+      setIdentifyInUse(null)
+    }, MODULE_IDENTIFY_TIME_MS)
+    setTimeoutID(timeoutID)
+  }
+
+  const handleIdentifyFixture = (fixtureSerialNumber: string): void => {
+    const module =
+      unconfiguredMods.find(m => m.serialNumber === fixtureSerialNumber) ?? null
+    if (identifyInUse === null && module !== null) {
+      stackerIdentifyHandler(module)
+    } else if (
+      identifyInUse !== fixtureSerialNumber &&
+      identifyInUse !== null
+    ) {
+      const previousModule =
+        unconfiguredMods.find(m => m.serialNumber === identifyInUse) ?? null
+      if (previousModule !== null && module !== null) {
+        sendIdentifyStacker(previousModule, false)
+        if (identifyTimeout !== null) {
+          clearTimeout(identifyTimeout)
+        }
+        stackerIdentifyHandler(module)
+      }
+    }
+  }
+
   const fixtureOptions = availableOptions.map(cutoutConfigs => {
     const usbPort = (modulesData?.data ?? []).find(
       m => m.serialNumber === cutoutConfigs[0].opentronsModuleSerialNumber
@@ -188,20 +244,45 @@ export function AddFixtureModal({
         ? `${usbPort.port}.${usbPort.hubPort}`
         : usbPort?.port
 
-    return (
-      <FixtureOption
-        key={cutoutConfigs[0].cutoutFixtureId}
-        optionName={getFixtureDisplayName(
-          cutoutConfigs[0].cutoutFixtureId,
-          portDisplay
-        )}
-        buttonText={t('add')}
-        onClickHandler={() => {
-          handleAddFixture(cutoutConfigs)
-        }}
-        isOnDevice={isOnDevice}
-      />
-    )
+    const fixtureSerialNumber = cutoutConfigs[0].opentronsModuleSerialNumber
+    if (
+      fixtureSerialNumber !== undefined &&
+      cutoutConfigs[0].cutoutFixtureId.includes(FLEX_STACKER_FIXTURE)
+    ) {
+      return (
+        <FixtureOption
+          key={cutoutConfigs[0].cutoutFixtureId}
+          optionName={getFixtureDisplayName(
+            cutoutConfigs[0].cutoutFixtureId,
+            portDisplay
+          )}
+          buttonText={t('add')}
+          onClickHandler={() => {
+            handleAddFixture(cutoutConfigs, fixtureSerialNumber)
+          }}
+          secondaryButtonText={t('identify')}
+          secondaryOnClickHandler={() => {
+            handleIdentifyFixture(fixtureSerialNumber)
+          }}
+          isOnDevice={isOnDevice}
+        />
+      )
+    } else {
+      return (
+        <FixtureOption
+          key={cutoutConfigs[0].cutoutFixtureId}
+          optionName={getFixtureDisplayName(
+            cutoutConfigs[0].cutoutFixtureId,
+            portDisplay
+          )}
+          buttonText={t('add')}
+          onClickHandler={() => {
+            handleAddFixture(cutoutConfigs)
+          }}
+          isOnDevice={isOnDevice}
+        />
+      )
+    }
   })
 
   return (

app/src/organisms/DeviceDetailsDeckConfiguration/__tests__/AddFixtureModal.test.tsx

@@ -14,15 +14,18 @@ import { renderWithProviders } from '/app/__testing-utils__'
 import { i18n } from '/app/i18n'
 import { useNotifyDeckConfigurationQuery } from '/app/resources/deck_configuration'
 
+import { useSendIdentifyStacker } from '../../ModuleWizardFlows/hooks'
 import { AddFixtureModal } from '../AddFixtureModal'
 
 import type { ComponentProps } from 'react'
 import type { UseQueryResult } from 'react-query'
-import type { Modules } from '@opentrons/api-client'
-import type { DeckConfiguration } from '@opentrons/shared-data'
+import type { AttachedModule, Modules } from '@opentrons/api-client'
+import type { DeckConfiguration, IdentifyColor } from '@opentrons/shared-data'
 
 vi.mock('@opentrons/react-api-client')
 vi.mock('/app/resources/deck_configuration')
+vi.mock('/app/organisms/ModuleCard/utils')
+vi.mock('/app/organisms/ModuleWizardFlows/hooks.tsx')
 
 const mockCloseModal = vi.fn()
 const mockUpdateDeckConfiguration = vi.fn()
@@ -35,8 +38,14 @@ const render = (props: ComponentProps<typeof AddFixtureModal>) => {
 
 describe('Touchscreen AddFixtureModal', () => {
   let props: ComponentProps<typeof AddFixtureModal>
+  let sendIdentifyStacker: (
+    module: AttachedModule,
+    start: boolean,
+    color?: IdentifyColor
+  ) => void
 
   beforeEach(() => {
+    sendIdentifyStacker = vi.fn()
     props = {
       cutoutId: 'cutoutD3',
       addressableAreaId: 'D3',
@@ -52,13 +61,14 @@ describe('Touchscreen AddFixtureModal', () => {
     vi.mocked(useModulesQuery).mockReturnValue(({
       data: { data: [] },
     } as unknown) as UseQueryResult<Modules>)
+    vi.mocked(useSendIdentifyStacker).mockReturnValue(sendIdentifyStacker)
   })
 
   it('should render text and buttons', () => {
     render(props)
     screen.getByText('Add to Slot D3')
     screen.getByText(
-      'Add this hardware to your deck configuration. It will be referenced during protocol analysis.'
+      'Choose an item below to add to your deck configuration. It will be referenced during protocol analysis.'
     )
     screen.getByText('Fixtures')
     screen.getByText('Modules')
@@ -79,7 +89,7 @@ describe('Touchscreen AddFixtureModal', () => {
     render(props)
     screen.getByText('Add to Slot D3')
     screen.getByText(
-      'Add this hardware to your deck configuration. It will be referenced during protocol analysis.'
+      'Choose an item below to add to your deck configuration. It will be referenced during protocol analysis.'
     )
     expect(screen.queryByText('Staging area slot')).toBeNull()
     screen.getByText('Trash bin')
@@ -111,7 +121,7 @@ describe('Desktop AddFixtureModal', () => {
     render(props)
     screen.getByText('Add to Slot D3')
     screen.getByText(
-      'Add this hardware to your deck configuration. It will be referenced during protocol analysis.'
+      'Choose an item below to add to your deck configuration. It will be referenced during protocol analysis.'
     )
 
     screen.getByText('Fixtures')
@@ -130,7 +140,7 @@ describe('Desktop AddFixtureModal', () => {
     render(props)
     screen.getByText('Add to Slot A1')
     screen.getByText(
-      'Add this hardware to your deck configuration. It will be referenced during protocol analysis.'
+      'Choose an item below to add to your deck configuration. It will be referenced during protocol analysis.'
     )
     screen.getByText('Fixtures')
     screen.getByText('Modules')
@@ -144,7 +154,7 @@ describe('Desktop AddFixtureModal', () => {
     render(props)
     screen.getByText('Add to Slot B3')
     screen.getByText(
-      'Add this hardware to your deck configuration. It will be referenced during protocol analysis.'
+      'Choose an item below to add to your deck configuration. It will be referenced during protocol analysis.'
     )
     screen.getByText('Fixtures')
     screen.getByText('Modules')
@@ -158,7 +168,7 @@ describe('Desktop AddFixtureModal', () => {
     render(props)
     screen.getByText('Add to Slot B2')
     screen.getByText(
-      'Add this hardware to your deck configuration. It will be referenced during protocol analysis.'
+      'Choose an item below to add to your deck configuration. It will be referenced during protocol analysis.'
     )
     screen.getByText('Magnetic Block GEN1')
     expect(screen.getByRole('button', { name: 'Add' })).toBeInTheDocument()

app/src/organisms/ODD/ProtocolSetup/ProtocolSetupDeckConfiguration/__tests__/ProtocolSetupDeckConfiguration.test.tsx

@@ -4,6 +4,7 @@ import { when } from 'vitest-when'
 
 import { BaseDeck } from '@opentrons/components'
 import {
+  useCreateLiveCommandMutation,
   useModulesQuery,
   useUpdateDeckConfigurationMutation,
 } from '@opentrons/react-api-client'
@@ -58,6 +59,7 @@ const render = (
 
 describe('ProtocolSetupDeckConfiguration', () => {
   let props: ComponentProps<typeof ProtocolSetupDeckConfiguration>
+  const mockCreateLiveCommand = vi.fn()
 
   beforeEach(() => {
     props = {
@@ -80,6 +82,10 @@ describe('ProtocolSetupDeckConfiguration', () => {
     vi.mocked(useModulesQuery).mockReturnValue(({
       data: { data: [] },
     } as unknown) as UseQueryResult<Modules>)
+    mockCreateLiveCommand.mockResolvedValue(null)
+    vi.mocked(useCreateLiveCommandMutation).mockReturnValue({
+      createLiveCommand: mockCreateLiveCommand,
+    } as any)
   })
 
   afterEach(() => {