Note: Under development!
This page will contain:
- Instructions to access and use the GUI, in general. ✅
- Instructions to create a workspace with pre-calibrated platforms and pre-existing platform curbs (aka deck slots). ✅
- Instructions to place physical lab objects on the baseplate correctly. ✅
- Instructions to create a protocol using the GUI. ✅
- Link to instructions to calibrate new platforms and slots: https://docs.openlabautomata.xyz/en/Calibration#deck-position ✅
- 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)
- Link to learning resources ✅
- Link to Assembly Guide ✅
¶ Requirements
If you have not yet done so, please follow the main usage thoroughly:
¶ Deck setup
¶ Platforms Calibration Guide
Follow the deck setup and position on the Workspace XYZ Calibration Guide section.
¶ 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.
- Place the baseplate on the aluminum frame.
- Make sure that the contact points are correctly aligned with the slots one the aluminum profile. It must sit in place firmly.
- Place some curbs on the baseplate.
- Try to form corners at different places. This shape will be useful to align objects in the next step.
- Place and align your objects on the baseplate, for example:
- One p200 tip rack with tips.
- One tube rack with some tubes.
- 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
¶ Access to the GUI
¶ Find your Pi's local IP address
To open the graphical user interface, you need to know the Pi's address. If you do not know your Pi's IP, follow the relevant section of the Setup Guide
In that page you will be able to install all the prerequisites software programs to start the GUI
¶ Start the GUI
There is a systemctl service unit for this now. See files in the systemd.units directory.
Get support or report errors by creating an issue here.
Open the GUI by visiting: http://localhost:3333
To start it manually, change to the gui directory and run node:
cd gui
node bin/www
¶ Prerequisites
You will need to have installed Node.js, npm and MongoDB.
You should also install nodemon globally:
npm install -g nodemon # The global flag may not be requried.
¶ 1. Clone the repo
Choose a directory where you want to download the app, and start a terminal in that directory. To check out how to do so for your specific operating system go here
In the terminal run the following command to download the latest version of the app:
git clone https://gitlab.com/pipettin-bot/pipettin-gui.git
After that, use the cd command to enter the directory that was just created for the app's files, which should be named pipettin-gui. This folder will be referred to as "main folder" below.
cd pipettin-gui
¶ 2. Install all dependencies
In the main folder, start by running npm install. This will install Concurrently, which enables a smooth project startup. Next, execute npm run install-deps to install all dependencies used in both the front and the backend.
npm install
npm run install-deps
¶ 3. Start the database
The GUI expects to connect to MongoDB on port 27017. The database and all the collections will be created when you run the server.
The installation instructions should have left MongoDB running on your system at that port. If you get database errors below or an empty dashboard on the app, revisit those instructions.
¶ 4. Pre-start the app
Open a terminal at the pipettin-gui directory.
If you want to populate the database with default data, you can do so by running the following command:
cd api
npm run seed
This command will add a basic workspace, a few platforms and a protocol to the database.
¶ 5. Start the app
Use cd .. to change back to the main app directory, or open a new terminal at the pipettin-gui directory.
Back on the main folder of the project, run the following command, which will start the latest development version of both the client (frontend) and the server (backend) simultaneously.
npm run dev
A pre-build version of the app can be started by running the following command:
npm start
Open the protocol designer app by visiting http://localhost:3000 on your browser.
The client runs on port 3000, while the server operates on port 3333. It's important to note that the port number assigned to the server shouldn't be changed as it is the designated port for establishing a connection with the robot controller.
¶ Create a virtual workspace
Steps:
-
Open the GUI by pointing your browser to the Pi's IP address on your local network, on port 3333.
- For example:
http://192.168.0.12:3333
- For example:
-
Click on the "Workspace" drop-down menu.
.png)
- Select "New" to create a workspace.
- A workspace menu should open
- 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.
- Congrats! You created a new workspace. It should look like this:
¶ Add curbs to the workspace
To-Do: This section is missing a proper tutorial
¶ Add platforms to the workspace
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.
- Go to "Insert platform" and select a tip rack
2. Add tip box
- Drag tip box
- Add more platforms
- Select Item
- Add tips (content) to the tip racks
- Tips added
- Select tubes
- Add tubes (content) to the tube racks
- It should look like this:
- More tubes selected
- 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.
¶ Align and calibrate platforms
One you finished adding platforms to the workspace, we need to make the virtual and the physical workspace match. The robot must be told where each object is located.
Follow the relevant section on Calibration Guide
¶ Create a protocol
¶ Instructions to create a protocol using the GUI
- Go to the protocols section on the right side of the GUI and click on "Add new protocol"
- 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 this menue 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.
- Since the protocol is created with no steps, you need to click on "Add step"
- You will see a ton of options for your steps. Transfer, Wait, Human Intervention, Comment, and mix. Click on "Transfer".
- 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:
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.
- 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.
¶ Protocol template
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.
.png)
When you finished, click on the "Ctreate" 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".
¶ Instructions to create a protocol using Newt (or PLR)
This section is missing a proper tutorial
¶ Run your protocol
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 webapp)
- Using python (eventually)
¶ Pre-run considerations
Note: This section is missing a proper documentation.
¶ Run the protocol
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