⚠️ Run these commands on your printer’s host, not your local computer.
SSH into your Raspberry Pi, BTT CB1/CB2/Manta, or similar host. For all-in-one printers (Creality K1, K2 series, Flashforge Adventurer 5M/Pro), SSH directly into the printer itself as root.
Note: Both bash and sh work. The installer is POSIX-compatible for BusyBox environments.
KIAUH users: HelixScreen is available as a KIAUH extension! Run kiauh and find HelixScreen in the extensions menu, or use the one-liner above. See scripts/kiauh/ for details.
Pre-flight checks: On AD5M and K1, the installer validates that Klipper and Moonraker are running before proceeding. If either is missing, you’ll get a clear error message explaining what’s needed.
After installation, the setup wizard will guide you through initial configuration.
Upgrading from an older version? If HelixScreen keeps showing the setup wizard after an update, see UPGRADING.md for how to fix configuration issues.
HelixScreen does not have to run on your printer. You can install it on any supported Linux device and have it drive a display while it talks to your printer’s Moonraker over the network. This is ideal when the printer sits on the floor and you want the screen at your desk, or when your printer’s stock panel can’t be replaced (some QIDI models).
Common setups:
A spare Raspberry Pi (3/4/5, Zero 2 W, CM4) with a touchscreen, sitting at your desk
A mini PC or x86 box with an HDMI touchscreen
Your desktop, running the app in a window (macOS or Linux) for monitoring
How it works: HelixScreen is a Moonraker client. It only needs network access to your printer’s Moonraker instance (port 7125 by default) — it does not need to run on the same machine as Klipper.
Steps:
Install HelixScreen on the device that will drive the display, using the Quick Start one-liner or the platform section that matches that device (e.g. a Raspberry Pi uses the MainsailOS steps). Install it on the screen device, not the printer.
Make sure the device is on the same network as your printer and can reach it — from the device, ping <printer-ip> should succeed.
On first boot, the setup wizard reaches Step 4: Moonraker Connection. Enter your printer’s IP address (not localhost), for example 192.168.1.50. Leave the port at the default 7125 unless you’ve changed it.
The wizard tests the connection, then discovers your printer’s capabilities as usual.
Point it at Moonraker, not Mainsail/Fluidd. HelixScreen connects to Moonraker’s API (port 7125), not the Mainsail/Fluidd web interface. You do not need Mainsail or Fluidd installed on the screen device at all.
To change the host later, go to Settings > System > Host, or edit moonraker_host in settings.json.
Note: A remote screen controls the printer the same as an on-printer screen would. Features that require running on the printer (for example, HelixScreen taking over the printer’s own physical panel, or on-device WiFi configuration in the wizard) don’t apply to a remote install — but all printing, monitoring, and control features work normally.
HelixScreen also runs on an Android phone or tablet. It is the same remote client described above, just on a device you already own: it talks to your printer’s Moonraker over the network and does not install anything on the printer.
This is experimental. It works, but it has had less real-world use than the Linux builds. Expect rough edges and please report them.
What you need:
Android 9.0 or newer
The phone or tablet on the same network as your printer
Your printer’s IP address
Which file to download. Grab it from the latest release:
File
Use it for
helixscreen-android-arm64-v<VERSION>.apk
Essentially every modern phone and tablet. Start here
helixscreen-android-x86_64-v<VERSION>.apk
Emulators and x86 Chromebooks
helixscreen-android-universal-v<VERSION>.apk
Works everywhere, but a larger download. Use it if arm64 refuses to install
Ignore the .aab file on the release page. That one is only for publishing to Google Play and will not install on a device.
Installing it.
Download the APK on the device, or transfer it there.
Open it. Android will warn that it came from outside the Play Store and offer to let your browser or file manager install apps. Allow it for that app, then confirm the install.
If you prefer a cable, adb install helixscreen-android-arm64-v<VERSION>.apk from a computer works too.
First run. The setup wizard appears exactly as it does elsewhere. At Step 4: Moonraker Connection, enter your printer’s IP address (for example 192.168.1.50) and leave the port at 7125.
Good to know:
It runs in landscape. Turn the device sideways, or let auto-rotate handle it.
It asks for very little. Network access, and permission to keep the screen awake so a print you are watching does not black out. No location, storage, contacts, or camera.
Updating means downloading the new APK and installing over the old one. There is no in-app updater on Android yet, and the app will not update itself.
Foldables and unusual screen shapes can show layout quirks when the device folds or resizes. Reports with a screenshot are welcome.
It cannot do the printer-side things. Anything that requires running on the printer, like taking over the printer’s own panel or configuring the printer’s WiFi during the wizard, does not apply here. Printing, monitoring, and control all work normally.
Coming to Google Play. Play Store distribution is in progress. When it lands, installs from Play will be signed differently from these APKs, which means moving from a sideloaded install to the Play version will require uninstalling first and setting the app up again. Sideloading will keep working either way.
This covers any Klipper printer with a Raspberry Pi running MainsailOS (or similar), including SOVOL SV06, SOVOL SV08, Voron, RatRig, and other printers where Klipper runs on a separate Pi. Also works on x86 Linux PCs (e.g., mini ITX) running Debian/Ubuntu with Klipper and a touchscreen.
Hardware:
Raspberry Pi 3, 4, or 5 — any of them work. Pi 3 / Zero 2 W is plenty for HelixScreen; Pi 4/5 only matters if your overall Klipper setup wants more headroom for cameras, slicing, etc.
Both 64-bit and 32-bit Raspberry Pi OS / MainsailOS supported
Touchscreen display (HDMI, DSI, or SPI)
Network connection (Ethernet or WiFi)
Software:
MainsailOS installed and working
Klipper running and printing works via Mainsail web interface
SSH access to your Pi
Debian 11 (Bullseye) or newer — glibc 2.31+. See the OS version note below.
About 100MB free disk space
32-bit vs 64-bit: The installer automatically detects your OS architecture and downloads the correct binary. If you’re unsure which you have, run uname -m — aarch64 means 64-bit, armv7l means 32-bit.
OS version — Bullseye or newer. The pi and pi32 packages are dynamically linked
against glibc 2.31, the version in Debian 11 (Bullseye). They will not start on an
older release. Debian 10 (Buster) ships glibc 2.28, which is too old — the binary fails
at load with version 'GLIBC_2.29' not found or similar. Check yours with:
Terminal window
ldd--version|head-1# glibc version
cat/etc/os-release|head-2# distro release
This matters mainly on stock printer images, several of which still ship Buster even
though current Raspberry Pi OS and MainsailOS are well past it. If you are on one of
those and cannot upgrade the OS, install the cc1 package instead — it is statically
linked and carries its own C library, so it runs on old armv7 systems regardless of what
glibc they have. It has been used successfully this way on non-Creality armv7 hardware
(e.g. Rockchip RV1126 boards). See TROUBLESHOOTING.md.
Easiest option: We provide a ready-made firmware image — a fork of Forge-X 1.4.0 with HelixScreen pre-configured. Just put it on a flash drive and install on your printer. No SSH, no manual setup. If you’d rather install HelixScreen on an existing Forge-X or Klipper Mod setup, follow the manual instructions below.
Important: ForgeX must be installed and configured for GuppyScreen mode before installing HelixScreen. HelixScreen uses ForgeX’s infrastructure (Klipper, Moonraker, backlight control) but replaces the GuppyScreen UI.
Moonraker is included in stock firmware on port 4408
Install:
Terminal window
python3-c"import urllib.request as u;u.urlretrieve('https://raw.githubusercontent.com/prestonbrown/helixscreen/main/scripts/install.sh','/tmp/install.sh')" && sh/tmp/install.sh
Why not wget? Recent K2 firmware (Tina/OpenWrt) ships neither wget nor curl on the
PATH — even the BusyBox wget applet has been compiled out. Every K2 does include python3
(Klipper and Moonraker need it) with working SSL, so the command above uses Python to fetch the
installer over HTTPS; the installer then uses Python for the rest of the download and extraction.
If your firmware still has wget (older builds did), wget -O - http://dl.helixscreen.org/install.sh | sh also works.
What’s different from K1:
ARM processor (Allwinner, not MIPS) — standard cross-compilation
Stock Moonraker — no community firmware required
OpenWrt-based init system (procd, not SysV)
CFS (Creality Filament System) support for RS-485 filament management
Most users never need this — ZMOD handles initial install and ongoing updates through Moonraker’s update manager and that path “just works.” Use the manual route only if you’re pinning a specific version, working from a --local zip, or recovering from a failed update.
ZMOD installs HelixScreen into a chroot rooted at /usr/data/.mod/.zmod/. When you SSH into the printer you land in the host filesystem, not the chroot — so a plain curl … | sh writes into the squashfs base view that HelixScreen never sees. The installer detects this and refuses to run with a friendly message; the fix is to enter the chroot first:
Terminal window
sshroot@<printer-ip>
chroot/usr/data/.mod/.zmod
# now you're in the same view HelixScreen runs from:
Tested and working. Prebuilt binaries ship in releases and the installer has auto-detection support. Requires the community OpenCentauri COSMOS firmware — stock Elegoo firmware is not supported (no SSH, no Klipper, no Moonraker).
OpenCentauri COSMOS is a full firmware replacement for the Centauri Carbon. It ships with Klipper, Moonraker, Mainsail, and a gui-switcher that lets you pick which touch UI to run.
The installer auto-detects COSMOS, installs HelixScreen to /user-resource/helixscreen/, and registers it with gui-switcher as the selected touch UI. It stops the currently active UI (grumpyscreen, atomscreen, or guppyscreen) and starts HelixScreen in its place.
COSMOS’s config-manager tool lets you switch between installed UIs without uninstalling HelixScreen:
Terminal window
config-manageruiscreen_uigrumpyscreen# or atomscreen, guppyscreen, helixscreen
/etc/init.d/gui-switcherrestart
Notes:
Moonraker on COSMOS listens on port 80 directly (no nginx); HelixScreen’s cc1 preset is configured for this
Install directory: /user-resource/helixscreen/ (/ is read-only squashfs on COSMOS)
Init script: /etc/init.d/helixscreen (LSB-style, PIDFILE=/var/run/gui.pid for gui-switcher compatibility)
The cc1 preset ships with factory white-balance calibration (per-channel panel gain) so colors look neutral out of the box on the Centauri Carbon’s 4.3” panel — no manual tuning needed
COSMOS’s config-manager has a fixed allowlist for the screen_ui slot. The installer handles this automatically via an init-script wrapper so HelixScreen can be selected without patching COSMOS itself; the uninstaller fully reverses it
If you’re testing on this printer, please report your results via GitHub Issues or Discord.
The Creality Sonic Pad is a standalone 7” touchscreen that can run Klipper. It uses a 32-bit ARM userspace (armhf) despite having a 64-bit capable processor (Allwinner H616).
Tested firmware: SonicPad-Debian only.
This is the only Sonic Pad firmware HelixScreen has been tested on. It replaces
Creality’s stock OpenWrt image with Debian 11 (bullseye), which is what gives the
Pad a normal systemd + GNU userspace for HelixScreen to install into.
HelixScreen is not tested on Creality’s stock Sonic Pad firmware. The stock
image is a heavily cut-down OpenWrt build, so the installer’s assumptions about
systemd, package tooling, and archive utilities do not hold there. If you are on
stock firmware, flash SonicPad-Debian first.
HelixScreen requires Klipper and Moonraker to already be installed and working on the Sonic Pad. This is typically done via KIAUH or a similar tool. HelixScreen replaces whatever touchscreen UI you’re currently using (e.g., KlipperScreen).
Hardware:
Creality Sonic Pad (7” 1024x600 capacitive touchscreen)
The installer detects the Sonic Pad as a 32-bit ARM platform and downloads the pi32 release binary. HelixScreen installs to ~/helixscreen/ and runs as a systemd service.
Notes:
The Sonic Pad has a Goodix GT9xx touchscreen controller — the touch calibration wizard runs automatically on first boot if needed
Moonraker runs on localhost:7125 (default)
The display-sleep service is automatically stopped to prevent backlight conflicts
The Snapmaker U1 is an all-in-one printer with a built-in touchscreen. HelixScreen replaces the stock UI and launches automatically on boot.
Hardware:
Snapmaker U1
Built-in touchscreen display
Network connection
Software:
SSH access — via either firmware path:
Stock Snapmaker firmware (1.2+): enable the Root access option in printer settings (added in V1.2.0). This turns on SSH. (Stock-firmware support is newly added and not yet verified end-to-end on a stock device — see note below.)
SSH login (root@<printer-ip> or lava@<printer-ip>, password: snapmaker)
Notes:
Reinstall after a firmware update — any firmware update (stock or PAXX) resets system files and can overwrite HelixScreen; re-run the installer afterward.
Remote screen (“gui” camera) works on PAXX firmware — the built-in “gui” webcam in Mainsail/Fluidd shows the live HelixScreen UI, and you can tap it to control the printer remotely. Enable Remote Screen in the firmware settings web UI at http://<printer-ip>/firmware-config/ — it registers the “gui” webcam and restarts HelixScreen and Moonraker for you (hand-editing the config value alone is not enough). The physical “case” camera is unaffected. Stock firmware is not yet confirmed to expose the feed. Setup steps: Supported Printers → Snapmaker U1.
Two harmless Moonraker warnings are expected — after install, the Mainsail/Fluidd “Moonraker warnings found” banner may show “Unable to find DBus PolKit Interface” and “Unable to initialize System Update Provider for distribution: buildroot”. Both are inherent to Moonraker on the U1’s buildroot firmware (no PolKit, no OS package manager) and do not affect HelixScreen or printing. They are not specific to HelixScreen — installing simply restarts Moonraker, which re-surfaces them. See Troubleshooting.
Detects your platform, architecture (32-bit or 64-bit), and Klipper ecosystem
Downloads the correct release
Stops any competing UIs (KlipperScreen, etc.)
Installs to ~/helixscreen (if Klipper ecosystem detected) or /opt/helixscreen (fallback)
Configures and starts the systemd service
Sets up Moonraker update_manager for web UI updates
Install path auto-detection: The installer checks for ~/klipper, ~/moonraker, ~/printer_data, or an active moonraker.service. If any are found, HelixScreen installs alongside them in your home directory. Override with INSTALL_DIR=/custom/path.
Important: Installing HelixScreen replaces your current screen UI (GuppyScreen on Forge-X, KlipperScreen on Klipper Mod). Make sure you have a backup method to access your printer (SSH, Mainsail/Fluidd web interface).
The install script automatically detects your firmware (Forge-X or Klipper Mod) and installs to the correct location.
What the installer does on Forge-X:
Verifies ForgeX is installed and sets display mode to GUPPY
Stops and disables GuppyScreen (chmod -x on init scripts)
Disables stock Flashforge UI in /opt/auto_run.sh
Patches /opt/config/mod/.shell/screen.sh to skip backlight commands when HelixScreen is running (prevents ForgeX’s delayed_gcode from dimming the screen)
Installs HelixScreen to /opt/helixscreen/
Creates init script at /etc/init.d/S90helixscreen
What the installer does on Klipper Mod:
Stops Xorg and KlipperScreen
Disables their init scripts (chmod -x)
Installs HelixScreen to /root/printer_software/helixscreen/
Note: AD5M runs as root, so sudo is not needed.
Note: AD5M uses BusyBox utilities. Use unzip to extract .zip archives.
Note: AD5M uses SysV init (BusyBox), not systemd.
Requires SSH access. Enable it on stock firmware (1.2+) via the Root access option in printer settings, or install PAXX Extended Firmware (SSH on by default). PAXX is not required — it’s just the turnkey option.
Firmware versions: Tested on PAXX Extended Firmware 1.2.x, 1.3.x, and 1.4.x. Stock-firmware support is newly added and not yet verified end-to-end on a stock device. After any firmware update, reinstall HelixScreen — the update resets the printer’s system files and the stock screen will return until you reinstall (see Upgrading the firmware).
The installer automatically detects the Snapmaker U1 and installs to /userdata/helixscreen/. It configures autostart so HelixScreen launches instead of the stock UI on boot.
This sets HelixScreen to launch on boot and disables the stock UI program (/usr/bin/gui) so HelixScreen owns the screen. (The stock UI program lives in a read-only part of the firmware and is only disabled, never deleted — the uninstaller re-enables it.)
If you can’t run the uninstaller, revert manually. HelixScreen disables the stock UI program rather than deleting it, so re-enable it and remove HelixScreen’s files:
Terminal window
chmod+x/usr/bin/gui# re-enable the stock UI program
rm-rf/userdata/helixscreen# remove HelixScreen
reboot
Notes:
SSH is required — enable stock firmware’s Root access option, or use PAXX Extended Firmware (SSH on by default). PAXX is not required.
Display resolution may need manual configuration if the screen appears stretched or misaligned (see Display Configuration)
A firmware update resets the printer’s system files and brings the stock screen back — reinstall HelixScreen afterward
Upgrading the Extended Firmware with HelixScreen installed
A firmware upgrade is safe to run with HelixScreen installed — it does not brick the printer. HelixScreen’s files live in a layer that the upgrade clears, so after upgrading you simply reinstall HelixScreen.
Because HelixScreen replaces the stock touchscreen, the stock screen’s on-device “Local Update” button is gone. Upgrade over the network instead:
In a web browser on the same network, open http://<printer-ip>/firmware-config.
Choose Firmware Upgrade, upload the new U1_extended_<version>_upgrade.bin, and let it complete. The printer reboots into the new firmware.
The stock screen comes back (HelixScreen was cleared by the upgrade). Reinstall HelixScreen with the Quick Install one-liner. Your settings, WiFi, and printer config are preserved (they live on a separate partition the upgrade keeps).
Recovery: screen is blank or the printer is off the network
If something goes wrong and the printer comes up with a blank screen and is unreachable over WiFi, recover over a wired connection:
Plug a USB-Ethernet adapter into the printer and connect it to your router. The printer auto-configures the wired link and gets an IP from your router (check the router’s client list).
SSH in over that wired IP: ssh root@<wired-ip> (password snapmaker).
Run the uninstaller to return to the stock UI, then reboot:
Once the stock screen is back and the printer is on WiFi again, you can reinstall HelixScreen.
If the uninstaller can’t run, reset HelixScreen’s persistence flag and files manually, then reboot: rm -f /oem/.debug && rm -rf /oem/overlay/* && rm -rf /userdata/helixscreen && sync && reboot. This returns the printer to a clean stock state.
Calibrate your touchscreen by tapping the targets. This ensures accurate touch input.
Note: This step may be skipped automatically for known tier-1 supported printers that ship with default calibration values. You can always recalibrate later from Settings.
To rotate the display (e.g., if your screen is mounted upside-down), add to your settings.json (typically at ~/helixscreen/config/settings.json):
{
"display": {
"rotate": 180
}
}
Valid values: 0, 90, 180, 270. Restart HelixScreen after changing.
Touch coordinates are automatically adjusted to match the rotation — no separate touch configuration is needed.
Rotation and display backends: When rotation is configured on Raspberry Pi, HelixScreen checks whether your display hardware supports rotating the image directly. Most DSI/HDMI displays on Pi do not support hardware rotation. In that case, HelixScreen automatically switches from the DRM (GPU) backend to the framebuffer backend, which handles software rotation without any screen flicker. This switch is transparent — no manual configuration needed.
If you experience any display issues with rotation, you can also force the framebuffer backend manually by setting HELIX_DISPLAY_BACKEND=fbdev (see below).
By default, HelixScreen uses GPU-accelerated rendering via DRM/KMS when available. On boards where DRM is not supported, it falls back to CPU-based software rendering (fbdev backend).
When rotation is configured, HelixScreen may automatically switch to the fbdev backend if the display hardware doesn’t support hardware rotation. This is normal and provides flicker-free rotation.
Supported DRM hardware:
Raspberry Pi 3B+, Pi 4, Pi 5
BTT CB1, CB2 (and other Allwinner H616/H618 boards)
Display must be connected via HDMI or DSI (SPI displays are not supported)
To force a specific backend:
Edit your systemd service override:
Terminal window
sudosystemctledithelixscreen
Add the following lines:
[Service]
Environment="HELIX_DISPLAY_BACKEND=fbdev"
Then restart:
Terminal window
sudosystemctlrestarthelixscreen
Valid backends: drm (GPU-accelerated), fbdev (CPU rendering, maximum compatibility).
How to revert to auto-detection:
Remove the override and restart:
Terminal window
sudosystemctlreverthelixscreen
sudosystemctlrestarthelixscreen
Note: On Raspberry Pi 5, you may also need to specify the correct display device if auto-detection picks the wrong one. Add Environment="HELIX_DRM_DEVICE=/dev/dri/card1" for DSI displays or Environment="HELIX_DRM_DEVICE=/dev/dri/card2" for HDMI. See CONFIGURATION.md for details.
If you installed via the installer script, it automatically configures Moonraker’s update_manager. You can update HelixScreen with one click from the Mainsail or Fluidd web interface:
Open Mainsail/Fluidd in your browser
Navigate to Machine (Mainsail) or Settings (Fluidd)
Find HelixScreen in the update manager
Click Update when a new version is available
Note: The installer adds an [update_manager helixscreen] section to your moonraker.conf. If you installed manually, see Manual Update Manager Setup below.
The update process preserves your settings.json settings. If you want to reset to defaults, use the --clean flag — it removes your HelixScreen settings and caches everywhere they live, then does a fresh install:
--clean asks for confirmation before wiping anything. Your Klipper config, Moonraker settings, print history, and G-code files are not touched — only HelixScreen’s own settings.
To reset settings and pin a specific version in one step, combine --clean with --version:
Important: Do not add install_script, managed_services, or persistent_files
to this section — these options are not supported with type: web and Moonraker will
log warnings about unparsed config options. Service restart after updates is handled
automatically by a systemd path unit installed during setup.
If you use a webcam with HelixScreen, install libturbojpeg0 for faster camera feed rendering:
Terminal window
sudoaptinstalllibturbojpeg0
The installer attempts this automatically, but it’s listed here in case your Pi was offline during installation. HelixScreen detects and uses it automatically for 3-5x faster JPEG decoding via hardware SIMD acceleration.
The AD5M has limited RAM (~108MB total, with only ~24MB free after Klipper, Moonraker, and screen UI). HelixScreen is built with static linking and memory optimization for this environment.
Measured memory comparison (VmRSS):
Component
KlipperScreen
HelixScreen
Screen UI
~50 MB (Python + X Server)
~10 MB (C++)
Total
~50 MB
~10 MB
On Klipper Mod systems, switching from KlipperScreen to HelixScreen frees approximately 40 MB of RAM - a significant improvement on a memory-constrained device!
Note: The 10 MB footprint includes the full LVGL widget tree, draw buffers for UI elements (gradients, color pickers, AMS spool icons), and runtime state for all panels. Images are loaded on-demand, not pre-cached.
If you experience memory issues:
Reduce print history retention in Moonraker
Avoid keeping many G-code files on the printer
Consider disabling the camera stream if not needed
