FAQ

Quick answers to common questions about HelixScreen.

General

What is HelixScreen?

HelixScreen is a touchscreen interface for Klipper 3D printers. It connects to your Moonraker instance and provides a modern, touch-friendly UI for controlling your printer.

Key features:

30+ panels, 20+ overlays, and a customizable multi-page widget dashboard
3D G-code preview, bed mesh visualization, frequency response charts
6 multi-material backends (AFC, Happy Hare, ACE, AD5X IFS, CFS, tool changers) with Spoolman integration
First-run wizard with auto-detection of 70+ printer models
Theme editor with 17 presets (dark and light), 9 languages
Sound system, timelapse integration, label printing, exclude objects
Auto-detecting layout system for displays from 480x320 to 1920x480
~13MB RAM — designed for embedded displays, no desktop required

Which printers are supported?

HelixScreen works with any Klipper-based printer running Moonraker. Tested and supported platforms:

Platform	Status	Notes
Voron 0.1, 2.4, Trident	Tested	Primary development platforms
Doron Velta / RatRig V-Core	Tested
FlashForge AD5M / 5M Pro	Tested	Requires Forge-X or Klipper Mod firmware
QIDI Q2, Max 4	Supported	Requires FreeDi firmware for Moonraker access
Creality K1 / K1C / K1 Max / K1 SE	Supported	Requires rooting or Guilouz firmware
Creality K2 Max / K2 Plus	Tested	Runs natively with CFS support
Creality Sonic Pad	Supported	32-bit ARM, dedicated build
FlashForge AD5X	Tested	IFS filament system integrated
SOVOL SV06 / SV08	Tested	Community reports welcome
Elegoo Centauri Carbon 1	Tested	Requires OpenCentauri COSMOS firmware; ships with factory white-balance calibration
Other Klipper printers	Should work	Any printer with Moonraker API access

Note: “Tested” means the HelixScreen team has verified the platform. “Untested” means binaries exist but haven’t been verified on real hardware. See the Installation Guide for platform-specific instructions.

Which displays are supported?

Tested and confirmed working:

BTT 5” HDMI/DSI touchscreen
BTT 7” HDMI/DSI touchscreen
FlashForge AD5M built-in 4.3” display (800x480)

Active testing underway:

FlashForge AD5X built-in 4.3” display (800x480)

Should work but not yet tested:

Official Raspberry Pi 7” DSI touchscreen
Creality K2 built-in 4.3” display (480x800, portrait — may need rotation)
Other HDMI displays
SPI displays (with proper configuration)

Display sizes: HelixScreen auto-detects the best layout for your display. 800x480, 1024x600, and 1920x480 (ultrawide) are fully supported. 480x320 displays will run but may have layout overlap issues — improved small-screen support is ongoing.

Display rotation: All three binaries (main, splash, watchdog) support 0°, 90°, 180°, and 270° rotation via config or command line.

If you test on hardware not listed above, please let us know your results!

How is this different from KlipperScreen and GuppyScreen?

Feature	HelixScreen	KlipperScreen	GuppyScreen
UI Framework	LVGL 9 XML	GTK 3 (Python)	LVGL 8 (C)
Declarative UI	Full XML	Python only	C only
Disk Size	~75-115MB	~50MB	~60-80MB
RAM Usage	~13MB	~50MB	~15-20MB
Reactive Binding	Built-in	Manual	Manual
3D G-code preview	Yes	2D layers	No
3D bed mesh	Yes	2D heatmap	2D heatmap
Status	Pre-1.0 (active)	Mature (maintenance)	Unmaintained

HelixScreen advantages:

Low memory footprint (~13MB vs ~50MB for KlipperScreen)
Declarative XML layouts (change UI without recompiling)
Modern reactive architecture with 6 multi-material backends
3D visualizations (G-code preview, bed mesh)
70+ printer auto-detection database
9 languages (English, German, Spanish, French, Italian, Japanese, Portuguese, Russian, Chinese)

Installation

What Raspberry Pi do I need?

Pi Model	Supported	Notes
Pi 5	✅ Recommended	Best performance
Pi 4	✅ Recommended	Great performance
Pi 3B+	✅ Minimum	Works well
Pi 3B	⚠️ Usable	May be slow
Pi Zero 2 W	✅ OK	Good for space-constrained setups
Pi Zero (original)	❌ No	Too slow

Memory: 1GB minimum, 2GB+ recommended.

32-bit and 64-bit: Both are supported. The installer automatically detects your architecture (uname -m) and downloads the correct binary — aarch64 gets the 64-bit build, armv7l gets the 32-bit build. No manual selection needed.

Can I run HelixScreen alongside KlipperScreen/GuppyScreen?

