Skip to content

GitLab

Last edited by amarok
Page history

Tips & Tricks

Since more and more people will start exploring their Evergreen devices, the same questions will most likely arise as in this first forum thread here.

The intention of this section is to collect and conserve knowledge with respect to Tips & Tricks in dealing with the Librem 5 while ramping up and constantly improving.

First steps for new Librem 5 users

Check out this post and watch the Librem 5 Video Walkthrough.

Known issues

For a full list of PureOS-related issues see the issue tracker entries.

WiFi does not connect

If the Librem 5 won't connect to your network, verify that the phone's date, time, and time zone are set correctly in Settings > Details > Date & Time. At present, it's necessary to turn off the automatic date/time settings and set these manually. After successful connection, you can return the settings to automatic. If you're using MAC filtering on your router, don't forget to allow your Librem 5 in the router settings first. Using hidden SSID on your router may cause intermittent disconnection.

PureOS updates fail after first setup

This is caused by an improper timezone or date/time setting required to configure the WiFi connection initially. Solution: Re-enable the "Automatic Date & Time" setting in Settings > Details > Date & Time

This issue has been solved in more recent versions of PureOS

Standby mode

Currently no standby / suspend mode available. Screen just gets dark.

Battery fuel meter

Needs adjustments and for the time being is not precise. E.g. when fully loaded, the red charging led turns off and battery fuel meter indicates 70%. Recent improvements have synced the battery level indicator in the notifications area to the level in the Power settings panel.

To check the battery state from a shell use upower -d. Or read technical details with:

cd /sys/class/power_supply/max170xx_battery
cat capacity
65
cat temp
432

Show battery percentage

By default the Phosh interface shows the battery level as a graphic. To show the battery level as a percentage, use this command:
gsettings set org.gnome.desktop.interface show-battery-percentage true

GPS

GPS: Seems to work internally but user interfaces in PureOS are still missing (except switching GPS on and off in Settings > Privacy > Location Services). See https://forums.puri.sm/t/app-for-gps-settings-on-librem-5/12136

Phosh now acts as a geoclue agent so applications like GNOME maps and Pure Maps can use use location services with the internet connection to show your location on the maps; see: https://puri.sm/posts/librem-5-news-summary-april-2021/

Convergence

Convergence is not yet supported by the software.

General

Backup

See this thread: https://forums.puri.sm/t/new-post-app-showcase-backups/11459. Alternatively: Example of a quick backup solution using rsync and a systemd timer

Dark mode

Not available out-of-the-box. Can be tweaked by using GNOME Tweaks app and set any theme you want there.

Alternatively, use gsettings: gsettings set org.gnome.desktop.interface gtk-theme "Adwaita-dark"

Firewall

To enable ufw (uncomplicated firewall), open terminal and enter sudo ufw status and if it's not yet enabled, enter sudo ufw enable. The default is usually all you need, but you have the options of adding additional rules. Use sudo ufw disable to disable the firewall. To call up a graphical interface inside the terminal, first install gufw and install x11-xserver-utils. Next type the following command: DISPLAY=:0 xhost + and hit enter, resulting in: access control disabled, clients can connect from any host.
Now type: DISPLAY=:0 GDK_BACKEND=x11 sudo gufw and the graphical version will appear right in the terminal. Note that after you close the terminal, the app icon in the phone's app list will not be operational unless you repeat the above process, at least unless someone adapts it later.

IMEI

To find the IMEI of your Librem 5, go to Settings > Mobile > Modem Details.

You can also get this information with: mmcli -m any | grep imei

Notifications

Accessed by touching the battery icon at the top right corner of the screen.

Ringtones

Customize rintones following this blog post.

Root account

Locked by default. So there is no root password available. More technical details here. Unlock root account with sudo passwd, check out this discussion for more background.

You can start a shell as root by running the command: sudo -s

Terminal

Access additional Terminal keyboard controls by clicking on the globe icon (reveals Ctrl, Alt, and arrow keys, plus other symbols, controls, and Function keys - including Esc and Tab; press the >_ key to see the extras).

Here's a quick and fun introduction to basic Terminal commands: https://ubuntu.com/tutorials/command-line-for-beginners#1-overview

