Setting Tool Offsets

From Jubilee
Jump to navigation Jump to search

This page is a draft

The goal is to set the XYZ offset values per nozzle such that all nozzles are aligned relative to each other. In other words, if we start at location (a,b,c) with Tool-0, change to any other tool, and return to location (a,b,c), the nozzle tips should be in more-or-less the exact same spot. In practice we can align tools within 0.02mm of each other in XY using the method below.

Offset Conventions

This setup adopts the idea of a control point, a point that everything is referenced off of. When no tools are active and the carriage is empty, this control point is the XYZ trigger point of the Z Probe. When a tool is picked up and fully retracted from the parking post, the control point becomes the tip of that tool. This behavior is done automatically as long as a tool table offset is defined for that tool with the G10 L1 command somewhere in the Duet's config file.

Tool offsets are unique to each tool (even tools of the same type!) and must be measured from your machine. In most cases, they cannot be taken directly from the CAD model because of real-world imperfections in fabrication and assembly processes. The rest of this guide is about how to measure your tool's XYZ offsets from the Z Probe.

Measuring Z offsets: Manual

This guide shows you how to set the tool height from the bed such that the lowest tip of the tool touches the bed at Z=0.

Note: Bed Temperature

Z offsets can be measured while the bed is either hot or cold, but the temperature of your bed must be stable. If it has recently been heated or cooled-down, wait 3 minutes for the temperature to remain stable at the setpoint before measuring the offset as the aluminum bed plate can expand vertically up to 0.1mm during this time.

Z Offset Detailed Steps

Have a look at the diagram below to get a sense of what we are measuring.


The offset value is the negative distance between tool tip and the limit switch.

First clear any existing offsets for the tool you wish to calibrate.

G10 P<tool_index> Z0

where <tool_index> is the tool index.

Lower the bed (increase Z) such that the tool will not crash into the bed when it’s picked up. Then pickup the tool. If it’s an extruder, heat it up to printing temperature and do a retraction (about 10mm) so it doesn’t ooze. Clean any residual ooze if any emerges. Now move it to the approximate center of the bed with

G0 X150 Y150

To measure the Z offset, select a piece of paper. With calipers, measure its average thickness by taking a few readings in various spots. Remember that number. Then slide it into the bed above the tool. Alternatively a feeler gauge provides an accurate, pre-measured, source of thickness.

Manually step the Z upwards until it just barely “snags” the paper. At this point, your tool is above the bed at a value approximately equal to the thickness of the paper.

Take a look at the head position in the top left corner of the machine browser interface. Take note of the Z value, example in the image below.

Z offset.jpg

To calculate the offset, subtract the thickness of the piece of paper (or feeler gauge) from the Z value just noted, then negate that value. i.e if the paper thickness is 0.20mm and the Z value is 3.40mm, then the offset is -(3.40 - 0.20) = -3.20mm

Now go to Settings -> System Editor -> config.g to edit the config file. Scroll down until you see the Tool Definitions section. You will see a line that looks like:

G10 P0 X-4.5 Y44.04 Z0     ; Set tool 0 offset from the bed.

