Q2 Install Guide

Q2 Install Guide

This guide covers installing the AIO on a stock Qidi Q2.

---

Section 1 — Before You Install

Requirements:

• Qidi Q2 running stock Klipper firmware — legacy_mks or 01.01.02+ layout (see the firmware note below)
• SSH access to the printer — see SSH Guide if you haven't set this up yet
• Printer connected to your network with outbound HTTPS access to GitHub

Firmware layout note: The AIO supports both the legacy_mks firmware layout and 01.01.02+ firmware. Options 2 (Just Faster Printer) and 3 (Just Faster Box) automatically detect your layout and route to the correct install path — no separate menu needed. Option 1 (BunnyBox + HelixScreen) is currently legacy_mks-only. If you're unsure which layout you have, the installer will tell you on the status line.

On 01.01.02+ firmware the status line reads Q2 firmware 1.1.2 / qidi layout (unsupported) in red. That refers to the blocked addon and repair paths, not to options 2 and 3 — those work.

---

Section 2 — Which option do I pick?

Do you have a Qidi Box?

• No → Option 2: Just Faster Printer

  • Installs faster, cleaner macros. Keeps the stock Makerbase touchscreen UI. No multi-material support.

• Yes, and I want the full MMU stack (Happy Hare + HelixScreen) → Option 1: BunnyBox + HelixScreen

  • Installs Happy Hare MMU firmware (BunnyBox) and the HelixScreen LVGL touchscreen UI. The stock screen is replaced. Full multi-material printing with the Qidi Box.

• Yes, but I want to keep the stock screen and use the box as-is → Option 3: Just Faster Box

  • Same as Just Faster Printer but with box-aware macros active. The stock Makerbase UI stays. The Qidi Box AMS backend remains in control.

---

Section 3 — Running the Installer

SSH into the printer first:

ssh mks@<printer-ip>

Default password: makerbase

Then run the installer:

bash <(curl -fsSL https://raw.githubusercontent.com/Camden-Winder/Qidi-Q2-superuser/main/Q2/aio_menu.sh)

Do not run as root (sudo bash ...). The script elevates with sudo only where needed and enforces this.

The installer will show a disclaimer screen, then the main menu:

============================================
   Qidi Q2 Superuser - AIO Setup Menu (RC3.02)
============================================
  Just Faster: not found | BunnyBox: not found | Helixscreen: not found
  BoxWrite: off | Mainsail: not found
  Firmware: legacy mks layout
--------------------------------------------
  INSTALL
   1) Install BunnyBox & HelixScreen    (Q2 with Qidi Box)
   2) Install Just Faster Printer       (Q2 without Box)
   3) Install Just Faster Box           (Q2 with Qidi Box, no BunnyBox)
   4) Update Macros                     (re-fetch AOI macro files)
  UNINSTALL
   5) Revert to Backup                  (full uninstall + restore stock)
   6) Uninstall Mainsail                (remove web UI only)
  ADDONS
   7) Mainsail                          (web UI on port 100)
  INFO
   8) About
   9) Health Check / Run Verifiers
  TESTING
   10) Testing
   0) Exit
============================================
Enter selection:

Options 2 and 3 automatically detect 01.01.02+ firmware and route to the correct install path — there is no separate firmware submenu.

---

Section 4 — After Install

Option 1 — BunnyBox + HelixScreen: see Q2 BunnyBox & HelixScreen for post-install steps, including first-time MMU gear calibration.

Options 2 and 3 — Just Faster Printer / Just Faster Box: see Q2 Just Faster for post-install steps.

---

Section 5 — Maintenance & Addons

These can be run at any time from the main menu, regardless of which install path you chose — on legacy_mks firmware. On 01.01.02+ firmware, options 4 (Update Macros) and 7 (Mainsail) are currently blocked and will show an "Unsupported Qidi Q2 firmware layout" message; only options 2, 3, 5 and 9 are available there.

Option 4 — Update Macros

Re-fetches the AOI-owned macro files for your installed group (BunnyBox, Just Faster Printer, or Just Faster Box) plus all four KAMP files. Useful after a new AOI version ships with macro improvements. You will be prompted to confirm before any files are overwritten. It reads your install group from aoi.ini and refuses to run if that file is missing.

