Installation

This guide walks you through installing HelixScreen on your 3D printer’s touchscreen display.

Target Audience: Klipper users who want to use pre-built packages. If you’re a developer building from source, see DEVELOPMENT.md.

Quick Start
Prerequisites
MainsailOS Installation
Flashforge Adventurer 5M Installation
Creality K1 Installation
Creality K2 Series
FlashForge Adventurer 5X
Elegoo Centauri Carbon 1
Creality Sonic Pad
Snapmaker U1
First Boot & Setup Wizard
Display Configuration
Starting on Boot
Updating HelixScreen
Uninstalling
Getting Help

Quick Start

⚠️ 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.

Raspberry Pi (MainsailOS):

curl -sSL https://raw.githubusercontent.com/prestonbrown/helixscreen/main/scripts/install.sh | sh

The installer automatically detects your platform and downloads the correct release.

Creality K1/K1C/K1 Max: Run directly on the printer via SSH:

wget -O - http://dl.helixscreen.org/install.sh | sh

No SSL required — uses plain HTTP. See Creality K1 Series for details.

Flashforge Adventurer 5M: The easiest option is our ready-made firmware image — just flash from a USB drive. For manual installation on existing Forge-X or Klipper Mod setups, see Flashforge Adventurer 5M Installation.

Flashforge Adventurer 5X: Install ZMOD, which manages HelixScreen installation and updates. See FlashForge Adventurer 5X.

Snapmaker U1: Run directly on the printer via SSH (requires Extended Firmware):

curl -sSL https://releases.helixscreen.org/install.sh | sh

See Snapmaker U1 for details.

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.

Prerequisites

MainsailOS (Raspberry Pi)

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 (Pi 3 is minimum, Pi 4/5 recommended)
- Raspberry Pi Zero 2 W also supported
- 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
- 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.

Flashforge Adventurer 5M / 5M Pro

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.

Hardware:
- Flashforge Adventurer 5M or 5M Pro
- Stock 4.3” touchscreen (800x480)
- Network connection
Software:
- Custom Klipper firmware: Forge-X or Klipper Mod
- SSH access to the printer (usually root@<printer-ip>)
- About 100MB free disk space

Tested versions: Most thoroughly tested on ForgeX 1.4.0 with Flashforge firmware 3.1.5. Other versions may work fine.

AD5M Firmware Variants

The installer automatically detects which firmware you’re running and configures paths accordingly:

Firmware	Replaces	Install Location	Init Script
Forge-X	GuppyScreen	`/opt/helixscreen/`	`S90helixscreen`
Klipper Mod	KlipperScreen	`/root/printer_software/helixscreen/`	`S80helixscreen`

Memory Savings: On Klipper Mod, HelixScreen (~13MB) replaces KlipperScreen (~50MB), freeing ~37MB RAM on the memory-constrained AD5M.

Forge-X Prerequisites

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.

Install ForgeX following their instructions
Configure ForgeX with display = 'GUPPY' in variables.cfg
Verify GuppyScreen works on the touchscreen
Then run the HelixScreen installer

The HelixScreen installer will:

Keep ForgeX in GUPPY display mode (required for backlight control)
Disable GuppyScreen’s init scripts (so HelixScreen takes over)
Disable the stock Flashforge UI in auto_run.sh
Patch ForgeX’s screen.sh to prevent backlight dimming conflicts
Install HelixScreen as the replacement touchscreen UI

On uninstall, all ForgeX changes are reversed and GuppyScreen is restored.

Creality K1 Series

Creality K1, K1C, and K1 Max. Requires rooting and community firmware (for Moonraker).

See the Creality K1C Setup Guide for complete instructions — covers rooting, firmware options, and HelixScreen installation.

Quick version (if you already have root + Moonraker running):

One-Liner Install (Recommended)

If your K1 has internet access, install directly on the printer:

wget -O - http://dl.helixscreen.org/install.sh | sh

