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

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 @@
     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 @@
     (command): command is LoadLabwareCreateCommand =>
       command.commandType === 'loadLabware'
   )
+  const equipmentLoadInfoFromCommands = getEquipmentLoadInfoFromCommands(
+    commands,
+    labwareDefinitions
+  )
 
   const savedStepsWithUpdatedMoveLiquidFields = Object.values(
     savedStepForms
@@ -74,6 +75,20 @@
         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 @@
           dispense_submerge_position_reference: null,
           liquidClassesSupported: liquidClassesSupported ?? false,
           liquidClass: null,
+          pushOut_checkbox:
+            defaultPushOutVolume != null && defaultPushOutVolume > 0,
+          pushOut_volume: defaultPushOutVolume,
         },
       }
     }
@@ -188,10 +206,6 @@
     },
     {}
   )
-  const equipmentLoadInfoFromCommands = getEquipmentLoadInfoFromCommands(
-    commands,
-    labwareDefinitions
-  )
   return {
     ...appData,
     metadata: {

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

@@ -29,7 +29,9 @@
 import {
   getAdditionalEquipmentEntities,
   getLabwareEntities,
+  getPipetteEntities,
 } from '../../../../../../step-forms/selectors'
+import { getMaxPushOutVolume } from '../../../../../../utils'
 import {
   getBlowoutLocationOptionsForForm,
   getFormErrorsMappedToField,
@@ -70,7 +72,7 @@
     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 @@
     ]
   }
 
+  const maxPushoutVolume = getMaxPushOutVolume(
+    Number(formData.volume),
+    pipetteSpec
+  )
+
   const minXYDimension = isDestinationTrash
     ? null
     : getMinXYDimension(labwares[formData[`${tab}_labware`]]?.def, ['A1'])
@@ -317,6 +324,38 @@
             </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/fieldLevel/index.ts

@@ -442,6 +442,10 @@ const stepFieldHelperMap: Record<StepFieldName, StepFieldHelpers> = {
     maskValue: composeMaskers(trimDecimals(1)),
     castValue: numberOrNull,
   },
+  pushOut_volume: {
+    maskValue: composeMaskers(maskToFloat, onlyPositiveNumbers),
+    castValue: numberOrNull,
+  },
 }
 const profileFieldHelperMap: Record<string, StepFieldHelpers> = {
   // profile step fields

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

@@ -19,7 +19,7 @@
   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 @@
   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 @@
     ? 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,