Overview

a full real-time run of TAMV for 4 tools on a Jubilee

TAMV GUI has finally arrived. Check out it over on GitHub!

In order to achieve the highest possible precision when using multiple tools, Danal Estes graciously created the Tool Alignment with Machine Vision (TAMV) and Z Tool Align with Touch Plate (ZTATP) programs that allow us to correctly determine both XY and Z offsets for multiple independent tools on a toolchanger platform. For the Jubilee community, an updated version is maintained with slight enhancements as the current version referenced in this wiki, and you can always access the original release by Danal here.

TAMV = Tool Alignment with Machine Vision

TAMV is a fully automated process that uses a camera to calculate XY tool offsets set with G10 L1 tool offsets that go in config.g to correctly set the XY alignment for correct tool-to-tool behavior when printing.

ZTATP = Z Tool Align with Touch Plate

ZTATP is a partially automated process that uses a touch plate to calculate Z tool offsets also set with G10 L1 tool offsets that go in config.g to correctly set the Z alignment for tool-to-tool correct behavior when printing. It also sets the bed-to-tool-zero spacing!

For information on ZTATP, check out the Jubilee ZTATP Wiki Page.

Download the latest Jubilee TAMV files on GitHub.

Special note to AVOID MACHINE DAMAGE

TAMV will move your tools around in ways that may be different than day-to-day printing.

In particular, if your camera is anywhere beyond the Y coordinate of the parking stalls for other tools, collisions could occur. To ensure this does not happen, two things must be true:

TAMV expects a tool change, as initiated by a T0 or T1 or so forth, will not cause a collision, no matter where the tool is when the tool change initiates.

It is entirely possible that your tool change macros do not ensure this today, particularly when a ‘current tool’ is beyond the Y line of the parking stalls at the moment a tool change is initiated.

TAMV itself will always “manhattan move”, that is move in square blocks, and will move X (only!) first, then Y (only!) as required to get FROM wherever the tool is after a Tx, TO the camera.

If (big IF) your tool change macros end with the tool at a ‘safe Y’, then ‘Manhattan moves’ will always prevent collisions. In fact, this form of move is best practice within your tool change macros.

Please read this section for more information.

Requirements

Rasberry Pi 3B or 4B, with USB attached camera (no Picam at this time).
Almost any webcam with auto-exposure and the ability to focus within a few centimeters of the lens will work. Logitech C270 is one that is known to have a threaded lens and a case that can be removed and replaced with a printed case.
A Duet printer, reachable from the Pi by network, running V2 or V3 firmware
May run on Duet3+Pi; does NOT require that configuration, run on any Pi.

Useful Links for TAMV

Installation steps for TAMV

What you’ll need before you start

A Raspberry Pi with a working installation of Raspbian, with an internet connection from the Pi
Your SUDO user of choice (default is usually the “pi” user) and SUDO password (default is “raspberry”) with SSH login
An SSH client of your choosing, such as Windows 10 built in ‘winterm’ and ‘ssh’ or install PuTTY
A VNC client of your choosing, such as VNC Viewer

Enable boot to desktop and VNC for your Raspberry Pi

Login via SSH to your Raspberry Pi and and run the Raspberry Pi config tool using the command: sudo raspi-config

Select “3 Boot Options”

Select “Desktop / CLI”

Select “Desktop”

Now from the main menu, select “5 Interfacing Options”

Select “VNC”

Confirm that you would like to enable VNC server by selecting “Yes”

You’ll get a confirmation that the VNC server has been enabled

Select the “7 Advanced Options” from the main menu
Select “Resolution”
Select “DMT Mode 16 1024x768” or any other resolution you’d like
Once you’re done, reboot the Raspberry Pi!

Connect to the Raspberry Pi using VNC Viewer on Windows

Launch VNC Viewer on your computer, and select “File” -> “New connection…”

Enter the IP address or network name of your Raspberry Pi in the “VNC Server” field, and give this connection a name to identify it in the VNC viewer connection list

Right-click on the new connection you’ve just created and select “Connect”

You’ll be connected to your Raspberry Pi and prompted for a username and password. Use your SUDO login credentials (most commonly the Pi user) and click “Log In”

Welcome to the Raspbian desktop! Your background and interface may vary depending on the version of Raspbian you have running on the Pi

