Skip to content

Commit 0fa6ffe

Browse files
ecormanyecormany
committed
starting Protocols refactor; pausing to integrate new text
1 parent 887e5b1 commit 0fa6ffe

File tree

5 files changed

+360
-1
lines changed

5 files changed

+360
-1
lines changed

‎docs/flex-manual/docs/protocols/designer.md

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
## Protocol Designer
2+
3+
Protocol Designer is a web-based, no-code tool for developing protocols that run on Opentrons robots, including Opentrons Flex. You can use Protocol Designer to create protocols that:
4+
5+
- Aspirate, dispense, transfer, and mix liquids.
6+
7+
- Move labware around the deck with the gripper.
8+
9+
- Operate Opentrons Flex modules.
10+
11+
- Pause to let you verify progress or access samples.
12+
13+
All work on your protocol takes place within your web browser. When
14+
you're done creating or editing your protocol, you need to export it to
15+
a JSON file. Then upload that file to a robot and run it, as you would
16+
with any protocol.
17+
18+
### Protocol Designer requirements
19+
20+
Currently, Protocol Designer is only supported for use in Google Chrome
21+
and requires an internet connection. Uploading and running JSON
22+
protocols on Opentrons Flex requires version 7.0.0 or later of the
23+
Opentrons App.
24+
25+
You can't create or modify Python protocol files with Protocol Designer.
26+
27+
### Designing a protocol
28+
29+
Protocols are all about informing the robot what hardware it will use to
30+
take specific actions. This process is broken down into three tabs in
31+
Protocol Designer:
32+
33+
**Icon Tab**
34+
35+
The **File tab** is where you manage protocol files and specify hardware
36+
for use in your protocol.
37+
38+
The **Liquids tab** lets you define samples, reagents, and any other
39+
liquids that your robot will handle.
40+
41+
The **Design tab** is where you specify the initial state of the deck,
42+
add steps that the robot will perform, and view the projected outcomes
43+
of those steps.
44+
45+
To create a protocol from scratch, you'll start on the File tab, work
46+
with the Liquids and Design tabs, and then return to the File tab to
47+
export your work. The remainder of this section goes through the
48+
protocol creation process in detail.
49+
50+
#### Part 1: Create a protocol
51+
52+
When you launch Protocol Designer, you'll begin on the **File** tab. In
53+
the left sidebar, click **Create New** to open the Create New Protocol
54+
dialog. Click on the image of Opentrons Flex and then click **Next**.
55+
56+
Choosing to create a protocol for Opentrons Flex in Protocol Designer.
57+
58+
Enter a name for your protocol, which is how it will appear in the
59+
Opentrons App and on the touchscreen. You'll also see your protocol name
60+
in the Protocol Designer header while you're working on it. Optionally
61+
add a description and author information for your protocol.
62+
63+
Next, Protocol Designer guides you through choosing the hardware used in
64+
your protocol:
65+
66+
1. Pipettes and what type of tip racks you'll use with them. Every
67+
protocol requires at least one pipette.
68+
69+
2. Staging area slots in column 3 (optional).
70+
71+
3. Additional hardware used in your protocol, such as modules, the
72+
gripper, or the waste chute. Only are shown.
73+
74+
!!! note
75+
You can't currently use multiple Heater-Shaker Modules or Magnetic Blocks in a JSON protocol. If your application requires them, you'll need to use a Python protocol. See the below.
76+
77+
At any time, you can return to the File tab to rename your protocol, add
78+
an author name or description, or change your hardware configuration.
79+
80+
#### Part 2: Define liquids
81+
82+
Move on to the **Liquids** tab to set up samples and reagents. This tab
83+
is only for *defining* types of liquids. You'll indicate the starting
84+
positions and amounts of liquids in Part 3, on the Design tab.
85+
86+
Click **New Liquid** and then enter the name of your liquid and an
87+
optional description. You can also choose whether to *serialize* the
88+
liquid, so each well containing that liquid will be numbered on the deck
89+
map and in action steps. For example, if your protocol has blood
90+
samples, serialization can help you keep them separate in your workflow,
91+
while still labeling them all as "blood" and color-coding them the same.
92+
93+
Each type of liquid appears in a different color on the deck map in
94+
Protocol Designer, in the Opentrons App, and on the touchscreen. You can
95+
use the default color, pick another preset color, or enter an RGB hex
96+
code to set a custom color.
97+
98+
#### Part 3: Lay out the deck
99+
100+
Go to the Design tab to do the final setup step, which is placing
101+
labware and liquids on the deck. The main view on this tab is the deck
102+
map, which shows everything on the deck down to individual wells ---
103+
even on 384-well plates.
104+
105+
The deck map starts with the tip racks and modules you chose for your
106+
protocol in their default locations. Hover over any open slot and click
107+
**Add Labware or Adapter** to add more tip racks, other types of
108+
labware, or adapters. Drag and drop labware to an open slot to move it
109+
there, or to an occupied slot to swap the two pieces of labware.
110+
111+
!!! note
112+
You can'tmove modules or adapters around the deck map by drag and drop. This is to make it easier to move *labware* onto or off of a module.
113+
114+
- To change a module's position, return to the **File** tab and click
115+
**Edit** next to the module name.
116+
117+
- To change an adapter's position, add a new adapter. Then move the
118+
labware from the old adapter to the new adapter. Finally, delete the
119+
old adapter.
120+
121+
Hover over any labware and click **Add Liquids** to specify which wells
122+
contain which liquid. Clicking on a single well or dragging across a
123+
range of wells will reveal a form at the top of the screen. Choose one
124+
of the liquids you defined and the volume *each* well should start with,
125+
in μL. For example, if you select the first column on a 96-well plate
126+
and specify 100 μL, that will be 800 μL of liquid total (100 μL × 8
127+
wells).
128+
129+
#### Part 4: Add steps
130+
131+
At last, it's time to tell your robot how to move liquid around the
132+
deck. Click **Add Step** and choose the type of step.
133+
134+
- Pipetting steps
135+
136+
- **Transfer:** Move liquid from one well or group of wells to
137+
another. Specify the source, where liquid will be aspirated from, on
138+
the left. Specify the destination, where liquid will be dispensed,
139+
on the right. Click either gear icon to change behaviors such as
140+
flow rate, tip height, knocking droplets off (touch tip), air
141+
gapping, blowout, and more. In the Sterility & Motion section,
142+
choose the correct tip-use strategy for your application.
143+
144+
- **Mix:** Repeatedly aspirate and dispense liquid within the same
145+
well. Choose how much liquid to mix with, the number of mixing
146+
repetitions, and which wells will be mixed. Like with transfer
147+
steps, click either gear to change mixing behavior. You can also
148+
choose a tip-use strategy for mixing. These options are more limited
149+
than for transfers, since all liquid returns to its starting
150+
location when mixing.
151+
152+
- Gripper steps
153+
154+
- **Move Labware:** Control the Flex Gripper or move labware around
155+
the deck manually. Choose which labware you want to move and its new
156+
location. Check the **Use Gripper** box to have the gripper move the
157+
labware automatically, or leave it unchecked to have the protocol
158+
pause so you can move the labware manually. You need to use the
159+
gripper to dispose labware by moving it into the waste chute. You
160+
need to move labware manually to move it off the deck (without
161+
disposing it).
162+
163+
- Module steps
164+
165+
- **Heater-Shaker:** Control the temperature, shake speed, and labware
166+
latch of the Heater-Shaker Module. You can set an optional timer
167+
that will pause the protocol for a set period of time *after* the
168+
other actions are completed (heating to high temperatures or waiting
169+
for the module to passively cool to a temperature can take a long
170+
time).
171+
172+
- **Temperature:** Set a target temperature or deactivate the
173+
Temperature Module.
174+
175+
- **Thermocycler:** This action has two mutually exclusive sets of
176+
options.
177+
178+
- Change Thermocycler state: Set a block temperature, set a lid
179+
temperature, or move the lid.
180+
181+
- Program a Thermocycler profile: Define a *profile*, a timed
182+
heating and cooling routine that can be automatically repeated.
183+
Each step of the profile holds the block at a certain temperature
184+
for a certain time. Profiles do not change the temperature of the
185+
lid.
186+
187+
- **Pause:** Prevent the protocol from continuing until one of three
188+
criteria is met. Pauses can require user intervention (pressing a
189+
button on the touchscreen or in the app), wait for a fixed time, or
190+
wait until a module reaches a target temperature. Timed pauses are
191+
useful for incubation or letting the Magnetic Block work.
192+
193+
#### Part 5: Edit steps
194+
195+
Once you've created a step, preview its effects by hovering over it in
196+
the Protocol Timeline. Affected tips and wells will be highlighted, as
197+
will the entire labware containing those wells.
198+
199+
Show or hide the details of a step by clicking the disclosure triangle
200+
to the right of its name. For liquid handling steps, this will show
201+
every discrete aspirate and dispense pair comprising the step. For
202+
module steps, this will show the features of the module that the step
203+
controls.
204+
205+
Click on the name of a step in the Protocol Timeline to edit it.
206+
Shift-click to select a range of steps and enter batch editing mode. If
207+
you select only transfer or mix steps, you can change their behavior as
208+
a batch. Reorder steps by dragging and dropping them up or down in the
209+
Protocol Timeline.
210+
211+
When editing any step, click **Notes** to change the step name or add a
212+
description of what the step does. Custom step names replace their
213+
default action descriptions (like "Transfer" and "Temperature") in the
214+
Protocol Timeline, making it easier to navigate around your protocol.
215+
216+
#### Part 6: Export your protocol
217+
218+
When your protocol is complete, click **Final Deck State** to preview
219+
how the deck should appear at the end of your protocol. In this view (or
220+
when viewing a particular step), you can click on labware and examine
221+
the expected quantity of liquid in each well.
222+
223+
To save your work, return to the File tab and click **Export** to
224+
download your protocol as a JSON file. The file will have the name you
225+
chose in the Protocol Name field and will have a .json extension. You
226+
can find exported protocols in the default download location of your web
227+
browser.
228+
229+
To run your protocol, import it into the Opentrons App. (See the for
230+
details on installing and using the Opentrons App.) Then either run it
231+
from the app or send it to your Flex to run from the touchscreen.
232+
233+
### Modifying existing protocols
234+
235+
Click **Import** in the File tab to load an existing protocol. Choose
236+
any JSON protocol file from the standard system file picker. Once
237+
loaded, you can edit any aspect of the protocol, including its name,
238+
description, hardware configuration, and steps.
239+
240+
!!! warning
241+
Importing a protocol will replace any other protocol that you've been working on in Protocol Designer. Be sure to export your work before importing another file, or open Protocol Designer in a second browser tab to work on multiple files at once.

