Difference between revisions of "Phosh"

From postmarketOS
Jump to navigation Jump to search
(throw in one of martijn's nice photos)
(→‎External monitor: update link to convergence issue)
Line 100: Line 100:
== External monitor ==
== External monitor ==
{{note|PinePhone: does not work with all monitors currently, see: {{issue|735|pmaports}}}}
{{note|PinePhone: this appears to be broken for some users, see: {{issue|1009|pmaports}}}}
Plug in a cable to your external monitor into your phone. Phosh should recognize the screen automatically and you should be able to use it. For the PinePhone, see [https://www.youtube.com/watch?v=yBeza4UNOm8 this demo video].
Plug in a cable to your external monitor into your phone. Phosh should recognize the screen automatically and you should be able to use it. For the PinePhone, see [https://www.youtube.com/watch?v=yBeza4UNOm8 this demo video].

Revision as of 00:28, 10 April 2021

postmarketOS with Phosh on the Motorola Moto G 2015
postmarketOS with Phosh on the Motorola Moto G 2015
Name Phosh
Graphics stack Phoc on Wayland
Toolkit GTK3

Phosh is a phone shell based on the GNOME stack. It is developed by Purism for their own Linux smartphone, the Librem 5. With postmarketOS, it can be used on various other mobile devices too. We have shipped the PinePhone postmarketOS community edition with Phosh.


Use the pre-built images from the downloads section of postmarketos.org, or build your own image with pmbootstrap. If using the latter, Phosh can be installed by selecting it as the UI in pmbootstrap init.

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

When running pmbootstrap install you'll be prompted for a user password. Make sure to only use numeric characters [0-9] in this password as the Phosh lock screen uses this password as a PIN. On an existing Phosh install you can change your user password and PIN in the terminal with the standard passwd command.


First Boot

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. The first start of Firefox also takes longer than the following starts.

After boot, you are asked for your PIN. For pre-built images, this is 147147.

Install updates and reboot

GNOME software with updates available

Unless you have just built your own postmarketOS image a few minutes before doing the installation, it is highly recommended to install updates and then reboot your device. To do that, open the "Software" app, tap the "Updates" button on the bottom right. Then tap "Update All". When the updates are finished, all listed packages will disappear and you will be left with a screen showing only a horizontal line.

Once all updates are installed, reboot so you are actually using the newly installed software and not still the old versions. To do that, tap the top bar between the clock and the battery icon, tap the power symbol and then "Restart".

After rebooting, update the "Software" app once again. If you are running the build that was shipped with the PinePhone, you will immediately see an update for mobile-config-firefox (apk-polkit#18). Install this one too, so Firefox is configured for mobile. This tiny update does not need a reboot.

Do not report issues unless you have made sure that you have rebooted into an up-to-date system.

SSL handshake failed notification

The notification 'Unable to download updates from "odrs.gnome.org" ... SSL handshake failed' can be ignored. Just tap the "x" at the bottom, so it does not cover the "Update All" button anymore.

This message appears if you have just connected to Wi-Fi, and your device's date was not synced with the Internet yet (see the clock that is visible in the top bar). Then GNOME software will fail to download some software ratings via the secure HTTPS protocol, because it can't verify the server's certificates without knowing the date (as they could have expired). For our use case, this is all irrelevant: we don't need the software ratings right now, we want to do updates. Because these updates are signed with a different mechanism already, we don't use HTTPS, but instead the plain HTTP to download them. So we don't even need to have the date synced.

Enable SSH

It's highly recommended to enable and test SSH access to your phone, so you can control your phone from the terminal, transfer files and take part in development.

Contacts, SMS and calls

Unlock SIM card

If your SIM card needs a PIN, Phosh will display a SIM card icon with a question mark on top in the top bar. Open the top menu (tap between clock and battery icon), then tap the bigger SIM card icon again to type in the PIN.

Manage contacts

Open the bottom menu, and open the "Contacts" app (blue book with @ sign). The "Contacts Setup" screen will appear. Select the "Local Address Book" (read below for more options) and "Done". An empty contact list appears.

Hit the + button on the left to add a contact. If you go to the bottom menu (tap the bottom arrow) and open the app again, the "New Contact" screen appears.

Fill out at least the name and phone number, then hit "Add" on the top right.

Synchronization with an online account

For convenience, some people may choose to synchronize their contacts with an online account. In order to do that, close the "Contacts" app (otherwise "Settings" will not open). Then open "Settings" from the bottom menu. Select "Online Accounts" and then add a provider where contact synchronization is supported). After you have added your online account, you should be able to select it in the "Contacts" app.

Note that the online account providers also list services, which are known bad actors in regards of privacy (pmaports#725). From a privacy and anti-mass-surveillance point of view, the best solution is not using contact synchronization at all, or using a self-hosted solution (e.g. with Nextcloud).

Make a call

Either open the "Contacts" app and tap on the call icon next to an existing contact. Or open the "Calls" app, select "DialPad" at the bottom and type in the number (selecting existing contacts from within the "Calls" app is currently not possible: calls#88).

Previously called contacts / typed in numbers and received calls appear in "Recent" and can be called again from there. If you want to avoid typing in a number, consider calling the phone running Phosh from another phone. Then the number will appear in "Recent" as well and can be called back.

Write SMS

Add the target phone number as contact (as described above). Then open the "Chats" app (the one with two message bubbles), hit the "+" on the top right, select the contact and start typing your SMS.

Alternatively, write an SMS from another phone to your phone running Phosh to start a conversation.

Install software

The "Software" app doesn't show the applications available in postmarketOS and Alpine yet (pmaports#699). The best way to install new software is currently via SSH with Alpine's package keeper (apk, no relation to the Android app format). Use apk search to find software, and apk add to install it. Read apk -h for usage information.

To install the PDF reader Evince for example:

$ sudo apk add evince

Take a screenshot

Currently there is no way to take a screenshot directly from the user interface, however you can take a screenshot from the terminal!

First install grim using sudo apk add grim. Invoking grim results in a screenshot of the entire screen being saved into the current working directory.

If you need to delay the screenshot for e.g. 10 seconds you can do that as well: sleep 10 && grim.

If you need to invoke grim from an SSH session you need to first log in as the user account (su - user) and then invoke grim with a special environment variable: XDG_RUNTIME_DIR=/run/user/10000 grim.


If your phone is able to make photos on postmarketOS (if unsure, check the device wiki page), run the Megapixels app to take photos.

If it is not installed already, and it does not show up in the "software" app (pmaports#699), install it via SSH:

$ sudo apk add megapixels

It is also recommended to install eog and nemo to view and browse the images that were taken. Both can be opened from Megapixels once installed. New installations of postmarketOS with Phosh will come with all three apps installed by default.

External monitor

PinePhone: this appears to be broken for some users, see: pmaports#1009

Plug in a cable to your external monitor into your phone. Phosh should recognize the screen automatically and you should be able to use it. For the PinePhone, see this demo video.

Need a reminder of keyboard shortcuts to move applications between screens?


Starting Phosh

If postmarketos-ui-phosh is installed, Phosh will be automatically launched via the TinyDM display manager.

It can also be launched manually by running dbus-run-session /usr/bin/phosh.

Screen Scaling

Manual Scaling

The Phosh screen may be scaled lower for better compatibility with existing applications. Change the scale by modifying the scale factor variable found in /usr/share/phosh/phoc.ini, which has a default value of 2.

Screen scaling may also be performed on-demand from the command line or by making an application by following the Purism Easy Librem 5 App Development: Scale the Screen blog post. Those instructions work well for devices running Phosh even if written for a Librem5 running PureOS (Debian-based OS). Keep in mind some commands will need to be modified to work on postmarketOS.

Automatic Scaling

Via scale-to-fit it is possible to scale selected applications so they fit the screen:

$ scale-to-fit $APPID true

$APPID may be determined as follows

$ WAYLAND_DEBUG=1 $COMMAND 2>&1 | grep 'xdg_toplevel@[0-9]\+\.set_app_id'

where $COMMAND is the application's executable name. For further reference, look at LINMOB's article about scaling.


If you have trouble configuring everything with the graphical dialogs or just want to use the terminal, read along.

Unlock your SIM card with the PIN: mmcli -i 0 --pin=12345

Configure your APN for mobile data (example for mobile vikings in Belgium): mmcli -m 0 --simple-connect='apn=web.be,user=web,password=web,pin=1111'



Phosh uses feedbackd for haptics, the source repo is hosted on Purism's GitLab, device specific configuration files are hosted in the feedbackd-device-themes repo.

Feedbackd supports devices using the EV_FF (force feedback event) via the Linux input API, the pm8xxx-vibrator driver is a good example implementation of this.

Supported devices

Currently, feedbackd supports the Librem 5, PinePhone and most recently OnePlus 6/6T (and soon the PocoPhone F1). However it should be possible to get any MSM8996+ device working (and MSM8916), as long as the hardware is supported by the mainline driver.

For more details see Haptics.


Firefox looks weird

Firefox should look like this (on the right) after installing all updates. If the address bar is cut off, you don't have mobile-config-firefox installed. Make sure you have installed all updates, rebooted, and checked for updates again (as described in install updates and reboot above).

If you would like to contribute to mobile-config-firefox, see the related project page.

Reading the log

Phosh related applications are logging to ~/.cache/tinydm.log. It's recommended to only share the relevant piece of the log file, read through it and redact personal information (your phone number!) before sharing. Login via SSH, then read the file:

$ su - user
$ tail -F ~/.cache/tinydm.log

See also