Phosh: Difference between revisions
No edit summary |
merge with First Steps (Phosh) article |
||
Line 1: | Line 1: | ||
Phosh is a | Phosh is a ''pho''ne ''sh''ell based on the [https://en.wikipedia.org/wiki/GNOME GNOME] stack. It is developed by [https://puri.sm/ Purism] for their own Linux smartphone, the [https://puri.sm/products/librem-5/ Librem 5]. With postmarketOS, it can be used on various other mobile devices too. We have shipped the [[PINE64_PinePhone_(pine64-pinephone)|PinePhone]] [https://postmarketos.org/blog/2020/06/15/pinephone-postmarketos-community-edition/ postmarketOS community edition] with Phosh. | ||
= Installation = | |||
Using <code>pmbootstrap</code>, Phosh can be installed by selecting it as the UI in <code>pmbootstrap init</code>. | Using <code>pmbootstrap</code>, Phosh can be installed by selecting it as the UI in <code>pmbootstrap init</code>. | ||
Line 9: | Line 8: | ||
When running <code>pmbootstrap install</code> to flash a phone or sd card 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 <code>passwd</code> command. | When running <code>pmbootstrap install</code> to flash a phone or sd card 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 <code>passwd</code> command. | ||
= 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. The first start of Firefox also takes longer than the following starts. | |||
=== Install updates and reboot === | |||
[[File:Phosh-gnome-software-updates.png|thumb|right|frame|none|120px|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". | |||
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". | |||
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|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 === | |||
{{note|It's currently impossible to use created contacts for making calls or writing SMS ({{issue|730|pmaports}}, {{issue|729|pmaports}}, [https://source.puri.sm/Librem5/calls/-/issues/88 calls#88]). Until that is fixed, adding contacts is not really useful.}} | |||
Open the bottom menu, and open the "Contacts" app (blue book with <code>@</code> 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 <code>+</code> button on the left to add a contact. The screen appears to be stuck ({{issue|728|pmaports}}). 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 [https://wiki.gnome.org/Projects/GnomeOnlineAccounts/Providers 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 ({{issue|725|pmaports}}). 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 === | |||
Open the calls app, select "DialPad" at the bottom and type in the number to make a call. After doing this for the first time, the number appears in "Recent" and can be called 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. | |||
When {{issue|730|pmaports}} is fixed, it will be possible to start a call from the contacts app. [https://source.puri.sm/Librem5/calls/-/issues/88 calls#88] is about making it possible the other way around (selecting the contact from the calls app). | |||
=== Write SMS === | |||
Open the "Chats" app (the one with two message bubbles). Write an SMS to your phone running Phosh to start a conversation. | |||
Writing to a previously added contact is currently broken ({{issue|729|pmaports}}). | |||
= Configuration = | |||
== Starting Phosh == | == Starting Phosh == | ||
If <code>postmarketos-ui-phosh</code> is installed, Phosh will be automatically launched via the [https://github.com/canonical/lightdm LightDM] display manager. | If <code>postmarketos-ui-phosh</code> is installed, Phosh will be automatically launched via the [https://github.com/canonical/lightdm LightDM] display manager. | ||
It can also be launched manually by running <code>dbus-run-session /usr/bin/phosh</code>. | It can also be launched manually by running <code>dbus-run-session /usr/bin/phosh</code>. | ||
[ | == Screen 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 [https://wp.puri.sm/posts/easy-librem-5-app-development-scale-the-screen/ 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. | |||
== Modem == | == 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: | Unlock your SIM card with the PIN: | ||
Line 30: | Line 81: | ||
</code> | </code> | ||
= | = See also = | ||
* [[User:MartijnBraam/Phosh_Apps]] | |||
[[Category:Interface]] [[Category:Guide]] | |||
Revision as of 15:43, 28 August 2020
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
Using pmbootstrap
, 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
meta package or phosh
if postmarketOS specific customization is not wanted.
When running pmbootstrap install
to flash a phone or sd card 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.
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.
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".
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".
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
It's currently impossible to use created contacts for making calls or writing SMS (pmaports#730, pmaports#729, calls#88). Until that is fixed, adding contacts is not really useful. |
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. The screen appears to be stuck (pmaports#728). 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
Open the calls app, select "DialPad" at the bottom and type in the number to make a call. After doing this for the first time, the number appears in "Recent" and can be called 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.
When pmaports#730 is fixed, it will be possible to start a call from the contacts app. calls#88 is about making it possible the other way around (selecting the contact from the calls app).
Write SMS
Open the "Chats" app (the one with two message bubbles). Write an SMS to your phone running Phosh to start a conversation.
Writing to a previously added contact is currently broken (pmaports#729).
Configuration
Starting Phosh
If postmarketos-ui-phosh
is installed, Phosh will be automatically launched via the LightDM display manager.
It can also be launched manually by running dbus-run-session /usr/bin/phosh
.
Screen 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.
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'