Guide - genspace/opentrons GitHub Wiki

Intro

Power cord goes “flat side” to the “front” of the robot. (This is now marked with tape and marker. Line up the arrows.) Rocker switch above the power cord receptacle. The robot should now log into the Genspace wifi. It knows the password.

From a Linux terminal (probably similar on a Mac.) Type these commands to see who is on the network. You’ll have to put in your password to run the command which starts with “sudo”.

sudo nmap -sP {ip}

or this fancier command, puts an extra blank line between records:

sudo nmap -sP {ip} | sed 's,Nmap,\n&,g'

This will list all devices on the network which are identifying themselves via avahi (also called zeroconf) (also called bonjour.)

avahi-browse -a

Grab the Opentrons application from https://opentrons.com/ot-app. For Linux, download the “.appimage” file and set it to executable with the following command. Substitute the filename, obvs!

chmod +x filename.appimage

Run the Opentrons application. In the Opentrons application, select the robot. Optionally calibrate.

Get Camera Image

Acquiring an image from the onboard camera: https://support.opentrons.com/en/articles/2831465-using-the-ot-2-s-camera

Running the Opentrons Jupyter Notebook

Find the raspberry pi on your network:

sudo nmap -sP {ip} | awk '/^Nmap/{ip=$NF}/B8:27:EB/{print ip}'

Let’s say you’ve found the address 192.168.0.130

… or, find all computers on the network and figure out which one is the Opentrons “manually”

sudo nmap -sP 192.168.1.0/24

Also, you can portscan whichever ip address you’ve found

sudo nmap -p- 192.168.1.130

The opentrons robot will have port 48888 open. Connect to it with a browser: https://192.168.1.130:48888

Make a new notebook and paste in the example from https://docs.opentrons.com/#opentrons-api.

Make sure to edit that, adding “import robot” and “robot.connect()”, as described in: https://support.opentrons.com/en/articles/1795367-running-the-robot-using-jupyter-notebook

Alter for what you’re actually putting inside the robot. For example, I looked up the Corning 24-well labware, in this reference here: https://labware.opentrons.com/

Building an Opentrons Labware

Try using this https://github.com/Opentrons/opentrons/tree/edge/labware-designer, by following the readme in this directory. (Hint: It requires you to clone the “opentrons” repo and following this to get a dev environment running. https://github.com/Opentrons/opentrons/blob/edge/CONTRIBUTING.md#development-setup)

Or do it manually: https://support.opentrons.com/en/articles/3136504-creating-custom-labware-definitions

labware.load() and labware.create() are discussed here https://docs.opentrons.com/labware.html

Building an Opentrons Module

To read: https://support.opentrons.com/en/articles/2715311-integrating-the-ot-2-with-other-lab-equipment

Follow the “LED_Control” example in https://github.com/tinkersprojects/G-Code-Arduino-Library, on an Arduino with USB → Serial interface. Example (Adafruit Metro Mini)

Emulate a MagDeck in some way. The MagDeck firmware is at https://github.com/Opentrons/opentrons-modules Implement one of the MagDeck’s gcodes on the Arduino. Say, make gcode 0 blink the LED on the Arduino, and return the requisite “ok ok”. We may have to make the Arduino report the model and serial numbers.

If all else fails, try to replicate the MagDeck in toto, i.e., get a SAMD Arduino and build the opentrons-modules repo according to their instructions. This would be the kitchen-sink approach.

Other gcode projects as example:

https://github.com/james-martinez/grbl-cnc-arduino-nano-board

https://github.com/gnea/grbl

##Creating A Protocol

Find the simplest protocol, and use it with 24-well plate as labware. Try to use it with a custom labware.

Monitoring what’s going on in the Raspi in the robot.

Namely, why does the pipette crash into the trash bin when it’s trying to do pipette calibration.

Note: You’ll be using the following commands:

The network scanner “nmap”. Here’s a cheat sheet.

The command “ip address”. Type “ip address help” to get help with that specific sub-command of “ip”.

Find out your own ip address: ip address

Most likely 192.168.x.y. Let’s assume “192.168.1.101” is your ip address. That implies the IP address of your network itself is 192.168.1.0. Now, scan the hell out of said network to find everyone on it, including the Raspberry Pi in the robot.

sudo nmap -sP 192.168.1.0/24

Find the Raspberry Pi. It may very well be the Opentrons robot. Let’s say you found it at 192.168.1.132. Now, portscan the robot itself:

nmap -sV --version-intensity 4 192.168.1.132

Most likely, the robot is running the ssh daemon called Dropbear. Connect to it using your command-line ssh client https://support.opentrons.com/en/articles/3203681-enabling-ssh-access-to-your-ot2

curl -X POST 192.168.1.130:31950/server/ssh_keys\ -H "Content-Type: application/json"\ -d "{\"key\":\"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC3qpwZBdHwKcUjR6NQHOmN0Vxv0lqIdoJlhoOZZkVjyq0O+gGt0oQQrV6nPox9dsiUuhGv9/D/QlNDuiMc9eGoodyK+3JiJY5ESl4NTxVaU1bfFetqNYAELyYrXUmFDZDhsp48z2xDkX1/6djyoaDzG4+O8/fmRatuqkv6CFE+aExg6qfluLCV0RMh70jVJQWqYc0/Dld4kd0+7xutxfcea4mTWfoHe5tPs1Y3A7ZST/cn1yJoV7+LXI8LgJ2FBrxuryXUhL/PU1eDnCkfDxFmzQ/7orAR9BjOJOXqkwzd4tz1xCxi0jG0cxV39FVEcqB1h0lZjtgj4pn9xfjpOyV7 origin@assmodeus\"}"

You’re logged into the Opentrons robot’s RaspberryPi. Some info:

It runs ResinOS. (Opentrons has access to it, presumably with a ResinOS account, vpn thing.)

Inside that, it runs a Docker container based on Alpine.

Inside that, it runs a python API listening for commands from the client.

Also in the container, there’s a running Jupyter notebook. And Nginx.

I’m not sure if you are logged into the Alpine Docker container (signs point to yes. “alpine-release” file in /etc).

The ResinOS sees a /data directory. This is mounted inside the docker container. This is the only directory which is seen by the docker process. I’m not sure why we can’t run a “docker” command or see any docker-related stuff in the output of the “ps” command.

The /data/logs directory contains api.log (what the UI says to the API server running on the RasPi) and the serial.log (what the server on the RasPi says to the Smoothie Board.) Appendix 4 shows

The /data/system directory contains other stuff. Probably important.

Creating The Build System

According to the github repo instructions: https://github.com/Opentrons/opentrons/blob/edge/CONTRIBUTING.md#development-setup

Steps:

Install an Ubuntu system, mine is a Virtualbox virtual machine: Xubuntu guest in a Xubuntu host.

pyenv:

sudo apt-get install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev python-openssl git

curl https://pyenv.run | bash

pyenv install 3.6.4

nvm: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash

node: nvm install lts/carbon

yarn: curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -

echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

sudo apt-get update && sudo apt-get install --no-install-recommends yarn

errors when installing commitizen

Note: You can check the api.log and serial.log look like when the desktop app issues commands

Media

To send a video, (am I wrong about this?), set up an RTSP server on an external device, run ffmpeg on the opentrons and connect to this external device.

cd /var/lib/jupyter/notebooks
ffmpeg -f video4linux2 -s 640x480 -i /dev/video0 -ss 0:0:1 -frames 1 [targetFileName].jpg
ffmpeg -video_size 320x240 -i /dev/video0 -t 00:00:01 [targetFileName].mp4

To download that pic or video with wget:

wget http://[robot’sIpAddress]:48888/files/[targetFileName].mp4

For recording video of a running protocol:

/var/lib.jupyter/notebooks/take_a_video_of_running_protocol/signal_handling.py

Send a !kill -10 cat /var/lib/jupyter/notebooks/signal_handling.pidcommand in jupyter notebook to begin recording. Send a!kill -2 cat /var/lib/jupyter/notebooks/ffmpeg.pid command in jupyter notebook to end recording

Opentrons Jupyter Notebook

Find the raspberry pi on your network:

sudo nmap -sP 192.168.1.0/24 | awk '/^Nmap/{ip=$NF}/B8:27:EB/{print ip}'

Also, you can portscan whichever ip address you’ve found: sudo nmap -p- 192.168.1.130

The opentrons robot will have port 48888 open. Connect to it with a browser: https://192.168.1.130:48888

Make a new Python script and paste in the example from here.

Make sure to edit that, adding “import robot” and “robot.connect()”, as described here.

Alter for what you’re actually putting inside the robot. For example, I looked up the Corning 24-well labware, in this reference here.

Remote Access Via Raspberry Pi And VPN

Set up a Raspberry Pi as a VPN client. This link uses PIA (a commercial vpn service as the vpn. This uses one RasPi connected to the LAN via WiFi and can be used as the gateway. This is not the solution which creates a second VPN

Roll your own vpn server instead of using PIA as mentioned above.

Set up a Raspberry Pi as a wifi WiFi access point. hostapd bridge-utils https://www.raspberrypi.org/forums/viewtopic.php?t=100053; You will probably want to use nmcli, as per this guy’s script But you’ll want to craft your own nmcli commands as per this link

Alternatively use OpenWRT https://www.makeuseof.com/tag/raspberry-pi-vpn-travel-router/ This seems basic enough: https://openwrt.org/docs/guide-user/network/wifi/bridgedap

This will work for outgoing connections. Add something along

Find a “Raspberry Pi as VPN WiFi Router” tutorial / script.

Now trying OpenWRT on the Raspberry Pi

Raspberry Pi as a VPN client, and WiFi bridge. (Latest attempt) Start with clean Raspbian Buster Configure config.txt with screen size boot Set hostname set password Reboot Update apt -y install network-manager apt -y purge openresolv dhcpcd5 Using nmtui connect to Genspace using the WiFi interface (wlan0) Plug in a USB WiFi dongle Check that it came up as wlan1 Using nmtui, set up wlan1 as an AP with ssid “gadgetvpn” and password “gadgetvpn123” Reboot Test that you can connect to the internet, by connecting a computer to the gadgetvpn ap.

sudo apt -y install openvpn sudo apt-get install network-manager network-manager-openvpn

download the ovpn file sudo nmcli connection import type openvpn file theovpnfile.ovpn source https://computingforgeeks.com/how-to-use-nmcli-to-connect-to-openvpn-server-on-linux/

turn on tun0 connection from command line nmcli con show nmcli con up name_of_the_connection

To Do: Use nmtui (nmcli?, manual?) to set the subnet and ip address range of the gadgetvpn ap.

pi@raspberrypi:~ $ curl -X POST 192.168.1.130:31950/camera/picture --output "ot_pic.jpg"
ssh <un>@<ip>
ssh -L 127.0.0.1:48888:192.168.1.130:48888 [email protected]

How to test that you are connected to the VPN and have access to the other machines Point your web browser to ipinfo.io. If you are connected to the VPN, the website should report you are in Clifton, NJ. Ping 10.8.0.1, 10.8.0.6. Connect to the Raspberry Pi by running “ssh [email protected]”. The password is “gadgetvpn123”. (in progress). If I change the RasPi in the lab, you will need to delete your known_hosts file at “.../USER/.ssh/known_hosts”.

Connect to the Opentrons robot through the VPN (in progress). Point your browser to http://10.8.0.10:48888. This is the robot’s Jupyter notebook. Run "ssh -L 48888:10.42.0.174:48888 [email protected]". Point your browser to http://127.0.0.1:48888.

Solving the “cannot assign requested address” problem.

Hint: force ipv4

source: https://www.electricmonk.nl/log/2014/09/24/ssh-port-forwarding-bind-cannot-assign-requested-address/

How to install xvnc on another machine in the lab

Already having an OpenVPN jump server: sudo openvpn --config ./client.ovpn

Already having ssh server enabled on another machine which runs in the lab: ssh -4 -L 48888:192.168.1.130:48888 -L 31950:192.168.1.130:31950 -L 5901:127.0.0.1:5901 [email protected]

Install Xvnc source: https://www.server-world.info/en/note?os=Ubuntu_19.04&p=desktop&f=5

vncserver -kill :1 ps -ely | grep vnc

“Opening password file failed.”csource:https://github.com/TigerVNC/tigervnc/issues/457

On the server: vncserver :1 -geometry 1024x768 -localhost yes -SecurityTypes=none

On the client: xtigervncviewer 127.0.0.1:1

How to set the gateway and DNS on the Opentrons robot?

Monitoring what’s going on in the Raspi in the robot. Namely, why does the pipette crash into the trash bin when it’s trying to do pipette calibration.

Note: You’ll be using the following commands: The network scanner “nmap”. Here’s a cheat sheet. The command “ip address”. Type “ip address help” to get help with that specific sub-command of “ip”.

Find out your own ip address: ip address. Let’s assume “192.168.1.101” is your ip address. That implies the IP address of your network itself is 192.168.1.0. Now, scan the hell out of said network to find everyone on it, including the Raspberry Pi in the robot: sudo nmap -sP 192.168.1.0/24

Find the Raspberry Pi. It may very well be the Opentrons robot. Let’s say you found it at 192.168.1.132. Now, portscan the robot itself: nmap -sV --version-intensity 4 192.168.1.132

Most likely, the robot is running the ssh daemon called Dropbear. Connect to it using your command-line ssh client: https://support.opentrons.com/en/articles/3203681-enabling-ssh-access-to-your-ot2

You’re logged into the Opentrons robot’s RaspberryPi. It runs ResinOS. (Opentrons has access to it, presumably with a ResinOS account, vpn thing.) Inside that, it runs a Docker container based on Alpine. Inside that, it runs a python API listening for commands from the client. Also in the container, there’s a running Jupyter notebook. And Nginx. I’m not sure if you are logged into the Alpine Docker container (signs point to yes. “alpine-release” file in /etc).

In order to access most recent logs, use the journalctf command (https://github.com/Opentrons/opentrons/blob/4cf1719dcdfc35857366380fff979577d472da3b/CONTRIBUTING.md#buildroot)

The /data/logs directory contains api.log (what the UI says to the API server running on the RasPi) and the serial.log (what the server on the RasPi says to the Smoothie Board.) Appendix 4 shows

The /data/system directory contains other stuff. Probably important.

Creating the build system according to the github repo instructions https://github.com/Opentrons/opentrons/blob/edge/CONTRIBUTING.md#development-setup

Steps:

Install an Ubuntu system, mine is a Virtualbox virtual machine: Xubuntu guest in a Xubuntu host.

pyenv: sudo apt-get install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev python-openssl git

curl https://pyenv.run | bash

pyenv install 3.6.4

nvm: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash

node: nvm install lts/carbon

yarn: curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -

echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

sudo apt-get update && sudo apt-get install --no-install-recommends yarn