docs(api): miscellaneous changes for version 2.16 (#14265)

* add og tags and rename partial pickup page * Movement into the Waste Chute § * new Adding Trash Containers § * load trash when adapting OT-2 protocol to Flex 2.16 * misc trash addenda * no reason to hold back OT-2 apiLevel anymore * better return_tip() note
Opentrons · Dec 22, 2023 · ecadc94 · ecadc94
1 parent d9c0321
commit ecadc94
Show file tree

Hide file tree

Showing 14 changed files with 87 additions and 12 deletions.
diff --git a/api/docs/v2/adapting_ot2_flex.rst b/api/docs/v2/adapting_ot2_flex.rst
@@ -34,7 +34,7 @@ You also need to specify ``'robotType': 'Flex'``. If you omit ``robotType`` in t
             metadata = {
                 "protocolName": "My Protocol",
                 "description": "This protocol uses the OT-2",
-                "apiLevel": "2.14" 
+                "apiLevel": "|apiLevel|"
             }
 
     .. tab:: Updated Flex code
@@ -84,6 +84,13 @@ This example converts OT-2 code that uses a P300 Single-Channel GEN2 pipette and
                     "flex_1channel_1000", "left", tip_racks[tips]
                 )
 
+Trash Container
+===============
+
+OT-2 protocols always have a :py:obj:`.fixed_trash` in slot 12. In Flex protocols specifying API version 2.16 or later, you need to :ref:`load a trash bin <configure-trash-bin>`. Put it in slot A3 to match the physical position of the OT-2 fixed trash::
+
+    trash = protocol.load_trash_bin("A3")
+
 Deck Slot Labels
 ================
 

diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst
@@ -147,11 +147,13 @@ You can also specify a particular well as the blowout location::
 
     pipette.blow_out(plate['B1'])
 
-Many protocols use the trash bin for blowing out the pipette. You can specify the trash bin as the blowout location by using the :py:obj:`.ProtocolContext.fixed_trash` property::
+Many protocols use a trash container for blowing out the pipette. You can specify the pipette's current trash container as the blowout location by using the :py:obj:`.InstrumentContext.trash_container` property::
 
-    pipette.blow_out(protocol.fixed_trash['A1'])  
+    pipette.blow_out(pipette.trash_container)
 
 .. versionadded:: 2.0
+.. versionchanged:: 2.16
+    Added support for ``TrashBin`` and ``WasteChute`` locations.
 
 .. _touch-tip:
 

diff --git a/api/docs/v2/basic_commands/pipette_tips.rst b/api/docs/v2/basic_commands/pipette_tips.rst
@@ -77,7 +77,7 @@ For a more advanced "real-world" example, review the :ref:`off-deck location pro
 Dropping a Tip
 ==============
 
-To drop a tip in the trash bin, call the :py:meth:`~.InstrumentContext.drop_tip` method with no arguments::
+To drop a tip in the pipette's trash container, call the :py:meth:`~.InstrumentContext.drop_tip` method with no arguments::
     
     pipette.pick_up_tip()
 
@@ -99,6 +99,13 @@ To return a tip to its original location, call the :py:meth:`~.InstrumentContext
 
     pipette.return_tip()
 
+.. versionadded:: 2.0
+
+.. note::
+    You can't return tips with a pipette that's configured to use :ref:`partial tip pickup <partial-tip-pickup>`. This restriction ensures that the pipette has clear access to unused tips. For example, a 96-channel pipette in column configuration can't reach column 2 unless column 1 is empty. 
+
+    If you call ``return_tip()`` while using partial tip pickup, the API will raise an error. Use ``drop_tip()`` to dispose the tips instead.
+
 Working With Used Tips
 ======================
 

diff --git a/api/docs/v2/deck_slots.rst b/api/docs/v2/deck_slots.rst
@@ -152,7 +152,7 @@ Starting in API version 2.16, you must load trash bin fixtures in your protocol
 .. note::
     The :py:class:`TrashBin` class doesn't have any callable methods, so you don't have to save the result of ``load_trash_bin()`` to a variable, especially if your protocol only loads a single trash container. Being able to reference the trash bin by name is useful when dealing with multiple trash containers.
 