This works because dl.helixscreen.org serves over plain HTTP, which BusyBox wget supports.

Two-Step Install (No Internet on Printer)

If your printer doesn’t have internet access, download on another computer first:

Step 1: Download on your computer

Go to the latest release page and download:

helixscreen-k1.zip (the K1 release archive)
install.sh (the installer script, under “Assets”)

Or use the command line (replace vX.Y.Z with the actual version):

VERSION=vX.Y.Z  # Check latest at https://github.com/prestonbrown/helixscreen/releases/latest
wget "https://github.com/prestonbrown/helixscreen/releases/download/${VERSION}/helixscreen-k1.zip"
wget https://raw.githubusercontent.com/prestonbrown/helixscreen/main/scripts/install.sh

Step 2: Copy to your printer and install

scp helixscreen-k1.zip install.sh root@<printer-ip>:/usr/data/
ssh root@<printer-ip>   # password: creality_2023
sh /usr/data/install.sh --local /usr/data/helixscreen-k1.zip

Installs to /usr/data/helixscreen/, boot service at /etc/init.d/S99helixscreen.

Creality K2 Series

Hardware:
- Creality K2 Max, K2 Plus, or K2 Pro
- Stock 4.3” touchscreen display (480x800)
- Network connection
Software:
- Stock firmware with root access enabled (Settings → “Root account information”)
- SSH access (root@<printer-ip>, password: creality_2024)
- Moonraker is included in stock firmware on port 4408

Install:

wget -O - http://dl.helixscreen.org/install.sh | sh

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

FlashForge Adventurer 5X

Tested and working. Prebuilt binaries are included in releases. Installation is handled through the ZMOD firmware modification.

Hardware:
- FlashForge Adventurer 5X
- Built-in 4.3” touchscreen (800x480)
- Network connection
Software:
- ZMOD firmware modification installed
- ZMOD provides Klipper, Moonraker, and SSH access

Current status:

Dedicated build target: ad5x with its own toolchain and release binary
Prebuilt ad5x binaries are included in GitHub releases
ZMOD manages installation and updates via Moonraker update manager
Auto-detection: HelixScreen automatically detects ZMOD firmware (by recognizing ZMOD-specific Klipper device names) and applies ZMOD-optimized presets for display, input, and fan configuration. No manual configuration needed.
IFS (4-channel filament system) supported — see Filament Management

Elegoo Centauri Carbon

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).

Hardware:
- Elegoo Centauri Carbon (4.3” 480×272 touchscreen, Allwinner R528, armv7l)
- Network connection (WiFi or Ethernet)
Software:
- OpenCentauri COSMOS firmware installed (replaces stock Elegoo firmware; ships Klipper + Moonraker + grumpyscreen/atomscreen/guppyscreen)
- SSH access: root / default password OpenCentauri (change it after install)

Step 1: Install COSMOS firmware

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.

Download the latest update.swu from https://github.com/OpenCentauri/cosmos/releases
Copy it to the root of a FAT32-formatted USB stick
Insert the USB stick into the printer, power on
From the stock Elegoo UI, navigate to the firmware-update menu and apply the update
First boot takes 5–10 minutes while it reflashes the toolhead and bed boards — be patient
After reboot, connect to WiFi from the COSMOS UI and note the printer’s IP address

If the update fails or the device won’t boot, consult the OpenCentauri install guide and emergency USB recovery docs.

Step 2: Install HelixScreen

SSH into the printer (replace <ip> with your printer’s IP):

ssh root@<ip>
# Default password: OpenCentauri

Then run the installer:

curl -sSL https://raw.githubusercontent.com/prestonbrown/helixscreen/main/scripts/install.sh | sh

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.

Step 3: Switch back to another UI (optional)

COSMOS’s config-manager tool lets you switch between installed UIs without uninstalling HelixScreen:

config-manager ui screen_ui grumpyscreen   # or atomscreen, guppyscreen, helixscreen
/etc/init.d/gui-switcher restart

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.

