Usage

Info

Under development! This page is missing:

• Instructions to create a protocol using Newt (or PLR).
• Instructions to run a protocol and troubleshooting.
• Usage restrictions (related to design rationale, functional specification and working principle items).
• Video GUI (create a virtual workspace, add platforms to the workspace, create a protocol).

Requirements

To follow this guide, the machine needs to be ready to run, with every part installed and perfectly calibrated.

If this is not yet the case, please follow the relevant guides thoroughly:

1. Installation guide
2. Software setup guide
3. Electronics setup guide
4. Calibration guide

Features and Limitations

Warning

Content due soon: Pipettin Bot Features and Usage limitations.

Walkthrough video

Warning

Content due soon: Video (create a virtual workspace, add platforms to the workspace, create and run a protocol)

Access

Before you get started you will need to know the robot's address:

• Try the default mDNS address: http://pipettin.local:3000
• Read it directly from the robot's mini OLED display (if installed).
• Find it by network scanning.

You can now use this IP to access all applications.

Applications

The robot can be used through several applications:

Application	Port	Description
Pipettin Writer	3333	Friendly web interface for creating and running protocols.
Backend page	3000	Links to the main applications.
Mainsail	80	Machine control "joystick".
JupyterHub	8000	Electonic python notebook server.
Cockpit	9000	Linux system management web application.

Backend and Joystick pages:

HTTP only

Remember to use http to access these pages, and not https. HTTP encryption is not yet enabled, and is suitable for access in trusted local networks.

Workspace setup

First some definitions:

• A workspace is a virtual representation of the deck, where the robot will perform its actions.
• A deck is a collection of physical objects placed on particular positions of the baseplate.

These objects, usually called "labware", can be tip racks, tube racks, or any other object that you want to use with the robot.

As such, the workspace is meant to be a digital twin of the deck, and must be aligned with it to work correctly.

Place physical objects

The basic idea is to place objects along the 3D-printed anchors. These are meant to be used as "curbs", such that you can move objects around and still put them back easily, precisely and repeatably at the same position.

The basic anchors come in 2 types: straight and L-shape. The straight anchors are meant to be used as "curbs", while the L-shape anchors are meant to be used as "corners", and these can be combined to form larger shapes.

Procedure:

1. Place the baseplate on the aluminum frame (if not there already).
2. Make sure that the contact points are correctly aligned with the slots one the aluminum profile. It must sit in place firmly.
3. Place some anchors on the baseplate.
4. Try to form corners at different places. This shape will be useful to align objects in the next step.
5. Place your objects on the baseplate, aligning them to the anchors.
6. For example:
   • One p200 tip rack with tips.
   • One tube rack with some tubes.
7. Place a "discard tray" just below the tip-ejection post.
8. If using a pipette with a built-in tip ejector, place a trash container somewhere else.

Digital twins

The relative placement of physical objects on the baseplate must correspond with the position of virtual objects in the GUI's workspace. This will be achieved on the next step.

Curbs on the baseplate:

At first the objects are free to move. The curbs (the white 3D-printed part in "L" shape) should be square with the machines coordinates, and will help align the objects, in both position and angle.

Once in place, the position of the objects must be calibrated in the GUI, such that the virtual representation is perfectly aligned with the physical deck.

Alignment

Alignment is the process of telling the robot where each object is located, making the virtual workspace match the physical deck exactly.

It is critical that new platforms and curbs are calibrated to their anchors before using them, so we have guides for that:

• Workspace Calibration.

Warning

Never use an uncalibrated platform or curb, and always place the items with care. Failing to do so will probably crash your robot and cause damage.

Using the UI

Usage guide for the Pipettin Writer user interface, a user-friendly web application for the Pipettin bot.

Access

Access the UI by opening a web browser, and visiting the app's URL and port.

• If the UI is running on a remote computer (e.g. the robot's RPi) the URL will consist of it's IP followed by the UI's port (e.g. http://<your_pi's_ip>:3333).
• If you are running the software on the computer you are using, try opening a browser and visiting http://localhost:3333.
• The UI is also available through GitLab pages, and can be used after configuring the API's address.

Tip

If you do not know your Pi's IP yet, follow the relevant section of the Setup Guide

Ask for help or report errors by creating an issue here.

Create a virtual workspace

Steps:

1. Open the GUI by pointing your browser to the Pi's IP address on your local network, on port 3333.
2. For example: http://192.168.0.12:3333
3. Click on the "Workspace" drop-down menu.
4. Select "New" to create a workspace.
5. A workspace menu should open
6. Customize your workspace by giving it a name and description, then click on "create"

In this step, it's essential to align the virtual workspace with the physical one. To achieve this, you need to choose the weight, height, and length that correspond to your specific physical workspace.

1. Congrats! You created a new workspace.

Using curbs

To-Do: This section is missing a proper tutorial

