Jump to content

Plasma Mobile: Difference between revisions

From postmarketOS Wiki
No edit summary
Fossdd (talk | contribs)
Installation: add only systemd
 
(62 intermediate revisions by 25 users not shown)
Line 1: Line 1:
{{note|Plasma Mobile doesn't work on armhf due to an [https://gitlab.com/postmarketOS/pmaports/issues/75 issue with <code>qt5-qtdeclarative</code>]. If your device is actually armv7 but still runs on armhf, please change it.}}
{{Infobox interface
{{Infobox interface
| name = Plasma Mobile
| name = Plasma Mobile
| image = File:Plasma-mobile-hammerhead.jpg
| image = File:Plasma Mobile homescreen.png
| imagecaption = Plasma Mobile running on LG Nexus 5 (hammerhead)
| imagecaption = Plasma Mobile homescreen.
| graphics = KWin on Wayland
| graphics = KWin on Wayland
| toolkit = Qt 5
| toolkit = Qt 6
}}
}}


A mobile variant of the KDE Plasma [[User-Interfaces|user interface]], optimized for touchscreen.
A mobile variant of the KDE Plasma [[:Category:Interface|user interface]], optimized for touchscreen.
 
= Installation =
 
{{UI_init|only_systemd=true}}
 
Use the pre-built images from the downloads section of [https://postmarketos.org postmarketos.org], or build your own image with [[pmbootstrap]]. If using the latter, Plasma Mobile can be installed by selecting it as the UI in <code>pmbootstrap init</code>.
 
On existing systems, it can be installed by installing the <code>postmarketos-ui-plasma-mobile</code> meta package or <code>plasma-mobile</code> if postmarketOS specific customization is not wanted.
 
When running <code>pmbootstrap install</code> you'll be prompted for a user password. On an existing Plasma Mobile install you can change your user password and PIN in the Terminal with the standard <code>passwd</code> command.
 
[[File:Postmarketos-pinephone-plasma-mobile-v21.03.jpg|250px|thumb|postmarketOS v21.03 with Plasma Mobile on the PinePhone]]
 
= Usage =
== First Boot ==
{{note|If you get stuck, head over to [[Matrix and IRC|Matrix and IRC chats]]. [[How_to_report_issues|Report issues]].}}
As with all other interfaces in postmarketOS, the first boot takes longer than usual: the file system will be resized to use the entire device.
 
After boot, you are asked for your PIN. For pre-built images, this is <code>147147</code>.  If you flash a rootfs
created with pmbootstrap, the "PIN" is the user password you provided during pmbootstrap install.
 
== Connect to Wi-Fi ==
Swipe the top bar down to reveal a menu with a Wi-Fi symbol. Tapping the symbol itself will turn Wi-Fi on or off. To connect to a network the first time, hold down the Wi-Fi quick setting to open the settings application. Now select an access point.
 
== Install Updates ==
Go to the Home Screen (tap the bottom right X if you have an application open). Swipe from the bottom upwards to reveal the app menu and start Discover, KDE's graphical package manager frontend. When Discover asks for privileges ({{issue|1036|pmaports}}), type in your user's PIN (e.g. <code>147147</code> for pre-built images).
 
Swipe from the left to center to open Discover's menu, and select the entry with the up-arrow at the very bottom (it may say "Fetching updates" or the number of updates available). From here you can perform the updates. Depending on what has been updated, you need to reboot the device afterwards for changes to take effect.
 
== 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:
 
<syntaxhighlight lang="shell">
export $(cat /proc/$(pidof plasmashell)/environ | tr '\0' '\n')
</syntaxhighlight>
 
For the official KDE instructions on running Plasma Mobile, see https://develop.kde.org/docs/plasma-mobile/running-apps/.
 
== Taking screenshots ==
Screenshots can be taken by pressing the button for it in the top drawer.
You can however also do it with the command line:
 
<syntaxhighlight lang="shell">
qdbus org.kde.KWin /Screenshot org.kde.kwin.Screenshot.screenshotArea 0 0 1080 1920
</syntaxhighlight>
 
<code>qdbus-qt5</code> is from package <code>qt5-qttools</code>.
 
== Power Off and Reboot ==
Hold the power button for about three seconds, then let go. Do not hold it too long, or else you will force-reboot your device. You will be presented with the options to reboot, power off or cancel. [https://invent.kde.org/plasma/plasma-mobile/-/issues/71 plasma-phone#71] is about making this a bit more intuitive.
 
= Configuration =
 
== Keyboard shortcuts ==
 
The settings windows can be called by commands <code>kcmshell6 kcm_keys</code> and <code>kcmshell6 khotkeys</code>. The first one is for Application Shortcuts and the second brings up Custom Shortcuts. [This method seems to be deprecated as of 19-01-2025]
 
== Disabling double tap to wake ==
 
Until the proximity sensor functionality is integrated into Plasma, the "double tap to wake" feature, on the phone screens that support it, tend to wake the phone in the pockets of users, or even by picking it up as it is very sensitive/permissive. To disable the feature, one can edit the <code>~/.config/kwinrc</code> file to add under the [Wayland] group, the line
 
<syntaxhighlight lang="shell">
DoubleTapWakeup=false
</syntaxhighlight>
 
== Physical keyboard layout ==
 
The physical keyboard layout can be changed be creating <code>~/.config/kxkbrc</code> with the following content:
 
<syntaxhighlight lang="shell">[Layout]
LayoutList=de
Use=true
</syntaxhighlight>
 
Replace <code>de</code> in the <code>LayoutList</code> with your keyboard's language code. All available keyboard layouts should be in <code>/usr/share/X11/xkb/symbols/</code>. This still applies to Wayland, even if they come from X11.
 
= Nightly repository =
postmarketOS has a nightly repository which contains (semi-) nightly builds of all KDE packages to make it easy to develop Plasma Mobile and its applications on postmarketOS which are currently built against Qt6.
 
More info can be found at [[Nightly]].
 
= Troubleshooting =
 
== Desktop lock screen ==
When you get the desktop lock screen instead of the mobile version and no virtual keyboard opens such that you are unable to login, check if you have <code>ui_extras</code> enabled in <code>~/.config/pmbootstrap.cfg</code>. If yes, disable it and rebuild / reflash the image. This issue may occur in combination with the [[#Nightly repository]].
 
== Scaling ==
On devices such as the [[Samsung_Galaxy_A5_2015_(samsung-a5ulte)]], [[Samsung_Galaxy_A3_2015_(samsung-a3)]], [[BQ Aquaris X5 (bq-paella)]] or [[Moto_G4_Play_(motorola-harpia)]], you may need to set a custom scaling factor.
 
The following sets a 2x scale factor (fractional factors are possible):
 
<syntaxhighlight lang="shell">
kscreen-doctor output.1.scale.2
</syntaxhighlight>


== Status ==
If you're trying to run this from SSH session, you need to set extra env vars:
{{note|Plasma Mobile is known to have problem with Android's framebuffer drivers (e.g. {{issue|1647}}). Works best with mainlined devices.}}
It works on most devices with a working display, both with hardware acceleration and software rendering. There is however an issue making it unable to run on armhf devices without hardware acceleration.


<syntaxhighlight lang="shell">
XDG_RUNTIME_DIR=/run/user/10000 QT_QPA_PLATFORM=wayland kscreen-doctor output.1.scale.2
</syntaxhighlight>


Do note that this interface is unbearably slow without hardware acceleration and is not recommended for devices without it.
To persist this zoom setting across reboots, create a new file "set-plasma-zoom.desktop" in ~/.config/autostart/ with the following contents:


== Installation ==
<syntaxhighlight lang="shell">
Using <code>pmbootstrap</code>, Plasma Mobile can be installed by selecting it as the UI in <code>pmbootstrap init</code>.
[Desktop Entry]
Exec=/usr/bin/kscreen-doctor output.1.scale.2
Name=Set zoom level
Terminal=False
Type=Application
</syntaxhighlight>


On existing systems, it can be installed by installing the <code>postmarketos-ui-plasma-mobile</code> meta package or <code>plasma-phone-components</code> if postmarketOS specific customization is not wanted.
== Log output ==
Logs are written to <code>~/.local/state/tinydm.log</code>.


== Starting Plasma Mobile ==
== Logging isn't verbose ==
One needs to enable debug logging for certain components in <code>~/.config/QtProject/qtlogging.ini</code>. Without that, you barely see any log output. We [https://gitlab.postmarketos.org/postmarketOS/pmbootstrap/-/blob/917f03d5f9f015fa9fc0be8093d87b7f21d98d4a/aports/main/postmarketos-ui-plasma-mobile/APKBUILD#L27 ship such a qtlogging.ini file] in <code>postmarketos-ui-plasma-mobile</code> because Plasma Mobile is relatively new and we want to be able to debug it properly.


If <code>postmarketos-ui-plasma-mobile</code> is installed, Plasma Mobile will be automatically launched via the [https://github.com/canonical/lightdm LightDM] display manager.
If the file did not get installed for you, please double check if it is there and report in {{issue|1038}}.
 
== KWin doesn't work ==
{{note|Plasma Mobile shell uses some Wayland protocols, so you can't run it on X11 in case you tried to do that.}}
Please follow [https://blog.martin-graesslin.com/blog/2016/07/why-does-kwin_wayland-not-start/ these instructions] for debugging.
 
== Some env vars that may help Angelfish browser ==
<syntaxhighlight lang="bash">
# Recommended in https://bugreports.qt.io/browse/QTBUG-80665
export QTWEBENGINE_DISABLE_GPU_THREAD=1
# 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"
</syntaxhighlight>
( [https://github.com/sailfishos-flatpak/flatpak-runner/blob/a49f60f3347972eb673fc35b94c4ef1c2024297d/src/appsettings.cpp#L79 source] )
 
== Starting Plasma Mobile from the Terminal ==
If <code>postmarketos-ui-plasma-mobile</code> is installed, Plasma Mobile will be automatically launched via tinydm.


It can also be launched manually by running the following script:
It can also be launched manually by running the following script:
<pre>
 
<syntaxhighlight lang="shell">
#!/bin/sh
#!/bin/sh


Line 47: Line 166:
else
else
# NOTE: using GALLIUM_DRIVER=llvmpipe might give you better performance (or not work at all.)
# 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.
# see: https://gitlab.postmarketos.org/postmarketOS/pmaports/-/issues/852
export GALLIUM_DRIVER=softpipe
export GALLIUM_DRIVER=softpipe
export KWIN_COMPOSE=Q
export KWIN_COMPOSE=Q
Line 55: Line 174:
kwin_wayland --framebuffer --xwayland plasma-phone 2>&1 | logger -t "$(whoami):plasma-mobile"
kwin_wayland --framebuffer --xwayland plasma-phone 2>&1 | logger -t "$(whoami):plasma-mobile"
fi
fi
</pre>
</syntaxhighlight>
 
For the official KDE instructions on running Plasma Mobile, see [https://docs.plasma-mobile.org/RunningApps.html their website].
 
== Taking screenshots ==
In command line:
qdbus org.kde.KWin /Screenshot org.kde.kwin.Screenshot.screenshotArea 0 0 1080 1920
 
== Troubleshooting ==
=== 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 will be enabled automatically if no hardware acceleration is detected, just make sure <code>mesa-dri-swrast</code> is installed.
 
=== Log output ===
If Plasma is launched via LightDM using the <code>postmarketos-ui-plasma-mobile</code> package, logs can be viewed by running <code>logread | grep plasma-mobile</code>. The log can also be viewed live by running <code>logread -f</code>; anything related to Plasma and KDE will have a <code>$username:plasma-mobile</code> prefix.
 
=== Logging isn't verbose ===
One needs to enable debug logging for certain components in <code>~/.config/QtProject/qtlogging.ini</code>. Without that, you barely see any log output. We [https://github.com/postmarketOS/pmbootstrap/blob/917f03d5f9f015fa9fc0be8093d87b7f21d98d4a/aports/main/postmarketos-ui-plasma-mobile/APKBUILD#L27 ship such a qtlogging.ini file] in <code>postmarketos-ui-plasma-mobile</code> 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 [https://gitlab.com/postmarketOS/pmbootstrap/issues/1038 1038].
 
=== KWin doesn't work ===
{{note|Plasma Mobile shell uses some Wayland protocols, so you can't run it on X11 in case you tried to do that.}}
Please follow [https://blog.martin-graesslin.com/blog/2016/07/why-does-kwin_wayland-not-start/ these instructions] for debugging.


== Guide ==
== WiFi does not autoconnect ==
Follow the [https://wiki.postmarketos.org/wiki/Display Display] guide to change and fix display related issues.


== See also ==
There's an unfortunate bug that makes re-connecting to WiFi require tapping the network again each time. [https://gitlab.postmarketos.org/postmarketOS/pmaports/-/issues/1049#note_302396 This comment in the bug thread] explains a work around to connect to networks automatically.
* [[Packaging-Plasma-Mobile|Packaging efforts]]


== Flickering in Mozilla Firefox ==
In case you experience flickering with the Mozilla Firefox web browser, it is because of [https://bugs.kde.org/show_bug.cgi?id=424586 a rendering bug in the browser], and can be mitigated by switching to the WebRenderer rendering backend by setting <code>gfx.webrender.all</code> to <code>true</code> in the browser's <code>about:config</code> window.
[[Category:Interface]]
[[Category:Interface]]

Latest revision as of 12:19, 19 March 2025

Plasma Mobile
Plasma Mobile homescreen.
Plasma Mobile homescreen.
Name Plasma Mobile
Graphics stack KWin on Wayland
Toolkit Qt 6
In postmarketOS
Package postmarketos-ui-plasma-mobile
Status Available

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

Installation

Note This user interface recommends systemd Using OpenRC instead of systemd might or might not work

Use the pre-built images from the downloads section of postmarketos.org, or build your own image with pmbootstrap. If using the latter, 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-mobile if postmarketOS specific customization is not wanted.

When running pmbootstrap install you'll be prompted for a user password. On an existing Plasma Mobile install you can change your user password and PIN in the Terminal with the standard passwd command.

postmarketOS v21.03 with Plasma Mobile on the PinePhone

Usage

First Boot

Note If you get stuck, head over to Matrix and IRC chats. Report issues.

As with all other interfaces in postmarketOS, the first boot takes longer than usual: the file system will be resized to use the entire device.

After boot, you are asked for your PIN. For pre-built images, this is 147147. If you flash a rootfs created with pmbootstrap, the "PIN" is the user password you provided during pmbootstrap install.

Connect to Wi-Fi

Swipe the top bar down to reveal a menu with a Wi-Fi symbol. Tapping the symbol itself will turn Wi-Fi on or off. To connect to a network the first time, hold down the Wi-Fi quick setting to open the settings application. Now select an access point.

Install Updates

Go to the Home Screen (tap the bottom right X if you have an application open). Swipe from the bottom upwards to reveal the app menu and start Discover, KDE's graphical package manager frontend. When Discover asks for privileges (pmaports#1036), type in your user's PIN (e.g. 147147 for pre-built images).

Swipe from the left to center to open Discover's menu, and select the entry with the up-arrow at the very bottom (it may say "Fetching updates" or the number of updates available). From here you can perform the updates. Depending on what has been updated, you need to reboot the device afterwards for changes to take effect.

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 https://develop.kde.org/docs/plasma-mobile/running-apps/.

Taking screenshots

Screenshots can be taken by pressing the button for it in the top drawer. You can however also do it with the command line:

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

qdbus-qt5 is from package qt5-qttools.

Power Off and Reboot

Hold the power button for about three seconds, then let go. Do not hold it too long, or else you will force-reboot your device. You will be presented with the options to reboot, power off or cancel. plasma-phone#71 is about making this a bit more intuitive.

Configuration

Keyboard shortcuts

The settings windows can be called by commands kcmshell6 kcm_keys and kcmshell6 khotkeys. The first one is for Application Shortcuts and the second brings up Custom Shortcuts. [This method seems to be deprecated as of 19-01-2025]

Disabling double tap to wake

Until the proximity sensor functionality is integrated into Plasma, the "double tap to wake" feature, on the phone screens that support it, tend to wake the phone in the pockets of users, or even by picking it up as it is very sensitive/permissive. To disable the feature, one can edit the ~/.config/kwinrc file to add under the [Wayland] group, the line

DoubleTapWakeup=false

Physical keyboard layout

The physical keyboard layout can be changed be creating ~/.config/kxkbrc with the following content:

[Layout]
LayoutList=de
Use=true

Replace de in the LayoutList with your keyboard's language code. All available keyboard layouts should be in /usr/share/X11/xkb/symbols/. This still applies to Wayland, even if they come from X11.

Nightly repository

postmarketOS has a nightly repository which contains (semi-) nightly builds of all KDE packages to make it easy to develop Plasma Mobile and its applications on postmarketOS which are currently built against Qt6.

More info can be found at Nightly.

Troubleshooting

Desktop lock screen

When you get the desktop lock screen instead of the mobile version and no virtual keyboard opens such that you are unable to login, check if you have ui_extras enabled in ~/.config/pmbootstrap.cfg. If yes, disable it and rebuild / reflash the image. This issue may occur in combination with the #Nightly repository.

Scaling

On devices such as the Samsung_Galaxy_A5_2015_(samsung-a5ulte), Samsung_Galaxy_A3_2015_(samsung-a3), BQ Aquaris X5 (bq-paella) or Moto_G4_Play_(motorola-harpia), you may need to set a custom scaling factor.

The following sets a 2x scale factor (fractional factors are possible):

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

To persist this zoom setting across reboots, create a new file "set-plasma-zoom.desktop" in ~/.config/autostart/ with the following contents:

[Desktop Entry]
Exec=/usr/bin/kscreen-doctor output.1.scale.2
Name=Set zoom level
Terminal=False
Type=Application

Log output

Logs are written to ~/.local/state/tinydm.log.

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

Note 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 https://bugreports.qt.io/browse/QTBUG-80665
export QTWEBENGINE_DISABLE_GPU_THREAD=1
# 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 )

Starting Plasma Mobile from the Terminal

If postmarketos-ui-plasma-mobile is installed, Plasma Mobile will be automatically launched via tinydm.

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

#!/bin/sh

export QML2_IMPORT_PATH=/usr/lib/qt/qml:/usr/lib/qt5/qml
export QT_QPA_PLATFORMTHEME=KDE
export QT_QUICK_CONTROLS_STYLE=Plasma
export QT_WAYLAND_DISABLE_WINDOWDECORATION=1
export XDG_CURRENT_DESKTOP=KDE
export KDE_SESSION_VERSION=5
export PLASMA_PLATFORM=phone:handset
export QT_VIRTUALKEYBOARD_STYLE=Plasma
export QT_QUICK_CONTROLS_MOBILE=true
export QT_ENABLE_GLYPH_CACHE_WORKAROUND=1
sleep 2

if [ -d "/dev/dri" ]; then
	kwin_wayland --drm --xwayland plasma-phone 2>&1 | logger -t "$(whoami):plasma-mobile"
else
	# NOTE: using GALLIUM_DRIVER=llvmpipe might give you better performance (or not work at all.)
	# see: https://gitlab.postmarketos.org/postmarketOS/pmaports/-/issues/852
	export GALLIUM_DRIVER=softpipe
	export KWIN_COMPOSE=Q
	export LIBGL_ALWAYS_SOFTWARE=1

	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"
fi

WiFi does not autoconnect

There's an unfortunate bug that makes re-connecting to WiFi require tapping the network again each time. This comment in the bug thread explains a work around to connect to networks automatically.

Flickering in Mozilla Firefox

In case you experience flickering with the Mozilla Firefox web browser, it is because of a rendering bug in the browser, and can be mitigated by switching to the WebRenderer rendering backend by setting gfx.webrender.all to true in the browser's about:config window.