Creality Sonic Pad

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).

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)
- Network connection (Ethernet)
Software:
- Klipper and Moonraker installed and working (via KIAUH or similar)
- SSH access (sonic@<pad-ip>)
- About 100MB free disk space

Installation:

The standard installer works on Sonic Pad:

curl -sSL https://raw.githubusercontent.com/prestonbrown/helixscreen/main/scripts/install.sh | sh

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

Snapmaker U1

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:
- Extended Firmware installed (required for SSH access)
- SSH access (root@<printer-ip> or lava@<printer-ip>, password: snapmaker)

Raspberry Pi / MainsailOS Installation

Step 1: Connect to Your Pi

Open a terminal and SSH into your Raspberry Pi:

ssh pi@mainsailos.local
# Or use your Pi's IP address:
ssh pi@192.168.1.xxx

Default password is usually raspberry unless you changed it.

Step 2: Run the Installer

curl -sSL https://raw.githubusercontent.com/prestonbrown/helixscreen/main/scripts/install.sh | sh

The installer automatically:

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.

Step 3: Complete the Setup Wizard

After installation, HelixScreen starts automatically. The on-screen wizard guides you through:

WiFi configuration (if not connected via Ethernet)
Finding your Moonraker instance
Identifying your printer
Selecting heaters, fans, and LEDs

See First Boot & Setup Wizard for details.

Flashforge Adventurer 5M Installation

Ready-Made Firmware Image (Easiest)

We maintain a ready-made firmware image — a fork of Forge-X 1.4.0 with HelixScreen pre-configured. This is the fastest way to get up and running:

Download the image from github.com/prestonbrown/ff5m
Copy it to a USB flash drive
Insert the flash drive into your AD5M or AD5M Pro and install

That’s it — no SSH, no manual commands. HelixScreen will be ready to go after the firmware installs.

If you already have Forge-X or Klipper Mod installed and prefer to add HelixScreen manually, continue with the instructions below.

Manual Installation

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).

Automated Installation (Recommended)

The AD5M uses BusyBox which doesn’t support HTTPS downloads directly. This is a two-step process:

Download on your local computer (Steps 1-2)
SSH into the printer as root and run the installer (Step 3)

Step 1: Download on your computer

Go to the latest release page and download:

helixscreen-ad5m.zip (the AD5M release archive)
install.sh (the installer script, under “Assets”)

Or use the command line (replace vX.Y.Z with the actual version):

VERSION=vX.Y.Z  # Check latest at https://github.com/prestonbrown/helixscreen/releases/latest
wget "https://github.com/prestonbrown/helixscreen/releases/download/${VERSION}/helixscreen-ad5m.zip"
wget https://raw.githubusercontent.com/prestonbrown/helixscreen/main/scripts/install.sh

Step 2: Copy to your printer

# AD5M requires -O flag for scp (BusyBox lacks sftp-server)
# Note: Use /data/ not /tmp/ - AD5M's /tmp is a tiny tmpfs (~54MB)
scp -O helixscreen-ad5m.zip install.sh root@<printer-ip>:/data/

Windows users: The -O flag is not supported by Windows 11’s built-in OpenSSH. Use one of these alternatives instead:

WSL (recommended) — open a WSL terminal and run all commands as shown (Linux tools work natively)

WinSCP (free, GUI) — set the protocol to SCP, then drag and drop files to /data/ on the printer

PuTTY pscp (free, command-line): pscp helixscreen-ad5m.zip install.sh root@<printer-ip>:/data/

Step 3: SSH into the printer and run the installer

# From your local computer, SSH into the printer as root
ssh root@<printer-ip>

# Now on the printer, run the installer
sh /data/install.sh --local /data/helixscreen-ad5m.zip

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/
Creates init script at /etc/init.d/S80helixscreen

Manual Installation

Forge-X Manual Installation

