Merge pull request #124 from OpenTrons/update-docs-getting-started-page

Update docs getting started page

Author: andySigler

docs/source/api.rst

@@ -13,7 +13,7 @@ Robot
 All protocols are set up, simulated and executed using a Robot class.
 
 .. autoclass:: Robot
-   :members: connect, home, reset, run, simulate, commands, move_to, containers, actions, disconnect, pause, resume, stop, diagnostics, get_warnings, add_instrument, get_mosfet, get_motor
+   :members: connect, home, reset, run, simulate, commands, move_to, containers, actions, disconnect, head_speed, pause, resume, stop, diagnostics, get_warnings, add_instrument, get_mosfet, get_motor
 
 Pipette
 -----------------

docs/source/getting_started.rst

@@ -54,7 +54,7 @@ Now that you've installed Opentrons API on your computer, you have access to a v
       trash_container=trash,
       tip_racks=[tiprack],
       min_volume=20,
-      max_volume=2000,
+      max_volume=200,
       axis="a",
       channels=1
   )
@@ -78,46 +78,29 @@ Now that you have a robot to run commands on, you need to tell it what container
 Containers
 ^^^^^^^^^^
 
-For each container you want to use on the deck, you need to load it into your file by telling the robot what it is, where it is, and what to label it. The label you give the container is what will appear in the app when you start calibrating.
-
 .. code-block:: python
+	
+	plate = containers.load('96-flat', 'B2', 'optional-unique-name')
 
-	mycontainer = containers.load(
-		'container type', 	
-		'slot position'		 
-		'given name'		   
-	)
+Each container on the deck is loaded using the container's name and assign it to a slot. The API comes packaged with a set of containers, and users can create and add their own custom containers.
 
 **containers.load** (*container, slot, name*)
 
 	* **container -** type of container (aka "trough-12row")
 	* **slot -** the slot location on the deck ("A1" through "E3")
-	* **name -** custom name, used inside API when saving calibration data
+	* **name -** (optional) custom name, used inside API when saving calibration data
 
-The example below declares 3 different containers and assigns them to the appropriate slots on the deck.
+The robot will save calibrated container coordinates from old runs based on the ``container`` and ``slot`` combination. Therefore, if you repeatedly place the same container type in the same slot, the robot will assume your old calibrated coordinates for that container.
 
-.. testcode:: main
-	
-	tiprack = containers.load(
-  		'tiprack-200ul',  
-   		'A1',             
-		'tiprack'         
-	)
+However, if you include the optional third argument ``name``, the robot will assume coordinates based off the ``name`` and ``slot`` combination. This allows a container to differentiate it's saved coordinates from previous protocols.
 
-	plate = containers.load(
-		'96-PCR-flat',
-		'B2',
-		'plate'
-	)
-
-	trash = containers.load(
-		'point',
-		'C3',
-		'trash'
-	)
+The example below declares 3 different containers and assigns them to the appropriate slots on the deck. The trash uses a custom name, so that it doesn not inherit the coordinates of previous "point" containers at slot "C3".
 
-
-The robot will save calibration data from old runs based on the container type, slot position and given name.  Thus, if you always give something the same arguments, it will populate the app with old calibration data.  If you do not want it to do this, simply change the given name to unique names.
+.. testcode:: main
+	
+	tiprack = containers.load('tiprack-200ul', 'A1')
+	plate = containers.load('96-PCR-flat', 'B2')
+	trash = containers.load('point', 'C3', 'my-weird-trash-container')
 
 
 Pipettes
@@ -126,39 +109,45 @@ Pipettes
 .. code-block:: python
 	
 	mypipette = instruments.Pipette(
-		name="mypipette",
-		axis="b",	
+		axis="b",
 		max_volume=200,
-		min_volume=20,		
-		trash_container=trash,		
-		tip_racks=[tiprack],									
-		channels=1					
+		min_volume=20,
+		tip_racks=[tiprack],
+		trash_container=trash,
+		channels=1,
+		name="mypipette"
 	)
 
 **instruments.Pipette** (*name, trash_container, tip_racks, min_volume, max_volume, axis, channels*)
 
-	* **name -** name you give pipette
 	* **axis -** axis the pipette is on (a or b)
 	* **max_volume -** maximum volume of pipette
-	* **min_volume -** minimum volume of pipette
-	* **trash_container -** given name of container where you want to deposit tips
-	* **tip_racks -** array (list) of container(s) where you want to pick up tips
-	* **channels -** number of channels (1 or 8)
+	* **min_volume -** (optional) minimum volume of pipette
+	* **tip_racks -** (optional) array (list) of container(s) where you want to pick up tips
+	* **trash_container -** (optional) given name of container where you want to deposit tips
+	* **channels -** (optional) number of channels (1 or 8)
+	* **name -** (optional) name you give pipette
 
