fix(api): preserve pre-v2.18 API tip drop alternating behavior

[jbleon95]

Overview

Closes AUTH-42

In PR #14560, the ability to provide custom offsets for disposal location objects (trash bins and waste chutes loaded in API v2.16 and above) was added to be introduced in v2.18. With this addition came a slight change in behavior to our alternate tip drop behavior.

For context, automatic tip drop alternation was something added in API v2.15, that when no explicit location was provided for drop_tip, the pipette's location it dropped the tip in would cycle between a left bias and right bias, to prevent tips from stacking up as quickly.

When deck configured trash was introduced initially, there was no way to provide custom offsets, and so we'd always do the tip alternation regardless of whether the trash location was passed or not. With the addition of offsets, we've gone back to the pattern we used for labware based trash, where if you provide it even with no offset, we go to the center of the trash. However, the PR did not add a version gate for this change in behavior, which meant that 2.16 and 2.17 protocols would behave slightly differently in this new robot version. This PR fixes that and preserves parity with those API levels.

Test Plan

Tested the following two protocols on robot and ensured that the 2.17 protocol and 2.18 worked as expected.

metadata = {
    'protocolName': 'Tip Drop Alternation 2.17 test',
}

requirements = {
    "robotType": "Flex",
    "apiLevel": "2.17"
}

def run(context):
    trash = context.load_trash_bin('A3')
    tip_rack = context.load_labware('opentrons_flex_96_tiprack_200ul', 'C2')
    pipette = context.load_instrument("flex_1channel_1000", mount="left", tip_racks=[tip_rack])

    # On 2.17 it should alternate for all four drop tip calls, regardless of trash being provided as location or not
    pipette.pick_up_tip()
    pipette.drop_tip(trash)

    pipette.pick_up_tip()
    pipette.drop_tip(trash)

    pipette.pick_up_tip()
    pipette.drop_tip()

    pipette.pick_up_tip()
    pipette.drop_tip()

metadata = {
    'protocolName': 'Tip Drop Alternation 2.18 test',
}

requirements = {
    "robotType": "Flex",
    "apiLevel": "2.18"
}

def run(context):
    trash = context.load_trash_bin('A3')
    tip_rack = context.load_labware('opentrons_flex_96_tiprack_200ul', 'C2')
    pipette = context.load_instrument("flex_1channel_1000", mount="left", tip_racks=[tip_rack])

    # On 2.18 it should alternate only for the latter two calls, and go to the XY center for the first two
    pipette.pick_up_tip()
    pipette.drop_tip(trash)

    pipette.pick_up_tip()
    pipette.drop_tip(trash)

    pipette.pick_up_tip()
    pipette.drop_tip()

    pipette.pick_up_tip()
    pipette.drop_tip()

Changelog

• added a version gate for alternate_tip_drop to preserve 2.16 and 2.17 tip dropping behavior.

Review requests

Is there anything that should be added to the docstring or release notes regarding this change?

Risk assessment

Low.

[SyntaxColoring]

This looks like it'll do what it says on the tin, thanks!

---

This is a matter of API design, but with this:

    pipette.pick_up_tip()
    pipette.drop_tip(trash)

I would always expect this to alternate, even on new API versions. Because I said to drop a tip "in the trash", not drop a tip "in a specific offset in the trash." When people have multiple trash containers on the deck, I think they'd want to select a trash container explicitly without opting out of alternation.

[jbleon95]

This looks like it'll do what it says on the tin, thanks!

This is a matter of API design, but with this:

    pipette.pick_up_tip()
    pipette.drop_tip(trash)

I would always expect this to alternate, even on new API versions. Because I said to drop a tip "in the trash", not drop a tip "in a specific offset in the trash." When people have multiple trash containers on the deck, I think they'd want to select a trash container explicitly without opting out of alternation.

I don't disagree myself, but this wouldn't be possible right now without a not-insignifcant refactor of how we have disposal location offsets working, plus

• This matches the behavior of labware based trash when users provided it as an argument
• With this version users can put in their own offsets if tip stacking proves to be a problem
• They can also set the trash they want to use with trash_container and switch between them as necessary

If this ends up causing pain points with protocols in the future, we can always add an easier way to use tip drop alternation for multiple trash bins in a future API version

[ecormany]

Thanks for the heads up. We'll want to amend these lines in the docstring:

opentrons/api/src/opentrons/protocol_api/instrument_context.py

Lines 1022 to 1025 in cdecc11

	Starting with API version 2.15, if the trash container is the default fixed
	trash, the API will instruct the pipette to drop tips in different locations
	within the trash container. Varying the tip drop location helps prevent tips
	from piling up in a single location.

I can open a PR based on the 2.18 docs release branch for that. You can go ahead and merge these approved code changes to edge.