Calibration

Note

Under development!

Warning

Content below is incomplete or missing. This page is missing, at least:

• Instructions to calibrate the robot's CNC axes, coordinate system.
• Instructions to calibrate new platforms, slots, tools, and the tool-changer.
• Instructions to calibrate micropipettes (volumetric and tip placement).
• Required skills.

Required skills and resources

Due soon: Required skills and resources for the calibration process

Tool Calibration Guide

Tool-changer calibration

Info

Due soon. The following uses vocabulary for the old version of the tool-changer, and is incomplete. Though conceptually similar, it must be updated.

There are 3 important measurements for each tool:

• The XYZ coordinates of an empty carriage when it is just "in front" of a parked tool.
• The XYZ of a carriage when it has docked completely with a parked tool.
• The length of a tool along the Y axis, measured from the front of the carriage.

If you measure and configure these parameters correctly, collisions should not happen.

Note

• The carriage's coordinates are those shown in the GUI after a successful homing.
• If during calibration the tool "loading" Z coordinate is different from the tool "parking" coordinate, set this offset value in the z_parking_offset slot of the configuration. If your machine is perfect, the coordinates will not differ, and the offset should be set to zero.

1. Manually remove any tools, and place them in their corresponding parking posts.
2. Open the GUI and the Joystick.
3. Home the machine.
4. To get the tool-change coordinates, use the joystick to move the machine to the following locations, and take note of the coordinates at each step.
   1. Align the carriage just in front of the a tool's parking post, but clear of it.
   2. Slide the carriage in, until the latch "clicks".
   3. Adjust the parking switch set screw such that it barely triggers at this position.
   4. Slide out the carriage, now with the tool loaded, until the alignment rods slide out of the parking post completely.
   5. Slide out the carriage, until the Y position is such that the tool cannot crash into other tools.
   6. Slide the tool back into the parking post, until the latch "clicks" again.
   7. Slowly slide out the carriage until the magnets detach.
   8. Slide out the carriage until the alignment rods slide out of the bearings in the carriage.
5. Repeat step 4 with the other tools.
6. Update pipette definitions with the new information.

Each set of coordinates is required to define the tool-change movements for a tool.

Below you will find examples, illustrating the expected result of the calibration procedure.

Example

Initial conditions:

• Homed machine and tools.
• Coordinate space correctly configured.

In the following sections you will:

1. Record and configure coordinates to dock a pipette tool.
2. Record and configure coordinates to eject a tip.
3. Record and configure coordinates to park a pipette tool.

Docking coordinates

Warning

TO-DO

Parking coordinates

Warning

TO-DO

Tip ejection coordinates

Tip

If the pipette is not correctly fastened to the adapter, it will become obvious notice at this step. As the tip ejector starts making force, the pipette will change alingment, which can change again when a tip is placed. To correct this, make sure the bottom piece holding the pipette is very tight.

Troubleshooting

Lost steps

The machine's stepper motors can skip steps if they can't produce enough force (e.g. when ejecting or placing tips).

Possible solutions:

1. Adjust GT2 belt tension. The skipping might be actually happening at the stepper pulleys, not in the stepper.
2. Adjust Vref to increase current, and thus torque.
3. Remove a magnet from the tool-changer head. This is simpler and will affect all tools.

Tool offset calibration

Info

Due soon. The following uses vocabulary for the old version of the tool-changer, and is incomplete. Though conceptually similar, it must be updated.

First, you must calibrate the position of items with respect to the a "first" tool, to which you will assign zero offset. This tool can be anything, but if you change it, you'll need to recalibrate all your tools.

Other tools will have offsets with respect to that one.

1. Manually load the reference tool (e.g. p200) and home the machine.
2. Follow the instructions at doc/platforms/README.md to calibrate XYZ coordinates for platforms, relative to the first tool.
3. Follow the "Offset calculation procedure" section to obtain XY offsets for the second tool.
4. Follow the instructions at doc/platforms/README.md again, to calibrate Z coordinates for platforms, relative to the second tool.
5. Update platform and pipette definitions with the new information.

Offset calculation procedure:

1. Place reference object on the workspace, which you can align precisely to the pipette's point (or tip if placed).
2. Align the first tool to the object using the GUI's joystick.
3. Record the XY coordinates.
4. Remove the first tool and place the second tool (manually).
5. Align the second tool to the object using the GUI's joystick.
6. Record the XY coordinates.
7. Calculate the difference between the first and the second set of coordinates, to obtain the second tool's offset.

List of To-Do's

• The Z coordinate offset will be discussed later.
• Each platform will have a specific "default load bottom" parameter, associated with each pipette.
• Also the tip lengths will have to be measured. See the next section.

Use the recorded coordinates to calculate the offsets of the second tool (p20) using the first tool (p200) as a reference:

cal = {"p200": {"x": 168.875,"y": 73.875,"z": 25.91},
       "p20": {"x": 169.875,"y": 80.875,"z": 50.98}}

offset_x = cal["p20"]["x"] - cal["p200"]["x"]
offset_y = cal["p20"]["y"] - cal["p200"]["y"]

print("x: ", offset_x)
print("y: ", offset_y)

Note

Note that we subtracted from the second set of coordinates. This is because the GCODE is built for the coordinates of the first tool, and the offsets are added just before saving each command.

Workspace Calibration Guide

Prerequisites

This guide assumes that all of these things have been done:

• Fully assembled robot.
• Full software setup.
• You can access Pipettin Writer (the GUI) and Mainsail (the joystick for manual control).

If you have not yet done so, please follow the Assembly and Software & Electronics setup guides.

Deck position

Info

Due soon. Calibration of the position of the baseplate (i.e. its local origin of coordinates) relative to the machine's physical origin of coordinates (i.e. where the home position is located).

Platform position

Info

Due soon. Platform position calibration

• XY and Z coordinates.
• Offsets for each tool.

Platforms are virtual objects with properties representing physical objects in the workspace, such as tip boxes and tube racks.

Platforms can also be edited.

"Manual control" is achieved through Mainsail.

To do

IMAGE SHOWING PLATFORMS MENU

Even though there are a ton of things you can edit of each platform, the most important thing about this is the XYZ axes configuration. X and Y are moved manually and Z is moved holding the tip.

Repeat this calibration each time the platforms change position.

XY position

To do

Calibration of XY position.

Z position

Each platform has a top and bottom attribute, which we must calibrated with the reference tool.

To do

Calibration of Z position.

Examples

Tip Box

Tube rack

Platform curbs

Info

Due soon. This is not implemented yet in the UI yet.

See issues:

• https://gitlab.com/pipettin-bot/pipettin-gui/-/issues/34
• https://gitlab.com/pipettin-bot/pipettin-gui/-/issues/100

Pipette Calibration Guide

Calibration instructions for micropipette tools.

Tip-placement

Info

Due soon. This can be written once the tip ejection post is mounted on the robot, once for every tool and tip type.

Tip-ejection post

Info

Due soon. This can be written once the tip ejection post is mounted on the robot, once for every tool and tip type.

Homing sequence

Info

Due soon. The following uses vocabulary for the old version of the tool-changer, and is incomplete. Though conceptually similar, it must be updated.

