Skip to content



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).


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

Usage Limitations

Due Soon: Pipettin Bot Usage limitations.

Walkthrough video

Due Soon: Video (create a virtual workspace, add platforms to the workspace, create and run a protocol)

Deck setup

Place physical objects

The basic idea is to place objects along the 3D-printed curbs. Use these to align the objects easily, precisely and repeatably, to the workspace's surface, and to prevent any object from moving along the workspace.

  1. Place the baseplate on the aluminum frame.
  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 curbs 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 and align your objects on the baseplate, for example:
  6. One p200 tip rack with tips.
  7. One tube rack with some tubes.
  8. A "discard tray" should be placed just below the tip-ejection post.

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 setup 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 objects.

To do so, just head over to the "Deck Position" section in the Calibration Guide

Platforms Calibration Guide

Calibration is the process of telling the robot where each object is located, making the virtual and the physical workspace must match exactly.

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


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 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. an 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 do not know your Pi's IP yet, follow the relevant section of the Setup Guide

If you are running the software on the computer you are using, try opening a browser and visiting http://localhost:3333.


Get support or report errors by creating an issue here.

Create a virtual workspace


  1. Open the GUI by pointing your browser to the Pi's IP address on your local network, on port 3333.
  2. For example:

  3. Click on the "Workspace" drop-down menu.


  1. Select "New" to create a workspace.


  1. A workspace menu should open


  1. Custom 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. It should look like this:


Using curbs

To-Do: This section is missing a proper tutorial

Adding items


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


  1. Add tip box


  1. Drag tip box


  1. Add more platforms





  1. Select Item


  1. Add tips (content) to the tip racks


  1. Tips added


  1. Select tubes


  1. Add tubes (content) to the tube racks


  1. It should look like this:


  1. More tubes selected


  1. 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.




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"


  1. Name your new protocol and write a simple description of it. Then click on "save"


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.



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"


  1. You will see a ton of options for your steps. Transfer, Wait, Human Intervention, Comment, and mix. Click on "Transfer".


  1. 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 flap:



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


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.


Select the volume you want to transfer


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.


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


  • What if something goes wrong?

Note: This section is missing a proper documentation.


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

Move on to the Assembly Guide