LUNAROPS · OPERATIONAL UPLINK 100% UPTIME 1,247d POSTS 893 JEFF.MOON@LUNAROPS.DEV UTC --:--:--

Klipper Input Shaping

16 min read 3D Printing
3d-printingklipperinput-shapingresonancefirmwarehardware
Contents

There is a particular kind of 3D-printing ugliness called ringing — the rippled echo that appears just past every sharp corner of a print, where the moving toolhead has tried to change direction faster than the frame can absorb the inertia, and the frame vibrates a few cycles before settling. For thirty years the cure was simply to move slower: print at acceleration low enough that the frame never excited its own resonance, accept whatever speed that bought you, and live with it. Klipper’s input shaping turned that compromise into an engineering problem with a clean answer: instead of slowing the toolhead down, send it a shaped motion command whose vibrations cancel the frame’s resonance by destructive interference. The math is not new — it comes from a 1990s control-systems literature on crane operation and robotic arms — but applying it to consumer 3D printers required moving motion planning off the dollar microcontroller on the printer and onto a Raspberry Pi where the heavy computation could happen. The result is one of the most consequential firmware shifts in hobby 3D printing this decade: a $300 Ender 3 with a shaped Klipper config prints meaningfully cleaner at 200 mm/s than the same printer on Marlin did at 50 mm/s. This post walks what input shaping actually does, how an ADXL345 accelerometer campaign tells you the frequencies you need to cancel, why the extruder gets its own separate treatment via pressure advance, and the honest setup complexity Klipper adds in exchange for the speed.

The Resonance Problem

A 3D printer’s frame is a mechanical system with a natural resonance frequency, the same way a tuning fork or a guitar string has one. When the toolhead accelerates, the whole moving assembly — the carriage, the hotend, the belts, the rails — wants to behave like a mass on the end of a spring. The “spring” is the slight flex in the belts, the rails, the frame itself, and the bed; the “mass” is everything moving. Push the mass suddenly in one direction and the system overshoots a little, returns, overshoots a little less, returns, and so on, decaying over a handful of cycles. The frequency of those cycles is the resonance frequency — typically 30–80 Hz for a typical bedslinger, often higher for CoreXY or motion-system-light designs.