# Download on your computer (replace vX.Y.Z with actual version)
VERSION=vX.Y.Z
wget "https://github.com/prestonbrown/helixscreen/releases/download/${VERSION}/helixscreen-ad5m.zip"

# Copy to printer (AD5M requires scp -O for legacy protocol)
# Note: Use /data/ not /tmp/ - AD5M's /tmp is a tiny tmpfs (~54MB)
# Windows users: use WinSCP (SCP protocol) or PuTTY's pscp instead — see note above
scp -O helixscreen-ad5m.zip root@<printer-ip>:/data/

# SSH into printer
ssh root@<printer-ip>

# Extract to /opt (Forge-X location)
cd /opt
unzip -q /data/helixscreen-ad5m.zip

# Stop GuppyScreen
/opt/config/mod/.root/S80guppyscreen stop 2>/dev/null || true
chmod -x /opt/config/mod/.root/S80guppyscreen

# Install init script
cp /opt/helixscreen/config/helixscreen.init /etc/init.d/S90helixscreen
chmod +x /etc/init.d/S90helixscreen

# Start HelixScreen
/etc/init.d/S90helixscreen start

# Clean up
rm /data/helixscreen-ad5m.zip

Klipper Mod Manual Installation

Note: Klipper Mod’s /tmp is a small tmpfs (~54MB). The package is ~70MB, so we must use /mnt/data instead.

# Download on your computer (replace vX.Y.Z with actual version)
VERSION=vX.Y.Z
wget "https://github.com/prestonbrown/helixscreen/releases/download/${VERSION}/helixscreen-ad5m.zip"

# Copy to printer's data partition (NOT /tmp - it's too small!)
# Windows users: use WinSCP (SCP protocol) or PuTTY's pscp instead — see note above
scp -O helixscreen-ad5m.zip root@<printer-ip>:/mnt/data/

# SSH into printer
ssh root@<printer-ip>

# Extract to /root/printer_software (Klipper Mod location)
cd /root/printer_software
unzip -q /mnt/data/helixscreen-ad5m.zip

# Stop KlipperScreen
/etc/init.d/S80klipperscreen stop 2>/dev/null || true
chmod -x /etc/init.d/S80klipperscreen

# Install init script (S80 to match KlipperScreen's boot order)
cp /root/printer_software/helixscreen/config/helixscreen.init /etc/init.d/S80helixscreen
chmod +x /etc/init.d/S80helixscreen

# Update the install path in the init script
sed -i 's|DAEMON_DIR=.*|DAEMON_DIR="/root/printer_software/helixscreen"|' /etc/init.d/S80helixscreen

# Start HelixScreen
/etc/init.d/S80helixscreen start

# Clean up
rm /mnt/data/helixscreen-ad5m.zip

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.

Step 4: Reboot

reboot

After reboot, HelixScreen will start automatically on the touchscreen.

Step 5: Complete Setup

Use the touchscreen to complete the setup wizard. The printer should auto-detect since it’s running locally.

Snapmaker U1 Installation

Requires Extended Firmware. Stock firmware does not provide SSH access. Install Extended Firmware first before proceeding.

SSH into the printer:

ssh root@<printer-ip>
# or: ssh lava@<printer-ip>
# password: snapmaker

Quick Install (Recommended)

curl -sSL https://releases.helixscreen.org/install.sh | sh

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.

Manual Install

If you prefer to install manually or the one-liner doesn’t work on your network:

Step 1: Download the release archive

wget https://releases.helixscreen.org/stable/helixscreen-snapmaker-u1.zip

Step 2: Extract to the install directory

mkdir -p /userdata/helixscreen && unzip -q helixscreen-snapmaker-u1.zip -d /userdata/helixscreen

Step 3: Configure autostart

bash /userdata/helixscreen/scripts/snapmaker-u1-setup-autostart.sh /userdata/helixscreen

This replaces the stock UI (unisrv) on boot with HelixScreen.

Step 4: Start HelixScreen

