Sovol on mainline Klipper

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

System architecture#

A reference description of the Sovol Zero as shipped, captured from the running machine — host filesystem, Klipper config, MCU runtime, git remotes. It exists to support the migration: knowing exactly what hardware and software is in play, and which pieces are vendor-specific versus stock.

The Sovol Zero is a CoreXY printer, an industrialised derivative of the Voron 0, with a 150×150×150 mm build volume in a closed frame. It runs Klipper on a Linux host talking to multiple STM32 MCUs over CANbus. Internally Sovol calls it the “SV08 mini” — the vendor firmware package ships as SV08mini_Update_Package-*.deb, and it shares its CAN toolhead module with the SV08 Max — though it’s sold only as the Sovol Zero.

Building the firmware

Mon, 01 Jan 0001 00:00:00 +0000

Building the firmware#

The MCU firmware (Katapult + Klipper) can be built either on the printer’s own host or on a Mac / Linux box, then the .bin copied over. Both produce identical images — pick whichever is handy.

Toolchain#

On the printer host (the Sovol Zero board’s Allwinner H616, Debian aarch64)#

arm-none-eabi-gcc is already installed — it’s the vendor’s own build chain. Clone the sources and build in place; no extra setup, and none of the macOS quirk below:

Easy install

Mon, 01 Jan 0001 00:00:00 +0000

Easy install — for most people#

The clean-slate page bakes everything into the image offline, by hand. You don’t have to. There’s a friendlier path: flash a base image, let it come up, and answer a short wizard over SSH — the same first-run experience as any Armbian board. No ext4 editing, no debugfs.

Two facts make this easy on the Zero:

The board has a microSD slot, and the H616 boots SD before eMMC. So you can run the whole thing from a microSD — no reader, no pulling the module, no risk to the stock eMMC. Leave the eMMC alone as a factory backup, or move the system onto it later.
The first SSH login runs Armbian’s friendly setup wizard (armbian-firstlogin): it makes you change the root password, creates your user, and asks locale + timezone — right there in the SSH session.

Use the Sovobian image for all of these — it’s upstream Armbian CB1 with the 40 MHz eMMC overlay already baked, and it ships the 6.12.68 kernel where onboard Ethernet works out of the box. A plain BTT CB1 image drives the eMMC at 3× the validated clock (see the CB1 difference) — don’t use it.

KIAUH stack

Mon, 01 Jan 0001 00:00:00 +0000

The application stack via KIAUH#

Everything above Klipper — Moonraker, Mainsail, Crowsnest — is already stock upstream, so the fastest clean install is dw-0/kiauh. Clone it and install, in order: Klipper, Moonraker, Mainsail, Mainsail-Config, Crowsnest.

Point Klipper’s host at the same master checkout your MCUs were built from, with a venv built from its requirements.txt, and set [update_manager klipper] channel: dev in moonraker.conf so it tracks master.

Two post-install fixes#

Both come from experience on this board:

Over stock firmware

Mon, 01 Jan 0001 00:00:00 +0000

Runbook — migrating in place over the stock firmware#

The printer works and you migrate on top of it. The vendor OS stays, the application and MCU firmware move to upstream, and the OS is an optional last step. This is the incremental de-vendoring path.

Each step below is a link into the component that does the work — this page is only the order.

1. Back up everything first#

Vendor stack rsync, an SWD dump of the toolhead, and ideally a full eMMC image. The backups are what make every later step reversible. → Recovery: back up first

Flashing over SWD

Mon, 01 Jan 0001 00:00:00 +0000

Flashing over SWD with a Flipper Zero (DAP Link)#

The toolhead Katapult is request-only and can’t be recovered over CAN once an app is broken, so an SWD probe is the safety net. Any CMSIS-DAP probe works — an ST-Link V2 clone, or a Flipper Zero running the DAP Link app.

Verified scope. Everything here was tested only on the F103 toolhead, and only with a Flipper Zero (DAP Link app). An ST-Link should behave the same (it is standard SWD), and the H750 section below is reasoned, not tested. Corrections and additions are welcome — open a PR.

Klipper config

Mon, 01 Jan 0001 00:00:00 +0000

Translating the config to mainline#

