Skip to content

Commit 13e0b56

Browse files
ecormanyecormany
committed
refactor Software chapter
1 parent a735d2c commit 13e0b56

14 files changed

+925
-872
lines changed

‎docs/flex-manual/docs/advanced-operation.md

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
title: "Opentrons Flex: Advanced Operation"
3+
---
4+
5+
# Advanced Operation
6+
7+
Flex provides methods of advanced control that let you directly manipulate files on the robot and execute commands outside of protocols.
8+
9+
## Command line operation over SSH
10+
11+
You can work with your Flex through a Secure Shell (SSH) terminal connection. Terminal access lets you [run protocols directly from the command line](https://docs.opentrons.com/v2/new_advanced_running.html#command-line) or perform advanced tasks, such as customizing the Python environment on the robot. Protocols that reference external files on disk (apart from custom labware definition files) must be run from the command line.
12+
13+
!!!note
14+
- SSH keys are required before you can connect to Flex and issue commands from a terminal.
15+
- If you're unable to use a Wi-Fi network for SSH, see [Hardwired SSH Connections][hardwired-ssh-connections] below.
16+
17+
### Creating SSH keys
18+
19+
Follow these steps to create SSH keys on your Mac, Windows, or Linux computer:
20+
21+
1. Open a terminal window and type this command:
22+
23+
```
24+
ssh-keygen -f robot_key -t ecdsa
25+
```
26+
27+
1. Create a passphrase when prompted. This process generates a file, `robot_key.pub`. A passphrase is not required, but you should create one.
28+
29+
1. Copy the `robot_key.pub` file to the root of a USB-A flash drive. You will use this USB drive (and the saved key) for SSH authentication to the robot.
30+
31+
!!!note
32+
The flash drive must have a single partition formatted with a file system readable by the embedded Linux system on Flex. FAT32, NTFS, and ext4 file systems are supported. The macOS HFS+ and APFS file systems are not. macOS can read and write to FAT-formatted drives.
33+
34+
1. Eject the USB drive.
35+
36+
### Making an SSH connection
37+
38+
To make an SSH connection:
39+
40+
1. Insert the USB drive that holds the SSH key created earlier into a USB port on your Flex.
41+
42+
1. On your computer, open a terminal window and type the commands shown below. Replace `ROBOT_IP` with the IP address of your Flex.
43+
44+
```
45+
curl \
46+
--location --request POST \
47+
'http://ROBOT_IP:31950/server/ssh_keys/from_local'
48+
```
49+
The command is successful when you see a response message that indicates a new key was added.
50+
51+
1. After adding the key, type the command shown below. Replace `ROBOT_IP` with the IP address of your Flex.
52+
53+
```
54+
ssh -i robot_key root@ROBOT_IP
55+
```
56+
57+
1. Type the passphrase you set when creating the SSH key.
58+
59+
When an SSH connection is successful, the terminal command prompt changes to `root@` followed by the serial number of your robot (e.g., `root@FLXA1020231007001:~#`). You can now interact with the robot via the terminal window.
60+
61+
### Hardwired SSH connections
62+
63+
A hardwired connection uses an Ethernet cable to connect and transmit data directly between your computer and Flex. This is a secure alternative for SSH access in situations where network policies prevent you from making a wireless connection to the robot.
64+
65+
!!!note
66+
The hardwired SSH procedure requires assigning a static IP address to the robot. You may want to ask for help from your IT support team before proceeding.
67+
68+
#### Physical connection
69+
70+
Connect a computer to the robot using an Ethernet cable. If your computer has a built-in RJ-45 Ethernet port, plug one end into the computer and connect the other end to the Ethernet port on the robot. If you're using a computer without an Ethernet port, use an adapter with an Ethernet port to make this connection.
71+
72+
When disconnected from a network, your Flex will assign itself an IP address and subnet mask. You'll need this information to set a static address on your computer within the same IP address range and subnet as your Flex.
73+
74+
#### Finding the robot's IP address
75+
76+
You can get the IP address range and subnet mask from the robot by connecting it to your computer and checking the Opentrons App:
77+
78+
1. If the robot is connected by Ethernet cable to a switch or wall jack, disconnect it. Then establish a physical Ethernet connection to your computer, as described above.
79+
80+
1. Launch the Opentrons App.
81+
82+
1. Click the **Devices** tab and find your robot.
83+
84+
!!!note
85+
If your robot appears as inactive or inaccessible in the app, wait a few moments. Flex will configure itself and eventually become available again. If this does not happen, turn the robot's power off, wait a few seconds, turn the power back on, and check the app again after the robot boots up.
86+
87+
1. After locating your robot in the app, click the three-dot menu (⋮), select **Robot settings**, and then click the **Networking** tab.
88+
89+
The Networking tab will show you the IP address and subnet mask of your robot. When disconnected from a network, Flex will assign itself a non-routing IP address. Here's an example of a self-assigned IP address on a Flex:
90+
91+
- IP address: 169.254.29.160
92+
- Subnet mask: 255.255.0.0
93+
94+
#### Setting a static IP address
95+
96+
The static IP address on your computer needs to be in the same IP range and subnet that your Flex uses. Given the robot's IP address above, you could set your computer's IP address and subnet as shown here:
97+
98+
- IP address: 169.254.29.164
99+
- Subnet mask: 255.255.0.0
100+
101+
After you have a working hardwired connection, follow the instructions in [Making an SSH Connection](software-operation.md#making-an-ssh-connection) above.
102+
103+
## Jupyter Notebook
104+
105+
Flex runs a [Jupyter Notebook](https://jupyter.org/) server on port 48888, which you can connect to with your web browser. Use Jupyter to individually run discrete chunks of Python code, called *cells*. This is a convenient environment for writing and debugging protocols, since you can define different parts of your protocol in different notebook cells, and run a single cell at a time.
106+
107+
Access your robot's Jupyter Notebook either:
108+
109+
- In the Opentrons App. Go to **Devices** > your robot > **Robot Settings** > **Advanced** and then click **Launch Jupyter Notebook**.
110+
111+
- In your web browser. Navigate directly to `http://<robot-ip>:48888`, replacing `<robot-ip>` with the local IP address of your Flex.
112+
113+
For more details on using Jupyter, including preparing executable cells
114+
of code and running them on a robot, see the [Jupyter Notebook section](https://docs.opentrons.com/v2/new_advanced_running.html#jupyter-notebook) of the Python Protocol API documentation.
115+

‎docs/flex-manual/docs/opentrons-app.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
title: "Opentrons Flex: App"
3+
---
4+
5+
# Opentrons App
6+
7+
You can perform most functions of Flex either from the [touchscreen](../touchscreen/) or from a computer running the Opentrons App. This section covers using the app for features that are not available on the touchscreen.
8+
9+
## App installation
10+
11+
Download the Opentrons App at <https://opentrons.com/ot-app/>. The app requires Windows 10, macOS 10.10, or Ubuntu 12.04 or later. The app may run on other Linux distributions, but Opentrons does not officially support them.
12+
13+
### Windows
14+
15+
The Windows version of the Opentrons App is packaged as an installer. To use it:
16+
17+
- Open the .exe file you downloaded from opentrons.com.
18+
19+
- Follow the instructions in the installer. You can install the app for a single user or all users of the computer.
20+
21+
The app opens automatically once installed. Grant the app security or firewall permissions, if prompted, to make sure it can launch and communicate with Flex over your network.
22+
23+
### macOS
24+
25+
The macOS version of the Opentrons App is packaged as a disk image. To use it:
26+
27+
1. Open the .dmg file you downloaded from opentrons.com. A window for the disk image will open in Finder.
28+
29+
2. Drag the Opentrons icon onto the Applications icon in the window.
30+
31+
3. Double-click on the Applications icon.
32+
33+
4. Double-click on the Opentrons icon in the Applications folder.
34+
35+
Grant the app security or firewall permissions, if prompted, to make sure it can launch and communicate with Flex over your network.
36+
37+
### Ubuntu
38+
39+
The Ubuntu version of the Opentrons App is packaged as an AppImage. To use it:
40+
41+
1. Move the .AppImage file you downloaded from opentrons.com to your Desktop or Applications folder.
42+
43+
2. Right-click the .AppImage file and choose **Properties**.
44+
45+
3. Click the **Permissions** tab. Then check **Allow executing file as a program**. Close the Properties window.
46+
47+
4. Double-click the .AppImage file.
48+
49+
!!! note
50+
Do not use third-party AppImage launchers with the Opentrons App. They may interfere with app updates. Opentrons does not support using third-party launchers to control Opentrons robots.
51+
52+
## Transferring protocols to Flex
53+
54+
Every protocol will begin as a file on your computer, regardless of what method of [protocol development](../protocols/) you use. You need to import the protocol into the Opentrons App and then transfer it to your Flex. When transferring a protocol, you can choose to begin run setup immediately or later.
55+
56+
### Import a protocol
57+
58+
When you first launch the Opentrons App, you will see the Protocols screen. (Click **Protocols** in the left sidebar to access it at any other time.) Click **Import** in the top right corner to reveal the Import a Protocol pane. Then click **Choose File** and find your protocol in the system file picker, or drag and drop your protocol file into the well.
59+
60+
The Opentrons App will analyze your protocol as soon as you import it. *Protocol analysis* is the process of taking the JSON object or Python code contained in the protocol file and turning it into a series of commands that the robot can execute in order. If there are any errors in your protocol file, or if you're missing custom labware definitions, a warning banner will appear on the protocol's card. Correct the errors and re-import the protocol. If there are no errors, your protocol is ready to transfer to Flex.
61+
62+
<figure class="screenshot" markdown>
63+
![Expanded three-dot menu for a protocol, showing these options: Start setup, Reanalyze, Send to Opentrons Flex, Show in folder, and Delete](images/app-protocol-menu.png "Screenshot")
64+
<figcaption>Actions available in the three-dot menu (⋮) for imported protocols.</figcaption>
65+
</figure>
66+
67+
!!! note
68+
In-app protocol analysis is only a preliminary check of the validity of your protocol. Protocol analysis will run again on the robot once you transfer the protocol to it. It's possible for analysis to fail in the app and succeed on the robot, or vice versa. Analysis mismatches may occur when your app and robot software versions are out of sync, or if you have customized the Python environment on your Flex.
69+
70+
### Run immediately
71+
72+
Click the three-dot menu (⋮) on your protocol and choose **Start setup**. Choose a connected and available Flex from the list to transfer the protocol and begin run setup immediately. The run setup screen will appear both in the app and on the touchscreen, and you can continue from either place.
73+
74+
If you stay in the app, expand the sections under the Setup tab and follow the instructions in each one: Robot Calibration, Module Setup (if your protocol uses modules), Labware Position Check (recommended), and Labware Setup. Then click :material-play-circle: **Start run** to to begin the protocol.
75+
76+
If you move to the touchscreen, follow the steps in the [Run Setup section][run-setup] above.
77+
78+
### Run later
79+
80+
Click the three-dot menu (⋮) on your protocol and choose **Send to Opentrons Flex**. Choose a connected and available Flex from the list to transfer the protocol. A message indicating a successful transfer will pop up both in the app and on the touchscreen. To set up your protocol, you need to move to the touchscreen and follow the steps in the [Run Setup section][run-setup] above.
81+
82+
## Module status and controls
83+
84+
Use the Opentrons App to view the status of modules connected to your Flex and control them outside of protocols. Click **Devices** and then click on your Flex to view its robot details page. Under Instruments and Modules, there is a card for each attached module. The card shows the type of module, what USB port it is connected to, and its current status.
85+
86+
<figure markdown>
87+
![Card showing the status of a Heater-Shaker module, including a banner showing that it is currently hot.](images/app-module-status.png "Heater-Shaker status card")
88+
<figcaption>Module card for the Heater-Shaker Module.</figcaption>
89+
</figure>
90+
91+
!!! note
92+
The Magnetic Block does not have a card in Instruments and Modules, since it is unpowered and does not connect to Flex via USB.
93+
94+
Click the three-dot menu (⋮) on the module card to choose from available commands. You can always choose **About module** to see the firmware version and serial number of the module. (This information is very useful when contacting Opentrons Support!) The other commands depend on the type of the module and its current status:
95+
96+
| Module type | Commands |
97+
| -------------- | -------- |
98+
| **Heater-Shaker** | <ul><li>Set module temperature / Deactivate heater</li><li>Open labware latch / Close labware latch</li><li>Test shake / Deactivate shaker</li></ul> |
99+
| **Temperature** | <ul><li>Set module temperature / Deactivate module</li></ul> |
100+
| **Thermocycler** | <ul><li>Set lid temperature / Deactivate lid</li><li>Open lid / Close lid</li><li>Set block temperature / Deactivate block</li></ul> |
101+
102+
## Recent protocol runs
103+
104+
The robot details page lists up to 20 recent protocol runs. This provides additional information compared to the touchscreen, which only shows the most recent run for each unique protocol.
105+
106+
Each entry in the recent protocol runs list includes the protocol name, its timestamp, whether the run was canceled or completed, and the duration of the run. Click the disclosure triangle next to any run to show its associated labware offset data. Click the three-dot menu (⋮) for related actions:
107+
108+
- **View protocol run record:** Show the protocol run screen as it appeared when the protocol ended (succeeded, failed, or was canceled), including all performed steps.
109+
110+
- **Rerun protocol now:** The same as choosing **Start setup** on the corresponding protocol.
111+
112+
- **Download run log:** Save to your computer a JSON file containing information about the protocol run, including all performed steps.
113+
114+
- **Delete protocol run record:** Delete all information about this protocol run from Flex, including labware offset data. When you choose this option, it's as though the protocol run never happened.
115+
116+
!!! note
117+
If you need to maintain a comprehensive record of all runs performed on your Flex, you must use the **Download run log** feature to save this information to your computer.
118+
119+
Flex *will not* retain information about more than 20 runs on the robot. Proceeding to the Run Setup screen generates an entry in the list and counts towards the maximum of 20 runs, even if you never begin the protocol.

0 commit comments

Comments
 (0)