That oscillation is invisible at low acceleration because the toolhead is moving so slowly the position errors are smaller than the layer width, but at high acceleration it becomes the dominant visible artifact:

   command:        ┌──────────                  what nozzle does
                   │
                   │
                   │                            ┌──╱╲───╲─╱─╲─╱─╲─╲╱─
   real nozzle     │              vs.           │   ╲╱     ╲    overshoot
   position    ────┘                            │            ringing decay
                                                │
                                       ────────┘
                  (low accel:                    (high accel:
                   nozzle tracks                  nozzle overshoots, oscillates
                   command closely)               at frame's resonance frequency)

Each oscillation cycle deposits plastic at slightly the wrong place, and you see it as ridges parallel to the move direction immediately after the corner. Slower acceleration prevents the excitation in the first place; faster acceleration makes it worse. The whole game of high-speed printing prior to input shaping was tuning acceleration low enough to keep ringing tolerable.

Input Shaping: Cancel the Vibration, Don’t Avoid It

The insight from the control-systems world is that you do not have to slow down to avoid exciting resonance. You can instead send a sequence of acceleration commands carefully timed so that the vibrations they each induce cancel each other by destructive interference. The simplest version — the ZV (Zero Vibration) shaper — replaces a single sharp acceleration with two smaller accelerations, one immediately and one delayed by exactly half a period of the resonance frequency. The first acceleration starts the frame oscillating; the second is timed to land on the opposite phase of that oscillation and cancel it out. Net result: the frame ends up at the new speed without ringing.

   ZV INPUT SHAPING (simplified)

   wanted accel:    █  full step                      observed ringing
                    └────────                         ─╱╲───╱╲──────

   shaped accel:    ▌   ▌                             observed:
                    └─┬─┘                             ─    smooth, no ring
                      half-period of resonance

Mathematically, shaping is a convolution: take the input acceleration profile and convolve it with an impulse train whose impulse spacing is determined by the resonance frequency. The output is a motion profile that, played through a resonant system, produces no net oscillation. This is the same math as comb filtering or destructive interference in any other domain; it just happens to apply to a mass on a belt.

Klipper implements several shapers with different trade-offs:

Shaper Impulses Robustness to frequency error Smoothing penalty Best fit
ZV 2 Low (must hit resonance freq closely) Minimal Cleanest if frequency is well known
MZV 3 Moderate Small Good general-purpose default
EI (Extra Insensitive) 3 High Moderate Variable frequency or temp drift
2HUMP_EI 4 Very high Larger Two distinct resonance peaks
3HUMP_EI 5 Very high Largest Multiple peaks, complex frames

The trade-off is one of robustness versus smoothing. A ZV shaper cancels vibration perfectly at exactly its tuned frequency and leaves residual vibration if the actual frequency is off by even a few percent. An EI shaper cancels vibration over a wider band of frequencies but at the cost of slightly more smoothing — the motion is less crisp, corners are very slightly rounded, fine detail is mildly softened. For most printers, MZV is the right default: enough robustness to handle some frequency drift (the resonance frequency moves slightly as the printer warms up, as belts age, as you add accessories), low enough smoothing to keep prints sharp.

Why This Needed a Raspberry Pi

The reason input shaping arrived on consumer printers when Klipper did, and not earlier, is that doing the convolution math in real time at hundreds of millimeters per second is genuinely demanding. Traditional firmware like Marlin runs entirely on the printer’s microcontroller — typically an 8-bit AVR or a modest 32-bit ARM — which is busy doing real-time step generation and has little spare CPU for kinematics math. There simply was not room.

Klipper splits the firmware into two pieces. A small piece runs on the printer’s microcontroller and does nothing but generate step pulses on a precise schedule. The rest — kinematics, lookahead, acceleration planning, shaping — runs on a companion Raspberry Pi (or any Linux SBC) connected via USB or UART. The Pi has plenty of CPU to do the convolution math, lookahead over a long buffer of moves, and stream pre-computed step timings to the MCU. The split is the key architectural trick that makes input shaping possible on hardware that costs ten dollars.

This same architectural choice gives Klipper other wins (web UI via Mainsail or Fluidd, OctoPrint integration, easy slicer configuration), but input shaping is the headline. A printer with the same mechanicals and motors that ringed at 70 mm/s on Marlin can reliably print at 200+ mm/s on Klipper with shaping enabled, because the shaping handles the resonance problem that previously forced the speed cap. This is not marketing; it is a direct consequence of the math.

Measuring Resonance: The ADXL345 Campaign

To shape correctly, Klipper needs to know the resonance frequency of each axis of your printer. There are two ways to find it: visual tuning by printing test towers (slow, eyeball-based, imprecise), or by attaching an ADXL345 three-axis accelerometer to the toolhead and bed and letting Klipper sweep the axes through a frequency range while recording the resulting vibrations. The accelerometer method is faster, more accurate (±0.5 Hz), and works on both axes in about two minutes. It is the right approach.

The ADXL345 is a tiny digital accelerometer chip that costs a couple of dollars on a breakout board. It connects to the Pi (or to your printer’s MCU if it has a free SPI bus) via four wires. The most common setup: mount the breakout temporarily to the toolhead with a 3D-printed bracket, run shielded wires back to the Pi’s SPI header, configure Klipper to know about it, and run two G-code commands.

A working config snippet in printer.cfg:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

[mcu rpi]
serial: /tmp/klipper_host_mcu

[adxl345]
cs_pin: rpi:None

[resonance_tester]
accel_chip: adxl345
probe_points:
    100, 100, 20    # X, Y, Z in mm — center of the bed at safe Z

[input_shaper]
# values filled in after calibration
shaper_freq_x: 0
shaper_freq_y: 0
shaper_type: mzv

Then in the Klipper console:

TEST_RESONANCES AXIS=X
TEST_RESONANCES AXIS=Y

For each axis, Klipper executes a controlled frequency sweep — moving the toolhead back and forth on the named axis at frequencies from about 5 Hz to 133 Hz — while recording acceleration from the ADXL345. The data is written to a CSV file. A bundled Python script processes the CSV, finds the resonance peaks, and recommends shaper parameters:

~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o ~/printer_data/x.png
~/klipper/scripts/calibrate_shaper.py /tmp/resonances_y_*.csv -o ~/printer_data/y.png

The PNG output is the actual deliverable: a spectrum plot of resonance amplitude versus frequency, with the recommended shaper type and frequency annotated. A typical bedslinger shows a clear peak somewhere between 30 and 60 Hz; a CoreXY often shows a peak in the 50–80 Hz range. You take the recommended frequency, fill it into printer.cfg, restart Klipper, and the next print uses shaped motion.

Two important practical points:

  • Measure under realistic conditions. Resonance changes when the bed is heated, when there is filament loaded, when the bed Z position is different. Run the calibration with the printer warm, the bed at the height you typically print at, and ideally with a representative load on the toolhead.
  • Re-calibrate after mechanical changes. Adding a new fan, swapping the hotend, tensioning the belts, swapping the bed — anything that changes the moving mass or the frame stiffness changes the resonance. The calibration is not a one-time event for the life of the printer.

For a deeper measurement campaign, you can also mount the accelerometer to the bed rather than the toolhead and measure bedslinger-specific resonances (which are usually different from X-axis resonance because the bed mass and the toolhead mass are different). For a proper printer calibration cookbook of which input shaping is one piece, the resonance measurement is one of the more rewarding steps because the visible improvement after configuration is immediate.

Pressure Advance Is a Separate Problem

While input shaping deals with the frame and toolhead resonance, the extruder has its own dynamics problem that is not solvable by motion shaping. When the extruder pushes filament into the hotend, the filament compresses slightly between the gears and the nozzle — the whole filament-and-melt assembly acts like a soft spring. When extrusion stops or starts, that spring takes a moment to relax or load, which means actual flow rate from the nozzle lags the commanded flow rate. The visible artifacts are:

  • Blob at the start of an extrusion. When the extruder starts pushing after a non-print move, the pressure in the melt has to build up before flow begins; if the motion has already started, the early part of the line is under-extruded, and the moment pressure catches up the rest of the line is slightly over-extruded.
  • Tail at the end of an extrusion. When the extruder stops, the melt pressure does not collapse instantly; residual pressure continues to ooze for a moment, leaving a small blob.
  • Round-cornering. On sharp direction changes, the extrusion volume per unit length should change, but the pressure lag makes it sluggish.

Pressure Advance is Klipper’s separate compensation for this: it commands the extruder to push slightly ahead of the motion to pre-pressurize the melt for upcoming extrusion, and to retract slightly to bleed pressure when extrusion is about to stop. The tunable parameter, conventionally called pressure_advance (in seconds), is the amount of “lead time” applied. Typical values: 0.02–0.06 s for direct-drive extruders, 0.4–0.7 s for Bowden setups (where the compressible length of filament between gears and nozzle is much longer).

Pressure advance and input shaping are separate problems with separate tunings. Input shaping touches X/Y/Z motion to cancel frame ringing; pressure advance touches E (extruder) motion to fix flow-rate lag. Klipper applies both simultaneously, but they are calibrated independently. Klipper does not shape the extruder for the same reason it pressure-advances rather than shapes it: the extruder problem is dynamics of the molten plastic, not mechanical resonance.

Tuning pressure advance is a separate test-print campaign — usually printing a pattern of vertical lines at varying PA values and finding the one that produces the cleanest start/end. Klipper ships a test G-code macro for this and there are slicer-generated test patterns from Mainsail, OrcaSlicer, and Klipper’s documentation. The tuning is in line with the broader process of dialing in a printer — incremental, prints-based, with measurable convergence.

What This Costs You to Set Up

The honest setup-complexity picture. Klipper plus input shaping is not a five-minute upgrade.

Hardware adds. A Raspberry Pi (or any Linux SBC — an old Pi 3B+ works fine, a Zero 2 W is the budget choice), a power supply for it, a microSD card, and an ADXL345 accelerometer breakout. Most converted printers also need a USB cable to the printer’s MCU, or rewiring to use UART if you go that route. Total parts cost: $40–80 if you do not already have a Pi.

Software setup. Flash a Klipper image (the easiest path is KIAUH, the Klipper Installation And Update Helper, which scripts the whole install on Raspberry Pi OS). Configure printer.cfg for your specific printer — most popular printers have community-maintained configs you start from and tweak. Flash a Klipper firmware image to the printer’s MCU; this part is the most likely to trip beginners (the original Marlin firmware is overwritten, and a wrong serial port or pin map produces a non-functional printer until you fix it). Plan on a half day for first-time setup.

Calibration campaign. Input shaping requires the resonance measurement above. Pressure advance requires its own test print. Bed mesh, PID tuning, e-steps, retraction — all the usual calibration steps still need to be done. You will print a lot of test patterns. This is normal Klipper onboarding and takes most users a weekend of fiddling to converge.

Maintenance. Klipper updates often. Mainsail or Fluidd web UIs update independently. Klipper’s tight coupling between firmware on the MCU and Klipper host means version mismatches require a re-flash of the MCU firmware; the web UI usually walks you through this but it is something else to watch. Network access to the Pi is now mandatory for the printer to function, so put it on a stable network — bad Wi-Fi at the printer means pauses and disconnects mid-print.

Failure modes Klipper introduces. A Pi SD card that wears out leaves your printer non-functional. A Wi-Fi outage during a print can pause it. A bad Klipper config file silently breaks specific moves and may not surface until the middle of a 12-hour print. None of these are common, but they are failure modes Marlin did not have. The reading print failures playbook still applies, but with a few new categories specific to a Pi-as-brain architecture.

For a hobbyist who tinkers, this is acceptable cost. For someone who wants a printer that just prints and is rarely opened, Klipper’s added surface area is real. Some of the best modern slot-in printers (Bambu Lab, Prusa MK4) achieve high-speed printing with vendor-specific firmware that internally implements input shaping (and other compensations) without exposing the Klipper-level configuration to the user. Those are the right answer for someone who wants the speed without the tuning.

When It Is Worth It

The honest decision framework on whether to convert a printer to Klipper for input shaping:

  • You have a $200–500 printer (Ender 3, Voron build, Sovol, etc.) and want it to print fast. Yes. The conversion takes a weekend and the printer ends up printing 2–4x faster at noticeably better quality than it did on Marlin. This is the home-court win for Klipper.
  • You already have a Prusa MK4 or Bambu Lab printer. No. Those printers already implement equivalent compensations internally with vendor support. The marginal gain from going to Klipper is small, and the maintenance cost is real.
  • You are starting fresh and choosing what to buy. Honestly: a Bambu Lab A1 mini or P1S is probably faster to good prints than building a Klipper conversion from scratch. The “best DIY printer experience” niche has moved upmarket toward Voron self-builds, and the “cheap printer that prints well” niche has moved toward vendor-firmware machines that already include input shaping.
  • You want to understand the system. Klipper is the most educational printer firmware in widespread use. The configuration file is plain text, every behavior is documented, and the system rewards understanding. If learning is part of the goal, run Klipper.

This is a similar tradeoff to the resin-vs-FDM workflow decision: the technical capability is real but the operational tax is also real, and the right answer depends on which axis you optimize for. Klipper plus input shaping is a serious upgrade for tinkerers, marginal-to-irrelevant for owners of modern vendor-firmware machines, and a learning experience worth its own weight if you want to understand how a 3D printer turns G-code into accurate motion.

Verdict

Input shaping is the single most impactful firmware feature in hobby 3D printing this decade because it directly attacks the trade-off that defined the field for thirty years: you used to have to choose between speed and surface quality, and now you do not. The math is clean — convolve the acceleration profile with an impulse train tuned to your printer’s resonance, and the destructive interference cancels the ringing instead of preventing it — and Klipper made that math affordable by moving motion planning off the dollar microcontroller and onto a Raspberry Pi that has the headroom to do the convolution at print speed. The ADXL345 measurement campaign turns the tuning from eyeball-based test-tower printing into a two-minute frequency sweep with a clear PNG spectrum at the end. The MZV shaper is the right default for most printers; EI is worth it when frequencies drift; pressure advance handles the separate problem of extruder pressure lag and gets its own tuning. The honest cost is real setup complexity — a Pi, an accelerometer, a Klipper image, a re-flash of the printer MCU, a weekend of calibration prints, and Wi-Fi reliability you did not need before — and it is well worth it on a cheap printer (Ender 3 class) that you want to print fast, less obviously worth it on a Bambu Lab or Prusa MK4 that already implements equivalent compensations under the hood, and absolutely worth it if learning how the system works is part of the point. The technology that used to require a $2,000 industrial printer to print fast and cleanly is now a weekend’s worth of fiddling on a $40 of accessories. Treat it as the engineering it is, do the measurement campaign properly, and the printer you already own becomes the printer you wanted.

Sources

Comments