Username

Default user name is: purism. Additional user names can be added from the terminal; at present this is not supported in the Settings GUI.

Auto-mounting directories

When manually adding entries in /etc/fstab, specify the nofail option (in the 4th field) so that any problem with the device will not prevent the operating system from booting.

Screen Orientation

Phosh supports automatic screen orientation. To enable or disable it toggle the button in the notifications area.

Hostname

The default hostname is pureos. In order to change the hostname you need to edit, as root, both /etc/hostname and /etc/hosts

Software installations and updates (apps and OS)

Install Software

In case installing software from PureOS store does not work --> Do it from terminal, e.g. sudo apt install firefox-esr. Note that PureOS store, by default, lists software that has been adapted to the Librem 5's screen. Other packages can be found and installed using the search tool within the store, but may not scale well to the screen without further modification. Using Scale Screen app, a part of librem5-goodies, to temporarily reduce scale, may help with such non-adaptive apps.

System/Software Updates

Click Updates tab within the PureOS Store (and per this issue, hit the Restart & Update button twice); or, install from the Terminal by entering:
sudo apt update && sudo apt upgrade
(sudo = superuser do / i.e. admin level action)

Enable Flatpak with Flathub repository

Flatpak support and PureOS store integration are installed by default. Only need to add the Flathub repository via the terminal as described in their setup description step 3 For example:
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

Add App to favorites:

To add an app from your app list to the Favorites section (i.e. pin to the top of the list), long-press on the app, then select Add to Favorites. The Favorites section expands to accommodate the new favorite app. To remove an app from Favorites, long-press the app, then select Remove from Favorites.

Web Apps

You can create an app icon from a web page in the browser as shown in the Video Walkthrough at position 2m:20s. Deletion / adaption via Web Application Manager.

Recommended applications for common use cases

See this comprehensive list of mobile-optimized apps. A sampling of tested applications, including screenshots, can be found at: https://forums.puri.sm/t/list-of-apps-that-fit-and-function-well-post-them-here/11361

File manager

Nautilus is adaptive on both Amber and Byzantium.

Alternative: nemo scales well without additional tweaks, especially in landscape. It can be installed with the command: sudo apt install nemo, or search and install within PureOS store.

You can also install Portfolio file manager.

Screenshots

Install librem5-goodies (e.g. in the terminal with the command sudo apt install librem5-goodies). After the installation it will add several apps to the app tray: Screen Shot, Scale Screen... along with other included apps.

Application life-cycle

  • To close an application touch the "roof" symbol on the bottom of the screen which shows a carousel of open apps. From there you can close an app by tipping and swiping it up to the upper part/top of the mobile phone
  • To close a blocked/hanging application you can use the terminal and the killall command or use the app Usage (installed by default) where you can find the process of the app if you scroll down, tip on the app name and choose "Force quit".

USB

Mount USB sticks

USB drives are automatically recognized and mounted (you get a notification where you can open the mounted folder in a file manager).

Unmount (eject) USB sticks

This requires to use the umount command in the terminal or (easier) eject via the nautilus or nemo file manager: Select the mounted USB drive in the device tree node in nautilus or nemo, the choose eject in the File menu so safely unmount the USB drive

Calls

Calls/Voice quality

Adjust Internal Microphone volume in Settings > Sound for optimal clarity.

Calls from terminal

xdg-open tel://<phone-number> as seen here.

Mobile Settings

While Mobile is disabled, either by the settings toggle or by the kill switch, granular Mobile Settings are inaccessible. Also, at the moment, saved messages in Chats cannot be viewed, nor new messages composed; a fix for this is being worked on, and the issue does not affect other installed messaging apps, and also not other chat protocols used by chatty (e.g xmpp), if any.

Send SMS (text message) from terminal

At the current time, this is a bit untidy but it can be done.

# Pause chatty
killall -STOP chatty

# Create SMS and save its id
id=`sudo mmcli -m any --messaging-create-sms="text='your-content',number='dest-phone-number'"`
# id is e.g. Successfully created new SMS: /org/freedesktop/ModemManager1/SMS/6