killall unisrv 2>/dev/null; /userdata/helixscreen/bin/helix-launcher.sh &

Reverting to Stock UI

rm -rf /userdata/helixscreen
reboot

The stock UI resumes automatically when HelixScreen is not found.

Notes:

Extended firmware is required — stock firmware does not provide SSH access
Display resolution may need manual configuration if the screen appears stretched or misaligned (see Display Configuration)
The stock UI can be restored at any time by removing /userdata/helixscreen and rebooting

First Boot & Setup Wizard

When HelixScreen starts for the first time, a setup wizard guides you through configuration:

Step 1: Touchscreen Calibration

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.

Step 2: Language Selection

Choose your preferred language.

Step 3: Network Setup

Connect to your wireless network or configure Ethernet. You can:

Select from detected WiFi networks
Enter a hidden network name manually
Skip if using Ethernet or already connected

Step 4: Moonraker Connection

Enter your Moonraker host. For most setups:

MainsailOS: localhost or 127.0.0.1
AD5M: localhost
Remote printer: Enter the IP address

The wizard will test the connection before proceeding.

Step 5: Printer Identification

HelixScreen will try to identify your printer from its configuration. You can:

Confirm the detected printer type
Select from a database of 50+ printers
Enter custom settings

Step 6: Heater Selection

Choose which heaters to display and control:

Hotend/nozzle heater
Bed heater
Chamber heater (if available)

Step 7: Fan Selection

Select your cooling fans:

Part cooling fan
Hotend fan
Other auxiliary fans

Step 8: LED Selection (Optional)

If your printer has controllable LEDs:

Chamber lights
Status LEDs
NeoPixel strips

Step 9: Input Shaper (Optional)

Configure resonance compensation if your printer supports input shaping.

Step 10: Hardware Summary

Review your configured hardware before completing setup.

Completion

After the wizard, you’ll be taken to the home screen. Your settings are saved automatically.

Display Configuration

HDMI Displays (Plug and Play)

Most HDMI touchscreens work automatically. If touch input isn’t working:

Check that the USB cable from the display is connected to your Pi
Verify the display appears in /dev/input/:
Terminal window
```
ls /dev/input/event*
```

Official Raspberry Pi Touchscreen (DSI)

The official 7” Pi touchscreen is detected automatically via DSI connector.

If using non-standard orientation, edit /boot/config.txt:

# Rotate display 180 degrees
lcd_rotate=2

SPI Displays (Requires Configuration)

For SPI displays (like many small LCDs):

Enable SPI in /boot/config.txt
Install the appropriate overlay
Configure framebuffer settings

See the MainsailOS display documentation for specific display setup.

BTT Pad 7, CB2, and Similar

The BTT Pad 7, CB2, and similar “Klipper Pad” devices typically include:

Pre-configured display output
Touch input via USB

HelixScreen should detect and use these automatically.

Screen Rotation

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).

GPU Rendering (Experimental)

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:

sudo systemctl edit helixscreen

Add the following lines:

[Service]
Environment="HELIX_DISPLAY_BACKEND=fbdev"

Then restart:

sudo systemctl restart helixscreen

Valid backends: drm (GPU-accelerated), fbdev (CPU rendering, maximum compatibility).

How to revert to auto-detection:

Remove the override and restart:

sudo systemctl revert helixscreen
sudo systemctl restart helixscreen

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.

Starting on Boot

Enable Automatic Start

The installer configures systemd to start HelixScreen on boot. Verify with:

sudo systemctl is-enabled helixscreen
# Should show: enabled

If not enabled:

sudo systemctl enable helixscreen

Service Management

MainsailOS (systemd):

# Start HelixScreen
sudo systemctl start helixscreen

# Stop HelixScreen
sudo systemctl stop helixscreen

# Restart (after config changes)
sudo systemctl restart helixscreen

# View status
sudo systemctl status helixscreen

# View logs
sudo journalctl -u helixscreen -f

