Setting up the Ingcool 7IP-CAPLCD (7-inch HDMI Touchscreen) with KlipperScreen on MainsailOS

If you are setting up an Ingcool 7IP-CAPLCD 7-inch HDMI Capacitive Touchscreen on a Raspberry Pi running MainsailOS (Debian 12 Bookworm / Debian 13 Trixie), you’ll likely run into a blank screen or a terminal login prompt right where you were expecting the graphical KlipperScreen interface to be.

The docs from the manufacturer are there and helpful but they do not cover the underlying complexities of getting KlipperScreen working.

This guide provides a walkthrough process to get KlipperScreen rendering on the 7IP-CAPLCD quickly & reliably.

Prerequisites

  • Raspberry Pi 3B+/4B/5 running MainsailOS or Klipper on Debian Bookworm.
  • Ingcool 7IP-CAPLCD 7-inch HDMI Display (1024x600 resolution).
  • HDMI and USB touch cables connected between the Raspberry Pi and Display.

Step 1: Configure Boot Settings & Timings (config.txt)

Mount your SD card on your PC or edit the file via SSH.

Note on File Location: Depending on your OS version, config.txt will be located at:

  • Root Boot Partition / Older OS: config.txt (or /boot/config.txt)
  • Debian Bookworm/Trixie: /boot/firmware/config.txt NOTE: Debian Bookworm or newer provides comments that the file has moved if you open the one in the older location0
  1. Comment out the default KMS display driver line (this prevents the Pi from overriding custom HDMI resolution timings): This is somewhere in the middle of the config file and usually above the MainsailOS specific configuration that should not be modified.
#*************************************************************************************
# Removed for proper functionality with ingcool 7IP-CAPLCD Touchscreen.
#*************************************************************************************
# dtoverlay=vc4-kms-v3d
  1. Add or update the 7IP-CAPLCD settings (display block below) at the very bottom of the config.txt file:
#*************************************************************************************
# Ingcool 7IP-CAPLCD Configuration as provided by the online Wiki from ingcool:
# http://www.ingcool.com/wiki/7IP-CAPLCD?Amazon
#*************************************************************************************
hdmi_force_hotplug=1
config_hdmi_boost=10
hdmi_group=2
hdmi_mode=87
hdmi_timings=1024 1 200 18 200 600 1 50 6 50 0 0 0 60 0 51200000 3

Step 2: Configure Linux GPU Display Output (99-v3d.conf)

Bookworm requires explicit display driver options for X11 on the Pi’s VC4 GPU stack:

X11 (short for the X Window System, Version 11) is the basic display and windowing engine used by Linux to render graphical user interfaces (GUIs) on your Pi’s display without requiring a full desktop environment (like Raspberry Pi Desktop or GNOME) running in the background. This is the engine that we will use and setup for KlipperScreen.

  1. While SSH’ed Into your Raspberry Pi and run these commands to set up the 99-v3d.conf file and its content…
  2. Run these commands in sequence:
sudo mkdir -p /etc/X11/xorg.conf.d
sudo nano /etc/X11/xorg.conf.d/99-v3d.conf

Paste the following

Section "OutputClass"
    Identifier "vc4"
    MatchDriver "vc4"
    Driver "modesetting"
    Option "PrimaryGPU" "true"
EndSection

Step 3: Install KlipperScreen via KIAUH

Generally MainsailOS does not bundle KlipperScreen or its X11 dependencies by default. So the easiest and most streamlined way to get KlipperScreen installed then is to use Klipper Installation And Update Helper (aka KIAUH) to install them:

NOTES:

  • During this process a stable and reliable internet connection is needed as it will pull a lot of files down individually which can be taxing on an unstable Wifi.
  • During the setup you may be asked to login multiple times as needed for the installation process to have necessary permissions.

Install Process:

  1. While SSH’ed Into your Raspberry Pi and run these commands…
  2. Clone down KIAUH from Github and Launch it (if not already installed):
git clone https://github.com/dw-0/kiauh.git
./kiauh/kiauh.sh
  1. Navigate the KIAUH menues install KlipperScreen – the menues are occassionaly updated but generally it is:
    • 1) [Install] –> Touchscreen GUI: section –> 7) [KlipperScreen].
  2. Accept the default prompts (Y) during installation:
    • Agree to install X11 / display dependencies.
    • Agree to install NetworkManager for on-screen network monitoring.
      • Once you select Yes to install Network Manager your connection may drop as the network may be reset! This may cause your terminal to drop/clear and to no longer be able to see the installation process or prior logs in the terminal (depending what terminal app you are using – Putty clears the console).

      • Just give it a couple minutes 2-3 and then reboot the Raspberry Pi.

Step 4: Fix Non-Root X11 Permissions

By default, Debian restricts X11 from launching on non-root console terminals which can be an issue for KlipperScreen. We fix this by updating the settings in Xwrapper.config:

sudo sed -i 's/allowed_users=console/allowed_users=anybody/' /etc/X11/Xwrapper.config 2>/dev/null || echo "allowed_users=anybody" | sudo tee -a /etc/X11/Xwrapper.config

Step 5: Final Reboot & Service Check

Reboot your Pi to apply the GPU drivers, resolution timings, and service units:

sudo reboot

Upon boot, the system should clear the console prompt and automatically bring up the KlipperScreen dashboard in your 7IP-CAPLCD touchscreen!