id=${id/?*\/*\/*\/*\/*\/}
# strip that back to just the number e.g. 6

echo id = $id

# Send SMS
sudo mmcli -s $id --send

# Resume chatty
killall -CONT chatty

In my testing, the dest-phone-number did not have to be a full international-format mobile number. Your mileage may vary.

Unless you are a bash wiz it would be best to avoid any quote characters (` " ') in your-content.

If scripting this then it might be wise to wait until the text message is actually sent before resuming chatty. You can get the status of the message with: mmcli -m any --messaging-list-sms

As an aside, if your Librem 5 becomes gummed up with an MMS that you can't receive and process (yet) then you can list it with the previous command and then delete with: sudo mmcli -m any --messaging-delete-sms=index where index is replaced with the message number to delete.

Mail (Geary)

  • If the incoming mail server or the outgoing mail server require a port number then specify the hostname as hostname:portnumber
  • There is no support for the POP protocol. Mail can only be received using the IMAP protocol.
  • Config information is stored in /home/purism/.config/geary/account_01/geary.ini (or replace _01 with subsequent numbers if more than one account)

Contacts

Import contacts

From .vcf file: Install the librem5-goodies package from the command line, one of the scripts it has is a small yad/bash application to import contacts from a *.vcf file to GNOME Contacts. Import from SIM card is currently not supported.

Contacts information appears to be stored in:
/home/purism/.local/share/evolution/addressbook/system/contacts.db

General Carddav and Caldav functionality

Install the evolution package from the command line, add regular Carddav and Caldav accounts via Evolution interface, attach external screen (Evolution is not adaptive for Librem 5).

Locale

If you have set a specific locale (e.g. en_AU.UTF-8) then you will probably get warnings all over the place (e.g. from man, locale itself, from perl during an install). The solution appears to be:
sudo dpkg-reconfigure locales
Then page down to your chosen locale, press the space bar to select it - [ ] will change to [*], then Tab to move to Ok then Enter.
That will then take an eternity generating all the selected locales and eventually doing the one that you just selected.

Network Config

Network Manager stores the configuration in /etc/NetworkManager. Specifically, information that is per-connection is stored in the system-connections subdirectory in files called xyz.nmconnection where xyz is the connection name.
The proper way to 'get' and 'set' per-connection settings, if wanting to do from the command line, is via the nmcli command.

  • Show the connections that exist: nmcli conn show
  • Show a specific connection where uuid is as listed by the first command:
    nmcli conn show uuid | grep whatever
  • Retrieve a specific field: nmcli -g fieldname conn show uuid
  • Modify a specific field: nmcli conn modify uuid fieldname fieldvalue

Modem Manager

To get modem information:

  • Using the command: mmcli -m any will display information on all modems installed on the device, in the case of the Librem 5, there is only one.

Likewise to get SIM information, you can use the command: mmcli -i any That will show you your IMSI, among other pieces of information.

But you can also search explicitly to get modem indexes and SIM indexes.

  • Firstly, mmcli -L to list the modems. For example, gives: /org/freedesktop/ModemManager1/Modem/1
  • so the modem index to use at this moment in time is ‘1’.
  • Then, mmcli -m M where M is replaced with the modem index.
  • You can check, in passing, your own phone number (mmcli -m M | grep own:) and get the SIM index (mmcli -m M | grep SIM)
  • You can also check what mobile network you are on with mmcli -m M | grep operator. The operator id comprises three digits for the Mobile Country Code (MCC) followed by two or three digits for the Mobile Network Code (MNC).
  • The output for the SIM index looks like: SIM | dbus path: /org/freedesktop/ModemManager1/SIM/1 - so the SIM index is 1.
  • Finally, mmcli -i S where S is replaced with the SIM index.
  • -i and -m are abbreviated forms of --sim and --modem respectively.

Executing an AT command on the modem

There are two ways of doing this.

Method A:

mmcli can execute an AT command for you but Modem Manager has to be in "debug" mode for that to work. So:

change the ExecStart line in the file /lib/systemd/system/ModemManager.service by adding --debug so that the line looks like this:

ExecStart=/usr/sbin/ModemManager --debug

After that, run the following commands to make the change take effect:

sudo systemctl daemon-reload
sudo systemctl restart ModemManager.service

Then Modem Manager should be running in debug mode, and you can execute an AT command on the modem e.g.

sudo mmcli -m any --command=ATI

The ATI command is useful to identify the make and model of modem e.g. what variant of the Broadmobi 818 you have.

This approach has the advantage that if you want to execute the same command more than once, you can repeat the command in the shell.

It is recommended that you take Modem Manager out of debug mode once you have finished i.e. revert the change to the file that you edited above and re-execute the two systemctl commands.

Method B:

You can communicate directly with the modem. This involves installing a program like minicom, so do that first:

sudo apt install minicom

Then mmcli -m any | grep ttyUSB

The output will look like:

 |    ports: cdc-wdm0 (qmi), ttyUSB0 (qcdm), ttyUSB1 (at), ttyUSB2 (at),
 |           ttyUSB3 (at), wwan0 (net)

Pick any ttyUSBn device that is followed by (at) e.g. in the above output 1, 2 and 3 are good to use.

sudo minicom -D /dev/ttyUSBn

Type Ctrl/A and then E in order to enable local echo.

Type your AT command(s) e.g.

ATI

Type Ctrl/A and then X in order to exit from minicom.

Mobile Country Reference Data

  • Reference data for APNs (used to access the internet on the mobile network) is stored in the directory /usr/share/mobile-broadband-provider-info
  • Reference data for international dialling is stored in the locale file, in the LC_TELEPHONE section e.g. /usr/share/i18n/locales/ll_CC where ll is the language code and CC is the country code.

Managing Journals

By default, the Librem 5 uses journald for system journaling.

The system journal can get very big, which consumes significant scarce disk space and makes the journal slow to find things in.

To have the system journal automatically cleaned periodically, edit the file /etc/systemd/journald.conf and set values for SystemMaxUse and MaxFileSec. Unless you are specifically trying to troubleshoot an infrequent problem, values of 500M and 1month are reasonable.

By default journald will forward to syslogd but by default a suitable syslogd won't be running and so the forwarded messages won't go anywhere. If you prefer to use syslogd, rather than journald, for examining logged messages then

sudo apt install rsyslog

or such other implementation of syslogd as you prefer.

Note that the command to examine logged messages via journald is journalctl whereas messages logged by syslogd go in /var/log/syslog (unless you configure otherwise).

Tutorials

SECURE SHELL (ssh)

Note that using the L5's passcode to log in remotely provides relatively weak security. See related tutorials for better authentication solutions.

SECURE SHELL Logging in remotely to the L5’s terminal in order to execute commands

On your computer (the client): sudo apt update && sudo apt upgrade

Then:

sudo apt install openssh-client

On the Librem 5 (the remote device): sudo apt update && sudo apt upgrade

Then:

sudo apt install openssh-server

Confirm that it worked (i.e. is “active”): sudo systemctl status ssh

If not active: sudo systemctl enable ssh

If firewall blocks ssh on the remote device: sudo ufw allow ssh

Other firewall options available: stop start disable

Determine IP address of the remote device (L5):

Available in the What IP app, or via the L5’s terminal:
ip address or ifconfig

or log in to your router to find the L5’s IP address.

To log in over WiFi to the remote device (L5) from your computer:
ssh username@REMOTE.IP.ADDRESS.HERE

Example: ssh purism@192.168.xxx.xxx

Type the word “yes” at the next terminal question, then provide the password to your L5. The following prompt will appear:
purism@pureos:~$

You are now logged into your L5 from your computer’s terminal, and can easily execute any terminal commands remotely. This also makes it easy to copy terminal output and paste it here in the forum or elsewhere.

You can also connect your L5 to your computer over USB and use ssh via a Shared Connection in your computer’s network settings.

In the settings panel of the L5, under Sharing, you should now see that Remote Login is On. At the top of this panel, you can use the toggle to enable or disable remote sharing for security purposes.

To exit ssh, use the command exit in the terminal.

SSH File Transfer Protocol (sftp)

Once ssh is set up, a simpler way to remotely access files on the Librem 5 is with sftp.

With both devices powered on, from the host machine:

-Open the file browser

-Type Control+L to bring up the location bar

-Enter sftp://xxx.xxx.xxx.xxx (filling in the IP address of the L5

-Authenticate with the L5's password

This will mount the L5's file system. Navigate to the Home directory and the desired sub-directory to copy, cut, or paste as you like.

TIP: Bookmark the L5's IP in your file browser to access it with a mouse click whenever you want (as long as the L5 is powered on).

SECURE COPY (scp)

Copying files and folders remotely between devices on your network

Note that using the L5's passcode to log in remotely is relatively weak security. See related tutorials for better authentication solutions.

With ssh enabled, you can use the Secure Copy command (scp) to copy files or entire folders from the L5 to your computer, and vice versa. Note that in order to perform scp, you do not log in to the L5 via ssh first.

The syntax is:
scp remote_username@REMOTE.IP.ADDRESS.HERE:/remote/file.txt /local/directory

Examples:

scp purism@192.168.xxx.xxx:/home/purism/example.txt /home/yourusername/Desktop would copy the file example.txt located in the L5’s Home folder to the desktop of your computer.

scp purism@192.168.xxx.xxx:/home/purism/Pictures/2021-04-12-example.png /home/yourusername/Desktop would copy the image 2021-04-12-example.png located in the L5’s Pictures folder to the desktop of your computer.

To copy an entire folder from the L5 to your computer:

scp -r purism@192.168.xxx.xxx:/home/purism/Pictures /home/yourusername/Desktop will copy the folder “Pictures" from the L5 to your computer. (More convenient than copying individual images or files one at a time, in case there are many to copy.) The -r after scp stands for “recursive,” indicating that the copy action should continue until all is copied.

To copy a file from your computer to the L5, the syntax is:

scp file.txt remote_username@REMOTE.IP.ADDRESS.HERE:/remote/directory

If the file is not located in your computer’s Home directory, first change directory to the location of the file, using the command cd, for example cd Desktop, if the file is on your desktop, and so on.

Example, from your Home directory:

scp example.txt purism@192.168.xxx.xxx: (Use the actual ip address of your L5. This places the file in the L5’s Home directory.)

scp example.txt purism@192.168.xxx.xxx:/home/purism/Documents (This goes to the L5’s Documents folder.)

TIP: Although you perform scp without logging in to the other device with ssh, it may be helpful to use ssh first in order to list (ls) the contents of a folder so that it will be easy to copy and paste the name of a file or files for scp. Just be sure to exit ssh before you use scp or you’ll get an error.

(Related discussion on this topic can be found in the community forum: https://forums.puri.sm/t/tutorial-using-ssh-and-scp/13080)

ENHANCING SECURITY FOR SECURE SHELL (ssh)

Relying on the L5's passcode when using ssh for remote access provides relatively weak security. See below for more secure options.

  • Option 1: Use private/public key-pair authentication, and disable password-based authentication for remote login.

These instructions will also work with a Unix/Linux-based server, or the Pinephone.

Enable ssh access to your Librem 5. (See related tutorial.)

On computer, generate the public/private RSA keys.

Open a Terminal session on your computer and type the following command:

ssh-keygen -t rsa OR ssh-keygen

Enter file in which to save the key (/home/{YOUR_ID}/.ssh/id_rsa):
    Created directory ‘/home/{YOUR_ID}/.ssh’.
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in /home/{YOUR_ID}/.ssh/id_rsa.
    Your public key has been saved in /home/{YOUR_ID}/.ssh/id_rsa.pub.

On computer, copy the contents of the id_rsa.pub key onto the Librem 5. The following command will log into your Librem 5, and configure the keys to grant access via the authorized_keys file.

ssh-copy-id -i ~/.ssh/id_rsa.pub purism@host

(example: 192.168.xxx.xxx, substitute with your ip address)

You will be asked for your password into the Librem 5 in this step. Only your public key is copied. Always keep your private key private.

Restart your phone.

On computer, login to your phone using key-based authentication

ssh purism@host (ex. ssh purism@192.168.xxx.xxx)

On Librem 5, disable password-based authentication

ssh purism@host

Use an editor like nano or vim to edit the following /etc/ssh/sshd_config, using admin rights.

sudo nano /etc/ssh/sshd_config

Find the following line:

PasswordAuthentication yes

And change it to:

PasswordAuthentication no

If there is a # (this means "commented out", that is, excluded from the command/script) at the beginning of that line, remove it.

Save the file after making these changes and restart the SSH service using this command:

systemctl restart ssh

To test that password-based authentication is actually disabled, from computer, try to ssh into the Librem 5 using a different (or non-existent) id:

ssh otherid@host

You should get the following error: otherid@host: Permission denied (publickey)

You have now successfully disabled password based authentication in ssh.

(Related discussion on this topic can be found in the community forum: https://forums.puri.sm/t/tutorial-enable-key-based-authentication-via-ssh-on-your-librem-5/13137)

Setting a Custom Background in Phosh

Selected background image can be a .jpg or a .png, possibly other file types.

In the terminal, create the file gtk.css (if it doesn't already exist) using any installed text editor: nano ~/.config/gtk-3.0/gtk.css. Alternately, you can create the file manually in the Files app.

Then add the following to the gtk.css file. (Change the path to point to your chosen image.)

/*
 * Set a background for the lockscreen.
 */
phosh-lockscreen, .phosh-lockshield {
  background-image: linear-gradient(rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.7)),
                    url('file:///home/purism/Pictures/mybackground.jpg');
  background-size: cover;
  background-position: center;
}