Replace Z0 with Z-[Z offset value]. For example in the image example above, you would change the Z value to Z-3.20 (Don't forget the negative!)

Click save changes and reboot your machine.

Measuring Z offsets: Touchplate Automated

Not yet implemented.

Measuring XY offsets: Optical Manual

The goal is to find the XY offset from tool to ZProbe as shown in the image below.

Default extruder probe offset.png

But wait!! Sadly it is not sufficient to simply snag the values from the CAD model like above. Each tool is assembled slightly differently, so these values need to be measured on the actual tool itself.

Fret not! This process is very straightforward to do with a cheap USB Microscope.

Measuring and Setting Offsets with a USB Microscope

We use this microscope ($22) for calibration.

The General Idea

Our goal is to have the active tips of all tool move to the same position in the real world when commanded to move to the same position. Our coupling is repeatable, so the a single tool will be picked up in a consistent fashion. But all tools will be assembled slightly differently, so their “pickup” locations will likely all be different. We must dial in a constant offset setting for each tool such that they match each other.

To calibrate the tools against each other. We need a way to measure the differences in positions between tools. One way to do that is with a usb microscope pointed upwards to take pictures of nozzles in the same commanded position and then correcting this position by eye until the nozzles overlap each other. In practice, we can get XY nozzle alignment that’s better than 0.05mm using this method across tools.

To make this work, we need to ensure that the usb microscope position remains absolutely fixed to the frame when we change tools. The default usb microscope is pretty bad at doing this, so we made a better one that you can download and print.


The main idea is that we will use the first tool’s X/Y location as a reference (or datum) and calibrate the remaining tools relative to the first tool’s location.

Note that it is extremely important that the usb microscope does not move during this time. Tugging on the wire, leaning on the frame, and even moving the bed up-and-down during calibration will all mess with the calibration.

The Procedure

First check your existing configuration file and ensure that no XYZ offsets are being applied to any tools yet. We can identify these as commands that start with G10.

Pick up tool 0 and position it over a reference position. We chose 150x150 for this example.

Install the microscope onto the bed facing up. Adjust the Z height such that the microscope fits below the nozzle. Manually move the camera to the center of the bed. Focus the microscope on the tip of the nozzle. At this point, ensure that the microscope position is fixed to the bed. It is critical that the microscope does not move when these adjustments are being taken. For a more secure microscope holder, check out this 3D printable fixture (Note that some additional assembly hardware is required, including 6 D82-style magnets).

Take a picture of tool 0.

Now, pick up tool 1. Move it to 150x150 location, and take a second picture.

With a picture-viewing program, flip back-and-forth between the pictures of tool 0 and tool 1.


Use the image of tool 1 to decide what XY directions to move to such that both images have aligned nozzles. Note that one axis of the picture will be “flipped” since the microscope is upside-down pointing upwards. Delete tool 1’s picture.

Now adjust the nozzle slightly (0.1mm) in the XY directions you’ve chosen and take another picture for tool 1. Confirm that (1) the nozzle moved in the direction you wanted and (2) the distance between tool 1 and tool 0 is getting closer.

Repeat this process until tool 0 and tool 1’s images are aligned. At this point look at the XY location of tool 1 and subtract it from 150. This is your G10 XY offset.

Apply the offset directly into your GCode console.

G10 P1 X<some_value> Y<some_value>

Now move the tool to X150, Y150 using:

G0 X150 Y150

Confirm that this location is the correct location. If not, switch the signs of your offset, reapply it, and try again.

Repeat this process for any additional tools you may have, calibrating them against the location of tool 0. When finished, celebrate with a Victory GIF!

Nozzle Alignment.gif

Measuring XY offsets: Optical Automated

There is a script available that utilizes an upward looking camera and machine vision to automate the setting of tool offsets for 3D Print tools that have circular nozzles. The final output of the script is G10 commands ready to go into your config.g.

Optical Automated XY: Script Installation

Follow the instructions in the readme guide at

Also, OpenCV must be installed. One way to do that is the script available via this install script for Linux. However you choose to do it, do not install 'virtualized'. Most examples on the internet show a virtualized install.

Optical Automated XY: Running the script

Before you run for the first time:

  1. You will need either a USB microscope ($22), a USB camera, or a Raspberry Pi style camera. Many will work, if they are compatible with the operating system you're running TAMV from.
    Using an inexpensive USB microscope is highly recommended over using a webcam, due to the short distance between the camera lens and the nozzle which can cause focus and sensor noise issues with webcams.
  2. The camera must be fixed to the bed, so it is reachable by all tool nozzles.
  3. The camera must focus about 3 to 4 CM (about 1 to 1.5 inch) above the lens.
  4. Tool offsets MUST be set well enough that a tool can be placed over the camera. They only need to be accurate to 2mm or so.
  5. The printer MUST be capable of mounting each tool in succession, with no collisions, etc. Make sure your tool pickup and drop off macros adhere to a well-defined "clear zone" at the start/end of each tool change cycle.
    The calibration software will always move in X and then Y after tools are picked up to avoid collisions as much as possible.
  6. The script MUST run a graphical desktop environment, and never from a terminal alone. This can be a physical screen, or a VNC session. For more about VNC, see the [Raspberry Pi org instructions]{

Once all that is ready, run the script

cd ~/TAMV

It should require no arguments the first time it is run. It will guide you from there.

When the script finishes, it will give you a G10 for each tool. Put these in your config.g.

Measuring XY offsets: Vernier Manual