docs(api): how to use LPC enhancements and offsets in Jupyter (#11063)

Author: ecormany

api/docs/v2/robot_position.rst

@@ -13,12 +13,14 @@ Most of the time when executing a protocol, the Python Protocol API's methods ta
 Position Relative to Labware
 ****************************
 
-Every well on every piece of labware you load has three addressable positions — top, bottom, and center — that are determined by the labware definition. You can use these positions as-is or calculate other positions relative to them.
+When you instruct the robot to move to a position on a piece of labware, the exact point in space it moves to is calculated based on the labware definition, the type of action the robot will perform there, and labware offsets for the specific deck slot on your robot. This section describes how each of these components of a position are calculated and methods for modifying them.
 
-Top
-===
+Top, Bottom, and Center
+=======================
 
-The :py:meth:`.Well.top` method returns a position level with the top of the well, centered in both horizontal directions. 
+Every well on every piece of labware you load has three addressable positions — top, bottom, and center — that are determined by the labware definition and whether the labware is on a module or directly on the deck. You can use these positions as-is or calculate other positions relative to them.
+
+:py:meth:`.Well.top` returns a position level with the top of the well, centered in both horizontal directions. 
 
 .. code-block:: python
 
@@ -33,10 +35,7 @@ This is a good position to use for :ref:`new-blow-out` or any other operation wh
 
 .. versionadded:: 2.0
 
-Bottom
-======
-
-The :py:meth:`.Well.bottom` method returns a position level with the bottom of the well, centered in both horizontal directions. 
+:py:meth:`.Well.bottom` returns a position level with the bottom of the well, centered in both horizontal directions. 
 
 .. code-block:: python
 
@@ -57,10 +56,8 @@ This is a good position to start for aspiration or any other operation where you
 
 .. versionadded:: 2.0
 
-Center
-======
 
-The :py:meth:`.Well.center` method returns a position centered in the well both vertically and horizontally. This can be a good place to start for precise control of positions within the well for unusual or custom labware.
+:py:meth:`.Well.center` returns a position centered in the well both vertically and horizontally. This can be a good place to start for precise control of positions within the well for unusual or custom labware.
 
 .. code-block:: python
 
@@ -113,6 +110,65 @@ Changing these attributes will affect all subsequent aspirate and dispense actio
 .. versionadded:: 2.0
 
 
+.. _using_lpc:
+
+Using Labware Position Check
+============================
+
+All positions relative to labware are automatically adjusted based on the labware's offset, an x, y, z vector. The best way to calculate and apply these offsets is by using Labware Position Check when you run your protocol in the Opentrons App. As of version 6.0 of the app, you can apply previously calculated offsets — even across different protocols — as long as they are for the same type of labware in the same deck slot on the same robot.
+
+You shouldn't adjust labware offsets in your Python code if you plan to run your protocol in the app. However, if you are running your protocol in Jupyter notebook or with ``opentrons_execute``, Labware Position Check is not directly available. For these applications, you can calculate and apply labware offsets by:
+	
+	1. Creating a "dummy" protocol that loads your labware and has each used pipette pick up a tip from a tip rack
+	2. Importing the dummy protocol to the Opentrons App
+	3. Running Labware Position Check
+	4. Adding the offsets to your protocol
+	
+To prepare code written for Jupyter notebook so it can be run in the app, you need to include a metadata block and a ``run()`` function. And to enable Labware Position Check, you need to add a :py:meth:`.pick_up_tip` action for each pipette the protocol uses. For example, a dummy protocol using a P300 Single-Channel pipette, a reservoir, and a well plate would look like this:
+
+.. code-block:: python
+
+    metadata = {'apiLevel': '2.12'}
+
+    def run(protocol):
+        tiprack = protocol.load_labware('opentrons_96_tiprack_300ul', 1)
+        reservoir = protocol.load_labware('nest_12_reservoir_15ml', 2)
+        plate = protocol.load_labware('nest_96_wellplate_200ul_flat', 3)
+        p300 = protocol.load_instrument('p300_single_gen2', 'left', tip_racks=[tiprack])
+        p300.pick_up_tip()
+        p300.return_tip()
+		
+After importing this protocol to the Opentrons App, run Labware Position Check to get the x, y, and z offsets for the tip rack and labware. When complete, you can click **Get Labware Offset Data** to view automatically generated code that uses :py:meth:`.set_offset` to apply the offsets to each piece of labware:
+
+.. code-block:: python
+	
+    labware_1 = protocol.load_labware("opentrons_96_tiprack_300ul", location="1")
+    labware_1.set_offset(x=0.00, y=0.00, z=0.00)
+
+    labware_2 = protocol.load_labware("nest_12_reservoir_15ml", location="2")
+    labware_2.set_offset(x=0.10, y=0.20, z=0.30)
+
+    labware_3 = protocol.load_labware("nest_96_wellplate_200ul_flat", location="3")
+    labware_3.set_offset(x=0.10, y=0.20, z=0.30)
+    
+You'll notice that this code uses generic names for the loaded labware. If you want to match the labware names already in your protocol, add your own ``.set_offset()`` calls using the arguments provided by Labware Position Check:
+
+.. code-block:: python
+
+    reservoir = protocol.load_labware('nest_12_reservoir_15ml', 2)
+    reservoir.set_offset(x=0.10, y=0.20, z=0.30)
+    
+.. versionadded:: 2.12
+
+Once you've executed this code in Jupyter notebook, all subsequent positional calculations for this reservoir in slot 2 will be adjusted 0.1 mm to the right, 0.2 mm to the back, and 0.3 mm up.
+
+Remember, you should only add ``.set_offset()`` commands to protocols run outside of the Opentrons App. And you should follow the behavior of Labware Position Check: do not reuse offset measurements unless they apply to the *same labware* in the *same deck slot* on the *same robot*.
+
+.. warning::
+
+	Improperly reusing offset data may cause your robot to move to unforeseen positions, including crashing on labware, which can lead to incorrect protocol execution or damage to your equipment. The same is true of running protocols with ``.set_offset()`` commands in the Opentrons App. When in doubt: run Labware Position Check again and update your code!
+
+
 .. _protocol-api-deck-coords:
 
 *****************************