⚠️ 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.
The installer automatically detects your platform and downloads the correct release.
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.
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.
The one-liner above works on every supported platform, but each printer family has quirks: firmware prerequisites, different install locations, its own service and update commands. The guide for your printer has all of that:
Printer
Install guide
Generic Linux - Raspberry Pi, BTT CB1/CB2/Manta, x86
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 the setup to choose when:
Your printer has no built-in screen, like a Voron, RatRig, or any Klipper printer whose host has no panel of its own
The printer lives somewhere you don’t: another room, a garage, a workshop
You run more than one printer and want a single screen for all of them: with multi-printer support (beta) enabled, the printer manager switches between every printer you’ve added
Your printer’s stock panel can’t be replaced (some QIDI models)
Common screen devices:
A spare Raspberry Pi (3/4/5, Zero 2 W, CM4) with a touchscreen
A repurposed Klipper pad or a small self-built touchscreen PC
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 generic Linux 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.
Power controls are hidden. An Android app can’t power off or reboot the device it runs on, so the shutdown widget never appears on the Home panel (it shows as “Not available on Android” in the widget catalog) and the POWER section of the Advanced panel is hidden too. Moonraker power devices (smart plugs and the like) are unaffected.
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, and on BTT CB1/CB2/Manta host boards.
Raspberry Pi 3, 4, or 5, or a BTT CB1/CB2: 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.
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 when run as a normal user, or /opt/helixscreen when run as root
Configures and starts the systemd service
Sets up Moonraker update_manager for web UI updates
Where does it install? The installer puts HelixScreen in your home directory when it runs as a normal user (with or without a Klipper ecosystem alongside), and in /opt when it runs as root. Override with INSTALL_DIR=/custom/path/helixscreen (the directory name must contain helixscreen).
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.
Calibrate your touchscreen by tapping the targets. This ensures accurate touch input.
Note: This step is skipped automatically when your touchscreen doesn’t need calibration: most capacitive and USB touchscreens are factory-calibrated. Only resistive panels (and panels reporting broken coordinate ranges) get this step. You can always recalibrate later from Settings.
After the wizard, you’ll be taken to the home screen. Your settings are saved automatically.
Note: On printers whose install package ships pre-configured hardware (K2, AD5M, and similar), the hardware steps and the summary are collapsed, and a one-time telemetry opt-in screen appears instead.
The BTT Pad 7 and similar “Klipper Pad” devices are complete units, with the single-board computer and touchscreen integrated in one housing. Display output and USB touch input come pre-configured, and HelixScreen should detect and use them automatically.
Prefer rotating the display itself when it can. If your monitor has a rotation option (usually a button or an OSD menu), use it. On a Pi with a DSI panel, the kernel can rotate the panel in hardware: add video=DSI-1:panel_orientation=upside_down to /boot/firmware/cmdline.txt (HelixScreen detects this automatically on first boot; see TROUBLESHOOTING: display upside down or rotated). Rotation done by the display is free. HelixScreen’s rotate setting below is software rotation: it costs CPU on every frame, and on the Pi it also switches the display to the framebuffer backend (see the note on backends below). Use it when your display cannot rotate itself.
To rotate in software (e.g., a screen mounted upside-down that has no rotation of its own), 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 the DRM/KMS backend when available. DRM presents each frame with a vsynced page flip instead of a plain memory copy, which avoids tearing; rendering itself is CPU-based on both backends. On boards where DRM is not supported, it falls back to the framebuffer (fbdev backend), which copies each frame directly with no vsync.
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)
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.
Platform-specific update commands live in your printer’s install guide: the two-step offline process on printers without HTTPS fetch tools (K1, Adventurer 5M), the AD5X chroot path, bundled-installer locations. Start from Which printer are you installing on?.
Three ways to update, in order of preference: in the app itself, from the Mainsail/Fluidd update manager, or from the command line.
The app can update itself: Settings > Help & About > About > Check for Updates. It shows the new version, downloads it with a progress bar, and installs it; a Retry button appears if the download fails. No SSH and no web browser needed. The Update Channel row beside it picks Stable or Beta.
This option is hidden where something else manages updates for you, such as on the Snapmaker U1, whose firmware handles HelixScreen updates itself. On Android, the install step opens the Play Store listing if you installed from Google Play, and otherwise the GitHub release page, where you download the new APK. See Checking for Updates for the full walkthrough.
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.
This preserves your configuration and updates to the latest version. Printers without direct internet access use a two-step process instead; see your printer’s install guide.
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:
--yes skips the confirmation prompt, which a piped command cannot show; run the downloaded script interactively over SSH and you get the prompt instead. 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.
Platform-specific details are in your printer’s install guide: the bundled installer’s location on printers without HTTPS fetch tools, manual revert steps, what gets restored on each firmware.
Most issues are diagnosed from the logs. On systemd hosts (Raspberry Pi, BTT, x86, Sonic Pad):
Terminal window
# View recent logs
sudojournalctl-uhelixscreen-n100
# Follow live logs
sudojournalctl-uhelixscreen-f
# Filter by error/warning level
sudojournalctl-uhelixscreen-perr
Log locations for the other platforms (K1, K2, AD5M, AD5X, CC1, Snapmaker U1) are in your printer’s install guide: each has a launcher/crash log plus a platform-specific app log.
A problem reproduced at a higher log level gives far more to work with:
Set Settings > System > Log Level to Debug, or Trace for touch or display issues (Trace is very verbose). It takes effect immediately; no restart is needed.
Perform the action that misbehaves.
Send a debug bundle: Settings > Help & About > Upload Debug Bundle collects the logs (including everything since startup), strips personal data, and gives you a share code to include in your report. See Debug Bundles.
Turn the log level back to where it was. Debug and trace generate a lot of output; journald rotates and caps itself on systemd hosts, but the printer-hosted platforms write plain log files that nothing rotates.