Install the TAMV script

Launch a new “Terminal” process to access the CLI (Command Line Interface) of your Pi
Run the following command from the prompt, which will clone the GitHub repo to the current folder you’re in: git clone https://github.com/HaythamB/TAMV.git
Once the clone is done, you’ll need to switch to the new folder using: cd TAMV and then run the installation script using: ./install_opencv.sh This will install all the required dependencies and libraries for TAMV to run on your machine, and should take less than 15 minutes on a Raspberry Pi 4 with 4GB of memory. If the script won't run for some reason, type chmod a+x ./install_opencv.sh to make it executable and try running it again.
TAMV is installed, move on to the next step to get it up and calibrating.

Updating TAMV

Launch a new “Terminal” process to access the CLI (Command Line Interface) of your Pi
cd TAMV
git pull
All done.

If, for some reason, you fail to update using GIT, then simply save your config/settings.json file somewhere, then delete the entire TAMV folder, and re-download it and run again.

(pending) Webcam mounting and TAMV preparation

Preliminary steps

Mount webcam somewhere fixed on the bed using gluestick/double sided tape OR on the frame in a spot where the nozzle of the tool can be positioned over the lens.
Shorten webcam focal distance to about an inch away from the lens (webcams are generally set up for longer focus distances so this would probably necessitate opening up the camera shell and manually turning a focus ring)
Heat nozzles and clean up all nozzles from gunk and filament blobs to enable correct nozzle circle detection in TAMV.
Make sure they cool. You don’t want to ‘drool’ on the camera!
Set tool active and standby temperatures to 0 before running TAMV again to avoid drooling.

(pending) Running TAMV calibration for the first time

Run TAMV with no arguments. This MUST be on a VNC session, not ssh (because you have to see the graphic image).
cd
cd TAMV
python3 ./TAMV.py
Connect to your printer using the on-screen prompts (the green connect button at the top left of the application screen).
Jog your Jubilee Z probe into view of the camera and align it to save as your control point. (Alternatively, you can use the auto-CP detection function to do this automatically). Save your CP.
Select which tools to align using the checkboxes next to the tool designations on the right hand side of the screen.
Start calibration!

Once calibration is completed, the new measured offsets are already applied to your machine and saved using an M500 command to your config-override.g. You need to make sure the last line of your config.g contains an M501 command for this feature to be active on a Duet controller.

(pending) Post calibration checklist

Remove webcam from build plate
If you have already manually aligned Z, time to print!

Troubleshooting

Failed to connect to printer

Make sure you're using an IP address (preferred connection method) or a valid local network name.
Make sure your machine's axes have all been homed. TAMV will disconnect from the machine if this isn't valid.
In TAMV/config/settings.json, make sure the printer key entry contains a "default":1 key pair. If not, then please add it using standard JSON notation.
In TAMV/config/settings.json, make sure the printer key entry contains a "nickname": "printer nickname" key pair. If not, then please add it using standard JSON notation.

Failed to detect nozzle

If you are having issues getting the program to find the nozzle, you may need to adjust the lighting or focus of the camera.
Additionally, you need to make sure that the nozzle is clear of any filament. You can heat up the extruder before you start the TAMV script and do a slight retraction (~E-5) or brush material away if needed too.
If you're using nozzles with an opening of 0.6mm or larger, TAMV may have difficulty detecting them. There's a feature coming soon that will you to tell TAMV which tools have large nozzles and will adjust detection automatically as needed.
If TAMV consistently fails to detect your tools, try starting your calibration runs with the microscope slightly further away from the tool, which will blur the nozzle slightly. This sometimes helps in detection.

USB microscope common problems

If you're facing intermittent disconnects of the microscope while running TAMV, try running the microscope by connecting it through a powered USB hub. The current draw for the LED ring on the microscope sometimes overwhelms Raspberry Pi USB bus drivers, and causes it to error out. In this scenario, you cannot access the USB microscope again until you reboot the Pi.
In your settings.json file, located in the TAMV/config folder, see if the value for the key "video_src" is set to 0 or 1. Default for first connected USB camera should be 0 under Windows and Linux.
Also in settings.json, make sure the camera key entry contains a "default":1 key pair. If not, then please add it using standard JSON notation.

TAMV

Contents