AD5M (SysV init):

Forge-X:

/etc/init.d/S90helixscreen start|stop|restart|status
cat /tmp/helixscreen.log  # View logs

Klipper Mod:

/etc/init.d/S80helixscreen start|stop|restart|status
cat /tmp/helixscreen.log  # View logs

K1/Simple AF (SysV init):

/etc/init.d/S99helixscreen start|stop|restart|status
cat /tmp/helixscreen.log  # View logs

Disabling Other UIs

If you have another UI installed, disable it to avoid conflicts:

MainsailOS (systemd):

# Disable KlipperScreen (if installed)
sudo systemctl stop KlipperScreen
sudo systemctl disable KlipperScreen

AD5M Forge-X (SysV init):

# Disable GuppyScreen
/opt/config/mod/.root/S80guppyscreen stop
chmod -x /opt/config/mod/.root/S80guppyscreen

AD5M Klipper Mod (SysV init):

# Disable KlipperScreen
/etc/init.d/S80klipperscreen stop
chmod -x /etc/init.d/S80klipperscreen

K1/Simple AF (SysV init):

# Disable GuppyScreen
/etc/init.d/S99guppyscreen stop
chmod -x /etc/init.d/S99guppyscreen

Note: The HelixScreen installer automatically stops and disables competing UIs.

Updating HelixScreen

Check Current Version

On the touchscreen: Settings → scroll down to the bottom of the page to find the version number.

Or via SSH:

# Path varies by platform:
#   Pi: ~/helixscreen/bin/helix-screen (or /opt/helixscreen if no Klipper ecosystem)
#   K2: /opt/helixscreen/bin/helix-screen (assumed, untested)
#   AD5M Klipper Mod: /root/printer_software/helixscreen/bin/helix-screen
~/helixscreen/bin/helix-screen --version

Update from Mainsail/Fluidd Web UI (Pi Only)

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.

Update Using Install Script (Recommended)

The easiest way to update is using the install script with --update:

Raspberry Pi:

curl -sSL https://raw.githubusercontent.com/prestonbrown/helixscreen/main/scripts/install.sh | sh -s -- --update

Creality K1 (no HTTPS support - two-step process):

# On your computer (replace vX.Y.Z with actual version):
VERSION=vX.Y.Z  # Check latest at https://github.com/prestonbrown/helixscreen/releases/latest
wget "https://github.com/prestonbrown/helixscreen/releases/download/${VERSION}/helixscreen-k1.zip"
scp helixscreen-k1.zip root@<printer-ip>:/usr/data/

# On the printer (use the bundled install.sh - no need to download it again):
/usr/data/helixscreen/install.sh --local /usr/data/helixscreen-k1.zip --update

Flashforge Adventurer 5M (no HTTPS support - two-step process):

# On your computer (replace vX.Y.Z with actual version):
VERSION=vX.Y.Z  # Check latest at https://github.com/prestonbrown/helixscreen/releases/latest
wget "https://github.com/prestonbrown/helixscreen/releases/download/${VERSION}/helixscreen-ad5m.zip"
# Windows users: use WSL, WinSCP (SCP protocol), or PuTTY's pscp instead of scp -O
scp -O helixscreen-ad5m.zip root@<printer-ip>:/data/

# On the printer (use the bundled install.sh - no need to download it again):
# Forge-X:
/opt/helixscreen/install.sh --local /data/helixscreen-ad5m.zip --update
# Klipper Mod:
/root/printer_software/helixscreen/install.sh --local /data/helixscreen-ad5m.zip --update

This preserves your configuration and updates to the latest version.

Update to Specific Version

Raspberry Pi:

curl -sSL https://raw.githubusercontent.com/prestonbrown/helixscreen/main/scripts/install.sh | sh -s -- --update --version v1.2.0

Creality K1 / Flashforge Adventurer 5M: Download the specific version archive from GitHub Releases, then use --local as shown above.

Preserving Configuration

