feat(api): allow custom user offsets for deck configured trash bins and waste chute

[jbleon95]

Overview

Closes RSS-391.

This PR adds the ability to dispense, blow out, drop tip, and move to deck configured (api level 2.16 and above) trash bins and waste chutes. In addition, a few refactors were done to make these objects more robust for future development. This includes giving them access to the engine client, moving the creation of them to the core, and adding unit test coverage for these.

The offset feature is done via a new .top() method, which returns an identical trash bin/waste chute with an offset that is set there via the standard x, y, and z float parameters. There is no corresponding bottom parameter added, since these do not make sense for either the trash bin or waste chute.

One difference in behavior that will be seen in this future 2.18 version is that if you provide the trash bin directly as an argument for drop tip, i.e. drop_tip(trash_bin), even without an offset, we will not automatically alternate tip drop location. That will now only happen when it is the user set/automatically set trash and no argument is provided, which matches the behavior for labware based trash bins.

Currently these do no have API version gates. Once 7.2.0 is released and 2.17 is official, and we bump up our next version to 2.18, those will be added, which will also cover the change in behavior above so there is no difference in execution for lower api levels in the future 7.3.0.

Test Plan

Tested the functionality of the trash offsets with the following protocols. Some older version API protocols were ran to ensure nothing was broken in the refactors, in addition to unit test and integration test coverage for the trash.

metadata = {
    'protocolName': 'Trash offset test',
}

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

def run(context):
	trash_bin = context.load_trash_bin('A1')
	tip_rack = context.load_labware('opentrons_flex_96_tiprack_50ul', 'D2')

	pipette = context.load_instrument('flex_1channel_1000', mount="left", tip_racks=[tip_rack])

	pipette.pick_up_tip()
	# This will automatically cause a tip drop alternation
	pipette.drop_tip()

	pipette.pick_up_tip()
	# This will cause no tip drop alternation
	pipette.drop_tip(trash_bin)

	pipette.pick_up_tip()
	# This will cause no alternation and use the offset
	pipette.drop_tip(trash_bin.top(x=25, z=20))

	pipette.pick_up_tip()
	# This will resume tip drop alternation
	pipette.drop_tip()

metadata = {
    'protocolName': 'Trash and waste chute offset test',
}

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

def run(context):
	trash_bin = context.load_trash_bin('A3')
	waste_chute = context.load_waste_chute()
	tip_rack = context.load_labware('opentrons_flex_96_tiprack_50ul', 'D1')
	plate = context.load_labware('opentrons_96_wellplate_200ul_pcr_full_skirt', 'C1')

	pipette = context.load_instrument('flex_1channel_1000', mount="left", tip_racks=[tip_rack])

	pipette.pick_up_tip()

	pipette.move_to(trash_bin.top(z=30))
	pipette.aspirate(20, plate['A1'].top())

	pipette.dispense(20, waste_chute.top(x=-10, y=10))
	pipette.blow_out(waste_chute.top(z=-5))

	pipette.drop_tip()

Changelog

• added top method for deck configured TrashBin and WasteChute
• refactored TrashBin and WasteChute to be created in cores and have access to the engine client
• added an internal height method using the engine client to remove hard coding in deck conflict

Review requests

I chose top as the name of the offset method to match what we use with wells, but I am open to other suggestions if we don't think that is a good API name.

Risk assessment

Medium-low, I think our unit test coverage and the addition of protocol api integration tests have us well covered, and the implementation of the offset was done pretty straightforwardly.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 67.80%. Comparing base (c2cce41) to head (cbb7fb8).
Report is 2 commits behind head on edge.

Additional details and impacted files

@@           Coverage Diff           @@
##             edge   #14560   +/-   ##
=======================================
  Coverage   67.80%   67.80%           
=======================================
  Files        2509     2509           
  Lines       72156    72156           
  Branches     9287     9287           
=======================================
  Hits        48922    48922           
  Misses      21006    21006           
  Partials     2228     2228           

Flag	Coverage Δ
g-code-testing	92.43% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files	Coverage Δ
api/src/opentrons/commands/commands.py	95.45% <ø> (ø)
api/src/opentrons/commands/helpers.py	85.00% <ø> (ø)
api/src/opentrons/commands/types.py	100.00% <ø> (ø)
api/src/opentrons/protocol_api/__init__.py	100.00% <ø> (ø)
...i/src/opentrons/protocol_api/instrument_context.py	89.09% <ø> (ø)
api/src/opentrons/protocol_api/protocol_context.py	92.74% <ø> (ø)

[CaseyBatten]

These changes look good, and don't interrupt checks we've added elsewhere for height conflicts. We may want to test that when doing manual offsets over a trashbin on a 96ch drop tip with something tall like a 96ch adapter infront of it, that the instrument doesn't collide with that adapter. I believe all of our conflict checks take the actual current position of the instrument into account when checking for heigh collisions with slot items, so we are likely safely raising an error in such a case.

[TamarZanzouri]

can we change this name? maybe disposale_location?

[TamarZanzouri]

great change! a few comments but overall looks great!

[sanni-t]

Changes look good!