Q2 BunnyBox HelixScreen

Q2 BunnyBox & HelixScreen

---

What is done?

The main features of this install are Bunny Box and Helixscreen (see below). Other features are

• Faster print_start start (compatible with Bunny Box)
• Better print_end
  • Lowers the bed to 5 mm above the bottom
  • Begins a timer for idle fan shutdowns that leaves the box on
• Optionally disables unused processes so the system runs better (you are prompted at the end of the install)

Before You Start — this install needs you at the printer

Be physically at the printer before you start option 1. Partway through, the installer switches the display over to HelixScreen and then stops, waiting for you to complete HelixScreen's first-time setup wizard on the touchscreen:

HelixScreen is running its first-time setup wizard on the printer screen.
Please walk to the printer, complete the wizard, then return here.

  Have you completed the HelixScreen startup wizard? [y/N]:

The install will not continue until you answer y, and it will keep re-asking until you do. If you kick this off over SSH from another room, you will hit a hard stop here.

Do not answer y before you have actually finished the wizard. The installer checks HelixScreen's settings.json for panel_widgets immediately afterwards, and if the wizard has not written it, it skips the dashboard widget layout patch and you get a degraded home screen. To fix that afterwards, choose option 10 (Testing) from the main menu, then 10) Patch HelixScreen Dashboard Layout.

Re-installing over an existing BunnyBox

If BunnyBox / Happy Hare is already installed, option 1 stops and offers three choices before doing anything:

  1) Upgrade       — keep hardware configs, update firmware macros
  2) Fresh install — erase all MMU files and start completely clean
  0) Cancel

Pick 1) Upgrade unless you specifically want to start over — 2) Fresh install purges every Happy Hare / BunnyBox file, including your MMU hardware configuration under ~/printer_data/config/mmu/, and you will have to set the box up and calibrate it again. Anything other than 1 or 2 cancels.

If the installer instead finds only partial BunnyBox leftovers (a stale mmu/ directory, orphaned mmu_*.py extras, and the like) it lists them and asks whether to remove them for a clean install.

After Install

The installer backs up your config and runs the BunnyBox and HelixScreen installers. After it finishes:

1. Run FIRMWARE_RESTART from the HelixScreen terminal or Fluidd console.

2. From the AIO menu, run option 9 — Health Check to verify everything loaded correctly.

3. First-time only — calibrate the MMU gear steppers for each gate:

   1. Mark the filament at the MMU entry point with a pen
   2. Run MMU_CALIBRATE_GEAR GATE=0 LENGTH=100 from the console
   3. Measure how far the filament actually moved (in mm)
   4. Re-run with the measured value: MMU_CALIBRATE_GEAR GATE=0 LENGTH=100 MEASURED=<mm>
   5. Repeat steps 1–4 for each gate (GATE=1, GATE=2, etc.)

   For the full calibration walkthrough, see the upstream Happy Hare MMU Calibration guide.

4. If prompted "Would you like to disable unnecessary processes? (recommended)", answering yes is safe for normal Q2 use. See Q2 FAQ for exactly what it disables.

The screen switches to HelixScreen partway through the install, just before the wizard prompt — not after the FIRMWARE_RESTART. If the screen is black, re-run the installer; it detects and fixes the display service state.

Firmware note: BunnyBox + HelixScreen is currently legacy_mks-only. On 01.01.02+ firmware, use Just Faster Printer or Just Faster Box instead.

What is BunnyBox?

BunnyBox is a community firmware replacement for the Qidi Box (the multi-material unit that comes with the Q2). It's built on top of Happy Hare, which is the same MMU management layer used by projects like ERCF and Box Turtle.

Compared to Qidi's stock box firmware, BunnyBox gives you:

• Faster and more reliable filament loading and unloading
• Better error recovery when jams or runout events happen
• Full control over every parameter of the MMU system
• Compatibility with HelixScreen's UI widgets (lane status, spool display, etc.)

