Introduction

SSH is a way to connect to and control your OT-2 over the command line. It is required for some troubleshooting and advanced tasks.

This guide will walk you through setting up SSH for the first time. There are two parts to the process: installing SSH on your computer, and configuring your OT-2 to accept SSH connections from your computer.

You will create a special pair of files called an SSH key pair. The key pair comprises a private key, which remains on your computer, and a public key, which you will copy to your OT-2.

Setup will require a USB connection to your OT-2. After setup is complete, you will also be able to connect to your OT-2 with SSH over Wi-Fi. 

This guide applies to robot server versions 3.11.0 and later. 

Installing Prerequisites

You may need to install two small third-party tools:

  • OpenSSH, the SSH implementation that we recommend.
  • cURL, a tool to send simple network requests, which we need for setup.

On macOS

OpenSSH and cURL are both already installed by default on macOS. 

On Linux

OpenSSH and cURL might be installed by default, depending on your distribution. If they are not, use your distribution's package manager to install them (for instance, sudo apt install ssh curl ).

On Windows 10 

OpenSSH is provided by Microsoft as a separately installable Windows component. 

Open Settings. Go to Apps > Apps and Features > Manage Optional Features. Scan the list to see if OpenSSH Client is already there. If it is not, at the top of the page, select Add a feature, locate OpenSSH Client, and install it.

You do not need to install cURL on Windows; a different tool will replace it.

Opening the Command Line

Setup will take place over the command line. Don't worry if you've never used it before – we will walk you through it!

Open a new PowerShell window (Windows) or Terminal window (Linux and macOS).

Note on copy and paste: We recommend copying and pasting the commands you see in this guide instead of typing them out yourself. However, copying and pasting works a little differently in a terminal. The usual Ctrl+C and Ctrl+V keyboard shortcuts will do something else. Instead, to paste something on the command line:

  • On Linux and macOS, right-click inside the Terminal window and select Paste.
  • On Windows, right-click the title bar of the PowerShell window and select Edit > Paste.

Generating a Key Pair

1. Run ssh-keygen 

Having installed OpenSSH and opened a command line, you will have access to the ssh-keygen command. Paste into the window:

ssh-keygen -f ot2_ssh_key

And press Enter.

2. Enter a Passphrase

The program will ask you to choose a passphrase. You will use this passphrase later when you connect to your OT-2 over SSH. Providing a passphrase is optional, but we strongly recommend it. (Otherwise, anyone who has access to the file on your computer could also access your OT-2.)

When you type in the passphrase, your typing won't show up. Don't worry – it's just being hidden for security! Press Enter when you've finished, and then enter the passphrase again to confirm it.

Warning: If you lose this passphrase, you won't be able to recover it, and you'll have to start this guide all over to connect to your OT-2. We recommend storing your passphrase somewhere secure, like a password manager. 

3. Your New SSH Key Pair

After entering a passphrase, you should see something like this:

Two files will have been created in your home directory:

  • ot2_ssh_key, which will stay on your computer.
  • ot2_ssh_key.pub, which will be copied onto your OT-2.

Before continuing, make sure those files exist. Enter:

cat ot2_ssh_key.pub

That should show something like this: 

If you see something similar, congratulations! Your new SSH key is ready to install.

Installing The Key On Your OT-2 

Now that you have created an SSH key pair, you will install the public key to your OT-2. This will tell the OT-2 to accept connections from the matching private key, on your computer.

1. Connect Via USB

To show that you have physical access to the OT-2, you must connect to it via USB for this part. A Wi-Fi connection will not work. Plug in the USB cable, and confirm that your OT-2 is shown with a USB icon in the Opentrons App. You may need to refresh the list. 

2. Find Your OT-2's Wired IP Address

In the Opentrons App, find and take note of the part of your robot's Wired IP that comes before the slash (/).

In the example above, the part that we care about is 169.254.2.6.

3. Upload Your Public Key

Paste the following command, but don't press Enter yet – we will have to modify it slightly.

On Linux and macOS

curl \
-H 'Content-Type: application/json' \
-d "{\"key\":\"$(<ot2_ssh_key.pub)\"}" \
ROBOT_IP:31950/server/ssh_keys

On Windows 10

@{key = Get-Content ot2_ssh_key.pub | Out-String} | ConvertTo-Json | Invoke-WebRequest -Method Post -ContentType 'application/json' -Uri ROBOT_IP:31950/server/ssh_keys 

Use the arrow keys to move to the part of the command that says ROBOT_IP. Replace ROBOT_IP  with the actual Wired IP address you found above. Remember not to include the slash and trailing digits.

Your command line should look something like this, on Linux and macOS: 

Or like this, on Windows 10:

Press Enter to run the command. It should not take more than a second. If all goes well, you should see a response containing the phrase "Added key."

Connecting to Your OT-2 With SSH 

Congratulations! You've completed the first-time setup, and you're ready to finally connect.

Further Steps (Optional)

Enabling SSH Access to Multiple OT-2s

If you have additional OT-2s to connect to with SSH, you don't need to duplicate this entire process for each one. Instead, for each additional robot, just follow the steps under Installing The Key On Your OT-2.

Using the Same Key Pair for Multiple Computers

If you have additional computers with which you want to connect to your OT-2, you don't need to duplicate this entire process on each one.

By copying your SSH private key to those computers, you will share your access to the robot with them.

  1. In your home folder, locate the file ot2_ssh_key. Do not use the file ending in .pub! On Windows, file extensions may be hidden, making it difficult to distinguish between the two files. To enable them, follow: Display file extensions on Windows 7 and later.
  2. Send ot2_ssh_key to each additional computer, by email, USB drive, or any other method. Place it in your home folder on each additional computer.
  3. On each additional computer, follow just the steps under Installing Prerequisites, above.
Did this answer your question?