Qidi Box open source makeover using Happy Hare
Bunny Box is the Qidi Box mod that allows you to ditch Qidi's closed-source, proprietary firmware and use Happy Hare to control your Box. With added support for Qidi-specific qirks such as the extruder hall sensor and above-extruder cutter placement, this allows Qidi Box use with Freedi and Kalico as well as using non-Qidi multimaterial units with Qidi printers. Strong defaults are provided, but the beauty of Happy Hare is that almost anything can be tweaked!
-
Open source alternative to Qidi's Box control
- No more .so files (you can update Python again)
- Full control over Qidi Box configuration
- Make the Qidi Box work on older Qidi and non-Qidi printers
-
Fully featured Happy Hare
- Tip forming - save filament by reducing waste
- the entire loading process can be tinkered with - increase loading speeds, change toolchange sequences, etc.
- Spoolman support for better filament management
- configurable LED effects depending on print / filament state
NOT SUPPORTED:
- RFID tags - maybe in the future, but honestly who cares?
- Qidi Happy Hare fork - works, but not yet pulled into mainline. The
bunnyboxbranch is used as the installation source. Q2 and Max4 users can install mainline Happy Hare. - Plus4 - works, tested on Qidi's 1.7.3, FreeDi (so stock Klipper) and Kalico (with minor issues still to be resolved).
- Q2 - testing in progress!
- Max4 - HACKERS WANTED - The Max4 firmware stack is materially more complex than Plus4/Q2 - it's split into multiple smaller .cfg files and has additional closed-source modules. Brave volunteers that own the Max4 are encouraged to reach out and help figure it out!
Should be compatible with Beacon/Cartographer mods.
- Printer screen is broken on stock Qidi firmware while in print - probably won't be fixed
- Qidi Studio sync is not working
- Power-loss recovery is disabled. Qidi's PLR depends on closed-source code (binary
.soon Plus4, shell scripts on Q2) and cannot restore MMU tool/gate state. The stockDETECT_INTERRUPTIONpopup ("Resume last print?") would auto-cancel on timeout and, even if accepted, would resume with the wrong filament. Ourbunnybox_macros.cfgoverridesDETECT_INTERRUPTIONto silently clear the flag so the popup never appears.
If you run into issues please report them in the issue tracker here. We are also on Qidi's Discord server in a dedicated thread if you want to chat.
We are for now relying on a fork of Happy Hare until our new features are pulled to mainline. This is necessary for handling of the hall effect sensor in the extruder of Qidi printers and Qidi's weird cutter configuration.
Refer to the Happy Hare documentation.
Do I need to flash the Qidi Box firmware?
No! Qidi Box already runs Klipper (Qidi's fork). Since the Box is a slave to the host (printer), flashing is not needed regardless of if you are connecting to a Qidi printer, a Qidi printer flashed with FreeDi or Kalico, or a non-Qidi printer. Nonetheless, you can flash it - the instructions are here.
How do I go back to the stock firmware?
Re-run the installer script for your printer (Plus4, Q2, Max4). If it detects an existing bunnybox install it will offer 2) Revert to stock, which restores printer.cfg and the stock macro file from the oldest backup_hh_* directory and clears mmu__revision. The current bunnybox state is preserved in a new backup_revert_<timestamp>/ so the revert itself can be undone.
To script the revert (no menu prompt), pass --revert to the installer — see the "Reverting to stock" section in each printer's README (Plus4, Q2, Max4).
If no backup_hh_* directory exists (e.g. the install was done manually), restore your own backups of printer.cfg and gcode_macro.cfg (or klipper-macros-qd/ on Max4), delete the mmu/ folder and bunnybox_macros.cfg from your config directory, remove the mmu__revision line from saved_variables.cfg, and restart Klipper.
How do I update without losing my tuning and calibration?
Just re-run the installer for your printer. When it detects an existing install and you choose 1) Reinstall / update, your config is no longer overwritten wholesale. The update is split between two installers that own different parts of the config:
Happy Hare's own installer handles everything it manages: the MMU logic files (mmu_cut_tip.cfg, mmu_sequence.cfg, mmu_software.cfg, …, which it installs as symlinks into ~/Happy-Hare), and your parameters (mmu_parameters.cfg, mmu_macro_vars.cfg, addon configs), whose values it carries forward as it upgrades them. Your calibration (mmu/mmu_vars.cfg) is left untouched. This is why the bundled copies of those files in this repo can look "behind" — they're only reference snapshots; the live versions come from the Happy Hare fork at install time.
Bunny Box's smart merge handles only the files Happy Hare leaves frozen and that Bunny Box truly owns: mmu_hardware.cfg (Qidi pins), mmu.cfg, the addon *_hw.cfg hardware files, and the top-level bunnybox_macros.cfg. For these it does a 3-way merge against a snapshot of what it last installed (printer_data/config/.bunnybox_base, recorded by a .bunnybox_manifest):
- Files you never edited but that changed upstream are updated to the new defaults automatically.
- Files you edited but that didn't change upstream are left exactly as you have them.
- Files where your edits and the new defaults overlap are merged; if they collide on the same lines the installer asks you per file whether to keep yours, take the new version, or write a
*.bbmergecopy with conflict markers to resolve by hand.
When run from a git clone it also prints a short changelog of the config commits between your installed version and the latest. A full backup is still saved to backup_hh_<timestamp>/ every time, so any update is reversible.
Note: the Bunny Box smart merge now ships on all three installers (Plus4, Q2 and Max4). Plus4 installs Happy Hare from the
bunnyboxfork; Q2 and Max4 install mainline Happy Hare. In all cases Happy Hare's installer owns the logic/parameter upgrade and Bunny Box's smart merge owns the hardware/macro layer.
Can you add support for my printer?
I only have a Plus4 and so can't really make other printers work. There are people with the Q2 who are using Bunny Box though, so that will likely come soon. For the Max4, I don't have one, so that will only come if someone else makes it. As for older ones/non-Qidi printers, you're on your own - I don't have one and think it's unlikely anyone will make one for you.
I'm a bit of a noob, can you help me?
Unfortunately I probably won't be able to help you much - I'm pretty busy and issues with Happy Hare are very difficult to diagnose without having phyiscal access to the machine and full knowledge of its configuration. If you decide to use this, be aware that you are expected to read Happy Hare documentation and understand what you are doing.
I changed the speeds in mmu_parameters.cfg, why are loads weird now?
Qidi's encoder is not that great unfortunately. It's measurement will vary widely depending on speed. At the same time you cannot really adjust its sensitivity parameter, since it is used for clog detetion during print (when the filament is moving slowly). In effect, you should calibrate the lengts of tubes after changing speeds (using the encoder calibration routire in HH).
My filament is grinding in the gears
Repeated load/unload cycles without any significant extrusion will cause the filament to grind in the gears. This is normal.
I'm getting false-positive runouts on filament changes!
You probably forgot to remove the runout from your [hall_filament_width_sensor] section in printer.cfg! Comment out the runout gcode and the pause on runout parameter, or remove the entire section.
I think my config is awesome, can I share it here?
Yes! Please create a PR. If you are able to make a distint configuration (e.g. for a different printer or compatible with stock Qidi gcode) please make a new folder for it and add a README describing the configuration and installation. Small configuration tweaks can be made to the base configs, but should be well described and justified.I love this mod! Happy Hare is great! How can I make it even better!?
Fit a [proportional filament sensor (PFS)](addons/PFS) in place of the stock filament tangle sensor — it gives Happy Hare analog sync-feedback for tighter gear/extruder syncing and smarter clog/tangle detection. See [addons/PFS](addons/PFS/README.md) for the build, wiring and calibration guide.PRs are welcome! Just make sure to describe what system you're working with (Qidi Klipper, Klipper or Kalico) and what other mods you have. We prefer strong defaults that should work with everyone here, even if they are not optimal. Go slower or more wasteful by default, let willing users tune it to their demands.