Plasma Mobile

From postmarketOS
Revision as of 12:29, 14 August 2020 by Afontain (talk | contribs) (→‎Status: Remove some known-outdated information)
Jump to navigation Jump to search
Plasma Mobile doesn't work on armhf due to an issue with qt5-qtdeclarative. If your device is actually armv7 but still runs on armhf, please change it.
Plasma Mobile
Plasma Mobile running on LG Nexus 5 (hammerhead)
Plasma Mobile running on LG Nexus 5 (hammerhead)
Name Plasma Mobile
Graphics stack KWin on Wayland
Toolkit Qt 5

A mobile variant of the KDE Plasma user interface, optimized for touchscreen.


It works on most devices with a working display and with hardware acceleration. There is a (possibly outdated) script below that may allow it to start on framebuffer. Do note that this interface is unbearably slow without hardware acceleration and is not recommended for devices without it.


Using pmbootstrap, Plasma Mobile can be installed by selecting it as the UI in pmbootstrap init.

On existing systems, it can be installed by installing the postmarketos-ui-plasma-mobile meta package or plasma-phone-components if postmarketOS specific customization is not wanted.

Starting Plasma Mobile

If postmarketos-ui-plasma-mobile is installed, Plasma Mobile will be automatically launched via the LightDM display manager.

It can also be launched manually by running the following script:


export QML2_IMPORT_PATH=/usr/lib/qt/qml:/usr/lib/qt5/qml
export PLASMA_PLATFORM=phone:handset
sleep 2

if [ -d "/dev/dri" ]; then
	kwin_wayland --drm --xwayland plasma-phone 2>&1 | logger -t "$(whoami):plasma-mobile"
	# NOTE: using GALLIUM_DRIVER=llvmpipe might give you better performance (or not work at all.)
	# If it does give you a performance gain, please open an issue to discuss how to implement this properly.
	export GALLIUM_DRIVER=softpipe

	echo "startplasmamobile: using software rendering with: ${GALLIUM_DRIVER}" | logger -t "$(whoami):plasma-mobile"
	kwin_wayland --framebuffer --xwayland plasma-phone 2>&1 | logger -t "$(whoami):plasma-mobile"

Running Apps from SSH session

In order to run applications on the device, you need to set up your environment similar to the environment in which the plasmashell is running:

export $(cat /proc/$(pidof plasmashell)/environ | tr '\0' '\n')

For the official KDE instructions on running Plasma Mobile, see their website.

Taking screenshots

In command line:

qdbus org.kde.KWin /Screenshot org.kde.kwin.Screenshot.screenshotArea 0 0 1080 1920

qdbus-qt5 is from package qt5-qttools.



On devices such as Samsung_Galaxy_A5_2015_(samsung-a5ulte) and Moto_G4_Play_(motorola-harpia), you may need to set a custom scaling factor.

The following sets a 2x scale factor:

kscreen-doctor output.1.scale.2

If you're trying to run this from SSH session, you need to set extra env vars:

XDG_RUNTIME_DIR=/run/user/10000 QT_QPA_PLATFORM=wayland kscreen-doctor output.1.scale.2

Software rendering

Plasma can also be used if your device doesn't support hardware acceleration (if it's a non-armhf device) yet by using software rendering. Please note that the interface will be slow, and it might not be usable for the average user.

Software rendering is not enabled automatically for now. Make sure mesa-dri-gallium is installed (it contains swrast dri module).

Edit kwin wrapper startup script

$ sudo nano /usr/bin/kwinwrapper

Comment out existing startplasma invocation command at the end of file and replace it with

export KWIN_COMPOSE=QPainter
export GALLIUM_DRIVER=softpipe

startplasma-wayland \
        --framebuffer \
        --xwayland \
        --libinput \
        --inputmethod maliit-server \

Then restart lightdm

$ sudo rc-service lightdm restart

Log output

If Plasma is launched via LightDM using the postmarketos-ui-plasma-mobile package, logs can be viewed by running logread | grep plasma-mobile. The log can also be viewed live by running logread -f; anything related to Plasma and KDE will have a $username:plasma-mobile prefix.

Logging isn't verbose

One needs to enable debug logging for certain components in ~/.config/QtProject/qtlogging.ini. Without that, you barely see any log output. We ship such a qtlogging.ini file in postmarketos-ui-plasma-mobile because Plasma Mobile is relatively new and we want to be able to debug it properly.

If the file did not get installed for you, please double check if it is there and report in 1038.

KWin doesn't work

Plasma Mobile shell uses some Wayland protocols, so you can't run it on X11 in case you tried to do that.

Please follow these instructions for debugging.

Some env vars that may help Angelfish browser

# Recommended in
# Flags are based on workaround for SFOS (disable-gpu-compositing) and default Android settings:
# Multiple Raster Threads: Disabled
# Flags enabled by Qt if enable-embedded-switches is given
export QTWEBENGINE_CHROMIUM_FLAGS="--disable-gpu-compositing --num-raster-threads=1 --enable-viewport --disable-composited-antialiasing"

( source )


Follow the Display guide to change and fix display related issues.