Skip to content



Under development!


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

Pipette homing calibration


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


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.


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

Pipette volumetric calibration


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

Possible contents:

  • Measure the diameter of the pipette shafts.
  • Precision scale.
  • Tubes.
  • Calibration protocols.

Tip ejection post


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

Tool-changer calibration


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.


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


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
Parking coordinates
Tip ejection coordinates


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.


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


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/ 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/ 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 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


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


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


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


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.


Tip Box
Tube rack

Platform curbs


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

See issues:


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.