Not on the same display. Both compete for the framebuffer. The HelixScreen installer automatically disables any existing screen UI.

MainsailOS (systemd):

# Disable KlipperScreen
sudo systemctl stop KlipperScreen
sudo systemctl disable KlipperScreen

# Enable HelixScreen
sudo systemctl enable helixscreen
sudo systemctl start helixscreen

AD5M Klipper Mod (SysV init):

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

# Enable HelixScreen
chmod +x /etc/init.d/S80helixscreen
/etc/init.d/S80helixscreen start

AD5M Forge-X (SysV init):

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

# Enable HelixScreen
chmod +x /etc/init.d/S90helixscreen
/etc/init.d/S90helixscreen start

If you have two displays, you could theoretically run both (advanced configuration, not tested).

Do I need to install X11 or a desktop environment?

No. HelixScreen renders directly to the framebuffer (fbdev) or DRM. It doesn’t need:

X11 / Xorg
Wayland
Desktop environment (GNOME, KDE, etc.)
Display manager (LightDM, GDM, etc.)

This is why it uses less memory than alternatives.

Does this work with MainsailOS, FluiddPi, or other Klipper distros?

Yes! HelixScreen works with any Klipper distribution that includes Moonraker:

MainsailOS ✅
FluiddPi ✅
Custom Klipper installs ✅
KIAUH installs ✅

The web frontend you use (Mainsail, Fluidd, etc.) doesn’t matter - HelixScreen talks to Moonraker.

What gets preserved during upgrades?

Your configuration is safe. The installer preserves:

settings.json — all your settings
helixscreen.env — environment variable overrides
Custom printer images in config/custom_images/
Custom theme files in config/themes/

Your Klipper configuration is never touched. See the Upgrade Guide for instructions.

My display is upside down or rotated wrong

Set the rotation in your config file:

# Edit settings.json and add/change in the "display" section:
"rotation": 180

Valid values: 0, 90, 180, 270. Restart HelixScreen after changing.

Features

Does it support multiple extruders / toolchangers?

Yes. Full multi-extruder and toolchanger support:

✅ Per-extruder temperature control with extruder selector in the Temperature panel
✅ Toolchanger support via klipper-toolchanger — active tool badge on Home panel (T0, T1, etc.)
✅ Tool-prefixed temperatures on the print status overlay
✅ Dynamic discovery of all extruders from Klipper (extruder, extruder1, extruder2, etc.)
✅ Multiple filament systems can run simultaneously (e.g. toolchanger + Happy Hare)

Can I use my webcam?

Yes. HelixScreen shows your webcam feed on the home dashboard and during printing. It automatically detects webcams configured in Moonraker (crowsnest, camera-streamer, etc.) and displays the MJPEG stream.

For the best camera performance on Raspberry Pi, install libturbojpeg0:

sudo apt install libturbojpeg0

This enables SIMD-accelerated (hardware-optimized) JPEG decoding, which is 3-5x faster than the built-in software decoder. HelixScreen automatically uses it if available — no configuration needed. Without it, everything still works, just with slightly higher CPU usage during camera streaming.

Does it work with Spoolman?

Yes. Spoolman integration is supported:

Advanced panel → Spoolman to browse your spool inventory
Settings → Spoolman for weight sync settings
Assign spools to AMS slots and track filament usage

Can I print spool labels?

Yes. HelixScreen supports printing physical spool labels to thermal label printers:

Brother QL — via Network or Bluetooth
Phomemo — via USB or Bluetooth
Niimbot — via Bluetooth (B21, D11, D110)
MakeID — via Bluetooth (E1, L1, M1 — 9/12/16mm continuous tape)

Labels include spool name, material, color swatch, temperatures, and a QR code. See the Label Printing Guide for setup.

Does it support Happy Hare or AFC-Klipper?

Yes. Full multi-material support is available for:

Happy Hare — MMU2, ERCF, 3MS, Tradrack
AFC-Klipper — Box Turtle with full data parsing, 11 device actions, per-lane reset, and mock mode
ACE (Anycubic ACE Pro, via ValgACE/BunnyACE/DuckACE Klipper drivers) — supported
Tool changers — supported

Features include visual slot configuration with tool badges, endless spool arrows, tap-to-edit popup, Spoolman integration, and material compatibility validation.

Can I customize the home screen widgets?

Yes! The Home Panel displays configurable widgets — quick-access buttons for features like temperature, LED control, network status, AMS, and more.

To customize:

Go to Settings → Home Widgets (in the Appearance section)
Toggle widgets on or off
Long-press the drag handle to reorder

Up to 10 widgets can be shown. Some widgets (like AMS, humidity sensor, or probe) only appear if the relevant hardware is detected. See the Home Panel guide for the full widget list.