The vendor printer.cfg doesn’t run as-is on upstream Klipper — a few sections depend on vendor-only firmware behaviour. Translate these off the vendor config; the rest carries over.

Eddy on software I2C#

The vendor ran the LDC1612 on hardware i2c2, but only because its F103 firmware carries STM32F1 hardware-I2C errata workarounds that mainline lacks; on mainline, hardware i2c2 throws START_NACK → shutdown. Use bitbang instead:

Toolhead pinout & SWD

Mon, 01 Jan 0001 00:00:00 +0000

Toolhead pinout & SWD header#

Transcribed from Sovol’s official pin definition (Motherboard/Extra_Pin_definition.pdf in Sovol3d/SOVOL-ZERO) — see that PDF for the full labelled board image. The toolhead MCU is an STM32F103 (extruder_mcu), board silk MINI-ZJB-V1.0.

Connectors#

Connector	Pins (as silk-screened)
Cooling fan	`24V` · PWM `PA6` · FG `PA1`
Fan (top)	`24V` · PWM `PA7` · FG `PA2`
Model fan	`24V` · PWM `PB0` · FG `PA3`
Nozzle thermistor	`PA5` · `GND`
Heating block	`GND` · `24V` · `PB1` · `GND` · `PA4`
Heater	`24V` · MC_HEATER `PB7`
24 V supply	`GND` · `24V`
Extruder motor	DIR `PA9` · STEP `PA8` · EN `PA11` · UART `PA12`
X-axis limit	`PA10` · `GND` · `5V`
Limit / sensor	`5V` · `GND` · `PC15` · `PC14`
Eddy current sensor	`5V3` · `GND` · `PB10` (SCL) · `PB11` (SDA)
Mainboard comm (CAN)	CANL · `GND` · CANH (CAN_R `PB8` · CAN_T `PB9`)
SWD header (silk `5V3 IO CK G`)	`5V3` = 3.3 V · `IO` = SWDIO (`PA13`) · `CK` = SWCLK (`PA14`) · `G` = GND

The eddy sensor connector exposes PB10/PB11. On mainline Klipper drive the LDC1612 over software I2C on those pins, not hardware i2c2 — see the Klipper config page.

Vanilla Armbian

Mon, 01 Jan 0001 00:00:00 +0000

Vanilla Armbian on the Sovol Zero board#

The Klipper migration leaves Sovol’s stock OS image untouched — Klipper lives in /home/sovol, so swapping the Klipper layer never rewrites the rootfs or the bootloader. For a fully vendor-free machine the last layer is the OS on the eMMC. This is the harder, destructive step (it rewrites the whole boot device).

This is a verified end-to-end recipe for vanilla Armbian on the stock 8 GB eMMC module — no custom OS build, no replacement module. The original Armbian-on-Zero walkthrough is asnajder/zero-config, which this builds on; where the two disagree (most notably on the 8 GB module), the difference is explained below.

With an eMMC reader

Mon, 01 Jan 0001 00:00:00 +0000

Runbook — clean-slate build with an eMMC reader#

The path a recovery or a fresh build actually takes: OS first, application on top, MCUs usually last — and often untouched, because layer 2 survived whatever killed layer 3. This is the order verified end-to-end on the reference machine.

1. Inventory your backups#

Minimum viable: the config set (git repo or any copy) and the MCU state. Already-mainline MCUs need nothing here; vendor MCUs need the firmware steps below. A full eMMC image makes this a restore instead of a rebuild. → Recovery

Clean-slate (eMMC reader)

Mon, 01 Jan 0001 00:00:00 +0000

Clean-slate install with an eMMC reader#

The cleanest OS path: pull the eMMC module, flash it offline in a USB reader, bake in everything first boot needs, and power up a configured machine. This is the exact sequence used to (re)build the reference machine — twice — so every step has survived contact with reality.

Prerequisites: the eMMC module in a USB reader, a Linux machine or VM for the offline edits (macOS cannot write ext4 — see the offline-edit note below), and the MCUs already on mainline Katapult + Klipper (see MCU migration). If the MCUs ran mainline before, they still do — layer 2 survives layer 3.

MCU migration

Mon, 01 Jan 0001 00:00:00 +0000

MCU migration — both MCUs onto mainline#

