Happy Hare: one Klipper driver for every multi-material unit

One driver, and the browser-extension mental model

Happy Hare is described as the original open-source filament changer controller for multi-colour printing, and the philosophy is stated as providing a universal control system that adapts to your choice of MMU, so that switching hardware means the software transitions with you.

The list of supported hardware is long and specific. The project says it supports most community-built MMU and AFC systems, naming Box Turtle, ERCF, EMU, Tradrack, BTT ViViD, Night Owl, Angry Beaver, 3MS, 3D Chameleon, QuattroBox, PicoMMU, MMX, KMS, QIDI Box and custom designs. The repository description also lists the Klipper-side names VVD, KMS and 3MS alongside the hardware units.

The architecture that makes this work is called capability-based, and it gives selector machines and modular gear-per-gate designs native motor and sensor control, with room to grow into multi-unit and mixed-hardware printers. That is the interesting engineering claim. Rather than one code path per MMU model, the driver works out what a given machine can do and drives it accordingly, so a selector that has to physically move a gate and a gear-per-gate design that has a motor per gate end up under one control model.

The implementation model is worth understanding because it determines how you customise it. It is a Klipper extension that drives the hardware directly and exposes everything else through ordinary Klipper macros. The analogy offered is web browser terms: Klipper is the browser and Happy Hare is an extension that adds a whole new capability without changing how Klipper works underneath. The practical consequence is that if you can write a gcode_macro, you can customise how Happy Hare behaves.

That last point is the key to the whole design. The extension does not hide behind its own configuration language, it participates in Klipper's.

v4 is a rework, and the upgrade path is not automatic

The version section is blunt about the upgrade, and any reader with an existing v3 setup needs to read it carefully.

Happy Hare v4 is a major rework, not a drop-in update to v3. It introduces a modular multi-unit architecture, a restructured Klipper extension, and a guided Kconfig and menuconfig installer. The module and configuration layouts are different, so v3 configuration files cannot be loaded by v4, or vice versa. That is a hard incompatibility, not a deprecation warning.

The project then gives three paths. For new installations, use v4, described as the current generation and the home of new development, and start with the v4 documentation. For staying on v3, the mature v3 release remains available on the v3 branch, with its own wiki and its own resources and videos in README-V3.md. And for moving from v3 to v4, read the v3-to-v4 upgrade guide before changing branches.

On the migration itself the project is reassuring but clear: the installer preserves a backup, but v4 must be configured as a fresh setup. So the backup is a safety net for your printer configuration and your spool data, not a way to skip the reconfiguration.

The version history in the repository is much shorter than the v3 to v4 gap suggests, with v4.1.0 tagged on 2026-10-13 and the last push on 2026-10-19, so v4 is the active line. The licence is GPL-3.0 with a LICENSE file at the repository root.

The Kconfig installer replaces the hand-edited configuration

The reason v4 exists is stated in a sentence that is unusually direct about a design flaw. Happy Hare has always been exceptionally flexible, and that flexibility also earned it a reputation for taking time and care to configure. v4 changes that.

The new Kconfig and menuconfig based installer turns setup into a guided, top-down series of choices. You select your MMU, your control board, your toolhead and your features, and Happy Hare applies sensible defaults, asks only the questions relevant to your hardware, validates the result, and generates the Klipper configuration for you. The same configurator makes later changes and upgrades predictable, without taking away the option to customize by hand.

That is a direct response to the flexibility cost. A system with as many hardware variants as this one inevitably ends up with a configuration file full of device-specific settings that a new user has to understand before anything works. Generating that file from a guided choice instead is the difference between an MMU project and an MMU debugging project.

The Makefile shows the machinery behind it. KCONFIG_CONFIG defaults to .mmu_config and is exported so it can be overridden, which is the standard Kconfig convention for where the chosen configuration is stored. The build has a guard around probing for menuconfig, with a comment explaining that menuconfig.py will crash if output-sync is enabled on certain systems, and that the console and test targets must stay in the list because --output-sync buffers a recipe's output until it finishes, which for an interactive prompt means no prompt at all.

The comment is a nice piece of engineering honesty. Silent interactivity bugs in build systems are notoriously hard to diagnose, and here the constraint is written down next to the code that would break.

What the feature set actually covers

The features list is long, so it is worth sorting by what a user actually does with the thing.

The core loop is automated filament changing, from gate selection and preloading through load, unload, eject and complete toolchanges, with bypass support for ad hoc single-spool printing. That last part matters practically, because a machine with a four-gate MMU still needs to print a single-colour job without the changer intervening.

The multi-MMU control is flexible across selector and gear-per-gate designs, including independent units, dissimilar hardware and multiple toolheads on the same printer. So a printer with two different MMU types bolted on, or two toolheads fed from different units, is within scope.