Option 6 — Uninstall Mainsail

Removes the Mainsail web UI, its nginx site, and the camera proxy. nginx itself is removed only if the AIO installed it; if nginx was already present it is left in place and simply reloaded.

Option 7 — Mainsail

Installs the Mainsail web interface, accessible at http://<printer-ip>:100. The stock Qidi UI on port 80 is not affected. Includes a camera proxy so the webcam stream works in Mainsail.

Option 8 — About

Prints the AIO version, the detected firmware layout, your home and config paths, the stock display stack, and a description of the install paths and of what the Health Check covers. Read-only — safe to run on any firmware.

Camera streaming (installed with Mainsail)

Camera setup is not a separate menu entry — it runs automatically as the last step of the Mainsail install. It installs a ustreamer-camera systemd service on /dev/video0 bound to 127.0.0.1:8080, adds a location /webcam/ proxy to the Mainsail nginx site, and adds a [webcam] section to moonraker.conf so Mainsail's camera panel connects through port 100.

Two prompts you may see:

• "Existing webcam(s) already registered in Moonraker" — if Moonraker already knows about a camera, the AIO warns you before adding a second entry. Answer no to keep the existing one.
• "Camera config is from an older AIO release … Migrate camera now?" — shown when you re-run option 7 on a printer set up by an older AIO release, whose camera config used the wrong URL paths and had no nginx proxy. Answer yes to rewrite it to the current format.

Camera support has not been tested on 01.01.02+ firmware and will warn you if you try it there.

Idle fan shutdown

The 5-minute idle fan and heater shutdown is now built into all install paths by default — no separate addon step is needed.

---

Section 5b — Testing (option 10)

Option 10 opens a submenu of diagnostic and compatibility tools. Entries 3–9 are 01.01.02+ compatibility probes and are read-only or self-reversing. Two entries are destructive, and both are reached by a single number press:

• 1) Force Snapshot Capture — overwrites ~/aio_config_backup/ with your current config. If you run this after installing, your stock snapshot is gone and Revert to Backup can no longer return you to stock. Do not use it unless you know exactly why you need it.
• 2) Force Config Restore — rsync --delete from the snapshot over your live config.

Both ask for confirmation first, but take care not to mis-key 1 when you meant 10.

• 10) Patch HelixScreen Dashboard Layout — the only entry a normal user needs. Re-applies the HelixScreen widget layout if panel_widgets was missing when HelixScreen was installed. See Q2 BunnyBox & HelixScreen for when this happens.

---

Section 6 — Reverting

Option 5 — Revert to Backup uninstalls everything the AIO installed and restores your config from the ~/aio_config_backup/ snapshot taken on the very first AIO run. This gets you back to factory stock, including re-enabling the stock Makerbase UI. If that snapshot is missing or empty, the revert refuses to run rather than restore a partial state.

After reverting, run FIRMWARE_RESTART from the Klipper/Moonraker console — the AIO does not restart Klipper for you. Then check the touchscreen to confirm the stock UI comes back up cleanly. The Health Check runs automatically at the end of every revert.

On 01.01.02+ firmware, Revert to Backup is blocked

As of RC3.02, option 5 refuses to run on the 01.01.02+ / qidi layout and prints Blocked action: Revert to Backup. This is deliberate: revert_to_backup was written for the legacy mks layout. It runs the mutating repair path that this firmware is otherwise protected from, and it forces the boot target to graphical.target — where 01.01.02+ ships as multi-user.target. Running it left the printer on the wrong boot target.

If you are on 01.01.02+ and need to get back to your stock config, use Testing → 2) Force Config Restore, which restores your config from the same ~/aio_config_backup/ snapshot without touching services or the boot target. It will not undo service-level changes, so if you installed HelixScreen you will also need to re-enable the stock display stack by hand:

sudo systemctl unmask qidi-client
sudo systemctl enable --now qidi-client

A layout-aware revert for this firmware is a known gap and is tracked in the repo's HANDOFF.md.