/*
 * Set a background for the app grid.
 */
phosh-app-grid {
  background-image: linear-gradient(rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.7)),
                    url('file:///home/purism/Pictures/mybackground.jpg');
  background-size: cover;
  background-position: center;
}

Then: sudo systemctl restart phosh.

The background image can be set to different levels of transparency by changing the "0.7" entries above to anything on the scale of "0.0" (fully transparent) to "1.0" (fully opaque). It’s a linear-gradient effect, so the first 0.7 is transparency starting on top, and the second 0.7 is transparency ending at bottom.

You can also change the gnome background. (This is not needed in pureos-byzantium, as a graphical option is present.):

`gsettings set org.gnome.desktop.background picture-uri file:///path/to/picture_file`

e.g. gsettings set org.gnome.desktop.background picture-uri file:///home/purism/Pictures/image.png

Creating a Shortcut to Execute a Terminal Command

As an example, the following will create a shortcut to modem info, similar to using Android's *#*#INFO#*#* service code.

First, find an appropriate icon, edit it if desired, name it (e.g. modem.png), and save it to .local/share/icons, creating the icons folder if it doesn't exist already.

Next, create the shortcut button in .local/share/applications, naming it e.g. ModemInfo.desktop. This will insert the icon/launcher into the home screen's app grid.

In the terminal, enter mmcli -L to retrieve the modem's single-digit identifier. In this example, the command returns /org/freedesktop/ModemManager1/Modem/0 [QUALCOMM INCORPORATED] 0, which indicates "0" as the identifier. We can now run mmcli --modem=0 to manually retrieve the detailed modem and mobile network information. (If there is only one modem installed, you can skip mmcli -L and change mmcli --modem=0 to mmcli --modem=m any.)

Next, to enable the app screen launcher to run mmcli --modem=0 (or mmcli --modem=m any), copy the following text into the ModemInfo.desktop file, which was created previously in .local/share/applications:

[Desktop Entry] Name=ModemInfo Exec=gnome-terminal -x bash -c “mmcli --modem=0 | tee modeminfo.txt; exec bash” StartupNotify=true Terminal=false Type=Application Categories=Utilities; Icon=/home/purism/.local/share/icons/modem.png

The above automates opening the terminal, running the command, and also saves the terminal output to a text file (modeminfo.txt) in the home folder, as well as setting the icon to use as the launcher, all from a single tap on the app icon. The text file will be overwritten every time.

At this point, either view the output in the terminal opened by the launcher, or close the terminal and view the text file instead.

For another example, see how to create a launcher to quick-dial a frequent telephone number.