Cartographer - Phil1988/FreeDi GitHub Wiki
~ Thanks a lot and all credits to @git4tomd ~
Warning
You must be running FreeDi to use this guide. You must be using an X-Max 3 to use this guide. You should be using a Cartographer eddy probe. I don’t have any experience w/ Beacon. YMMV
Update FreeDi (as of April 2025 this is 1.42). Update using Mainsail. If you find you are still on 1.30 and Mainsail won’t show an update, you may need to manually update to 1.41 or greater. See: https://github.com/Phil1988/FreeDi/issues/174 Pay attention to the Discussion in the github. If you are running FreeDi and not reading the discussions when you have questions/issues, you are doing it wrong. Read the documentation. Review relevant discussions.
Preparation
Save your printer.cfg somewhere. Name it something that makes sense. Save your macro.cfg somewhere. Name it something that makes sense. You will be thankful you did this later when you get completely upside-down trying to get your Cartographer to work, and you just want to get back to printing some articulated dragon.
Hardware
Mount your Cartographer probe. This is well traveled. It needs to be 2.6 to 3.0 mm above your nozzle. I used this mount: https://www.printables.com/model/692991-qidi-x-max-3-beacon-cartographer-probe-low-profile
If you are unsure if you are 2.6mm - 3.0mm above the nozzle, print this (at a fine layer height) to measure: https://www.printables.com/model/1060868-cartographer-probe-nozzle-offset-tool/files
I have the newer Qidi nozzle, the version2.5. When I printed the tool above, I measured the height of the numbers from the bottom of the base and subtracted 1.5mm for the thickness of the Cartographer probe. What I found was the numbers were low by .15mm, so 2.4mm on the tool was actually 2.55mm. You should check yours. I found my nozzle was right between 2.4 and 2.6 indexes, so 2.5 + .15 = 2.65 which is within the specs from Cartographer.
About Cartographer
This guide is relevant to installing Cartographer Survey (Touch). It is NOT about installing Cartographer Classic (Scan). The difference is in the name, Touch touches the bed, Scan does not. While it sounds like a bad thing, Touch is much more accurate. You can read about that here: https://docs.cartographer3d.com/cartographer-probe/classic-vs-survey-touch
If you were using a non-conductive bed sheet, like G10/Garolite, you would have to use Cartographer Classic (Scan) since it could never let the nozzle touch the bed.
CARTOGRAPHER_TOUCH - macro that enables the Z offset of your nozzle and scanner coil to be automatically calculated.
Make sure Cartographer is the mounted within a range of 2.6 to 3mm above the tip of the nozzle.
Make sure your nozzle is clean! Remember the nozzle will touch the bed so anything below the nozzle may give inaccurate readings.
Consider installing a nozzle brush.
Be wary of updating Klipper! Make sure your configs don’t break after the update.
Configuration Guide
Klipper Setup
Follow Cartographer’s instructions here under Klipper Setup: https://docs.cartographer3d.com/cartographer-probe/installation-and-setup/installation/klipper-s etup
Just install the software and update mainsail.cfg then move to the instructions below.
Klipper Configuraton
I followed Cartographer’s instruction under Klipper Configuration: https://docs.cartographer3d.com/cartographer-probe/installation-and-setup/installation/klipper-configuation
But some items needed changes.
printer.cfg: Here are the steps I took. Things in bold are things I added/changed. Edit printer.cfg and after the [mcu] section add a new section:
[mcu scanner]
serial: /dev/serial/by-id/usb-Cartographer_614e_340022000E43304146393320-if00
That is not your serial device, that is mine. Go get yours (ssh in and look to see what your device is called) and change that line to match. This section needs to be added because we are going to reference the “scanner” in a few other areas of the file. Comment out the entire [probe] section, and add a [scanner] section:
[scanner]
mcu: scanner
# Offsets are measured from the centre of your coil, to the tip of your nozzle
# on a level axis. It is vital that this is accurate.
x_offset: 0 # adjust for your cartographers offset from nozzle to middle of coil
y_offset: 23 # adjust for your cartographers offset from nozzle to middle of coil
backlash_comp: 0.068508 # you will change this number later
# Backlash compensation distance for removing Z backlash before measuring
# the sensor response. (set to COco recommended number)
sensor: cartographer # this must be set as cartographer unless using IDM etc.
sensor_alt: carto # alternate name to call commands. CARTO_TOUCH etc
mesh_runs: 2 # Number of passes to make during mesh scan.
Near the Temperature sections, I added:
[temperature_sensor Cartographer_MCU]
sensor_type: temperature_mcu
sensor_mcu: scanner
min_temp: 0
max_temp: 105
My complete changed [bed_mesh] section:
[bed_mesh]
Speed:500
Horizontal_move_z: 5
mesh_min: 25,18 # Minimum position of the detection point
mesh_max: 305,300
probe_count: 30,30 # Number of measuring points - 6x6 - 7x7 etc.
algorithm:bicubic
zero_reference_position: 162.5, 162.5 # center of your bed
After I added the following section:
[safe_z_home]
home_xy_position: 162.5,162.5
# Example home_xy_position: 175,175 - This would be for a 350 * 350mm bed.
z_hop: 10
I added the following in [stepper_z], leave the other lines alone
[stepper_z]
homing_retract_dist: 0 # cartographer needs this to be set to 0
I kept my stock ADXL345 sensor settings. With the Cartographer, you now how 2 so you can choose which one to use.
# Only use ONE of the adxl345 sections below
# STOCK ADXL345
[adxl345]
cs_pin: MKS_THR:gpio13
spi_software_sclk_pin: MKS_THR:gpio14
spi_software_mosi_pin: MKS_THR:gpio15
spi_software_miso_pin: MKS_THR:gpio12
axes_map: -x, z, -y
# CARTOGRAPHER ADXL345
#[adxl345]
#cs_pin: scanner:PA3
#spi_bus: spi1
Now reboot your printer. You will probably get Klipper errors, that is somewhat to be expected.
Calibrate Probe
For the most part, follow the Cartographer guide here for calibration: https://docs.cartographer3d.com/cartographer-probe/installation-and-setup/installation/calibration
When it asks to position in the center of the bed, use 162.5 for the X and Y coordinate. You should walk through the section yourself. These are the commands I did, please don’t blindly punch these in:
PROBE_SWITCH MODE=touch
SAVE_CONFIG
G28 X Y
G0 X162.5 Y162.5
CARTOGRAPHER_CALIBRATE METHOD=manual
ACCEPT
SAVE_CONFIG
G28
PROBE_ACCURACY
CARTOGRAPHER_ESTIMATE_BACKLASH
(I did this in multiple areas and put average in BACKLASH_COMP)
BED_MESH_CALIBRATE
G28
(I removed the filament at this point and made sure the nozzle was
clean)
CARTOGRAPHER_THRESHOLD_SCAN
CARTOGRAPHER_CALIBRATE
SAVE_CONFIG
Modify start Macros
Add the following into your print start macro in macros.cfg
[gcode_macro G29]
variable_k:1
gcode:
{% if k|int==1 %}
BED_MESH_CLEAR
; Clear levelling data
BED_MESH_CALIBRATE ADAPTIVE=1 ADAPTIVE_MARGIN=5
; Start adaptive meshing
CARTOGRAPHER_TOUCH ; Perform touch probe
{% endif %}
If everything went well, you should be done.
Post install
If you use screws_tilt_adjust to level your bed, you will need to modify your printer.cfg file since the probe is in a different location now:
[screws_tilt_adjust]
#horizontal_move_z: 5
screw_thread: CCW-M4
speed: 300
# modified for Cartographer
#screw1: 8,32
screw1: 36, 9
screw1_name: front left screw
#screw2: 264,32
screw2: 290, 9
screw2_name: front right screw
#screw3: 264,286
screw3: 290,264
screw3_name: rear right screw
#screw4: 8,286
screw4: 36,264
screw4_name: rear left screw
Macro for brushing nozzle
Earlier I mentioned that the nozzle needs to be clean. I added the silicon brush sent with the Cartographer and stuck it on the plastic housing in front of the bed plate. I then modified the G29 macro to heat the nozzle and brush between the BED_MESH_CALIBRATE and the CARTOGRAPHER_TOUCH commands.
If you want to do this, take your time and make sure you are not going to hit the bed with the nozzle/hotend.
(modified G29 macro)
[gcode_macro G29]
variable_k:1
gcode:
{% if k|int==1 %}
BED_MESH_CLEAR
; Clear levelling data
BED_MESH_CALIBRATE ADAPTIVE=1 ADAPTIVE_MARGIN=5 ; Start adaptive meshing
#BED_MESH_CALIBRATE
; Nozzle silicone brush wipe section
M109 S150
G0 X25 Y-7 Z5 F10000 ; move over silicone brush
G0 X25 Y-7 Z-0.5 F10000 ; drop down below bed
G0 X55 Y-6 Z-0.5 F10000 ; brush right
G0 X25 Y-6 Z-0.5 F10000 ; brush left
G0 X55 Y-7 Z-0.5 F10000 ; brush right
G0 X25 Y-7 Z-0.5 F10000 ; brush left
G0 X55 Y-7 Z-0.5 F10000 ; brush right
G0 X25 Y-6 Z-0.5 F10000 ; brush left
G0 X55 Y-6 Z-0.5 F10000 ; brush right
G0 X25 Y-7 Z-0.5 F10000 ; brush left
G0 X25 Y-7 Z5 F10000 ; rise up above bed
G0 X162.5 Y162.5 Z5 F10000 ; move to center
; End Nozzle silicone brush wipe section
CARTOGRAPHER_TOUCH
{% endif %}
Links
https://github.com/Phil1988/FreeDi/wiki/Post-install-and-config-section https://docs.cartographer3d.com/cartographer-probe/installation-and-setup/installation https://docs.cartographer3d.com/cartographer-probe/troubleshooting https://openqidi.com/books/upgrades-updates/page/cartographer-probe-installation-on-vanilla-klipper https://openqidi.com/books/upgrades-updates/page/cartographer-installation-with-qidi-stock-firmware