Tag Archives: kde-plasma

How to setup Onboard Virtual Keyboard for Debian 13 + KDE Plasma 6 + Wayland (uinput-based)

Posted on by

Preface: From Almost Giving Up to Finally Being Able to Type

Honestly, this article was written when I was very close to giving up on using an on-screen keyboard under KDE Plasma Wayland.

On Debian 13 with KDE Plasma 6 running on Wayland, the only officially supported virtual keyboard is Maliit.
In practice, however, it comes with a series of nearly deal-breaking problems:

  • The keyboard only appears once
  • After swiping it down, it can never be summoned again
  • Requires restarting KWin or the entire desktop session
  • Completely unsuitable for real tablet or 2-in-1 usage

After digging through GitHub issues and KDE Discuss threads, I honestly started to think:

“Maybe choosing KDE Wayland on a touch device is simply a dead end.”

That changed when I found a KDE Discuss thread from 2022:

Plasma 6 and Wayland no on-screen keyboard working - Help - KDE Discuss

In that thread, a user named @INVICTRA mentioned:

I managed to get Onboard working on wayland. Kubuntu 25.04

Edit the shortcut and add GDK_BACKEND=x11
Set input source to GTK
Set keystroke generator to uinput

The post was short and incomplete, but it revealed something important:

Onboard + X11 backend + uinput might be the real breakthrough.

With that clue, I started experimenting, filling in the missing pieces: kernel modules, permissions, udev rules, and Wayland constraints.
In the end, I successfully achieved a stable, repeatable, non-freezing virtual keyboard on:

Debian 13 + KDE Plasma 6 + Wayland

This article is the fully documented result of that process.

1. Why This Is Necessary (Background)

  • As of late 2025, KDE Plasma Wayland officially supports only Maliit
  • Maliit currently suffers from severe bugs on Plasma (cannot be re-opened after hiding)
  • Wayland intentionally forbids synthetic input (fake keyboard/mouse events)
  • Onboard can create a real input device via the Linux kernel uinput subsystem
  • uinput devices are kernel-level input devices and are not blocked by Wayland

In short:

Wayland does not allow you to fake keystrokes,
but uinput lets you attach a real virtual keyboard.

Under Debian + KDE Plasma Wayland today,
this is practically the only solution that actually works.

2. System Requirements

  • Debian GNU/Linux 13
  • KDE Plasma 6
  • Wayland session
  • XWayland installed (usually installed by default)
  • User has sudo privileges

3. Install Required Packages

sudo apt update
sudo apt install onboard xwayland

4. Enable the Kernel uinput Module

1. Check if uinput is loaded

lsmod | grep uinput

If there is no output, load it manually:

sudo modprobe uinput

2. Enable uinput at boot

echo uinput | sudo tee /etc/modules-load.d/uinput.conf

5. Configure uinput Permissions (Critical Step)

1. Create the group

sudo groupadd -f uinput

2. Add your user to the group (example: hln)

sudo usermod -aG uinput hln

Important: You must log out or reboot after this step.

3. Create a udev rule

sudo nano /etc/udev/rules.d/99-uinput.rules

Contents:

KERNEL=="uinput", MODE="0660", GROUP="uinput"

Reload rules:

sudo udevadm control --reload
sudo udevadm trigger

4. Verify After Reboot

ls -l /dev/uinput

Expected output:

crw-rw---- 1 root uinput /dev/uinput

Confirm group membership:

groups

You should see uinput.

6. Launch Onboard Using the X11 Backend (Very Important)

Under Wayland, Onboard must be forced to use the X11 backend:

GDK_BACKEND=x11 onboard

It is recommended to test this first in a terminal.

7. Required Onboard Settings

Open Onboard → Preferences → Keyboard → Advanced

Set the following:

  • Input Options

    • Input event source: GTK

  • Keystroke Generation

    • Key-stroke generator: uinput

If you previously tried uinput and it did not work,
you must re-test after completing the permission setup.

8. Verification

  1. Open a text-input application (Kate / Firefox / Konsole)
  2. Focus a text field
  3. Click keys on Onboard

Successful behavior:

  • Text appears in the application
  • Keyboard can be shown and hidden repeatedly
  • No need to restart KWin
  • No freezing or dead state
  • Completely avoids Maliit bugs

9. Create a Desktop Launcher (Recommended)

nano ~/.local/share/applications/onboard-x11.desktop

Contents:

[Desktop Entry]
Name=Onboard (Wayland Safe)
Exec=env GDK_BACKEND=x11 onboard
Type=Application
Icon=onboard
Categories=Utility;Accessibility;

You can now:

  • Pin it to the KDE panel
  • Place it on the desktop
  • Use it as a one-click virtual keyboard launcher

10. Limitations and Notes

Known Limitations

  • Does not work on the SDDM login screen
  • Not Wayland-native (runs via XWayland)
  • Elevated input permissions (recommended for personal devices only)

Advantages

  • No swipe-down freeze issue
  • Full Ctrl / Alt / Function key support
  • Works with Fcitx5 (Chewing / Zhuyin)
  • Compatible with Synergy / KVM
  • Stable for long-term use

11. Reverting the Setup (Optional)

sudo rm /etc/udev/rules.d/99-uinput.rules
sudo gpasswd -d hln uinput
sudo reboot

12. Conclusion

On Debian 13 with KDE Plasma Wayland:

Onboard + uinput is currently the only virtual keyboard solution that truly works.

It is not an official or perfect solution,
but KDE is a volunteer-driven community, and expectations should remain realistic.

What matters most is that the problem is solved:
I can now use a keyboard-less tablet to type Taiwanese Mandarin with Zhuyin or English and actually get work done.