-This example loads a single channel, 20-200 uL pipette on the ``b`` axis that pulls tips from tiprack and deposits them in trash
-
-.. testcode:: main
+To use the tip-tracking features, create your pipette with tip racks and a trash container like the following example:
 
-	pipette = instruments.Pipette(
-		name="p200",
-		trash_container=trash,
-		tip_racks=[tiprack],
-		min_volume=20,
+.. code-block:: python
+	
+	mypipette = instruments.Pipette(
+		axis="b",	
 		max_volume=200,
-		axis="b",
-		channels=1
+		tip_racks=[tiprack],
+		trash_container=trash	
 	)
 
+	mypipette.pick_up_tip()     # picks up tip at A1
+	mypipette.drop_tip()   		# drops tip in the trash container
+	mypipette.pick_up_tip()     # picks up tip at B1
+	mypipette.return_tip()      # drops tip back at B1
+
+.. testcode:: main
+
+	
+
 Commands 
 -----------------------------
 
@@ -172,33 +161,48 @@ Before you can start moving liquid around, you need to pick up a tip!  You can p
 
 **pipette.pick_up_tip** (*location*)
 
-	* **location -** container[position] location to pick up tip
+	* **location -** container[position] the tip's current position
 
 .. testcode:: main
 
 	p200.pick_up_tip(tiprack['A2'])
 
-However, if you just want to go through the tips in a tip rack in order, there is no need to call a location. The example below will pick up the first available tip, and the API will keep track of which tips have been used so far in the protocol.
-
-.. testcode:: main
-	
-	p200.pick_up_tip()
-
 In addition to picking up a tip, there is a command to drop tip.
 
 **pipette.drop_tip** (*location*)
 
-	* **location -** container[position] location to drop tip
+	* **location -** container[position] the position to drop the tip
 
 .. testcode:: main
 
 	p200.drop_tip(tiprack['A2'])
 
-While you can only pick up tips from tip racks, you can eject tips back into the tiprack, or send them to the trash.  While you can specify trash as a location, you can also use the default version of drop tip like the example below.
+The behavior or tip commands changes depending on whether you have attached tip racks and/or trash containers to your pipette. 
+This happens when a pipette is created through using it's ``tip_racks`` and ``trash`` properties.
 
-.. testcode:: main
+.. code-block:: python
 
-	p200.drop_tip()
+	p200 = instruments.Pipette(
+	    axis='a',
+	    max_volume=200,
+	    tip_racks=[tiprack],
+	    trash=trash)
+
+With a list of one or more tip racks, a pipette can automatically iterate through it's tips without passing any arguments, and automatically drop tips in the trash.
+
+.. code-block:: python
+
+	p200.pick_up_tip()  	# automatically goes to tiprack['A1']
+	p200.drop_tip()		# automatically goes to trash
+
+**pipette.return_tip** ()
+
+With one or more tip racks attached, a pipette can also return a tip to it's original position
+
+.. code-block:: python
+
+	p200.pick_up_tip()  	# automatically goes to tiprack['A1']
+	p200.return_tip()	# automatically goes back to tiprack['A1']
 
 
 Aspirate
@@ -212,13 +216,26 @@ Aspirate
 .. testcode:: main
 
 	p200.aspirate(200, plate['A1'])
+	p200.dispense()
 
 You can link multiple aspirates together in order to pick up liquid from multiple locations
 
 .. testcode:: main
 
 	p200.aspirate(50, plate['A1']).aspirate(100, plate['B1'])
 
+If no volume is passed, the pipette will automatically aspirate to it's ``max_volume``
+
+.. testcode:: main
+	
+	p200.aspirate(plate['A1'])		# 200ul
+
+In addition, if no location is passed, the pipette will aspirate from it's current position
+
+.. testcode:: main
+	
+	p200.aspirate()				# 200ul from this position
+
 
 Dispense
 ^^^^^^^^
@@ -238,7 +255,6 @@ If you want to deposit all of the liquid you just aspirated, there is no need to
 
 .. testcode:: main
 
-	p200.aspirate(200, plate['A1'])
 	p200.dispense(plate['B1'])
 
 
@@ -257,11 +273,17 @@ While you can call multiple aspirate and dispense commands to the same location,
 
 	p200.mix(3, 100, plate['A1'])
 
+Call ``mix()`` without a location, and the pipette will mix at the previously referenced well
+
+.. testcode:: main
+
+	p200.dispense(plate['B2']).mix(3, 100)
+
 
 Chaining Commands
 ^^^^^^^^^^^^^^^^^
 
-Now that you know the basic commands, you can start transferring liquids!  However, your code can get lengthy quickly is you write it like this.
+Now that you know the basic commands, you can start transferring liquids!  However, your code can get lengthy quickly if you write it like this.
 
 .. testcode:: main
 
@@ -277,12 +299,7 @@ Instead of giving each command it's own line, you can chain them together using
 .. testcode:: main
 
 	p200.pick_up_tip().aspirate(200, plate['A1']).dispense(plate['B1'])
-
-
-Command Attributes
------------------------------
-
-In addition to commands, you can attach attributes to your movements.  
+ 
 
 Touch Tip
 ^^^^^^^^^
@@ -311,7 +328,7 @@ You can blow out liquid immediately after a dispense command in the same locatio
 
 .. note:: 
 
-	If the trash container is given a "point" labware name, instead of another container (like "trough-12row"), there is no need to call a position within the container.
+	Since the trash container is given a "point" labware name, it has no wells inside it. Therefore there is no need to call a position within the container.
 
 Delay
 ^^^^^
@@ -324,26 +341,29 @@ Delay commands can be called between any movement commands, so you have complete
 
 .. testcode:: main
 
-	p200.delay(10).aspirate(100, plate['A1'])
+	p200.aspirate(120, plate['A1']).delay(1).dispense(10)
+	p200.dispense(plate['B2']).delay(60)
+	p200.aspirate(100, plate['B2'])
 
-Dispensing Positions
-^^^^^^^^^^^^^^^^^^^^
+Position Within a Well
+^^^^^^^^^^^^^^^^^^^^^^
 
-Want to deposit at the top of a tube?  Pull liquid from the bottom of the well?  Mix from the middle?  Easy.
+Want to deposit at the top of a tube?  Pull liquid from the bottom of the well?  It's easy with a Well's ``top()`` and ``bottom()`` methods.
 
 **container.top** (*distance*)
 
-**container.bottom** (*distance*)
+	* **distance -** (optional) distance above/below top of Well (mm)
 
-	* **distance -** distance from calibration position (mm)
+**container.bottom** (*distance*)
 
-Containers are calibrated to the bottom of the well, and each labware definition has an inherent depth, which provides the calculated top position.  You can specify each of these locations anytime you use a container[position], as well as adjust them up (+) or down (-) by adding a distance.
+	* **distance -** (optional) distance above bottom of Well (mm)
 
 .. testcode:: main
 
-	p200.dispense(plate['A1'].top())         # at the top of well
-	p200.mix(3, 100, plate['B2'].bottom(5))  # 5mm above bottom of well
-	p200.dispense(plate['A1'].top(-3))       # 3mm below top of well
+	well = plate['A1']
+	p200.dispense(well.top())         # at the top of well
+	p200.mix(3, 100, well.bottom(5))  # 5mm above bottom of well
+	p200.aspirate(well.top(-3))       # 3mm below top of well
 
 Homing
 ------
@@ -355,7 +375,7 @@ You can instruct the robot to home at any point in the protocol, or just home on
 	* **axes -** the axes you want to home
 	* **enqueue -** True or False
 
-When the python file is loaded into the protocol, it runs through all of the commands.  When enqueue=False (default), this will cause the robot to home immediately upon loading the protocol, whereas if enqueue=True, it will run when it is called in the protocol.
+Normally, home commands are run immediately when called, and therefore should not be included in a protocol. However, if you need to home during a protocol run, include the argument ``enqueue=True``.
 
 .. testcode:: main
 
@@ -364,6 +384,25 @@ When the python file is loaded into the protocol, it runs through all of the com
   robot.home('ab', enqueue=True)   # adds "home ab" command to protocol queue
   robot.home('xyz', enqueue=True)  # adds "home xyz" command to protocol queue
 
+Head Speed
+----------
+
+The speed of the robot's X and Y movements can be sped up or slowed down.
+
+**robot.head_speed** (*rate*)
+
+	* **rate -** the speed at which the X and Y axis will move (millimeters per minute)
+
+This method will immediately set the speed of the robot, and all following movements will use that speed.
+
+.. note::
+	Speeds too fast (around 6000 and higher) will cause the robot to skip step, be careful when using this method
+
+.. testcode:: main
+
+  robot.head_speed(4500)
+  p200.pick_up_tip()
+
 Move To
 -------