Happy Hare

Happy Hare is the original open-source filament changer controller for multi-color printing. Its philosophy is to provide a universal control system that adapts to your choice of MMU (Multi-Material Unit): switch hardware and the software transitions seamlessly with you.

It is implemented as a Klipper extension that drives the hardware directly and exposes everything else through ordinary Klipper macros. It helps to think of it in 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. If you can write a gcode_macro, you can customize how Happy Hare behaves.

Now in its fourth generation, Happy Hare brings the MMU, printer, slicer, spool inventory and user interface together as one polished system. 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.

Happy Hare supports most community-built MMU/AFC systems, including Box Turtle, ERCF, EMU, Tradrack, BTT ViViD, Night Owl, Angry Beaver, 3MS, 3D Chameleon, QuattroBox, PicoMMU, MMX, KMS, QIDI Box, and custom designs. Its capability-based architecture gives selector machines and modular gear-per-gate systems native motor and sensor control, with room to grow into multi-unit and mixed-hardware printers.

Pair it with KlipperScreen for Happy Hare for dedicated touchscreen control, or use the native Happy Hare panels in Mainsail and Fluidd.

Features

• Automated filament changing from gate selection and preloading through load, unload, eject and complete toolchanges, with bypass support for ad hoc single-spool printing.
• Flexible multi-MMU control for selector and gear-per-gate designs, including independent units, dissimilar hardware and multiple toolheads on the same printer.
• Guided calibration and validation for selectors, drive gears, encoders, bowden paths, toolheads, motors and sensors.
• Gate, slicer and tool-to-gate maps that track every filament and remap any slicer tool to any physical spool, backed by upload-time G-code preprocessing.
• Runout, clog and tangle protection using filament-path sensors, encoders and FlowGuard, with automatic EndlessSpool handoff to a replacement spool.
• Quality-focused filament movement with synchronized gear/extruder control, sync-feedback buffers, encoder flow verification, tip forming or cutting, smart purging and guided cold pulls.
• Spool intelligence including material, color, temperature and availability, full Spoolman/Filament Hub integration, and beta NFC/RFID tag reading for automatic spool identification.
• Active spool and enclosure hardware with eSpooler rewind/assist, functional LEDs, physical eject buttons, temperature-controlled fans and managed filament drying.
• Persistent state and deep diagnostics including calibration and map recovery, toolchange statistics, maintenance counters, dedicated logging, built-in help, hardware tests and soak testing.
• Complete UI control through native MMU panels in Mainsail and Fluidd, plus the dedicated KlipperScreen Happy Hare extension for touchscreen operation.
• Macro-level customization for parking, pause/recovery, load/unload sequences, print lifecycle hooks and other printer-specific behavior.

v3 or v4?

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/menuconfig installer. The module and configuration layouts are different, so v3 configuration files cannot be loaded by v4, or vice versa.

• New installations: use v4, the current generation and the home of new development. Start with the v4 documentation.
• Staying on v3: the mature v3 release remains available on the v3 branch; continue to use the v3 wiki and the v3 resources and videos.
• Moving from v3 to v4: read the v3-to-v4 upgrade guide before changing branches. The installer preserves a backup, but v4 must be configured as a fresh setup.

What's new in v4?

Happy Hare has always been exceptionally flexible. That flexibility also earned it a reputation for taking time and care to configure. v4 changes that.

The new Kconfig/menuconfig-based installer/configurator turns setup into a guided, top-down series of choices. Select your MMU, control board, toolhead and features; 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.

Underneath the easier setup is a modular, multi-unit architecture. Different MMU/AFC designs can run independently on the same printer, including machines with multiple toolheads, while still sharing the mature mapping, runout, Spoolman, NFC/RFID, encoder, eSpooler, LED and UI ecosystem Happy Hare is known for.

Multi-color printing worth the machinery

The setup and tuning journey can take patience, but this is why we do it. These prints from @igiannakas were produced with an ERCF v2, OrcaSlicer and Happy Hare.

Donations

Happy Hare is a labor of love rather than a funded project, but v4 and its new documentation site are a substantial undertaking:

If you have found value in Happy Hare and want to contribute, donations are welcome via PayPal. Any support goes toward improving the experience for whichever MMU/AFC you run. Thank you!

Getting help

Join the Happy Hare Discord, where there are channels for each MMU type and the main integrations. Bugs and feature requests can also be filed in the GitHub issue tracker.

For the fastest help, include klippy.log, mmu.log, the output of MMU_STATUS SHOWCONFIG=1, the exact error text, and a clear description of what was happening. Pictures or video are especially useful for physical problems.

Built with five years of MMU experience (and probably too much coffee)

Happy Hare is built on over five years of hands-on experience with many MMU designs, starting with ERCF, continuing through Box Turtle, and now the modular EMU system. Every new design brings another interesting challenge to solve—and another excuse to print something colorful.

Multi-color printing can be addictive and occasionally frustrating. Be patient, read the docs, ask the community when you get stuck, and remember to enjoy the machine you built.

Copyright (C) 2022-2026 Paul Morgan