KlipperScreen Setup Guide for Voron — Touch Display Installation

Klipper Firmware Display

KlipperScreen is a touchscreen user interface for Klipper-based printers. It runs as a web-based UI rendered on a local display connected to your Raspberry Pi, giving you a full-featured printer control panel without needing a phone, tablet, or laptop. This guide covers display hardware selection, installation via KIAUH or manual methods, configuration for Voron-specific macros, customizing layouts, and troubleshooting common issues. Last updated: May 2025.

What is KlipperScreen?

KlipperScreen is a Python application that runs on the same Raspberry Pi (or SBC) that runs Klipper and Moonraker. Instead of connecting to Mainsail or Fluidd from a browser on another device, KlipperScreen renders a touch-optimized interface directly on a screen physically attached to the printer. It communicates with Klipper through Moonraker's API, meaning it has full access to everything: print status, temperature control, bed mesh visualization, webcam stream, move controls, and custom macros.

Key advantages over a phone/tablet:

• Always-on display — no unlocking a device or opening a browser
• Dedicated to the printer — family members or guests can operate the printer easily
• Touch-optimized UI — larger buttons, swipe gestures, fewer accidental taps
• Printers can be completely network-independent for basic operation

Display Hardware

Official Raspberry Pi Touchscreen (7")

• Interface: DSI (Display Serial Interface) — direct ribbon cable to Pi
• Resolution: 800x480
• Pros: Native Pi support, excellent Linux integration, no USB power needed
• Cons: 7" is large for Voron enclosures, relatively expensive ($60-80), low resolution by modern standards
• Mounting: Needs custom bracket or 3D-printed mount to attach to Voron frame

Waveshare Displays (3.5" to 7")

• Interface: HDMI (for larger sizes) or SPI (for smaller sizes)
• 3.5" SPI: 480x320, suitable for V0.2 builds where space is tight
• 4" HDMI: 800x480, good balance of size and readability
• 5" HDMI: 800x480 or 1024x600, the most popular Voron size
• 7" HDMI: 1024x600, large and very readable
• Pros: Wide size selection, good value, many have capacitive touch
• Cons: SPI models require GPIO pins and have slower refresh rates; HDMI models need USB for touch input

DSI vs HDMI vs SPI

Recommended: 5" HDMI Touchscreen

For most Voron builds, a 5" HDMI capacitive touchscreen (800x480 or 1024x600) is the sweet spot. It's large enough to read comfortably, small enough to mount on the front frame or top panel of any Voron model, and the capacitive touch is much more responsive than resistive alternatives. Popular models from Waveshare or generic HDMI displays work well.

Installation via KIAUH

KIAUH (Klipper Installation And Update Helper) is the easiest method. KIAUH has KlipperScreen as a built-in installation option:

cd ~/kiauh
./kiauh.sh

1. Select option 4 (Advanced) from the main menu
2. Select option 5 (KlipperScreen)
3. Confirm the installation path (default: ~/KlipperScreen)
4. KIAUH clones the repo, installs dependencies (PyGObject, GTK, etc.), and sets up the systemd service
5. After installation, enable the service: sudo systemctl enable KlipperScreen
6. Reboot: sudo reboot

Manual Installation

If you prefer manual control or can't use KIAUH:

cd ~
git clone https://github.com/jordanruthe/KlipperScreen.git
cd ~/KlipperScreen
./scripts/KlipperScreen-install.sh

The installer script handles dependency installation and systemd service setup. After it completes, verify the service status:

sudo systemctl status KlipperScreen

KlipperScreen Configuration

KlipperScreen's main config file is ~/KlipperScreen/screen.conf. Key settings for Voron users:

Screen Dimensions and Rotation

[main]
# Screen dimensions (pixels)
width=800
height=480

# Rotation: 0, 90, 180, 270
rotation=0

# Touch rotation (if different from display)
touch_rotation=0

Adjust width and height to match your display's native resolution. Set rotation if you mount the display in landscape vs portrait orientation.

Printer Name

# Printer name shown on screen
printer_name=Voron V2.4

Menu Layout and Theme

# Menu layout: configurable panels
config_panel_layout=main

# Theme selection (dark mode is default)
theme=z-bolt-dark

Available themes include: z-bolt-dark (default, excellent readability), z-bolt-light, material-dark, material-light, and several community themes. Dark mode is strongly recommended for Voron enclosures — less glare through the acrylic panels.

Customizing KlipperScreen for Voron

Adding Voron-Specific Macro Buttons

KlipperScreen can display custom macro buttons for your Voron's specific needs. Edit ~/KlipperScreen/screen.conf and add menu items:

[menu __main]
menu_items = calibrate, level, macros

[menu __main __calibrate]
name=Calibrate
icon=calibrate
menu_items = z_tilt, qgl, bed_mesh, pid

[menu __main __calibrate __z_tilt]
name=Z Tilt
method=printer.gcode.script
params=Z_TILT_ADJUST

[menu __main __calibrate __qgl]
name=Quad Gantry Level
method=printer.gcode.script
params=QUAD_GANTRY_LEVEL

[menu __main __calibrate __bed_mesh]
name=Bed Mesh
method=printer.gcode.script
params=BED_MESH_CALIBRATE

[menu __main __calibrate __pid]
name=PID Calibrate
method=printer.gcode.script
params=PID_CALIBRATE HEATER=extruder TARGET=250

Hiding Irrelevant Panels

If your Voron doesn't have certain features (e.g., no aux fan, no chamber heater), hide those panels to keep the UI clean:

# Hide panels you don't need
[main]
show_heater_bed=true
show_extruder=true
show_fan=true
show_chamber=false

Custom Background

Replace ~/KlipperScreen/styles/background.jpg with your own image. A dark Voron logo or a photo of your printer makes nice custom backgrounds. The image is 800x480 pixels (or your screen's resolution).

KlipperScreen Features

Print Status

The main screen shows current print state (printing/paused/complete), elapsed time, remaining time, progress bar, layer number, and file name. Swipe left to see the temperature graph.

Bed Mesh Visualization

After running BED_MESH_CALIBRATE, the bed mesh is displayed as a color-coded height map. Green is level, red is high, blue is low. This is invaluable for diagnosing bed leveling issues.

Temperature Graph

Real-time temperature plot for hotend, bed, and any additional temperature sensors (chamber, enclosure). Tap any line to see exact values at that point.

Webcam Stream

If configured in Moonraker, the webcam stream appears on a dedicated panel. Touch the stream to toggle fullscreen. Note: GPU-accelerated decoding on Pi improves stream performance significantly.

Move Controls

Touch X/Y/Z move buttons with selectable step sizes (0.1mm, 1mm, 10mm, 100mm). The extruder section allows jogging filament forward or backward. Hold buttons for continuous movement.

Troubleshooting

Touch Calibration Utility

For displays that need touch calibration, KlipperScreen includes a built-in calibration mode. Hold two fingers on the screen at startup to enter calibration mode, or add to screen.conf:

[touch]
calibration=3782 52 162 3789

Values come from xinput_calibrator output. If your display uses resistive touch (common on cheaper SPI panels), recalibration may be needed over time as the touch layer wears.

Alternative: Mainsail Mobile PWA on Tablet

If you decide not to install KlipperScreen, a popular alternative is using Mainsail's Progressive Web App (PWA) on a tablet or old phone mounted to the printer frame. Key differences:

• No installation on the Pi required — just run Moonraker
• Larger screen available (tablet 8-10" vs typical 5-7" display)
• Wireless — device can be handheld or mounted
• Less Pi CPU/RAM overhead (KlipperScreen uses resources for rendering)
• Disadvantage: depends on WiFi connection, battery needs charging, device can be borrowed/moved

Many Voron owners use both: KlipperScreen on a small display for everyday operation, and a tablet running Mainsail PWA for advanced features and webcam viewing.