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
- Known issues
- General
- Software installations and updates (apps and OS)
- Recommended applications for common use cases
- Application life-cycle
- USB
- Calls
- Mail (Geary)
- Contacts
- Locale
- Network Config
- Modem Manager
- Executing an AT command on the modem
- Mobile Country Reference Data
- Managing Journals
- Tutorials
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 appUsage
(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
wherell
is the language code andCC
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
ssh
)
SECURE SHELL (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.
sftp
)
SSH File Transfer Protocol (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).
scp
)
SECURE COPY (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)
ssh
)
ENHANCING SECURITY FOR SECURE SHELL (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.