Phosh is a phone shell based on the GNOME stack. It was initiated 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.

postmarketOS with Phosh on the Motorola Moto G 2015

Installation

Phosh
	; Default Phosh homescreen.
Name	Phosh
Graphics stack	Phoc on Wayland
Toolkit	GTK3
In postmarketOS
Package	postmarketos-ui-phosh
Status	Available

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-phosh^PMOS 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 (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 passwd command.

Usage

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.

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.

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

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 sudo apk add chatty

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

As of postmarketOS v23.06, it is possible to install programs graphically via GNOME Software. However, you can also install packages from a terminal 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

As of Phosh 0.27.0 (available in postmarketOS v23.06 and newer), it is possible to take a screenshot by holding down the power button and pressing the screenshot button in the pop-up menu. However, you can also take a screenshot from the terminal if that's more convenient for your needs.

First install grim using sudo apk add grim. Invoking grim 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: 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 grim tries to take a screenshot of the wrong output (e.g. failed to copy output HDMI-A-1), specify the output with grim -o output with an output from ls /sys/class/drm without the card1- prefix.

Record the screen

To take a screen recording, install wf-recorder using sudo apk add wf-recorder.

Similarly to "Take a screenshot" you can invoke this from an SSH session using XDG_RUNTIME_DIR=/run/user/10000 wf-recorder, and to stop the recording press Ctrl+C.

The default destination filename is recording.mp4. See the man page or --help for more info on the usage.

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 (pmaports#699), install it via SSH:

$ sudo apk add megapixels

If you have a Librem 5, you need to use Millipixels instead:

$ sudo apk add millipixels

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?

postmarketos-tweaks

Install postmarketos-tweaks (via the Software app or apk add postmarketos-tweaks), 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 pmaports!3819 is merged to edge, USB tethering can be enabled as follows.

Connect your phone over USB to your desktop.
On the phone, open Settings
Go to the Network panel tab.
You should see 1 wired connection at the top, tab the edit settings button (gear)
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).
Go to the IPv4 tab.
Select 'Shared to other computers' and tab the Apply button in the right corner.

Configuration

Starting Phosh

Restarting

The easiest way is sudo service tinydm restart.

Explanation of Phosh starting process in pmOS

If postmarketos-ui-phosh 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 elogind, the autologin credentials provider, and the tinydm display manager.

The daemon actually managing the sessions is elogind which is the login daemon used with GNOME environments not integrated with the desktop system daemon systemd (Phosh on PostmarketOS currently does not use systemd). elogind 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 elogind session interacting with the main screen seat will proceed to start the display manager tinydm (TinyDM website) using autologin 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 /var/lib/tinydm/default-session.desktop which contains an Exec directive executing dbus-run-session /usr/bin/phosh 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 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 /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.

To manually set the scaling in phoc.ini:

Find the name of your screen output device in ls /sys/class/drm
Open /etc/phosh/phoc.ini
Add the following (replace DSI-1 with the output name you found earlier and 1.5 with the scaling factor):
```
[output:DSI-1]
scale = 1.5
```

Screen scaling may also be performed on-demand from the command line:

Install wlr-randr:
```
$ sudo apk add wlr-randr
```
Find the name of your screen output device in ls /sys/class/drm
Run (replace DSI-1 with the output name you found earlier and 1.5 with the scaling factor):
```
$ wlr-randr --output DSI-1 --scale 2
```

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.

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

Haptics

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

Keyboard shortcuts

Can be configured in Settings -> Keyboard -> Keyboard Shortcuts.

Troubleshooting

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 ~/.local/state/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 ~/.local/state/tinydm.log

Debug logging can be enabled by creating the file ~/.phoshdebug with for example the following content:

export G_MESSAGES_DEBUG=all

Debug logging can also be enabled on-demand with a running phosh instance by sending SIGUSR1 to the process. Sending SIGUSR1 again will disable debug logging.

$ kill -SIGUSR1 $(pidof phosh)

Inspecting sessions

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

sudo loginctl list-sessions will list the ongoing sessions, and on a normal phone or tablet you should have a one session called c1 connected to seat0.
sudo loginctl seat-status 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.
sudo loginctl unlock-session c1 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.)
sudo loginctl terminate-session c1 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.