feat(protocol-designer,-shared-data): introduce push out field in PD

This PR introduces UI and form data for push out as a checkbox expand form field in moveLiquid -> dispense. Previously, push out volumes were not configurable by the user, and were added implicitly. In order to migrate older protocols, we need to grab their default pushouts from their pipette specs. The utility `getDefaultPushOutVolume` takes into account transfer volume in order to access the correct liquids properties (default or low volume).

Closes AUTH-911

Author: ncdiehl11

protocol-designer/fixtures/protocol/8/doItAllV3MigratedToV8.json

@@ -226,7 +226,9 @@
           "stepName": "transfer",
           "stepDetails": "",
           "id": "3961e4c0-75c7-11ea-b42f-4b64e50f43e5",
-          "dispense_touchTip_mmfromTop": -2
+          "dispense_touchTip_mmfromTop": -2,
+          "pushOut_checkbox": false,
+          "pushOut_volume": 0
         },
         "54dc3200-75c7-11ea-b42f-4b64e50f43e5": {
           "moduleId": null,

protocol-designer/fixtures/protocol/8/doItAllV4MigratedToV8.json

@@ -258,7 +258,9 @@
           "stepName": "transfer",
           "stepDetails": "",
           "id": "3961e4c0-75c7-11ea-b42f-4b64e50f43e5",
-          "dispense_touchTip_mmfromTop": null
+          "dispense_touchTip_mmfromTop": null,
+          "pushOut_checkbox": false,
+          "pushOut_volume": 0
         },
         "4f4057e0-75c7-11ea-b42f-4b64e50f43e5": {
           "engageHeight": "6",

protocol-designer/fixtures/protocol/8/doItAllV7MigratedToV8.json

@@ -276,7 +276,9 @@
           "stepName": "transfer",
           "stepDetails": "",
           "id": "f9a294f1-f42b-4cae-893a-592405349d56",
-          "dispense_touchTip_mmfromTop": null
+          "dispense_touchTip_mmfromTop": null,
+          "pushOut_checkbox": true,
+          "pushOut_volume": 7
         },
         "5fdb9a12-fab4-42fd-886f-40af107b15d6": {
           "aspirate_delay_checkbox": false,

protocol-designer/fixtures/protocol/8/doItAllV8.json

@@ -239,7 +239,9 @@
           "stepName": "transfer",
           "stepDetails": "",
           "id": "d2f74144-a7bf-4ba2-aaab-30d70b2b62c7",
-          "dispense_touchTip_mmfromTop": null
+          "dispense_touchTip_mmfromTop": null,
+          "pushOut_checkbox": true,
+          "pushOut_volume": 7
         },
         "240a2c96-3db8-4679-bdac-049306b7b9c4": {
           "blockIsActive": true,

protocol-designer/fixtures/protocol/8/example_1_1_0MigratedToV8.json

@@ -206,7 +206,9 @@
           "stepName": "transfer things",
           "stepDetails": "yeah notes",
           "id": "e7d36200-92a5-11e9-ac62-1b173f839d9e",
-          "dispense_touchTip_mmfromTop": null
+          "dispense_touchTip_mmfromTop": null,
+          "pushOut_checkbox": false,
+          "pushOut_volume": 0
         },
         "18113c80-92a6-11e9-ac62-1b173f839d9e": {
           "aspirate_delay_checkbox": false,

protocol-designer/fixtures/protocol/8/newAdvancedSettingsAndMultiTemp.json

@@ -140,7 +140,9 @@
           "stepName": "transfer",
           "stepDetails": "",
           "dispense_touchTip_mmfromTop": null,
-          "id": "292e8b18-f59e-4c63-b0f3-e242bf50094b"
+          "id": "292e8b18-f59e-4c63-b0f3-e242bf50094b",
+          "pushOut_checkbox": true,
+          "pushOut_volume": 2
         },
         "960c2d3b-9cf9-49b0-ab4c-af4113f6671a": {
           "moduleId": "d6966555-6c0e-45e0-8056-428d7c486401:temperatureModuleType",

protocol-designer/fixtures/protocol/8/ninetySixChannelFullAndColumn.json

@@ -139,7 +139,9 @@
           "stepName": "transfer",
           "stepDetails": "",
           "dispense_touchTip_mmfromTop": null,
-          "id": "83a095fa-b649-4105-99d4-177f1a3f363a"
+          "id": "83a095fa-b649-4105-99d4-177f1a3f363a",
+          "pushOut_checkbox": true,
+          "pushOut_volume": 7
         },
         "f5ea3139-1585-4848-9d5f-832eb88c99ca": {
           "aspirate_airGap_checkbox": false,
@@ -229,7 +231,9 @@
           "stepName": "transfer",
           "stepDetails": "",
           "dispense_touchTip_mmfromTop": null,
-          "id": "f5ea3139-1585-4848-9d5f-832eb88c99ca"
+          "id": "f5ea3139-1585-4848-9d5f-832eb88c99ca",
+          "pushOut_checkbox": true,
+          "pushOut_volume": 7
         }
       },
       "orderedStepIds": [

protocol-designer/src/assets/localization/en/form.json

@@ -235,6 +235,13 @@
       "preWetTip": {
         "label": "pre-wet tip"
       },
+      "pushOut": {
+        "pushOut_volume": {
+          "caption": "Valid range between {{min}}-{{max}}µL",
+          "label": "Push out volume"
+        },
+        "title": "Push out"
+      },
       "setTemperature": {
         "options": {
           "false": "Deactivate module",

protocol-designer/src/assets/localization/en/tooltip.json

@@ -72,6 +72,7 @@
       "nozzles": "Partial pickup requires a tip rack directly on the deck. Full rack pickup requires the Flex 96 Tip Rack Adapter.",
       "pipette": "Select the pipette you want to use",
       "preWetTip": "Pre-wet by aspirating and dispensing the total aspiration volume",
+      "pushOut_checkbox": "Helps ensure all liquid leaves the tip",
       "setTemperature": "Select the temperature to set your module to",
       "wells": "Select wells",
       "volume": "Volume to dispense in each well"

protocol-designer/src/load-file/migration/8_5_0.ts

@@ -1,6 +1,8 @@
 import floor from 'lodash/floor'
+import { getPipetteSpecsV2 } from '@opentrons/shared-data'
 import { PROTOCOL_DESIGNER_SOURCE } from '../../constants'
 import { swatchColors } from '../../components/organisms/DefineLiquidsModal/swatchColors'
+import { getDefaultPushOutVolume } from '../../utils'
 import { getMigratedPositionFromTop } from './utils/getMigrationPositionFromTop'
 import { getAdditionalEquipmentLocationUpdate } from './utils/getAdditionalEquipmentLocationUpdate'
 import { getEquipmentLoadInfoFromCommands } from './utils/getEquipmentLoadInfoFromCommands'
@@ -22,15 +24,10 @@ export const migrateFile = (
     liquids,
     robot,
   } = appData
-
   if (designerApplication == null || designerApplication?.data == null) {
     throw Error('The designerApplication key in your file is corrupt.')
   }
-  const savedStepForms = designerApplication.data
-    ?.savedStepForms as DesignerApplicationData['savedStepForms']
-
-  const ingredients = designerApplication.data.ingredients
-
+  const { savedStepForms, ingredients } = designerApplication.data
   const migratedIngredients: Ingredients = Object.entries(
     ingredients
   ).reduce<Ingredients>((acc, [id, ingredient]) => {
@@ -48,6 +45,10 @@ export const migrateFile = (
     (command): command is LoadLabwareCreateCommand =>
       command.commandType === 'loadLabware'
   )
+  const equipmentLoadInfoFromCommands = getEquipmentLoadInfoFromCommands(
+    commands,
+    labwareDefinitions
+  )
 
   const savedStepsWithUpdatedMoveLiquidFields = Object.values(
     savedStepForms
@@ -74,6 +75,20 @@ export const migrateFile = (
         dispense_labware as string,
         'dispense'
       )
+      const tipRackDef = labwareDefinitions[form.tipRack]
+      const pipetteName =
+        equipmentLoadInfoFromCommands.pipettes?.[form.pipette]?.pipetteName ??
+        null
+      const pipetteSpecs =
+        pipetteName != null ? getPipetteSpecsV2(pipetteName) : null
+      const defaultPushOutVolume =
+        pipetteSpecs == null
+          ? null
+          : getDefaultPushOutVolume(
+              Number(form.volume),
+              pipetteSpecs,
+              tipRackDef
+            )
 
       return {
         ...acc,
@@ -124,6 +139,9 @@ export const migrateFile = (
           dispense_submerge_position_reference: null,
           liquidClassesSupported: liquidClassesSupported ?? false,
           liquidClass: null,
+          pushOut_checkbox:
+            defaultPushOutVolume != null && defaultPushOutVolume > 0,
+          pushOut_volume: defaultPushOutVolume,
         },
       }
     }
@@ -188,10 +206,6 @@ export const migrateFile = (
     },
     {}
   )
-  const equipmentLoadInfoFromCommands = getEquipmentLoadInfoFromCommands(
-    commands,
-    labwareDefinitions
-  )
   return {
     ...appData,
     metadata: {

protocol-designer/src/pages/Designer/ProtocolSteps/StepForm/StepTools/MoveLiquidTools/SecondStepsMoveLiquidTools.tsx

@@ -29,7 +29,9 @@ import {
 import {
   getAdditionalEquipmentEntities,
   getLabwareEntities,
+  getPipetteEntities,
 } from '../../../../../../step-forms/selectors'
+import { getMaxPushOutVolume } from '../../../../../../utils'
 import {
   getBlowoutLocationOptionsForForm,
   getFormErrorsMappedToField,
@@ -70,7 +72,7 @@ export const SecondStepsMoveLiquidTools = ({
     getAdditionalEquipmentEntities
   )
   const enableLiquidClasses = useSelector(getEnableLiquidClasses)
-
+  const pipetteSpec = useSelector(getPipetteEntities)[formData.pipette]?.spec
   const addFieldNamePrefix = addPrefix(tab)
   const isWasteChuteSelected =
     propsForFields.dispense_labware?.value != null
@@ -147,6 +149,11 @@ export const SecondStepsMoveLiquidTools = ({
     ]
   }
 
+  const maxPushoutVolume = getMaxPushOutVolume(
+    Number(formData.volume),
+    pipetteSpec
+  )
+
   const minXYDimension = getMinXYDimension(
     labwares[formData[`${tab}_labware`]].def,
     ['A1']
@@ -318,6 +325,38 @@ export const SecondStepsMoveLiquidTools = ({
             </Flex>
           ) : null}
         </CheckboxExpandStepFormField>
+        {tab === 'dispense' ? (
+          <CheckboxExpandStepFormField
+            title={i18n.format(
+              t('form:step_edit_form.field.pushOut.title'),
+              'capitalize'
+            )}
+            checkboxValue={propsForFields.pushOut_checkbox.value}
+            isChecked={propsForFields.pushOut_checkbox.value === true}
+            checkboxUpdateValue={propsForFields.pushOut_checkbox.updateValue}
+            tooltipText={propsForFields.pushOut_checkbox.tooltipContent}
+          >
+            {formData.pushOut_checkbox === true ? (
+              <InputStepFormField
+                showTooltip={false}
+                padding="0"
+                title={t(
+                  'form:step_edit_form.field.pushOut.pushOut_volume.label'
+                )}
+                caption={t(
+                  'form:step_edit_form.field.pushOut.pushOut_volume.caption',
+                  { min: 0, max: maxPushoutVolume }
+                )}
+                {...propsForFields.pushOut_volume}
+                units={t('application:units.microliter')}
+                errorToShow={getFormLevelError(
+                  'pushOut_volume',
+                  mappedErrorsToField
+                )}
+              />
+            ) : null}
+          </CheckboxExpandStepFormField>
+        ) : null}
         <CheckboxExpandStepFormField
           title={i18n.format(
             t('form:step_edit_form.field.delay.label'),

protocol-designer/src/step-forms/test/createPresavedStepForm.test.ts

@@ -217,6 +217,8 @@ describe('createPresavedStepForm', () => {
       disposalVolume_volume: '1',
       path: 'single',
       preWetTip: false,
+      pushOut_checkbox: null,
+      pushOut_volume: null,
       stepDetails: '',
       stepName: 'transfer',
       volume: null,

protocol-designer/src/steplist/formLevel/errors.ts

@@ -19,7 +19,7 @@ import {
   THERMOCYCLER_PROFILE,
 } from '../../constants'
 import { getPipetteCapacity } from '../../pipettes/pipetteData'
-import { canPipetteUseLabware } from '../../utils'
+import { canPipetteUseLabware, getMaxPushOutVolume } from '../../utils'
 import { getWellRatio } from '../utils'
 import { getTimeFromForm } from '../utils/getTimeFromForm'
 
@@ -423,41 +423,55 @@ const ASPIRATE_TOUCH_TIP_SPEED_REQUIRED: FormError = {
   showAtForm: false,
   showAtField: true,
   page: 2,
+  tab: 'aspirate',
 }
 const DISPENSE_TOUCH_TIP_SPEED_REQUIRED: FormError = {
   title: 'Touch tip speed required',
   dependentFields: ['dispense_touchTip_speed'],
   showAtForm: false,
   showAtField: true,
   page: 2,
+  tab: 'dispense',
 }
 const ASPIRATE_TOUCH_TIP_MM_FROM_EDGE_OUT_OF_RANGE: FormError = {
   title: 'Value falls outside of accepted range',
   dependentFields: ['aspirate_touchTip_mmFromEdge'],
   showAtForm: false,
   showAtField: true,
   page: 2,
+  tab: 'aspirate',
 }
 const DISPENSE_TOUCH_TIP_MM_FROM_EDGE_OUT_OF_RANGE: FormError = {
   title: 'Value falls outside of accepted range',
   dependentFields: ['dispense_touchTip_mmFromEdge'],
   showAtForm: false,
   showAtField: true,
   page: 2,
+  tab: 'dispense',
 }
 const ASPIRATE_TOUCH_TIP_MM_FROM_EDGE_REQUIRED: FormError = {
   title: 'Value required',
   dependentFields: ['aspirate_touchTip_mmFromEdge'],
   showAtForm: false,
   showAtField: true,
   page: 2,
+  tab: 'aspirate',
 }
 const DISPENSE_TOUCH_TIP_MM_FROM_EDGE_REQUIRED: FormError = {
   title: 'Value required',
   dependentFields: ['dispense_touchTip_mmFromEdge'],
   showAtForm: false,
   showAtField: true,
   page: 2,
+  tab: 'dispense',
+}
+const PUSH_OUT_VOLUME_REQUIRED: FormError = {
+  title: 'Push out volume required',
+  dependentFields: ['pushOut_volume'],
+  showAtForm: false,
+  showAtField: true,
+  page: 2,
+  tab: 'dispense',
 }
 
 export interface HydratedFormData {
@@ -1073,6 +1087,27 @@ export const dispenseTouchTipMmFromEdgeRequired = (
     ? DISPENSE_TOUCH_TIP_MM_FROM_EDGE_REQUIRED
     : null
 }
+export const pushOutVolumeRequired = (
+  fields: HydratedFormData
+): FormError | null => {
+  const { pushOut_checkbox, pushOut_volume } = fields
+  return pushOut_checkbox && !pushOut_volume ? PUSH_OUT_VOLUME_REQUIRED : null
+}
+export const pushOutVolumeOutOfRange = (
+  fields: HydratedFormData
+): FormError | null => {
+  const { pushOut_checkbox, pushOut_volume, pipette, volume } = fields
+  if (pipette == null) {
+    return null
+  }
+  const maxPushOutVolume = getMaxPushOutVolume(
+    Number(volume),
+    (pipette as PipetteEntity).spec
+  )
+  return pushOut_checkbox && pushOut_volume > maxPushOutVolume
+    ? PUSH_OUT_VOLUME_REQUIRED
+    : null
+}
 
 /*******************
  **     Helpers    **

protocol-designer/src/steplist/formLevel/getDefaultsForStepType.ts

@@ -135,6 +135,8 @@ export function getDefaultsForStepType(
         pickUpTip_wellNames: undefined,
         pipette: null,
         preWetTip: false,
+        pushOut_checkbox: null,
+        pushOut_volume: null,
         tipRack: null,
         volume: null,
       }

protocol-designer/src/steplist/formLevel/index.ts

@@ -55,6 +55,8 @@ import {
   dispenseTouchTipMmFromEdgeOutOfRange,
   aspirateTouchTipMmFromEdgeRequired,
   dispenseTouchTipMmFromEdgeRequired,
+  pushOutVolumeRequired,
+  pushOutVolumeOutOfRange,
 } from './errors'
 
 import {
@@ -159,6 +161,8 @@ const stepFormHelperMap: Partial<Record<StepType, FormHelpers>> = {
       dispenseWellsRequired,
       aspirateTouchTipSpeedRequired,
       dispenseTouchTipSpeedRequired,
+      pushOutVolumeRequired,
+      pushOutVolumeOutOfRange,
       aspirateTouchTipMmFromEdgeOutOfRange,
       dispenseTouchTipMmFromEdgeOutOfRange,
       aspirateTouchTipMmFromEdgeRequired,

protocol-designer/src/steplist/formLevel/test/getDefaultsForStepType.test.ts

@@ -84,6 +84,8 @@ describe('getDefaultsForStepType', () => {
         blowout_location: null,
         blowout_flowRate: null,
         preWetTip: false,
+        pushOut_checkbox: null,
+        pushOut_volume: null,
 
         aspirate_airGap_checkbox: false,
         aspirate_airGap_volume: null,