Can I customize the colors or layout?

Yes! HelixScreen includes a built-in theme editor with 17 preset themes:

Go to Settings → Display Settings
Tap Theme to open the theme editor
Choose from presets: Ayu, Catppuccin, ChatGPT, Cupertino, Dracula, Everforest, Gruvbox, HelixScreen, Kanagawa, Material Design, Midnight, Nord (default), One Dark, Rose Pine, Solarized, Tokyo Night, or Yami
Toggle dark/light mode
Customize individual colors if desired - changes are saved to config/themes/

For layout customization, you can edit XML files in ui_xml/ (no recompilation needed).

Does it support multiple printers?

Yes! You can configure multiple Klipper printers and switch between them from the navigation bar or Settings. You view one printer at a time, but switching is instant. Enable this under Settings → Beta Features, then add printers via Settings → Printers.

Can I view print history?

Yes. The History panel shows past prints with statistics, thumbnails, and details. Access via the navbar or home screen.

Can I send G-code commands directly?

Yes. The Console panel lets you send G-code commands and view responses. Access via Advanced → Console.

Does it support power device control?

Yes. If you have Moonraker power devices configured, the Power panel lets you control them. Access via Settings → System → Power Devices, or Advanced → Power, or long-press the home panel power button.

Can I view and run bed mesh?

Yes. The Bed Mesh panel shows a 3D visualization of your bed mesh and lets you run calibration. Access via Controls → Bed Mesh.

Does it support input shaper?

Yes. The Input Shaper panel provides a full calibration workflow with frequency response charts, per-axis results, shaper comparison tables, and Save Config. Access via Advanced → Input Shaper. Requires an accelerometer configured in Klipper.

Does it support exclude objects?

Yes. During a print, you can exclude objects that failed. Tap the print status area to access exclude object controls.

Can I run macros?

Yes. The Macro panel shows your Klipper macros. Access via Advanced → Macros. You can also configure quick macro buttons in Settings → Macro Buttons.

Can I change which macro the Load / Unload / Purge buttons run?

Yes. Go to Settings > Printer > Macro Buttons and scroll to the Standard Macros section. Each button has a dropdown where you can select any macro from your Klipper config, or choose (Auto) to let HelixScreen detect it automatically. This works with or without an AMS system — see the Filament guide for details.

Can I customize the printer image on the home screen?

Yes. Tap the printer image on the Home Panel to open the Printer Manager, then tap the image again to open the Printer Image picker. You have three options:

Auto-Detect (default) — HelixScreen picks an image based on your printer type from Klipper
Shipped Images — Choose from 25+ pre-rendered images (Voron, Creality, FlashForge, Anycubic, RatRig, etc.)
Custom Images — Drop a PNG or JPEG file into config/custom_images/ and it appears automatically the next time you open the picker. You can also import images directly from a USB drive. Files must be under 5MB and 2048x2048 pixels max.

Your selection is saved to the display.printer_image config key and persists across restarts. See the Printer Manager guide for step-by-step instructions.

Can I rename my printer?

Yes. Tap the printer image on the Home Panel to open the Printer Manager. Then tap the printer name (shown with a pencil icon) to enable inline editing. Type the new name and press Enter to save, or Escape to cancel. The name syncs automatically with Mainsail and Fluidd. See the Printer Manager guide for details.

What languages are supported?

HelixScreen ships with 9 languages: English, German, Spanish, French, Italian, Japanese, Portuguese, Russian, and Chinese. Change the language in Settings → Language.

Does HelixScreen collect any data?

Only if you opt in. Telemetry is off by default. When enabled, it collects anonymous usage data (display resolution, platform, print outcomes) to help improve the software. No filenames, G-code, IP addresses, or personal information is ever collected. You can view, disable, and delete your data at any time in Settings → Telemetry. See the Telemetry page for full details.

Usage

Can I use a USB mouse or keyboard?

Yes. HelixScreen automatically detects USB mice and keyboards connected at startup. Both work alongside the touchscreen — you don’t have to choose one or the other. A small white cursor appears when a mouse is detected. Combo devices like the Logitech K400 (keyboard + trackpad) also work.

Devices must be plugged in before HelixScreen starts. If auto-detection doesn’t find your device, set HELIX_MOUSE_DEVICE or HELIX_KEYBOARD_DEVICE in helixscreen.env to the device path (run cat /proc/bus/input/devices to find it).

How do I calibrate my touchscreen?

If taps register in the wrong location:

Go to Settings (gear icon)
Scroll to System section
Tap Touch Calibration
Tap the crosshairs that appear on screen
Calibration saves automatically when complete

Note: This option only appears on touchscreen displays, not in the desktop simulator.

How do I change the theme or colors?