Adding items

Info

So, this is basically how it's supposed to look. But when we put different stuff onto the workspace, you can see they don't really fit within the space marked out by those dots – which shouldn't be happening. This serves as an illustration.

Expected result where all the platforms are inside the physical workspace

Once the new workspace is created, you'll want to start adding platforms to your virtual workspace. The term "platforms" refers to all the objects that live on the workspace.

1. Go to "Insert platform" and select a tip rack.
2. Add tip box.
3. Drag tip box.
4. Add more platforms.
5. Select a tip box item.
6. Add tips (content) to the tip racks.
7. Tips added.
8. Select tubes.
9. Add tubes (content) to the tube racks.
10. More tubes selected.
11. More tubes added.

One you finished adding platforms to the workspace, on the right part of your virtual workspace, you will se that all the platforms appear with its contents.

In this part you will be able to go to the tube box section and select how much liquid you want to add in each tube and what (water, buffer, DNTPs, PRIMERS).

You can also see that the tubes, for the user convenience, are colored by "Tags" and indicates the water level on each well.

Note

A tube must have non-zero volume to be used as a solution component source.

Create a protocol with the UI

Adding steps

1. Go to the protocols section on the right side of the GUI and click on "Add new protocol"
2. Name your new protocol and write a simple description of it. Then click on "save"

Protocol templates

You will see that there is a template option in which you can select "PCR Mix". This type of configuration automatically puts all the tubes to do PCRs, and even the protocol. But on this tutorial we are gonna click "None" to show you more types of configurations.

Protocol panel menus

You will see these menus above the protocol configurations:

• ✔ Validate protocol: Once you finish your protocol click here check that your protocol is working correctly before you run it.
• ▶ Run protocol: Once you finish your protocol, start running it.
• ⏸️ Pause execution: Pause your protocol if you need to.
• ◼ Stop execution: Stop running your protocol if you need to.
• ➔ Continue execution: Resume running your protocol if you have paused it.

1. Since the protocol is created with no steps, you need to click on "Add step".
2. You will see a ton of options for your steps. Transfer, Wait, Human Intervention, Comment, and mix. Click on "Transfer".
3. You'll se four main flaps; Source, Target, Volume and Tips. It might be helpful to use the "tags" option, as we used while adding platforms to the workspace.

You will be able to configure some important features of each step card.

Source

You can configure on which platform, with or without tags and what liquid your source is gonna be

Target

You can configure on which platform, with or without tags and what liquid your target is gonna be. If the option "sample" is selected while choosing the target, you will be able to see that below it says "Selected item(s): 2."

Two items (or more) were detected. That means that everything will be repeated for both tubes containing this tag, to avoid writing this step twice.

Volume

Select the volume you want to transfer

Tips

The tip's configuration options are pick from, discard to and behavior. Regarding this last one, there are three options of behavior (how to re-use the tips):

• Always re-use
• Avoid Target contamination
• Only avoid Source contamination
• Re/-use only the same source

The idea is that you configure the volume, since that volume can go, for example, in two different tubes. By doing that, you can use the same tip by repeating the pipetting without wasting tips.

This step can be repeated by adding a new step and changing some settings from the previous one.

1. When you finish creating your protocol and adding the needed steps, click on "Save protocol"

A message should appear confirming that the protocol was validated.

Using templates

When creating a new protocol, you will see that there is a template menu

Templates are forms that prepare the workspace and protocol automatically, to avoid doing this in several steps.

You can custom your protocol template as you wish, specifying which tips you want to use, where to throw the discard tips, etc.

Pipettin Writer comes with its amazing PCRmix template:

Complete it as you please, for example:

You will also note that the protocol template comes with "Component Groups"

This is a space to add names to reactions. You can add as many groups as you want.

When you finished, click on the "Create" button. After that, you will see that the program inserts all the platforms and objects detailed on the protocol template, as well as all the protocol steps.

The next step is to click on "Save protocol", then click on "Validate protocol"

If an error message appears, it indicates an issue has occured. The error message will pinpoint the specific step where the problem exists. You can identify this by selecting the option labeled 'Error in step...' – clicking it will instantly navigate you to the location of the error on the page.

After solving the problem, you have to, once again, click on "Save protocol", then click on "Validate protocol".

Write a protocol with Python

This section is missing a proper tutorial.

Protocols will be written using PLR, or Newt.

Running protocols

Note: This section is missing a proper documentation.

This section should describe the different ways a protocol can be executed:

• GUI
• Mainsail (the "printer" control web-app)
• Using python (eventually)

Pre-run considerations

Note: This section is missing a proper documentation.

Execution

To-Do: Add video showing how the robot works when running any protocol

Troubleshooting

• What if something goes wrong?

Note: This section is missing a proper documentation.

Congrats

Congrats! You've automated your lab life. Isn't that nice?

Move on to the Assembly Guide