Skip to content
Cartographer 3D

Updating Firmware

The update script handles almost every case: it detects whether you have a V3 or V4, whether it is on USB or CAN, and flashes the right file. Use the manual methods further down only if the script cannot detect your probe.

If your probe is not responding at all, or was never set up with the Katapult bootloader, go to Recovery via DFU instead.

Prerequisites

Section titled “Prerequisites”

You need the Cartographer firmware repository and Katapult on your Pi. Connect via SSH and run the following. It clones each repository if it is missing, or updates it if it is already there.

Terminal window
cd ~
if [ -d ~/cartographer_firmware/ ]; then
    echo "Cartographer Firmware Exists - Updating Repository"
    cd ~/cartographer_firmware/
    git pull
else
    git clone https://github.com/Cartographer3D/cartographer_firmware.git
fi
cd ~
if [ -d ~/katapult/ ]; then
    echo "Katapult Exists - Updating Repository"
    cd ~/katapult/
    git pull
else
    git clone https://github.com/Arksine/katapult.git
fi

Add both to moonraker.conf so they stay up to date. The Cartographer firmware entry is the same one used in Klipper Setup, so you may already have it.

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


[update_manager katapult]
type: git_repo
path: ~/katapult
origin: https://github.com/Arksine/katapult.git
is_system_service: False

Update script (USB or CAN)

Section titled “Update script (USB or CAN)”

Go to the firmware folder and run the script.

Terminal window
cd ~/cartographer_firmware
./fw_update.sh

The script shows a menu that you move through by pressing Enter.

It then tries to detect what type of probe you have, a V3 or a V4. It does this several ways: by reading your klippy.log, by querying Moonraker, and by querying the Cartographer API. Flashing the wrong firmware to a probe means recovering it via DFU, so the detection is deliberately thorough.

If your probe is on CAN you are asked which CAN interface it uses. Almost everyone uses can0, so press Enter. If you run the probe on a different interface, such as can1 or can2, type that name.

Select the firmware version. The latest is selected by default; type the number next to a different version if you need one.

Select Full or Lite firmware. Full is the default (option 1). See Full vs Lite firmware if you are unsure.

The script shows which firmware it will write, from which path, and over which interface.

It shows that information once more with a warning about what happens if you have chosen wrongly. If anything looks off, press N and ask on Discord.

Anonymous usage report

Section titled “Anonymous usage report”

After flashing, you are offered the chance to send an anonymous usage report. This is optional and nothing is uploaded unless you choose to submit it.

If you opt in, the report contains the probe identifier (USB serial or CAN UUID), probe version (V3 or V4), protocol (USB or CAN), firmware version and type (Full or Lite), and the CAN speed if applicable. It is used to understand real-world usage, such as USB versus CAN, Full versus Lite, and common CAN speeds, to guide development. Shared statistics are fully anonymised, identifiers are removed before analysis, and the data is never sold.

Manual update via Katapult over USB

Section titled “Manual update via Katapult over USB”

Use this if the script cannot find your probe but it is connected over USB and responds normally. You need to know whether you have a V3 or a V4; see Which version do I have?

Step 1 - Enter bootloader mode

Section titled “Step 1 - Enter bootloader mode”

The same step applies to V3 and V4.

Run this to put the probe into the Katapult bootloader. It finds the probe’s serial device for you.

Terminal window
CARTO=$(ls /dev/serial/by-id/ 2>/dev/null | grep -i cartographer | head -n 1)
if [ -z "$CARTO" ]; then
    echo "ERROR: No Cartographer probe found in /dev/serial/by-id/. Is it plugged in via USB?"
    exit 1
fi
cd ~/klipper/scripts || exit 1
~/klippy-env/bin/python -c "import flash_usb as u; u.enter_bootloader('/dev/serial/by-id/$CARTO')"

Once the probe is in bootloader mode it reappears as usb-katapult_… in /dev/serial/by-id/. The MCU name in that device name tells you the hardware version: stm32f042x6 is a V3, stm32g431xx is a V4.

Step 2 - Flash the firmware

Section titled “Step 2 - Flash the firmware”

Flash the latest Full USB firmware. The first line finds the Katapult device for you.

Terminal window
KATAPULT=$(ls /dev/serial/by-id/ 2>/dev/null | grep -i katapult | head -n 1)
cd ~/cartographer_firmware/firmware/v2-v3/survey/6.1.0
~/klippy-env/bin/python ~/katapult/scripts/flash_can.py -f CartographerV3_6.1.0_USB_full_8kib_offset.bin -d /dev/serial/by-id/$KATAPULT

For Lite firmware use CartographerV3_6.1.0_USB_lite_8kib_offset.bin. For a different release, change the folder and file name to match; the general form is:

Terminal window
~/klippy-env/bin/python ~/katapult/scripts/flash_can.py -f <firmware file> -d /dev/serial/by-id/<katapult device>

If it succeeds you will see output like this, and the probe reboots into the new firmware.

Manual update via Katapult over CAN

Section titled “Manual update via Katapult over CAN”

Use this if the script cannot find your probe but it is connected over CAN and responds normally. The probe must already be running CAN firmware; to move a USB probe to CAN see Switching Protocols.

Step 1 - Find the probe’s UUID

Section titled “Step 1 - Find the probe’s UUID”

If the probe is already configured, the UUID is the canbus_uuid value in the [mcu cartographer] section of printer.cfg (on the previous plugin it was under [mcu scanner]).

If it is not configured yet, query the bus. Note that this command does not list devices that Klipper is already connected to.

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

Step 2 - Flash the firmware

Section titled “Step 2 - Flash the firmware”

Replace <uuid> with your UUID, and can0 with your interface if it differs.

Terminal window
cd ~/cartographer_firmware/firmware/v2-v3/survey/6.1.0/
python3 ~/katapult/scripts/flash_can.py -i can0 -f CartographerV3_6.1.0_CAN_1M_full_8kib_offset.bin -u <uuid>

Files also exist for Lite (…_CAN_1M_lite_…) and for 500K and 250K networks (…_CAN_500K_…, …_CAN_250K_…). The file’s CAN speed must match the speed your bootloader and network are set to.

Once complete the probe reboots into the new firmware. If Klipper reports an MCU error afterwards, restart the firmware from the web interface.