feat(app, api-client): Support offset persistence in LPC (#17779)

Closes EXEC-1121, EXEC-1155, EXEC-1311, EXEC-1270, and EXEC-1120

This commit provides support for retrieving and storing offsets on the robot-server, adding necessary utilities for querying and injecting appropriate offset data into LPC. There's a lot of necessary cleanup and refactoring along the way, too. Note that this commit does add LPC Flex stacker support, hardcoded offset support, and older protocol analysis support, since these features somewhat organically fit into the rearchitecture required to support the new API changes.

Author: mjhuff

api-client/src/maintenance_runs/types.ts

@@ -7,6 +7,7 @@ import type {
 import type {
   RunCommandSummary,
   LegacyLabwareOffsetCreateData,
+  LabwareOffsetCreateData,
   RunStatus,
   RunAction,
 } from '../runs'
@@ -42,7 +43,7 @@ export interface MaintenanceRunError {
 }
 
 export interface CreateMaintenanceRunData {
-  labwareOffsets?: LegacyLabwareOffsetCreateData[]
+  labwareOffsets?: LegacyLabwareOffsetCreateData[] | LabwareOffsetCreateData[]
 }
 
 export interface LabwareDefinitionSummary {

api-client/src/runs/types.ts

@@ -172,6 +172,12 @@ export interface LegacyLabwareOffsetCreateData {
   vector: VectorOffset
 }
 
+export interface LabwareOffsetCreateData {
+  definitionUri: string
+  locationSequence: LabwareOffsetLocationSequence
+  vector: VectorOffset
+}
+
 type RunTimeParameterValuesType = string | number | boolean | { id: string }
 export type RunTimeParameterValuesCreateData = Record<
   string,

api-client/src/types.ts

@@ -1,6 +1,6 @@
 import type { AxiosRequestConfig } from 'axios'
 import type { ResponsePromise } from './request'
-import type { ModuleModel } from '@opentrons/shared-data'
+import type { AddressableAreaName, ModuleModel } from '@opentrons/shared-data'
 
 export interface HostConfig {
   hostname: string
@@ -60,7 +60,7 @@ export interface OnModuleOffsetLocationSequenceComponent
 export interface OnAddressableAreaOffsetLocationSequenceComponent
   extends BaseOffsetLocationSequenceComponent {
   kind: 'onAddressableArea'
-  addressableAreaName: string
+  addressableAreaName: AddressableAreaName
 }
 
 export type LabwareOffsetLocationSequenceComponent =

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

@@ -18,6 +18,7 @@
   "calibration_probe": "Calibration Probe",
   "calibration_probe_not_detected": "Calibration probe not detected",
   "cancel": "Cancel",
+  "changing_default_not_update_hardcoded": "Changing the default offset will not automatically update hardcoded offsets",
   "check_item_in_location": "Check {{item}} in {{location}}",
   "check_labware_in_slot_title": "Check Labware {{labware_display_name}} in slot {{slot}}",
   "check_remaining_labware_with_primary_pipette_section": "Check remaining labware with {{primary_mount}} Pipette and tip",
@@ -53,6 +54,8 @@
   "get_labware_offset_data": "Get Labware Offset Data",
   "go_back": "Go back",
   "go_back_confirmation": "Are you sure you want to go back to the the labware list without saving?",
+  "hardcoded": "Hardcoded",
+  "hardcoded_offsets_changed_in_python": "Hardcoded offsets must be changed in your Python protocol",
   "install_probe_1ch": "<block>Take the calibration probe from its storage location. Ensure the collar is fully unlocked. Push the pipette ejector up and press the probe firmly onto the pipette nozzle as far as it can go. Twist the collar to lock the probe.</block><block>Test that the probe is secure by gently pulling it back and forth. It should be firmly in place.</block>",
   "install_probe_8ch": "<block>Take the calibration probe from its storage location. Ensure the collar is fully unlocked. Push the pipette ejector up and press the probe firmly onto the <strong>backmost</strong> pipette nozzle as far as it can go. Twist the collar to lock the probe.</block><block>Test that the probe is secure by gently pulling it back and forth. It should be firmly in place.</block>",
   "install_probe_96ch": "<block>Take the calibration probe from its storage location. Ensure the collar is fully unlocked. Push the pipette ejector up and press the probe firmly onto the <strong>A1 (back left corner)</strong> pipette nozzle as far as it can go. Twist the collar to lock the probe.</block><block>Test that the probe is secure by gently pulling it back and forth. It should be firmly in place.</block>",
@@ -109,6 +112,8 @@
   "moving_to_slot_title": "Moving to slot {{slot}}",
   "need_help": "Need help?",
   "new_labware_offset_data": "New labware offset data",
+  "next_place_a_full_tip_rack_in_location": "Next, place <bold>a full {{tip_rack}}</bold> into <bold>{{location}}</bold>",
+  "next_place_labware_in_location": "Next, place a <bold>{{labware}}</bold> into <bold>{{location}}</bold>",
   "ninety_six_probe_location": "A1 (back left corner)",
   "no_labware_offsets": "No Labware Offset",
   "no_offset_data": "No offset data",

app/src/organisms/Desktop/Devices/RunPreview/index.tsx

@@ -56,7 +56,6 @@ export const RunPreviewComponent = (
 ): JSX.Element | null => {
   const { t } = useTranslation(['run_details', 'protocol_setup'])
   const robotSideAnalysis = useMostRecentCompletedAnalysis(runId)
-  console.log(robotSideAnalysis)
   const runStatus = useRunStatus(runId)
   const { data: runRecord } = useNotifyRunQuery(runId)
   const isRunTerminal =

app/src/organisms/LabwarePositionCheck/LPCContentContainer.tsx

@@ -76,12 +76,13 @@ export function LPCContentContainer(
   const showDesktopFooter = !commandUtils.isRobotMoving
 
   const handleExit = (): void => {
-    if (
-      step !== LPC_STEP.DETACH_PROBE &&
-      step !== LPC_STEP.LPC_COMPLETE &&
+    if (step === LPC_STEP.HANDLE_LABWARE && commandUtils.errorMessage == null) {
+      commandUtils.headerCommands.handleNavToDetachProbe()
+    } else if (
+      step === LPC_STEP.DETACH_PROBE &&
       commandUtils.errorMessage == null
     ) {
-      commandUtils.headerCommands.handleNavToDetachProbe()
+      commandUtils.headerCommands.handleCloseAndHome()
     } else {
       void commandUtils.handleCloseNoHome()
     }

app/src/organisms/LabwarePositionCheck/LPCFlows/LPCFlows.tsx

@@ -11,7 +11,7 @@ import type { LPCLabwareInfo } from '/app/redux/protocol-runs'
 
 // Inject the props specific to the legacy LPC flows, too.
 export interface LegacySupportLPCFlowsProps extends LPCFlowsProps {
-  existingOffsets: LabwareOffset[]
+  runRecordExistingOffsets: LabwareOffset[]
 }
 
 export interface LPCFlowsProps {
@@ -21,7 +21,7 @@ export interface LPCFlowsProps {
   deckConfig: DeckConfiguration
   labwareDefs: LabwareDefinition2[]
   labwareInfo: LPCLabwareInfo
-  mostRecentAnalysis: CompletedProtocolAnalysis
+  analysis: CompletedProtocolAnalysis
   protocolName: string
   maintenanceRunId: string
 }

app/src/organisms/LabwarePositionCheck/LPCFlows/hooks/index.ts

@@ -1 +1,2 @@
 export { useLPCLabwareInfo } from './useLPCLabwareInfo'
+export * from './useInitLPCStore'

app/src/organisms/LabwarePositionCheck/LPCFlows/hooks/useCompatibleAnalysis.ts

@@ -0,0 +1,123 @@
+import type {
+  CompletedProtocolAnalysis,
+  ProtocolAnalysisSummary,
+  RunTimeCommand,
+} from '@opentrons/shared-data'
+import {
+  ANALYTICS_LPC_ANALYSIS_KIND,
+  useTrackEvent,
+} from '/app/redux/analytics'
+import { useEffect, useRef, useState } from 'react'
+import {
+  useCreateProtocolAnalysisMutation,
+  useProtocolAnalysisAsDocumentQuery,
+} from '@opentrons/react-api-client'
+import { useNotifyRunQuery } from '/app/resources/runs'
+
+// TODO(jh, 03-17-25): Add testing here.
+
+// TODO(jh, 03-14-25): Remove this adapter logic and Mixpanel event once analytics
+//  indicate that users no longer run old analyses.
+
+// If analysis is incompatible with LPC, force reanalysis and use that fresh analysis,
+// otherwise, use the current analysis.
+export function useCompatibleAnalysis(
+  runId: string,
+  mostRecentAnalysis: CompletedProtocolAnalysis | null
+): CompletedProtocolAnalysis | null {
+  const [
+    compatibleAnalysis,
+    setCompatibleAnalysis,
+  ] = useState<CompletedProtocolAnalysis | null>(null)
+  const [compatibleAnalysisId, setCompatibleAnalysisId] = useState<
+    string | null
+  >(null)
+  const hasProcessedAnalysis = useRef(false)
+
+  const trackEvent = useTrackEvent()
+  const protocolId = useNotifyRunQuery(runId).data?.data.protocolId ?? ''
+  const { createProtocolAnalysis } = useCreateProtocolAnalysisMutation(
+    protocolId
+  )
+  const { data: freshAnalysis } = useProtocolAnalysisAsDocumentQuery(
+    protocolId,
+    compatibleAnalysisId,
+    {
+      enabled: compatibleAnalysisId != null,
+      staleTime: Infinity,
+    }
+  )
+
+  if (compatibleAnalysis == null && freshAnalysis != null) {
+    setCompatibleAnalysis(freshAnalysis)
+  }
+
+  const isLocSeqAnalysisType = isLocationSequenceAnalysisType(
+    mostRecentAnalysis?.commands ?? []
+  )
+
+  useEffect(() => {
+    if (mostRecentAnalysis != null && !hasProcessedAnalysis.current) {
+      hasProcessedAnalysis.current = true
+
+      if (!isLocSeqAnalysisType) {
+        createProtocolAnalysis(
+          {
+            forceReAnalyze: true,
+            protocolKey: protocolId,
+          },
+          {
+            onSuccess: res => {
+              if (res != null) {
+                // @ts-expect-error TODO(jh, 03-17-25): Something is wrong with the typing here.
+                const data = res.data as ProtocolAnalysisSummary[]
+                // The last analysis is the most recent.
+                setCompatibleAnalysisId(data[data.length - 1].id)
+              }
+            },
+          }
+        )
+      } else {
+        setCompatibleAnalysis(mostRecentAnalysis)
+      }
+
+      trackEvent({
+        name: ANALYTICS_LPC_ANALYSIS_KIND,
+        properties: {
+          runId,
+          kind: isLocSeqAnalysisType ? 'newAnalysis' : 'oldAnalysis',
+        },
+      })
+    }
+  }, [
+    mostRecentAnalysis,
+    isLocSeqAnalysisType,
+    protocolId,
+    runId,
+    trackEvent,
+    createProtocolAnalysis,
+  ])
+
+  return compatibleAnalysis
+}
+
+// Whether the internal structure of the analysis commands reflects an LPC-compatible analysis.
+function isLocationSequenceAnalysisType(commands: RunTimeCommand[]): boolean {
+  return commands.some(cmd => {
+    switch (cmd.commandType) {
+      case 'loadLabware':
+      case 'moveLabware': {
+        if (cmd.result != null && 'locationSequence' in cmd.result) {
+          return true
+        }
+        break
+      }
+      // If we see these commands, we can assume we are dealing with location sequence protocols.
+      case 'flexStacker/setStoredLabware':
+      case 'flexStacker/retrieve': {
+        return true
+      }
+    }
+    return false
+  })
+}

app/src/organisms/LabwarePositionCheck/LPCFlows/hooks/useInitLPCStore/index.ts

@@ -0,0 +1,66 @@
+import { useEffect } from 'react'
+import { useDispatch } from 'react-redux'
+
+import { FLEX_ROBOT_TYPE } from '@opentrons/shared-data'
+
+import { startLPC, LPC_STEPS } from '/app/redux/protocol-runs'
+import { getActivePipetteId } from './utils'
+
+import type { LPCWizardState, LPCLabwareInfo } from '/app/redux/protocol-runs'
+import type {
+  CompletedProtocolAnalysis,
+  DeckConfiguration,
+  LabwareDefinition2,
+  RobotType,
+} from '@opentrons/shared-data'
+
+export interface UseLPCInitialStateProps {
+  runId: string
+  analysis: CompletedProtocolAnalysis | null
+  protocolName: string | undefined
+  maintenanceRunId: string | null
+  labwareDefs: LabwareDefinition2[]
+  labwareInfo: LPCLabwareInfo
+  deckConfig: DeckConfiguration | undefined
+  robotType: RobotType
+}
+
+// Initialize the LPC store if store data is sufficiently present.
+export function useInitLPCStore({
+  analysis,
+  runId,
+  labwareDefs,
+  protocolName,
+  deckConfig,
+  robotType,
+  ...rest
+}: UseLPCInitialStateProps): void {
+  const dispatch = useDispatch()
+
+  const isReadyToInit =
+    analysis != null && protocolName != null && deckConfig != null
+
+  useEffect(() => {
+    if (isReadyToInit && robotType === FLEX_ROBOT_TYPE) {
+      const activePipetteId = getActivePipetteId(analysis.pipettes)
+
+      const initialState: LPCWizardState = {
+        ...rest,
+        protocolData: analysis,
+        labwareDefs,
+        activePipetteId,
+        protocolName,
+        deckConfig,
+        steps: {
+          currentStepIndex: 0,
+          totalStepCount: LPC_STEPS.length,
+          all: LPC_STEPS,
+          lastStepIndices: null,
+          currentSubstep: null,
+        },
+      }
+
+      dispatch(startLPC(runId, initialState))
+    }
+  }, [isReadyToInit, deckConfig])
+}