The clean way to put both MCUs fully on upstream Klipper — app and bootloader, no vendor bytes in the firmware. Build everything from the same Klipper master commit (see why master). The order is: build all four images, flash the toolhead once over SWD, then the mainboard over USB-Katapult.

Prerequisites#

An SWD programmer — ST-Link V2 (~$3 clone) or a Flipper Zero running the DAP Link app. Needed once, to bootstrap the toolhead: the vendor Katapult is request-only and can’t be recovered over CAN, so you flash a CAN-capable mainline Katapult onto the toolhead over SWD the first time, and never open the head again.
ARM toolchain — arm-none-eabi-gcc (already on the printer host) or brew install --cask gcc-arm-embedded on macOS. See Building the firmware.
openocd ≥ 0.11 for the SWD flash.
SSH access to the printer.

Back up first#

Before erasing anything, take your rollback — the SWD dump of the toolhead especially. The full backup checklist (vendor stack, SWD dump, eMMC image) is on the recovery page. The one that matters most here:

Plugins

Mon, 01 Jan 0001 00:00:00 +0000

Plugins and venv extras#

The add-ons this machine actually runs, on top of the stock KIAUH stack.

scipy — required by the eddy probe#

Install scipy into the Klipper venv:

~/klippy-env/bin/pip install scipy

Without it the eddy probe calibration fails. If PyPI stalls when downloading from the board, sideload the wheels — see troubleshooting.

sovol_codes — the knob-screen codes#

The vendor firmware shows numeric codes on the knob screen (101/103, the 60+ shutdown range); mainline shows human-readable messages. To keep the codes on upstream Klipper, install the opt-in sovol_codes.py plugin:

Recovery

Mon, 01 Jan 0001 00:00:00 +0000

Runbook — recovering a machine that won’t come up#

Route by what actually failed. Because layer 2 survives layer 3, most recoveries are narrower than they feel — a dead OS doesn’t touch the MCUs, and a bad app flash doesn’t touch the OS.

The backup checklist and the detailed rollbacks live on the recovery page; this is the routing.

The OS won’t boot#

The MCUs are fine. Rebuild only the OS, then reconnect.

Calibration

Mon, 01 Jan 0001 00:00:00 +0000

Calibrate and verify#

With both MCUs on mainline, the config translated, and plugins in, calibrate the eddy probe and motion, then prove it with plastic.

Eddy and tap#

Run in order, SAVE_CONFIG after each:

LDC_CALIBRATE_DRIVE_CURRENT
PROBE_EDDY_CURRENT_CALIBRATE — builds the freq→height table
PROBE_EDDY_CURRENT_TAP_CALIBRATE — sets tap_threshold

Belt tension#

Aim for ~110 Hz plucking the XY belts over their 150 mm span. (The Z belt is factory ~137 Hz, but that’s a 21.5 cm span — a different length, so don’t compare the two numbers.) Tighter than that only cleans up the shaper graphs on paper and adds ringing. Klipper’s belt similarity test is unreliable here — the head-mounted accelerometer is noisy at standstill from motor hold-current buzz, so its readings swing run to run. Check tension by ear or a phone tuner instead (Android works; iPhone noise suppression corrupts the reading).

In place, no eMMC reader

Mon, 01 Jan 0001 00:00:00 +0000

Reprovisioning the OS without an eMMC reader#

No reader, and you don’t want to pull the module? You can put a fresh OS on the eMMC from the running board. The trick is the microSD slot: the H616 boots SD before eMMC, so you boot a fresh image from a card and clone it onto the eMMC from there.

There is no shortcut over USB — the board exposes no USB-C / OTG port, so the usual sunxi-fel + U-Boot ums route to reach the eMMC over USB is off the table (see why FEL is out). SD-boot-and-clone is the only no-reader path.

Extras

Mon, 01 Jan 0001 00:00:00 +0000

Extras — optional hardware and practices#

Additions that are not part of the core migration but earned their place on a real machine.

USB WiFi dongle (when the onboard radio dies)#

The onboard RTL8189FTV is a known single point of failure — on this unit it died of PSU-inflicted causes (mmc: error -110 whilst initialising SDIO card on every boot, on stock firmware too, through ~21 attempts across two kernel stacks; software revival — power-cycling the chip via its GPIO, longer post-power-on-delay-ms, lower SDIO clock — changes nothing). If you see that signature, stop debugging and plug a dongle into one of the board’s USB-A ports.

