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

TO DO

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 several important measurements for each tool and parking post:

• The XYZ coordinates of an empty carriage when it is just "in front" of a parked tool.
• The length of a tool along the Y axis, measured from the front of the carriage.
• The Y-axis clearance of the parking posts when empty and with their tools parked.

A full set of tool-changing coordinates is required to define the tool-change movements for a tool.

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

Preparation

1. Remove any tools from the tool-head, and place them in their corresponding parking posts.
2. Open the GUI and the Joystick (i.e. Mainsail).
3. Home the machine and the remote actuator.

Docking coordinates

Warning

TO-DO

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. Place the tool on its parking post, but not fully against the post. Remember this location.
2. Align the carriage just in front of the a tool at its parking post, but clear of it. Write down the Y coordinate.
3. Carefully move the head plate towards the tool, aligning and inserting the locking pin into the wedge-plate. Write down the X, Y, and Z coordinates.
4. Execute the GCODE commands for engaging and locking.
5. Move the head-plate away from the backpanel (now with the tool loaded) until it is clear of the parking post. Write down the Y coordinate.
6. Use a ruler or calipers to measure how much distance the tool added to the tool-head over the Y axis.

Adjust for tool sagging

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

Parking coordinates

Warning

TO-DO

1. Slide the tool back in the parking post, up to the Y-axis docking coordinate from the previous steps.
2. Execute the GCODE commands for releasing and clearing. The tool should now be free of the tool-head.
3. Compare the tool's location with the original location, at the first step of the docking calibration.
   • If the tool is not at the same location, set the y_parking_closeup parameter equal to the difference (positive value if the tool should be closer to the post, or negative in the opposite case).

Setting parameters

Warning

TO-DO

Update pipette definitions with the new information.

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

TO DO

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

Warning

TO-DO

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

Requirements:

• Calibrated tool changing and tool offsets.
• Calibrated tip-rack platform and calibrated workspace (with the tip-rack item in it).
• Known parameters for the tip holder's stages.
• Container definition for the tip (i.e. name and total length).
• The tip's container name should be added to the tip_map in the tool's parameters, associating it to the corresponding tip stage.

Procedure:

1. Move over a tip (you can use the go-to command from the UI).
2. Use Mainsail to carefully lower the tool, until its barely above the top of the tip. Write down the Z coordinate.
3. Lower the tool carefully, until it barely fits the tip. Write down the Z coordinate.
   • Take the difference between this value and the previous distance. This is a candidate for the tip_fit_distance parameter.
4. Raise the pipette and check if the tip is placed correctly (i.e. does it fall out easily? does it seal correctly?).
5. If the fit was not tight enough, repeat the following until the tip fit is good:
   • Repeat step 3.
   • Lower the pieptte a bit more, pressing on the tip, and write down the Z coordinate.
   • Repeat step 4.
   • When the tip fit is good, take the difference between the last Z coordinate you wrote down, and the coordinate from step 2.
   • This is the total_sealing_distance.
6. Move the tool upwards and then to the side of the tip rack.
7. Lower the tool carefully until the tip touches the baseplate. Write down the Z coordinate.
8. Take the difference between the tool's Z offset and this value. This is how much the tip adds to the tip holder.
9. Take the difference between this value, and the tip's total length. This is the total_fitting_distance for the tip.
10. Subtract the tip stage's z_offset from total_fitting_distance, and set tip_fit_distance to the resulting value value in the tool's parameters, at the corresponding tip stage's section.
11. Calculate probe_extra_dist by this formula and save it to the tool's parameters: probe_extra_dist = total_sealing_distance - total_fitting_distance

Tip-ejection post

Procedure:

1. With a tip placed (see the tip-placement section), use Mainsail to move the tool towards the tip ejection post.
2. Carefully insert the tip holder in the ejector, such that the ejector's tabs are between the top-end of the tip, and the next stage of the tip holder.
3. Write down the XYZ coordinates of this position.
4. Slowly move the pipette upwards until the tip is ejected. Write down the Z coordinates of this position.
5. Use these values to configure the tip-ejector in the corresponding tip stage of the tool's parameters.

Built in ejectors

The micropipette adapter tools take advantage of the tip ejector built into traditional micropipettes. If the pipette is not correctly fastened to the adapter, it will become obvious notice at this step. As the tip ejector starts pressing on the tip to eject it, the pipette will change alingment, which can change again when a tip is placed, and cause collisions. To correct this, check that the fastener pieces holding the pipette are sufficiently tight.

Homing sequence

TO DO

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