Go to Settings → Display Settings
Tap Theme to open the theme editor
Browse available presets and see live preview
Toggle dark/light mode
Tap Apply to save (some changes require restart)

How do I adjust settings during a print?

Tap the Tune button on the print status screen to access:

Print Speed (50-200%) - Adjust movement speed
Flow Rate (75-125%) - Adjust extrusion rate
Z-Offset - Baby stepping for first layer adjustment

Fan control is available from the home screen fan widget or controls panel.

Does HelixScreen support firmware retraction?

Yes, if your printer has [firmware_retraction] configured in Klipper. Go to Settings → Retraction Settings (under Printer section) to adjust:

Retract length and speed
Unretract extra length and speed
Enable/disable firmware retraction

This option only appears if Klipper reports firmware retraction capability.

How do I check why the UI is slow?

Check your display connection: SPI displays are significantly slower than HDMI or DSI. If possible, use an HDMI or DSI-connected display for best performance.
Disable animations: Go to Settings → toggle Animations off
Check CPU/memory via SSH: Run top or htop to see if something else is using resources
Reduce logging: If you added -vv or -vvv to the service, remove it
Consider a faster SBC: Pi 4 or Pi 5 will be noticeably smoother than a Pi 3 or Pi Zero

Why does the setup wizard keep appearing?

The wizard runs when no valid configuration exists. Causes:

Config file missing or deleted
Config file has invalid JSON
Permissions prevent reading config

Fix: Check /opt/helixscreen/config/settings.json exists and is valid JSON.

How do I change the Moonraker address?

There’s currently no UI to change this after initial setup. Your options:

Edit the config file directly:

sudo nano /opt/helixscreen/config/settings.json
# Edit moonraker_host and moonraker_port in the "printer" section
sudo systemctl restart helixscreen

Or re-run the setup wizard:

# Either delete the config to trigger wizard on next start:
sudo rm /opt/helixscreen/config/settings.json
sudo systemctl restart helixscreen

# Or force wizard with command-line flag:
helix-screen --wizard

Troubleshooting

Touch doesn’t work

Check input device: ls /dev/input/event*
Test manually: sudo evtest /dev/input/event0
Specify device: Add "touch_device": "/dev/input/event1" to input section in config

Screen is black

Check service: sudo systemctl status helixscreen
Check logs: sudo journalctl -u helixscreen -n 50
Check framebuffer: ls /dev/fb* or ls /dev/dri/*
Try specifying device: Add "drm_device": "/dev/dri/card1" to display section in config

Can’t connect to Moonraker

Check Moonraker: sudo systemctl status moonraker
Test manually: curl http://localhost:7125/printer/info
Check firewall: sudo ufw status
Verify IP: hostname -I

See TROUBLESHOOTING.md for more solutions.

Development & Contributing

Is HelixScreen open source?

Yes! HelixScreen is licensed under GPL v3. Source code is on GitHub.

How can I contribute?

See the Contributing Guide for:

Code standards
Development setup
Pull request process

We welcome:

Bug reports
Feature suggestions
Code contributions
Documentation improvements

How do I build from source?

See the Development Guide for build instructions, dependencies, and development setup.

What programming language is HelixScreen?

C++17 for application logic
XML for UI layouts (LVGL 9 declarative system)
Makefile for build system
Bash for scripts

Getting Help

Where can I get help?

HelixScreen Discord — community support, setup help, feature discussions, and development updates
GitHub Issues — bug reports and feature requests

Where can I report bugs?

Open an issue on GitHub Issues with:

HelixScreen version
Hardware info (Pi model, display)
Steps to reproduce
Relevant log output

Where can I request features?

Open a GitHub issue with the “enhancement” label, or suggest it in the Discord.

How do I enable debug logging?

Easiest method: Go to Settings > System > Log Level and select Debug from the dropdown. The change takes effect immediately — no restart needed. Set it back to Warn when you’re done.

Alternative (via config file): Add HELIX_LOG_LEVEL=debug to your helixscreen.env file and restart:

# MainsailOS / Pi
echo 'HELIX_LOG_LEVEL=debug' >> ~/helixscreen/config/helixscreen.env
sudo systemctl restart helixscreen

# AD5M (Forge-X)
echo 'HELIX_LOG_LEVEL=debug' >> /opt/helixscreen/config/helixscreen.env
/etc/init.d/S90helixscreen restart

Available levels: warn (default), info, debug, trace. Set back to Warn after debugging — verbose logging impacts performance.

Where are the logs?

# systemd journal (MainsailOS)
sudo journalctl -u helixscreen -f

# If using file logging
cat /var/log/helix-screen.log
# or
cat ~/.local/share/helix-screen/helix.log

For more details, see: