Phosh

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.

= Installation = 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.

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

When running  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 (but there is a keyboard button for entering a non-numeric password if you happened to have set one). On an existing Phosh install you can change your user password and PIN in the terminal with the standard  command.

= Usage =

First Boot
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.

Install updates and reboot


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  (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.

This bug is tracked in.

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.

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.

If you see a "No WWAN Adapter Found" message, tap the toggle-icon on the top right. It should turn blue and a "SIM Locked" message screen should appear instead, with an "Unlock" button.

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. 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).

Import contacts from a .vcf file
To import a .vcf file, open the "Contacts" app, click on the menu icon in the top right corner, and select "Import". A window will pop up allowing you to select your .vcf file. Once selected, click "Confirm" in the confirmation popup that shows up.

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
First install chatty with

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. The best way to install new software is currently via SSH with Alpine's package keeper (, no relation to the Android app format). Use  to find software, and   to install it. Read  for usage information.

To install the PDF reader Evince for example:

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. Invoking  results in a screenshot of the entire screen being saved in your Pictures directory.

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

If you need to invoke grim from an SSH session you need to first log in as the  account  and then invoke grim with a special environment variable:.

If grim tries to take a screenshot of the wrong output (e.g. ), specify the output with   with an output from   without the   prefix.

Camera
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, install it via SSH:

It is also recommended to install  and   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
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?

postmarketos-tweaks
Install postmarketos-tweaks (via the Software app or ), to get a graphical application that allows various tweaks. For example:
 * Change the GTK theme to a dark one (dark mode)
 * Change icon themes
 * Change the time after which the phone suspends
 * Enable or disable all animations

USB Tethering
Once is merged to edge, USB tethering can be enabled as follows.


 * 1) Connect your phone over USB to your desktop.
 * 2) On the phone, open Settings
 * 3) Go to the Network panel tab.
 * 4) You should see 1 wired connection at the top, tab the edit settings button (gear)
 * 5) An old panel opens which doesn't fit your screen (use Phosh Mobile Settings to enable scale-to-fit for this panel only, it will be shown in the list of active apps).
 * 6) Go to the IPv4 tab.
 * 7) Select 'Shared to other computers' and tab the Apply button in the right corner.

= Configuration =

Restarting
The easiest way is.

Explanation of Phosh starting process in pmOS
If  is installed, Phosh uses the GNOME login and session handling. A session is defined as the lifecycle of a user interaction with the system. Phosh will be automatically launched as a session using the login daemon, the   credentials provider, and the   display manager.

The daemon actually managing the sessions is  which is the login daemon used with GNOME environments not integrated with the desktop system daemon   (Phosh on PostmarketOS currently does not use systemd). is responsible for restarting the session if it crashes, and terminating all active sessions when the system powers off. Each user session occurs at a seat. Usually there will be just one seat: the session interacting with the screen. However if you also use a console (such as a serial port) this also becomes a seat.

On the way up the  session interacting with the main screen seat will proceed to start the display manager   (TinyDM website) using   to provide the default user with Wayland as the display server. On PostmarketOS the default user will be user ID 10000 which is what the installation scripts have set up.

Tinydm in turn will launch Phosh by looking into the file  which contains an   directive executing   which in turn will produce the passcode screen so you can proceed to log into your phone.

It can also be launched manually by running.

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 /etc/phosh/phoc.ini. If the default value was not set in postmarketOS' device configuration, then the setting will be in /usr/share/phosh/phoc.ini instead.

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  it is possible to scale selected applications so they fit the screen: may be determined as follows where  is the application's executable name. For further reference, look at LINMOB's article about scaling.

Modem
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:

Configure your APN for mobile data (example for mobile vikings in Belgium):

Overview
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  (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.

= Troubleshooting =

See also Debugging the GNOME stack.

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  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  or. 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:

Inspecting sessions
It is possible to manipulate the elogind user sessions as root using. For example:


 * will list the ongoing sessions, and on a normal phone or tablet you should have a one session called c1 connected to seat0.
 * will display the graphics, input and sound devices that seat0 for session c1 is connected to. This is a good way to verify that your graphics (both GPU and display controller), input, and sound devices are correctly set up.
 * will unlock the screen lock from the command line, if the screen happened to lock on you. (This does not apply to the login screen though, you still have to log in properly.)
 * will terminate the session and bring you back to the login screen. You will see a new cN session spawning (such as c3) since the session number increment by one for every new session.

See also the official documentation at Freedesktop.org.

Some apps don't show up in the shell / Terminal apps don't open
Some apps are currently hidden from the shell by postmarketos-hidden-desktop-entries. This mainly consists of terminal apps as these currently do not work in Phosh unless you install an alternative terminal emulator, e.g. GNOME Terminal. King's Cross (the default terminal emulator in Phosh) does not support launching terminal apps from desktop files it seems. It is also debated how useful these are in a mobile shell.

= See also =


 * GNOME apps