WIP

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.

Tip: Calibration setup on the bench

If you are wondering how calibration looks like on the bench, here is a setup. Having the scale nearby is a real time saver. Taking fast measurements means that closing the lids is not as critical to prevent evaporation (although this can be accounted for with a control tube).

How to edit tool parameters

You will need to open the tools menu on the Pipettin Writer UI. Click on "Menu" buttton on the left side of the navbar, and then select the "Tools" item from the drop-down list that appears.

Calibration sheet template: https://docs.google.com/spreadsheets/d/1KZMEsKyrwZiT8NY0MaJC5Bq-OI-2W5kdStQT5__uxu4/edit?usp=sharing

• Make a copy of this "template" sheet to your Drive. You may find it useful.
• It is setup for 5 tubes: 1 source, 3 targets, and an evaporation control (not used by the robot).

Main calibration procedure:

1. Measure the diameter of the pipette shafts, and set the shaft_diameter parameter. Set scaler_adjust to 1.
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. Setup a protocol.
   • Create a protocol with a single TRANSFER step, 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).
2. Check for leaks.
   • Run the protocol and measure the final weight of all tubes. Repeat a few times.
   • If the pipette leaks, the first aspiration will be consistently under target, the last dispense will be under target at least as much, and the middle dispenses will be over target.
   • To fix this inspect the piston assembly for mistakes and/or add lubricant (use a silicone-based grease for nitrile o-rings).
3. Check for correct free travel.
   • The travel_distance parameter under the homing section should match the free travel distance from the endstop exactly.
   • At this limit, the shaft should still have some free travel left, otherwise you'll see that the first aspirations are consistently under target.
   • To check this, home the pipette manually (e.g. run HOME_E2 in Mainsail) and disable the steppers. Try rotating the motor manually, to check that the shaft has not hit its limit.
   • If there is too much or to little free travel:
     • Update the parameter in Klipper's config for the homing macro (e.g. [gcode_macro HOME_E2])
     • Update travel_distance in the tool's parameter to match it.
4. Set backlash_correction.
   • Repeat the test protocol.
   • If the above worked out nice, set backlash_correction volume equal to the average difference (in microliters) 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.

Tip: Eyeballing backlash

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 downwatds by 0.1 mm to dispense air, and check if the drop inside the tip starts moving downwards or not, and repeat. When it does, note the total displacement, and start moving upwards until the drop starts moving again.

This is good as an initial approximation. If too much is observed, try fixing issues in the mechanical assembly first.

A well assembled pipette will have little or no backlash. We have observed up to ~0.4 mm backlash distance with the cheapest actuators, which corresponds to a 12 uL backlash_correction error in a 6 mm shaft. This may sound terrible but can actually be corrected quite well.

1. Set extra_draw_volume.
   • Repeat the test protocol.
   • Increase the value of extra_draw_volume if after the previous steps you observe that the initial aspiration and the last dispense are consistently below target, while the intermetiate dispenses are fine.
   • A symptom requiring this correction is that it runs out of volume on the last dispense, and blows a bit of air.
   • This correction can be confounded by sealing issues (i.e. leaks), and can be distinguished from it by the correct intermetiate dispenses.
   • Note: you can try setting back_pour_correction instead, or both simultaneously (details below).
2. Set capillary_correction.
   • Repeat the test protocol.
   • If the final dispense is consistently below the target because volume remains in the tip, but the initial aspiration is on target, set this parameter to true and tune the tension_correction parameters. These parameters are related to the familiar "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.
3. Set additional correction parameters if needed. These are related to "wetting" tips.
   • 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.
     • Serial pipetting with lots of dispenses make the sequence last longer, and increase the deviations introduced by liquid evaporation inside the tip.
   • Set under_draw_correction if you need to consistently aspirate extra volume (extra_draw_volume and back_pour_correction only apply to the first aspiration).
   • 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.

Troubleshooting

If you feel lost in calibration, this section may help.

Systematic error in serial dispenses

Serial dispenses have known issues in big brand robots. The Hamilton company, for instance, recommends discarding the first and last dispenses in a series. There are however several sources of inaccuracy.

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. Typical tolerances in a cheap 2mm-pitch leadscrew will allow errors in the 1% range.

This can be solved by using precision encoders on the rail, higher quality mechanical components, or by calibration and software correction.

The pipettes.py module does not yet feature such software corrections, which might also be hard to measure without proper equipment. We encourage you to use quality lead-screws and bearings, or switch to linear rails instead, if this becomes a problem.

You are welcome to reach out to us for help.

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.