-Call ``load_trash_bin()`` multiple times to add more than one bin. See :ref:`Adding a Trash Container <pipette-trash-container>` for more information on using pipettes with multiple trash bins.
+Call ``load_trash_bin()`` multiple times to add more than one bin. See :ref:`pipette-trash-containers` for more information on using pipettes with multiple trash bins.
 
 .. _configure-waste-chute:
 

diff --git a/api/docs/v2/index.rst b/api/docs/v2/index.rst
@@ -123,7 +123,7 @@ For example, if we wanted to transfer liquid from well A1 to well B1 on a plate,
             }
 
             # requirements
-            requirements = {"robotType": "OT-2", "apiLevel": "2.14"}
+            requirements = {"robotType": "OT-2", "apiLevel": "|apiLevel|"}
 
             # protocol run function
             def run(protocol: protocol_api.ProtocolContext):

diff --git a/api/docs/v2/modules/multiple_same_type.rst b/api/docs/v2/modules/multiple_same_type.rst
@@ -49,7 +49,7 @@ When working with multiple modules of the same type, load them in your protocol
 
       from opentrons import protocol_api
 
-      metadata = { 'apiLevel': '2.14'}
+      metadata = { 'apiLevel': '|apiLevel|'}
 
       def run(protocol: protocol_api.ProtocolContext):
         # Load Temperature Module 1 in deck slot C1 on USB port 1

diff --git a/api/docs/v2/modules/setup.rst b/api/docs/v2/modules/setup.rst
@@ -42,7 +42,7 @@ Use :py:meth:`.ProtocolContext.load_module` to load a module.
 
             from opentrons import protocol_api
             
-            metadata = {'apiLevel': '2.14'}
+            metadata = {'apiLevel': '|apiLevel|'}
             
             def run(protocol: protocol_api.ProtocolContext): 
                 # Load a Magnetic Module GEN2 in deck slot 1.

diff --git a/api/docs/v2/moving_labware.rst b/api/docs/v2/moving_labware.rst
@@ -129,6 +129,22 @@ Also note the ``hs_mod.open_labware_latch()`` command in the above example. To m
 
 If the labware is inaccessible, the API will raise an error. 
 
+Movement into the Waste Chute
+=============================
+
+Move used tip racks and well plates to the waste chute to dispose of them. This requires you to first :ref:`configure the waste chute <configure-waste-chute>` in your protocol. Then use the loaded :py:class:`WasteChute` object as the value of ``new_location``::
+
+    chute = protocol.load_waste_chute()
+    protocol.move_labware(
+        labware=plate, new_location=chute, use_gripper=True
+    )
+
+.. versionadded:: 2.16
+
+This will pick up ``plate`` from its current location and drop it into the chute.
+
+Always specify ``use_gripper=True`` when moving labware into the waste chute. The chute is not designed for manual movement. You can still manually move labware to other locations, including off-deck, with the chute installed.
+
 .. _off-deck-location:
 
 The Off-Deck Location
@@ -148,7 +164,7 @@ You can also load labware off-deck, in preparation for a ``move_labware()`` comm
 
     from opentrons import protocol_api
 
-    metadata = {"apiLevel": "2.15", "protocolName": "Tip rack replacement"}
+    metadata = {"apiLevel": "|apiLevel|", "protocolName": "Tip rack replacement"}
     requirements = {"robotType": "OT-2"}
 
 

diff --git a/api/docs/v2/new_pipette.rst b/api/docs/v2/new_pipette.rst
@@ -9,7 +9,7 @@ Pipettes
 .. toctree::
     pipettes/loading
     pipettes/characteristics
-    pipettes/configuring
+    pipettes/partial_tip_pickup
     pipettes/volume_modes
 
 Opentrons pipettes are configurable devices used to move liquids throughout the working area during the execution of protocols. Flex and OT-2 each have their own pipettes, which are available for use in the Python API.

diff --git a/api/docs/v2/pipettes/characteristics.rst b/api/docs/v2/pipettes/characteristics.rst
@@ -1,3 +1,5 @@
+:og:description: Details on Opentrons pipette movement and flow rates.
+
 .. _pipette-characteristics:
 
 ***********************

diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst
@@ -1,3 +1,5 @@
+:og:description: How to load Opentrons pipettes and add tip racks to them in a Python protocol.
+
 .. _new-create-pipette:
 .. _loading-pipettes:
 
@@ -108,7 +110,7 @@ This code sample loads a P1000 Single-Channel GEN2 pipette in the left mount and
 
     from opentrons import protocol_api
 
-    metadata = {'apiLevel': '2.14'}
+    metadata = {'apiLevel': '|apiLevel|'}
 
     def run(protocol: protocol_api.ProtocolContext):
         tiprack1 = protocol.load_labware(
@@ -179,3 +181,37 @@ Additional calls to ``pick_up_tip`` will automatically progress through the tips
 .. versionadded:: 2.0
 
 See also :ref:`v2-atomic-commands` and :ref:`v2-complex-commands`.
+
+.. _pipette-trash-containers:
+
+Adding Trash Containers
+=======================
+
+The API automatically assigns a :py:obj:`.trash_container` to pipettes, if one is available in your protocol. The ``trash_container`` is where the pipette will dispose tips when you call :py:meth:`.drop_tip` with no arguments. You can change the trash container, if you don't want to use the default. 
+
+One example of when you might want to change the trash container is a Flex protocol that goes through a lot of tips. In a case where the protocol uses two pipettes, you could load two trash bins and assign one to each pipette::
+
+    left_pipette = protocol.load_instrument(
+        instrument_name='flex_8channel_1000', mount='left'
+    )
+    right_pipette = protocol.load_instrument(
+        instrument_name='flex_8channel_50', mount='right'
+    )
+    left_trash = load_trash_bin('A3')
+    right_trash = load_trash_bin('B3')
+    left_pipette.trash_container = left_trash
+    right_pipette.trash_container = right_trash
+
+Another example is a Flex protocol that uses a waste chute. Say you want to only dispose labware in the chute, and you want the pipette to drop tips in a trash bin. You can implicitly get the trash bin to be the pipette's ``trash_container`` based on load order, or you can ensure it by setting it after all the load commands::
+
+    pipette = protocol.load_instrument(
+        instrument_name="flex_1channel_1000",
+        mount="left"
+    )
+    chute = protocol.load_waste_chute()  # default because loaded first
+    trash = protocol.load_trash_bin("A3")
+    pipette.trash_container = trash  # overrides default
+
+.. versionadded:: 2.0
+.. versionchanged:: 2.16
+    Added support for ``TrashBin`` and ``WasteChute`` objects.
diff --git a/api/docs/v2/pipettes/configuring.rst → api/docs/v2/pipettes/partial_tip_pickup.rst b/api/docs/v2/pipettes/configuring.rst → api/docs/v2/pipettes/partial_tip_pickup.rst
@@ -1,3 +1,5 @@
+:og:description: How to change the number of tips an Opentrons pipette uses.
+
 .. _partial-tip-pickup:
 
 ******************
@@ -38,6 +40,7 @@ Here is the start of a protocol that performs both imports, loads a 96-channel p
             load_name="opentrons_flex_96_tiprack_1000ul",
             location="D3"
         )
+        trash = protocol.load_trash_bin("A3")
         pipette = protocol.load_instrument("flex_96channel_1000")
         pipette.configure_nozzle_layout(
             style=COLUMN,

diff --git a/api/docs/v2/pipettes/volume_modes.rst b/api/docs/v2/pipettes/volume_modes.rst
@@ -1,3 +1,5 @@
+:og:description: How to work with very small volumes of liquid on Opentrons Flex.
+
 .. _pipette-volume-modes:
 
 Volume Modes

diff --git a/api/docs/v2/versioning.rst b/api/docs/v2/versioning.rst
@@ -44,7 +44,7 @@ From version 2.15 onward, you can specify ``apiLevel`` in the ``requirements`` d
    from opentrons import protocol_api
 
    metadata = {'author': 'A. Biologist'}
-   requirements = {'apiLevel': '2.15', 'robotType': 'Flex'}
+   requirements = {'apiLevel': '|apiLevel|', 'robotType': 'Flex'}
 
    def run(protocol: protocol_api.ProtocolContext):
        protocol.comment('Hello, Flex!')