Then there is the safety and quality layer. Guided calibration and validation covers selectors, drive gears, encoders, bowden paths, toolheads, motors and sensors, which is the guided equivalent of a setup checklist. Runout, clog and tangle protection uses filament-path sensors, encoders and FlowGuard, with automatic EndlessSpool handoff to a replacement spool. Quality-focused filament movement covers synchronized gear and extruder control, sync-feedback buffers, encoder flow verification, tip forming or cutting, smart purging and guided cold pulls.

Spool intelligence is the feature that turns the MMU into an inventory system. It includes material, color, temperature and availability, full Spoolman and Filament Hub integration, and beta NFC and RFID tag reading for automatic spool identification. On top of that, active spool and enclosure hardware covers eSpooler rewind and assist, functional LEDs, physical eject buttons, temperature-controlled fans and managed filament drying.

Finally, the state and diagnostics layer: calibration and map recovery, toolchange statistics, maintenance counters, dedicated logging, built-in help, hardware tests and soak testing.

Where the control happens: macros, panels and KlipperScreen

The user interface story is a three-way split, and it is the part that decides whether the software is pleasant to live with.

The project says to configure it with a guided installer, control it from Mainsail, Fluidd or KlipperScreen, and let it manage the details from the first filament load to the last toolchange. Mainsail and Fluidd are the two web interfaces for Klipper, and Happy Hare has native MMU panels in both, so the primary control surface is a browser on your phone over your local network.

For a dedicated touchscreen, there is a separate KlipperScreen Happy Hare Edition extension maintained by the same author. The README also links the v4 documentation at moggieuk.github.io/Happy-Hare-Doc.

Underneath the panels, the macro layer is the extensibility story. The feature list includes macro-level customization for parking, pause and recovery, load and unload sequences, print lifecycle hooks and other printer-specific behaviour. Because everything is exposed through ordinary Klipper macros, a user can add their own parking behaviour, change what happens when a filament runs out mid-print, or hook into the print start and end sequence, without the project needing to anticipate every printer's requirements.

That is also why the browser-extension analogy holds up. The panels are the settings screen, the macros are the API, and the hardware control is the part you should not have to touch.

One detail in the feature list is worth singling out. The gate, slicer and tool-to-gate maps track every filament and let you remap any slicer tool to any physical spool, backed by upload-time G-code preprocessing. That solves a real annoyance in multi-material printing, where the tool order in the slicer file and the physical gate order in the printer rarely agree, and the fix is normally a post-processing step you have to remember to run.

The repository, the test suite, and the Raspberry Pi constraint

The repository layout shows a project that takes its testing seriously for a firmware-adjacent tool.

The top level has a Makefile, an install.sh, and the directories you would expect: components/ for the Klipper extension code, config/ for the configuration templates, installer/ for the Kconfig configurator, extras/ for optional pieces, lint/ for the linting setup with a ruff.toml, test/ for the test suite, and utils/ for helpers. There is also assets/ for the images, a README-V3.md for the previous generation, and both AGENTS.md and CLAUDE.md for agent-assisted development.

The Makefile is where the constraints show. Test files run in isolated Python processes, and the job count is four, with the comment explaining that four is deliberately both the default and the maximum for the Raspberry Pis on which contributors commonly run this suite. That is a decision made for the hardware the contributors actually have, and it is spelled out rather than left as a mysterious default.

The Makefile also handles the awkward details. The quiet build flag defaults to @ and the verbose flag is empty. The pip flags for the installer requirements are exported rather than passed on the command line, because install.sh forwards no make variables, and the comment gives the exact case where that matters: a PEP 668 python with no venv needs PIP_ARGS set to something like --user --break-system-packages.

There is a CSpell version pinned for the spellcheck target and CI, with a note to keep it compatible with Node versions commonly found on contributor machines, and a.cspell.config.yml with a.project-words.txt at the root, which is the usual arrangement for a project with a large vocabulary of hardware and tool names.

The unit test target takes a pattern, and the comment explains that a UT pattern skips the interactive picker, as do ALL=1 to run everything and LAST=1 to re-run the last selection, with the details in test/README.md.

Editorial conclusion

Happy Hare is a good pick for a Klipper user who has bought a community multi-material unit and wants it to work as a proper filament changer rather than as manual gate swapping, because the driver covers the whole path from gate selection through load, unload, eject and toolchange, with sensor based runout protection and spool inventory on top; it is the wrong pick if you are staying on v3 or moving from v3 to v4 casually, because the two generations use different module and configuration layouts and v4 cannot load a v3 configuration file, and before you upgrade you should read the v3-to-v4 upgrade guide and let the installer take its backup first.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. moggieuk/Happy-Hare on GitHub
4. README
5. Releases