- Python 98.5%
- Shell 0.8%
- Makefile 0.6%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
1b11270cbc## Problem `config/base/mmu_hardware.cfg` renders each unit's `[mmu_espooler <unit>]` pin options numbered from 0 within the unit: `respool_motor_pin_0..N-1`, plus `assist_motor_pin_*`, `enable_motor_pin_*` and `assist_trigger_pin_*`. `MmuESpooler.__init__` looked them up by **global** gate number (`range(first_gate, first_gate + num_gates)`). On any unit after the first, none of the rendered options were read: - In the test harness, a two-unit BoxTurtle boots with unit1's `respool_gates` and `assist_gates` empty, so its espoolers never run. - On real Klipper, the unread options should make boot fail with "Option 'respool_motor_pin_0' is not valid in section 'mmu_espooler unit1'". That conclusion comes from reading `configfile.check_unused`; I haven't reproduced it on hardware, and the harness doesn't run that check. So the only multi-unit espooler setups that work today must have hand-edited sections using global numbers. `mmu_sensors.py` already uses the unit-local index (`lgate`). ## Fix Pin options are read as per-unit (0-based) numbering only when global numbering can't explain them: every index is below the unit's gate count, and at least one index falls outside the unit's global range `[first_gate, first_gate + num_gates)`. Otherwise the pre-existing global reading is kept, so nothing that worked before this PR changes meaning. Generated configs always list every gate from `_0` (blank pins included), so on a later unit they always read as per-unit. Internal pin names (`respool_<gate>` etc.) are unchanged. If every index fits both readings on a later unit (for example, a lone `respool_motor_pin_2` when unit1 owns gates 2–5), the global reading is kept and klippy.log gets a warning: > MMU: Pin numbering in [mmu_espooler unit1] fits both per-unit and global gate numbers; reading it as global (gates 2-5). For per-unit numbering list every gate's pins from _0 to _3, leaving unused ones blank The two numberings are identical on single-unit machines and on the first unit, so those configs behave exactly as before, with no warning. ## Test Two tests in `TestEspoolerPinsOnLaterUnit` (`test/test_mmu_espooler.py`): - `clone_across_units(BOXTURTLE)` boots with unit1's espooler set up on gates 4–7. This fails before the PR. - The review repro: unit0 has 2 gates and unit1 has 4 (global 2–5), and unit1's only pin is `respool_motor_pin_2`. It must still drive gate 2. This failed on the first version of this PR. I also checked by hand (not committed) that a unit1 section using global `_4.._7` names still gives gates 4–7 with no warning. `make test`: 3270 tests OK. Related: #1498 (MMU_ESPOOLER ALLOFF=1 on multi-unit machines) had to work around this bug in its test. 🤖 Generated with [Claude Code](https://claude.com/claude-code) |
||
| .agents/skills | ||
| .claude | ||
| .github | ||
| assets/images | ||
| components | ||
| config | ||
| extras | ||
| installer | ||
| lint | ||
| test | ||
| utils | ||
| .cspell.config.yml | ||
| .gitignore | ||
| .project-words.txt | ||
| AGENTS.md | ||
| CLAUDE.md | ||
| install.sh | ||
| LICENSE | ||
| Makefile | ||
| README-V3.md | ||
| README.md | ||
| ruff.toml | ||
Happy Hare
Universal Automated Filament Changer / MMU driver for Klipper
One driver. Every kind of MMU. A complete Klipper experience.
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.
Explore the Happy Hare v4 documentation
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
v3branch; 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:
|
~58,500 lines: driver code ~30,000 lines: installer/configurator ~7,000 lines: macros/configuration ~46,000 lines: 1,900+ automated tests ~19,500 lines: docs across 73 pages 260+ documentation images |
|
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.
❝
There once was a printer so keen,
To print in red, yellow, and green.
It whirred and it spun,
Mixing colors for fun,
The most vibrant prints ever seen!
(\_/)
( *,*)
(")_(") Happy Hare Ready
Copyright (C) 2022-2026 Paul Morgan