Klipper Setup

Quick overview of the steps needed to setup the Cartographer3D Klipper plugin

If you are updating to the NEW Cartographer plugin, then it is necessary to remove parts of your old config to avoid Klipper errors. Therefore it is recommend to back-up your config to reference later. It is necessary to remove all instances of [scanner] from your printer.cfg, this INCLUDES any from the SAVE_CONFIG section at the bottom of the printer.cfg. Once you have done this save the file and you will return to the file directory.

Now open the moonraker.conf file, here you want to remove the old Cartographer Plugin update section, you added when you installed the old plugin.

Once you save and restart you will get a Klipper error for Unkown Pin Probe, this is normal and you can proceed to installation of the Klipper plugin below.

Installation Klipper plugin

A script has been made to simplify the process of installing the plugin.

The defaults assumes that klipper is in ~/klipper and the klippy-env is in ~/klippy-env. This should be standard on KIAUH and MainsailOS.

Run this command via SSH to install, customizing the paths if needed.

curl -s -L https://raw.githubusercontent.com/Cartographer3D/cartographer3d-plugin/refs/heads/main/scripts/install.sh | bash -s -- --klipper ~/klipper --klippy-env ~/klippy-env

Download the Cartographer Firmware Repository

You should download the Cartographer firmware repository to update your probe to the latest compatible firmware. Run this command via SSH to install.

cd ~
git clone https://github.com/Cartographer3D/cartographer_firmware.git

Configure Moonraker Update Manager

Modify your moonraker.conf file, via the web interface with the following.

[update_manager cartographer_plugin]
type: python
channel: stable
virtualenv: ~/klippy-env
project_name: cartographer3d-plugin
is_system_service: False
managed_services: klipper
info_tags: desc=Cartographer Plugin

[update_manager Cartographer Firmware]
type: git_repo
path: ~/cartographer_firmware
is_system_service: False
origin: https://github.com/Cartographer3D/cartographer_firmware.git
primary_branch: main

Configure Klipper

Below are the minimum, required, options listed. Except for the temperature_sensor blocks, you can omit those if you don't want to monitor temperature.

You will need to adjust this config for your printer and your probe, this is done by modifying the sections labeled `<blank>`

You MUST configure your homing of G28 to home in the middle of your bed, for example if you're using endstops you should add

[safe_z_home]
home_xy_position: 150, 150 # This should be for the CENTRE OF YOUR BED.

Documentation for safe_z_home here. If you're using sensorless, you may need to setup a [homing_override] details available here

[stepper_z]
endstop_pin: probe:z_virtual_endstop
homing_retract_dist: 0

[mcu cartographer] # See https://www.klipper3d.org/Config_Reference.html#mcu
# Remove either the serial or canbus_uuid line dependant on your setup.
serial: <blank>
canbus_uuid: <blank>
restart_method: command # Not needed for probes using CAN. 

[cartographer]
mcu: cartographer
x_offset: <blank> # This is the offset of your probe from the nozzle tip, to the centre of the coil.
y_offset: <blank> # This is the offset of your probe from the nozzle tip, to the centre of the coil.
verbose: no # For extra output

[bed_mesh]
zero_reference_position: <blank>, <blank> # The centre of your bed. 
speed: 300
horizontal_move_z: 3
mesh_min: <blank>, <blank> # The first probed coordinate, nearest to the origin. This coordinate is relative to the probe's location.
mesh_max: <blank>, <blank> # The probed coordinate farthest from the origin. This is not necessarily the last point probed, as the probing process occurs in a zig-zag fashion. As with mesh_min, this coordinate is relative to the probe's location.
probe_count: 20, 20
adaptive_margin: 10
mesh_pps: 0,0 # Disable interpolation - mesh is probably dense enough

[temperature_sensor cartographer]
sensor_type: temperature_mcu
sensor_mcu: cartographer
min_temp: 5
max_temp: 105

[adxl345]
# Select 1 of the cs_pin below depending on the probe you have. 
# Having the wrong one selected will cause an Endless Bootloop
# Cartographer V4 has int2 connected to the probes PA1 pin
cs_pin: cartographer:PA3 # For Cartographer V3
cs_pin: cartographer:PA0 # For Cartographer V4
spi_bus: spi1

[resonance_tester]
accel_chip: adxl345
probe_points:
    <blank>, <blank>, 20 # Fill out the blank with x and y coordinates where you want to run the resonance test.

Finding the Serial or UUID

Note, you need to replace the serial path or UUID with your probes serial path or UUID, this can be found by running the following commands

For USB based probes

ls /dev/serial/by-id/*

For CAN based probes

If you order a CAN Probe it will have it's baud rate set at 1,000,000. Make sure your system matches that.

~/klippy-env/bin/python ~/klipper/scripts/canbus_query.py can0

Take note of either the Serial ID or the UUID.

Update your probe

Now your probe is in your configuration, it is advisable to update the probe to the latest firmware version available to you. Instructions on how to update your probe are available here.

Calibration

Cartographer provides two methods of homing. We recommend always using the default scan method for general homing and using CARTOGRAPHER_TOUCH_HOME after all levelling has been done, just before your print starts.

Continue with Scan Calibration and Touch calibration.