The initial state of a pipette is assumed to be at the first stop (when it's shaft is fully depressed, but not further than the start of the second stop).

From this position the pipette is ready to load volume.

What we need to find is the distance that the carriage must travel from the homing sensor, to reach the second stop (but not further).

Tip

Before doing this, make sure that your limit switches and stepper motors are correctly wired and configured. Otherwise things might crash into each other and some parts may be damaged.

If everything worked out, now it's time to tune the homing position, using the retraction_displacement argument to home_pipette. This parameter defines how far the motor will travel downwards after hitting the limit switch on top.

Now:

1. Increase the value on retraction_displacement by some amount.
2. For example pipette.home_pipette(retraction_displacement=2)
3. Note: you can try with larger steps if you've already seen what "2" looks like and you are confident.
4. Re-run the home_pipette again with each new value.
5. Check if the pipette's shaft has reached the first stop.
6. The carriage will squeeze your fingers if you place them on top of the pipette's button. Try grabbing it from the sides, either to hold it down, or to check if there is still some distance before the first stop (after homing of course).
7. Repeat from step 1 until the pipette's shaft has reached the first stop after homing.
8. My final value was 22.9 mm for the p20 pipette tool.
9. My final value was 22.9 mm for the p20 pipette tool.
10. Change the pipette, and repeat all steps (for each tool you have).
11. In my case, I switched to the next tool with pipette.configure_pipette("p20").

Volumetric calibration

Info

Due soon. Old and messy calibration assays here and results here. Cleanup, update, and migrate.

Materials:

• Micrometer tool or good Calipers (0.01 mm, or better).
• Analytical / precision scale (0.1 microgram, or better).
• 1.5 mL microcentrifuge tubes.
• Micropipette tool:
• Correctly installed on its parking post, connected to the electronics, and configured (firmware-side).
• Calibrated tool parameters.
• Calibrated workspace, contents, and containers with a tube rack for 1.5 mL tubes and p200 tip rack.
• Calibrated tip-placement and tip ejection parameters.
• All liquid handling corrections disabled.

1. Measure the diameter of the pipette shafts, and set the shaft_diameter parameter.
2. Make sure that all of the above conditions are met. The correction parameters must be disabled by setting the following tool properties:

  "backlash_correction": 0,
  "scaler_adjust": 1,
  "capillary_correction": false,
  "extra_draw_volume": 0,
  "back_pour_correction": 0,
  "tip_priming_correction": false,
  "under_draw_correction": 0,

1. Start by measuring backlash_correction.
   • Create a protocol with a single TRANSFER, dispensing 30-50 uL serially in 3 or more tubes.
   • Measure the initial weight of all tubes, including the source tube (with sufficient water in it already).
   • Run the protocol and measure the final weight of all tubes. Repeat at least 3 times.
   • Set backlash_correction equal to the average difference between the first and second dispense moves.
   • Repeat a few more times to triple-check that there is now no difference between first and second dispense moves.
2. Set scaler_adjust.
   • Repeat the measurements and estimate the overall deviation between the target volumes and actual volumes. Yuo may benefit from using larger volumes per dispense (e.g. 40-50 uL).
   • For this calculation give greater importance to the intermediate dispenses (i.e. not to the initial aspiration or final dispense).
   • For example, if dispenses and aspirations are in average 1.5% below their targets, set scaler_adjust=1.015.
3. Set extra_draw_volume.
   • Increase the value of extra_draw_volume if after the previous steps you observe that the initial aspiration is consistently below its target.
   • Note: you may try setting back_pour_correction instead, or both simultaneously (details below).
4. Set capillary_correction.
   • If the final dispense is consistently below the target because volume remains in the tip, set this parameter to true and tune the tension_correction parameters. These parameters are related to the well-known "blow out" volume.
   • This correction is specific to each tip-stage, and more relevant to the smaller tips. Tune the start_vol and max_correction values by making small-volume serial dispenses that rely on the tip's tip. Look for the lowest volume where issues begin, and note the maximum magnitude of the deviation.
5. Set additional correction parameters if needed.
   • These are related to "wetting" new tips, similar to extra_draw_volume.
   • Set back_pour_correction if you observe that the liquid does not initially enter a new tip, and then suddenly does, distorting the results. The pipette might have trouble overcoming suface tension / wetting the tip, especially for small aspiration volumes.
   • Set tip_priming_correction if you need to pre-wet the tips before aspirating.
   • Set under_draw_correction if you need to consistently aspirate extra volume.

Tip

You can get an idea of the backlash by aspirating manually a small amount of water (e.g. 2uL), and then aspirating some air (e.g. 15 uL). Move the pipette axis outwards by 0.1 mm, and check if the drop starts moving downwards or not. When it does, note the total displacement, and start moving upwards until the drop starts moving again. We have observed up to ~0.4 mm backlash, which corresponds to a 12 uL error. This looks terrible but it can be corrected quite well.

Note

If you observe error across a serial dispense that is systematic (e.g. +1% in the second dispense, -1.5% on the third, 0.5% on the fourth, etc.) it is likely that the actuator has mechanical inaccuracies. This can be solved by using precision encoders on the rail, by using higher quality mechanical components, or by calibration and software correction.

The pipettes.py module does not yet feature such corrections, which might also be hard to measure. We encourage you to use quality lead-screws and bearings, or switch to linear rails instead.

Congrats!

You've set-up and taken care of your machine.

Come back to these pages once in a while, specially if you start encountering any issues.

You may move on to the User Guide, or go back to the Home Page.