‎docs/flex-manual/docs/protocols/development-service.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: "Opentrons Flex: Custom Protocol Service"
3+
---
4+
5+
# Custom Protocol Development service
6+
7+
Opentrons provides a [Remote Custom Protocol Development service](https://opentrons.com/instrument-services) for applications not already included in the Protocol Library. Our comprehensive authoring and validation service has a turnaround time of two weeks. As part of the service, Opentrons field applications scientists will:
8+
9+
- Develop the Python protocol.
10+
11+
- Validate the code.
12+
13+
- Install the protocol remotely.
14+
15+
- Create deck and reagent setup instructions.
16+
17+
- Optimize your protocol as much as needed within one week of initial delivery.
18+
19+
By default, Opentrons adds all custom protocols to the Protocol Library so the community can benefit from them. However, if your application requires privacy, you can opt out of inclusion in the Protocol Library.
20+
21+
!!! note
22+
The Custom Protocol Development service only writes Python protocols that control Opentrons hardware. It does not cover controlling the robot with code in other languages, nor does it cover controlling third-party hardware.
23+
24+
## Protocol request guidelines
25+
26+
Describing your protocol in detail enables Opentrons field applications scientists to accurately code the automation that you need. Consider your protocol's requirements, including:
27+
28+
- Hardware (pipettes, gripper, modules, fixtures).
29+
30+
- Labware (Opentrons verified, other standard, or custom).
31+
32+
Also consider special cases that apply to your protocol, like:
33+
34+
- Liquids that are volatile, viscous, or otherwise behave differently than water.
35+
36+
- Conservation of expensive reagents.
37+
38+
- Sterility and cross-contamination.
39+
40+
- Advanced pipetting techniques like air-gapping, high or low flow rate, or pipetting at specific locations within wells.
41+
42+
To explain the movements the robot will make in executing the protocol, start with your initial deck state. Where should modules, labware, and trash containers be located? Which liquids will be in which labware, and in what quantities? Use the coordinate systems printed on the Opentrons Flex deck and on standard labware to describe these locations.
43+
44+
Next, give step-by-step instructions on how Opentrons Flex should handle liquids, specifying quantities in microliters (µL) and giving exact source and destination locations (rows, columns, or individual wells of labware).
45+
46+
In general, following the style of the methods section of an academic paper will help the Opentrons team understand your instructions. And always err on the side of providing extra information—it may be exactly the detail we need to write code for your protocol.
47+
48+
## Custom protocol pricing
49+
50+
Custom Protocol Development is a service available to all owners of Opentrons Flex systems. Opentrons provides remote and onsite protocol development services customized to your specific workflow. Price and development time are based on the complexity of your protocol and the related code. See the [Instrument Services section](https://opentrons.com/instrument-services) of the Opentrons website to contact us for more information about our Custom Protocol Development offerings.
51+

‎docs/flex-manual/docs/protocols/index.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: "Opentrons Flex: Protocol Development"
3+
---
4+
5+
# Protocol Development
6+
7+
The Opentrons Flex system can run a wide variety of automated protocols, for tasks such as PCR, NGS, ELISA, and many more. There are several ways to get the protocol you need:
8+
9+
10+
- [Protocol Library](./library.md) provides fully built and verified protocols, as well as community-submitted protocols.
11+
- Our [Custom Protocol Development Service](./development-service) will work with you to build a protocol that suits your needs.
12+
- [Protocol Designer](./designer) lets you build protocols in your web browser without writing any code.
13+
- OpentronsAI will get you started with a Python protocol that you can run as-is or modify to suit your needs.
14+
- The [Python Protocol API](./python-api) offers a complete set of commands for controlling Flex, and can integrate with other Python tools.
15+
16+
This chapter provides an overview of each of these protocol development methods, as well as giving guidance on how to [adapt protocols written for the Opentrons OT-2](./ot-2) to run on Opentrons Flex.

‎docs/flex-manual/docs/protocols/library.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: "Opentrons Flex: Protocol Library"
3+
---
4+
5+
# Protocol Library
6+
7+
The Opentrons Protocol Library hosts protocols authored either by Opentrons itself or by members of the Opentrons community. To find a protocol that fits your target application, use the search field at the top of the [Protocol Library homepage](https://library.opentrons.com).
8+
9+
You can also browse protocols by categories, like DNA/RNA, cell biology, cell and tissue culture, proteins, commercial assay kits, or molecular biology. There's even a category for protocols that create art by pipetting! Take some time to check out the protocols in our library. Understanding what's available—and making some cool pixel art—is a great way to learn about the features and capabilities of your robot before moving on to using real samples and reagents.
10+
11+
## Searching for protocols
12+
13+
The Protocol Library search returns results as you type. You can select a result from the search list or click **View All Results** to go to the full results page, which shows more details about each protocol and lets you filter them based on several criteria.
14+
15+
Each protocol card will show:
16+
17+
| **Category** | **Description** |
18+
|--------------|-----------------|
19+
| **Protocol name** | The name of the protocol. |
20+
| **Verification** | Badges indicate if the protocol is verified by Opentrons, a third-party manufacturer, or members of the community. |
21+
| **Time estimate** | Approximately how long the protocol takes to run. |
22+
| **Description** | A short summary of what the protocol does. |
23+
| **Robot model** | Which Opentrons robots the protocol is compatible with. |
24+
| **Protocol editability** | JSON protocols are editable in Protocol Designer, with no coding required. Python protocols are editable in any text editor, using the Python Protocol API. |
25+
| **Modules** | Any hardware modules that are required. |
26+
27+
In addition to these categories, in the sidebar you can filter results by:
28+
29+
- **Pipettes:** Which pipettes the protocol uses (you can usually change a protocol's pipettes, but it may affect the run time and the number of tips consumed).
30+
31+
- **Categories:** Target applications, like DNA/RNA, cell biology, proteins, etc.
32+
33+
- **Protocol version:** Show or hide older versions of protocols.
34+
35+
## Protocol details
36+
37+
Click on a protocol to go to its detail page, which provides even more information. In addition to what is shown in search, here you can see:
38+
39+
- **Supporting data:** Additional data, explanations, or links to outside sources provided by the protocol author.
40+
41+
- **What you'll need:** A complete list of all equipment needed for the protocol, including the robot, modules, labware, pipettes, and third-party kits.
42+
43+
- **Protocol steps:** A list of steps written by the protocol author, as well as a visual deck map and list of liquids specified in the protocol file.
44+
45+
The details page also provides basic instructions for downloading and running the protocol. For more information on importing a protocol to the Opentrons App and setting up a run, see the [Transferring Protocols to Flex section][transferring-protocols-to-flex] in the Software and Operation chapter.

‎docs/flex-manual/mkdocs.yml

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,13 @@ nav:
3636
- Labware Types: labware/types.md
3737
- Using the Gripper: labware/gripper.md
3838
- Labware Definitions: labware/definitions.md
39-
- Protocol Development: protocol-development.md
39+
- Protocol Development:
40+
- Protocols Home: protocols/index.md
41+
- Protocol Library: protocols/library.md
42+
- Custom Protocol Service: protocols/development-service.md
43+
- Protocol Designer: protocols/designer.md
44+
- Python API: protocols/python-api.md
45+
- Converting OT-2 Protocols: protocols/ot-2.md
4046
- Software and Operation: software-operation.md
4147
- Maintenance and Service: maintenance-service.md
4248
- Appendices:

0 commit comments

Comments
 (0)