The update process preserves your settings.json settings. If you want to reset to defaults:

# Use your actual install path (~/helixscreen or /opt/helixscreen)
sudo rm ~/helixscreen/config/settings.json
sudo systemctl restart helixscreen

Manual Update Manager Setup

If you installed manually or the installer couldn’t find your moonraker.conf, add this to enable web UI updates:

# Add to moonraker.conf
# NOTE: The 'path' varies by platform:
#   Pi: ~/helixscreen (or /opt/helixscreen if no Klipper ecosystem)
#   K1/Simple AF: /usr/data/helixscreen
#   AD5M Klipper Mod: /root/printer_software/helixscreen
[update_manager helixscreen]
type: web
channel: stable
repo: prestonbrown/helixscreen
path: ~/helixscreen

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.

Then restart Moonraker:

sudo systemctl restart moonraker

Uninstalling

Using Install Script (Recommended)

The install script with --uninstall removes HelixScreen and restores your previous UI (GuppyScreen, KlipperScreen, etc.):

Raspberry Pi:

curl -sSL https://raw.githubusercontent.com/prestonbrown/helixscreen/main/scripts/install.sh | sh -s -- --uninstall

Creality K1 (use the bundled install.sh):

/usr/data/helixscreen/install.sh --uninstall

Flashforge Adventurer 5M (use the bundled install.sh):

# Forge-X:
/opt/helixscreen/install.sh --uninstall
# Klipper Mod:
/root/printer_software/helixscreen/install.sh --uninstall

Manual Uninstall

MainsailOS

# Stop and disable service
sudo systemctl stop helixscreen
sudo systemctl disable helixscreen

# Remove service file
sudo rm /etc/systemd/system/helixscreen.service
sudo systemctl daemon-reload

# Remove installation (check your actual path)
sudo rm -rf ~/helixscreen
# Or if installed to /opt:
sudo rm -rf /opt/helixscreen

AD5M Forge-X

# Stop and remove service
/etc/init.d/S90helixscreen stop
rm /etc/init.d/S90helixscreen

# Remove files
rm -rf /opt/helixscreen

# Re-enable GuppyScreen
chmod +x /opt/config/mod/.root/S80guppyscreen 2>/dev/null || true
chmod +x /opt/config/mod/.root/S35tslib 2>/dev/null || true

# Restore stock Flashforge UI in auto_run.sh (if it was disabled)
sed -i 's|^# Disabled by HelixScreen: /opt/PROGRAM/ffstartup-arm|/opt/PROGRAM/ffstartup-arm|' /opt/auto_run.sh 2>/dev/null || true

# Remove HelixScreen patch from screen.sh (restores backlight control)
# The automated uninstaller handles this; for manual removal, edit:
# /opt/config/mod/.shell/screen.sh and remove the helixscreen_active check

# Reboot to restore GuppyScreen
reboot

Note: The automated uninstaller (install.sh --uninstall) handles all ForgeX restoration automatically, including unpatching screen.sh.

AD5M Klipper Mod

# Stop and remove service
/etc/init.d/S80helixscreen stop
rm /etc/init.d/S80helixscreen

# Remove files
rm -rf /root/printer_software/helixscreen

# Re-enable KlipperScreen
chmod +x /etc/init.d/S80klipperscreen 2>/dev/null || true

# Reboot to restore KlipperScreen
reboot

K1/Simple AF

# Stop and remove service
/etc/init.d/S99helixscreen stop
rm /etc/init.d/S99helixscreen

# Remove files
rm -rf /usr/data/helixscreen

# Re-enable GuppyScreen
chmod +x /etc/init.d/S99guppyscreen 2>/dev/null || true

# Reboot to restore GuppyScreen
reboot

Getting Help

Check Logs First

Most issues are diagnosed from the logs:

MainsailOS (systemd):

# View recent logs
sudo journalctl -u helixscreen -n 100

# Follow live logs
sudo journalctl -u helixscreen -f