BunnyBox requires HelixScreen. The stock Qidi touchscreen UI does not support it.

BunnyBox Documentation

Mainsail is required for box controls

When using BunnyBox, you also need to install Mainsail (option 7 in the AIO menu — option 6 is the uninstaller) to get on-screen controls for the box. The stock Qidi UI (and Qidi's fork of Fluidd) only recognizes Qidi's own software talking to the box hardware — it does not detect or display controls when BunnyBox is managing the box instead. HelixScreen handles touchscreen controls, but Mainsail's web interface is what gives you the equivalent of Qidi's box panel for BunnyBox.

If you skip the Mainsail install, BunnyBox will still function correctly via macros and HelixScreen, but you'll be missing the web-based box control panel.

---

What is HelixScreen?

HelixScreen is a replacement UI for the Qidi Q2's touchscreen.

Compared to the stock Qidi screen software, HelixScreen gives you:

• A cleaner, more customizable home screen layout
• Native support for BunnyBox lane and spool status
• Faster access to common actions (nozzle clean, bed level, etc.)
• Regular updates from an active development team

HelixScreen Documentation

---

Day-to-day usage

Once BunnyBox and HelixScreen are installed, normal printing works the same way — slice in Orca, send to the printer, and hit start. The differences show up in how the box system behaves.

Tool changes mid-print

Tool changes are handled automatically from slicer-generated tool change commands. BunnyBox manages the entire sequence — unloading the current filament, loading the next, purging, and resuming the print. You don't need to do anything.

For best results, tip forming can be tuned for your filament. The recommended starting point is this video: Tip Forming Guide (YouTube) For advanced tuning, see the Happy Hare Tip Forming documentation.

Jam recovery

When a jam or runout is detected, HelixScreen surfaces the error on screen. Most recovery steps are available directly through the on-screen prompts — you typically don't need to manually run G-code for standard recovery. Follow the prompts on screen.

Checking lane status

The home screen widget shows which lane is loaded and displays spool color and material if you have Spoolman set up. See Spoolman for filament tracking setup.

---

Bypass gate for TPU or direct-drive filaments

The bypass gate lets you feed filament directly into the extruder, skipping the MMU gears entirely. This is useful for flexible filaments like TPU that don't feed well through the MMU.

To use it:

1. Select the bypass gate in the BunnyBox / Happy Hare UI
2. Once bypass is selected, the UI will show Load EXT — use this to load filament directly into the extruder
3. To remove it, use Unload EXT

Recommended: Top Spool Holder for Flexibles

When printing TPU or other flexibles via bypass, routing the filament from the top of the printer reduces tight bends that cause jams. This printable top spool holder is designed specifically for the Q2 and works with risers too:

Q2 Flexibles Top Spool Holder – The Mi3 Channel

Notes:

• If you have an encoder, clog detection still works in bypass mode
• Compression/tension sensors are disabled in bypass since the gear stepper isn't involved
• After using bypass, manually select a managed gate before your next MMU print — the UI may not deselect bypass automatically between jobs

---

Adaptive bed leveling

The AIO macro files use Qidi's G29/G31/G32 wrappers:

• G31 — enables adaptive bed leveling (default state after install). Every PRINT_START will call G29, which runs a KAMP adaptive mesh over the print area.
• G32 — disables adaptive bed leveling for the next print only. PRINT_START will load an existing default mesh profile instead of running a new mesh (if no default profile exists yet, it calibrates one and saves it). Useful for fast test prints or debugging.

G32 is not sticky: PRINT_END runs G31 at the end of every completed print, so adaptive meshing re-arms itself automatically. Run G32 again before each print you want to skip meshing on. You only need to run G31 manually if you ran G32 and then cancelled or never started the print — it takes effect immediately for the next print, no restart needed.

KAMP saves the adaptive mesh to the kamp profile (not default). Your manually-saved default mesh is not overwritten by print-start meshing.