Updatable Armbian

Mon, 01 Jan 0001 00:00:00 +0000

Keeping Armbian updatable#

The worry that an apt upgrade will “lose the dts” and break the eMMC is mostly unfounded, and the real constraint is narrower than it looks. This page separates the two.

Experimental in one place. Everything about why the kernel is held is confirmed and documented. The path off the hold (moving to a newer kernel and keeping onboard Ethernet) is not yet verified on the Zero — it’s flagged below. Take a full backup before testing it.

Recovery

Mon, 01 Jan 0001 00:00:00 +0000

Recovery and backups#

What makes every step in every path reversible, and how to get back a machine that won’t boot. Recovery is mostly a backup story: take the right snapshots before you touch anything, and a dead layer becomes a restore instead of a rebuild.

Back up first — the checklist#

Take these before erasing anything. They are what make each later step reversible.

The vendor stack (file-level, resumable rsync — not a raw dd over WiFi): vendor ~/klipper as a git bundle, ~/printer_data/config, ~/printer_data/build/*.bin, and the per-chip build configs ~/klipper/.config* (useful seeds even though their flash offsets are stale).

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshooting & tuning#

Things that bite when running a Sovol Zero on mainline Klipper, and how to clear them. Facts and fixes only — the full procedures live in the layer pages.

Flashing & CAN#

canbus_query / flashtool.py -q shows 0 nodes#

If Klipper is stopped, a query returning Total 0 uuids is normal — those tools enumerate only un-initialised / bootloader nodes, and a Klipper-configured app node does not answer. Read it as “everything is running its application”, not “the bus is dead”. Start Klipper (or put a node into its bootloader) to see it in a query.

Resources

Mon, 01 Jan 0001 00:00:00 +0000

Plugin & patches#

Two artifacts live as source in the repository, version-controlled and downloadable, and are documented here. They stay as code — the site describes them, the repo holds them.

`sovol_codes` — the knob-screen codes plugin#

The vendor Klipper fork shows numeric codes on the knob screen (101, 103, the 60+ shutdown range) by editing upstream core files in place — klippy/extras/homing.py, klippy/klippy.py, klippy/kinematics/corexy.py. That couples product UI to Klipper core and is the reason the printer is stuck on a squashed vendor snapshot instead of tracking upstream.

Sovol on mainline Klipper

Architecture

System architecture#

Building the firmware

Building the firmware#

Toolchain#

On the printer host (the Sovol Zero board’s Allwinner H616, Debian aarch64)#

Easy install

Easy install — for most people#

KIAUH stack

The application stack via KIAUH#

Two post-install fixes#

Over stock firmware

Runbook — migrating in place over the stock firmware#

1. Back up everything first#

Flashing over SWD

Flashing over SWD with a Flipper Zero (DAP Link)#

Klipper config

Translating the config to mainline#

Eddy on software I2C#

Toolhead pinout & SWD

Toolhead pinout & SWD header#

Connectors#

Vanilla Armbian

Vanilla Armbian on the Sovol Zero board#

With an eMMC reader

Runbook — clean-slate build with an eMMC reader#

1. Inventory your backups#

Clean-slate (eMMC reader)

Clean-slate install with an eMMC reader#

MCU migration

MCU migration — both MCUs onto mainline#

Prerequisites#

Back up first#

Plugins

Plugins and venv extras#

scipy — required by the eddy probe#

sovol_codes — the knob-screen codes#

Recovery

Runbook — recovering a machine that won’t come up#

The OS won’t boot#

Calibration

Calibrate and verify#

Eddy and tap#

Belt tension#

In place, no eMMC reader

Reprovisioning the OS without an eMMC reader#

Extras

Extras — optional hardware and practices#

USB WiFi dongle (when the onboard radio dies)#

Updatable Armbian

Keeping Armbian updatable#

Recovery

Recovery and backups#

Back up first — the checklist#

Troubleshooting

Troubleshooting & tuning#

Flashing & CAN#

canbus_query / flashtool.py -q shows 0 nodes#

Resources

Plugin & patches#

sovol_codes — the knob-screen codes plugin#

`sovol_codes` — the knob-screen codes plugin#