# Filter by error/warning level
sudo journalctl -u helixscreen -p err

AD5M / K1 (SysV init):

# View log file
cat /tmp/helixscreen.log

# Follow live logs
tail -f /tmp/helixscreen.log

Common Issues

See TROUBLESHOOTING.md for solutions to:

Connection problems
Display issues
Touch not responding
Configuration errors

Still Stuck?

Ask in the HelixScreen Discord for quick help
Check GitHub Issues for known problems
Open a new issue with:
- Your hardware (Pi model, display type)
- HelixScreen version
- Relevant log output
- Steps to reproduce

Platform-Specific Notes

Raspberry Pi 5

Pi 5 has multiple DRM devices. HelixScreen auto-detects the correct one, but if you have issues:

{
  "display": {
    "drm_device": "/dev/dri/card1"
  }
}

Common Pi 5 DRM devices:

/dev/dri/card0 - v3d (3D acceleration only, no display)
/dev/dri/card1 - DSI touchscreen (if connected)
/dev/dri/card2 - HDMI output

Camera Streaming Performance

If you use a webcam with HelixScreen, install libturbojpeg0 for faster camera feed rendering:

sudo apt install libturbojpeg0

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.

Low Memory Systems (Pi 3, Pi Zero 2 W)

HelixScreen is optimized for low memory, but if you experience issues:

Disable other services that aren’t needed
Reduce Moonraker’s cache size
Consider a lighter Mainsail configuration

Flashforge Adventurer 5M Memory Constraints

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

Next: User Guide - Learn how to use HelixScreen

Installation

Table of Contents

Quick Start

Prerequisites

MainsailOS (Raspberry Pi)

Flashforge Adventurer 5M / 5M Pro

AD5M Firmware Variants

Forge-X Prerequisites

Creality K1 Series

One-Liner Install (Recommended)

Two-Step Install (No Internet on Printer)

Creality K2 Series

FlashForge Adventurer 5X

Elegoo Centauri Carbon

Step 1: Install COSMOS firmware

Step 2: Install HelixScreen

Step 3: Switch back to another UI (optional)

Creality Sonic Pad

Snapmaker U1

Raspberry Pi / MainsailOS Installation

Step 1: Connect to Your Pi

Step 2: Run the Installer

Step 3: Complete the Setup Wizard

Flashforge Adventurer 5M Installation

Ready-Made Firmware Image (Easiest)

Manual Installation

Automated Installation (Recommended)

Manual Installation

Step 4: Reboot

Step 5: Complete Setup

Snapmaker U1 Installation

Quick Install (Recommended)

Manual Install

Reverting to Stock UI

First Boot & Setup Wizard

Step 1: Touchscreen Calibration

Step 2: Language Selection

Step 3: Network Setup

Step 4: Moonraker Connection

Step 5: Printer Identification

Step 6: Heater Selection

Step 7: Fan Selection

Step 8: LED Selection (Optional)

Step 9: Input Shaper (Optional)

Step 10: Hardware Summary

Completion

Display Configuration

HDMI Displays (Plug and Play)

Official Raspberry Pi Touchscreen (DSI)

SPI Displays (Requires Configuration)

BTT Pad 7, CB2, and Similar

Screen Rotation

GPU Rendering (Experimental)

Starting on Boot

Enable Automatic Start

Service Management

Disabling Other UIs

Updating HelixScreen

Check Current Version

Update from Mainsail/Fluidd Web UI (Pi Only)

Update Using Install Script (Recommended)

Update to Specific Version

Preserving Configuration

Manual Update Manager Setup

Uninstalling

Using Install Script (Recommended)

Manual Uninstall

Getting Help

Check Logs First

Common Issues

Still Stuck?

Platform-Specific Notes

Raspberry Pi 5

Camera Streaming Performance

Low Memory Systems (Pi 3, Pi Zero 2 W)

Flashforge Adventurer 5M Memory Constraints