There is always a risk with writing up a guide on how to use a device in active development. Many, if not all, of the steps I am going to outline below will most likely be out of date within a year or so. That being said, this is what works for now to get a Librem 5 to run PureOS from scratch. For your reference and mine.
Notes
- I will not be using Flatpaks. It’s a personal challenge, and an attempt to keep things light and fast.
- After all is said and done, call quality and reliability is key.
Steps
- Flashing PureOS w/ LUKS Encryption, Expanded File System, and New Encryption Key
- Initial Setup and Download of PureOS Byzantium
- Modify the Image of PureOS Byzantium
- Flash the New Image to the Librem 5
- Expand the File System
- Updating the Librem 5
- Update Software
- Updating Bootloader Firmware
- Updating Wi-Fi & Bluetooth Firmware
- Updating BroadMobi Modem Firmware
- Updating USB-C Firmware (WIP)
- Updating SmartCardReader Firmware (WIP)
- Turning on VoLTE Support
- Turn on VoLTE with bm818-tools
- Turn on VoLTE with bm818-tools from repository
- Turn on VoLTE with AT commands
- Managing GPS (WIP)
- Installing Software
- PureOS Repository and Flatpaks
- Removing Junk
- Building Software
- Building Millipixels from Source
- Building Tooth Mastodon Client from Source (WIP)
- Installing Signal Desktop (WIP)
- Quality of Life Settings
- Import Contacts
- Import Feeds
- Order a Case and a Screen Protector
- Screen Rotation
- Firefox ESR Mobile Config
- Setup Samba
Flashing PureOS w/ LUKS Encryption, Expanded File System, and New Encryption Key
Step 1. Initial Setup and Download of PureOS Byzantium
Boot your Desktop to PureOS, Debian, Ubuntu, or another Debian-based system.
sudo apt update && sudo apt upgrade
sudo apt install git python3-jenkins uuu python3-tqdm # We are flashing with NXP tools, not JumpDrive.
sudo apt install partclone
mkdir L5LUKS #This can be any name. Just be consistent.
cd L5LUKS
wget https://reboil.com/res/2022/exe/20220523T0237Z..librem5_image_reencrypt.sh #Downloads a bash script created by members of the Purism Forum.
git clone https://source.puri.sm/Librem5/librem5-flash-image.git
cd librem5-flash-image/scripts
./librem5-flash-image --dist byzantium --variant luks --skip-cleanup #Downloads a copy of the latest LUKS-version of PureOS Byzantium to your hard drive.
When it asks you to put your phone into flash mode, do “ctrl+c” to exit. You don’t want to flash the image yet, you have to make a number of changes to it before it is ready to be flashed.
ls and take note of the full name of the new folder containing the PureOS image. Mine was “tmp_librem5-flash-image_g0mfz4ag”.
Step 2. Modify the Image of PureOS Byzantium
Return to original folder with “20220523T0237Z..librem5_image_reencrypt.sh” (Do “cd ..” twice)
Make “20220523T0237Z..librem5_image_reencrypt.sh” executable by right clicking and allowing execution.
sudo ./20220523T0237Z..librem5_image_reencrypt.sh librem5-flash-image/scripts/tmp_librem5-flash-image_g0mfz4ag #Modify this command to point to the folder you noted in the previous step. This process will copy the Byzantium image to another folder and re-encrypt it with new passphrase and encryption keys.
When queried, enter the current LUKS passphrase “123456”
———- OUTPUT ———-
/dev/mapper/Librem5_Orig is active.
type: LUKS1
cipher: aes-xts-plain64
keysize: 256 bits
key location: dm-crypt
device: /dev/loop2p2
sector size: 512
offset: 4096 sectors
size: 7821312 sectors
mode: read/write
When queried, enter your new LUKS passphrase twice. This can be letters and/or numbers.
———- OUTPUT ———-
Reencryptipng new LUKS Container…
Enter passphrase for /dev/loop1p2:
Opening Reencrypted LUKS Container…
Enter passphrase for /dev/loop1p2:
/dev/mapper/Librem5_Reencrypted is active.
type: LUKS1
cipher: aes-xts-plain64
keysize: 256 bits
key location: dm-crypt
device: /dev/loop1p2
sector size: 512
offset: 4096 sectors
size: 7821312 sectors
mode: read/write
Transfering all data to the reencrypted LUKS Container…
Partclone v0.3.13 http://partclone.org
Starting to back up device(/dev/mapper/Librem5_Orig) to device(/dev/mapper/Librem5_Reencrypted)
Elapsed: 00:00:01, Remaining: 00:00:00, Completed: 100.00%
Total Time: 00:00:01, 100.00% completed!
done!
File system: EXTFS
Device size: 4.0 GB = 974080 Blocks
Space in use: 3.0 GB = 726386 Blocks
Free Space: 1.0 GB = 247694 Blocks
Block size: 4096 Byte
Elapsed: 00:00:18, Remaining: 00:00:00, Completed: 100.00%, Rate: 9.92GB/min,
current block: 974059, total block: 974080, Complete: 100.00%
Total Time: 00:00:18, Ave. Rate: 9.9GB/min, 100.00% completed!
Syncing… OK!
Partclone successfully cloned the device (/dev/mapper/Librem5_Orig) to the device (/dev/mapper/Librem5_Reencrypted)
Cloned successfully.
Unloading the crypt containers…
New Image created succesfully
Please put your Librem5 to flash mode
cd ‘librem5-flash-image/scripts/tmp_librem5-flash-image_g0mfz4ag_reencrypted’
uuu flash_librem5r4.lst
Step 3. Flash the New Image to the Librem 5
Put the Librem 5 into Flash Mode. If you have issues try another USB-C cable. That worked for me.
- Power down the phone
- Turn off all hardware kill switches
- Unplug the phone
- Remove the phone battery
- Hold down the volume up button
- Plug the phone into the computer (While holding the volume up button)
- Reinsert the battery (While holding the volume up button)
- Release the volume up button
cd librem5-flash-image/scripts/tmp_librem5-flash-image_g0mfz4ag_reencrypted
sudo uuu flash_librem5r4.lst #This will flash the newly encrypted image to the Librem 5.
———- OUTPUT ———-
uuu (Universal Update Utility) for nxp imx chips -- lib1.4.77
Success 1 Failure 0
2:1 4/ 4 [Done ] FB: Done
Step 4. Expand the File System
Boot the Librem 5 and unlock it with the new passphrase. The user login, however, is still “123456” and will need to be changed later. At this point, the Librem 5 is encrypted with a new LUKS passphrase and a new encryption key, but is not the full size of the drive. The next step is to resize the partition to the full size of the drive.
Connect the Librem 5 to your Desktop computer via USB.
sudo apt install picocom #Software used to interface with peripherals and the like.
sudo picocom -b 115200 /dev/ttyACM0
Log into the Librem 5 with the following credentials.
Login: purism
Password: 123456
sudo cfdisk /dev/mmcblk0
Select the partition /dev/mmcblk0p2 and press “Delete”.
Press “New” partition. It will appear with the full size of the drive. Select “primary” and confirm it.
Press “Write” to save the changes. Type “yes” to confirm, then press “Quit”.
sudo reboot
Reconnect to the Librem 5 via picocom like you did above.
sudo cryptsetup resize /dev/mapper/crypt_root
sudo resize2fs /dev/mapper/crypt_root
There is no need to change the LUKS passphrase because you changed it in a previous step, but if you want to change it again, you can do it now by running the following command:
sudo cryptsetup luksChangeKey /dev/mmcblk0p2
sudo reboot
Now unplug your Librem 5 from the desktop computer. You can confirm that the LUKS partition is the full size of the disk by running the “Disks” program. Storage is also visible using the “Usage” program.
To change your user password from the default “123456”, open a terminal and type passwd.
Updating the Librem 5
Step 1. Update Software
This one is easy. Connect to Wi-Fi or insert your SIM card and setup your APN in Settings to activate your data. You may have to toggle between your APN and another entry (with the same APN if you want) for it to acknowledge the data connection.
Open a terminal.
sudo apt update && sudo apt upgrade
Step 2. Updating Bootloader Firmware
This topic is far more contentious and you should know what you’re doing before deciding to move ahead with some of these updates. Firstly, they may not be required for proper function. Secondly, they may actually cause you to lose some of your freedom, as defined by the FSF. Thirdly, an older firmware version may actually work better on the hardware you have.
| Bootloader (U-Boot) | Commands / Instructions |
|---|---|
| Check Version | cat /proc/cmdline |
| My Output | u_boot_version=2022.10-g9d134279b6 |
| Site of Firmware | https://source.puri.sm/Librem5/uboot-imx |
| Install the package that will oversee the updating of the bootloader | wget https://source.puri.sm/Librem5/uboot-imx/-/jobs/399069/artifacts/raw/debian/output/u-boot-librem5_2022.10-librem5.1_arm64.deb && sudo apt install ./u-boot-librem5_2022.10-librem5.1_arm64.deb |
| Update the bootloader | sudo u-boot-install-librem5 /dev/mmcblk0 |
I was previously running a version of the bootloader from 2019. It would appear that when I reflashed my Librem 5, it also updated the bootloader to the 2022 version. So, I have no need for these instructions, but if you have a 2019 bootloader and want to update manually without reflashing your phone, this is an option.
Step 3. Updating Wi-Fi & Bluetooth Firmware
| Redpine Signals RS9116 Wi-Fi and Bluetooth Card | Commands / Instructions |
|---|---|
| Check Version | sudo dmesg | grep redpine | grep Version |
| My Output | redpine_91x: ================ RSI Version Info ============== |
| Site of Firmware | https://source.puri.sm/Librem5/redpine-firmware-nonfree/-/tree/master/files/firmware |
| Choose a Firmware Version | Select the .rps file that indicates support for both BT and WLAN: 1.0.5 (dev_oper_mode=13) 1.2.1 (dev_oper_mode=13) 1.2.20 (dev_oper_mode=13) 2.0.0.24 (dev_oper_mode=5) 2.3.2.3 (dev_oper_mode=5) 2.5.1.11 (dev_oper_mode=5) |
| Flash Firmware | Delete the file in the folder /lib/firmware of your Librem 5 called “RS9116_NLINK_WLAN_BT_IMAGE.rps“. Copy the new .rps file to the /lib/firmware folder. If the folder doesn’t exist, you can create it. Rename the file you copied to “RS9116_NLINK_WLAN_BT_IMAGE.rps“. When the Librem 5 reboots, it will look in this folder for this file and automatically flash the new firmware to the card.sudo wget https://source.puri.sm/Librem5/redpine-firmware-nonfree/-/raw/master/files/firmware/RS9116_NLINK_WLAN_BT_IMAGE.FW2.5.1.11.rps?inline=false -O /lib/firmware/RS9116_NLINK_WLAN_BT_IMAGE.rps |
| Post Flash Adjustments | Depending on the version you are flashing, you have to make some minor adjustments to /etc/modprobe.d/librem5-devkit.conf. If you are flashing a firmware version 1.x, you have to change the two instances of dev_oper_mod= from the number 5 to 13. If you are flashing a firmware version 2.x, you have to make sure both instances are set to 5. Reboot for this update to take effect. |
| New Output | redpine_91x: ================ RSI Version Info ============== |
In my experience, the newest firmware for the Redpine card (2.5.1.11) is the most stable. Keep in mind that it does not support BLE. People have had success connecting their PineTime watch to their Librem 5 using firmware from the 1.x versions, but that’s a trade off I’m not willing to make right now.
Step 4. Updating BroadMobi Modem Firmware
| BroadMobi BM818 Wireless Modem | Commands / Instructions |
|---|---|
| Check Version (via Terminal) | mmcli --modem=0 |
| My Output | firmware revision: MPSS.JO.2.0.2.c1.1-00032-9607_GENNS_PACK-1.351938.1 1 [Nov 26 2020 02:00:00] |
| Check Version (from Modem) | sudo apt install screenAT+BMSWVER ATI |
| My Output | M100E_YCSN0_1.0.0_210830, |
| Contact Purism Support / Obtain Firmware / Flash Firmware | At this point, it is strongly advised that you contact Purism Support at support@puri.sm and provide them with your modem versions along with your U-Boot version. They should reply with directions on how to update your BroadMobi modem. They will provide a .pdf with instructions on where to download the necessary packages, and how to flash the new firmware to the modem. These steps may depend on what firmware you are currently running, so I won’t recreate those steps here. |
| New Output | M100E_YCSN0_1.0.0_220926, |
As you can tell, using the method outlined by Purism Support I was able to upgrade the BroadMobi modem from V1.0.0.1 dated 2021 09 07 to V1.0.0.2 dated 2022 09 30. Is this necessary? Probably not unless you are having issues with VoLTE. I’m still glad I know how to do it though.
Step 5. Updating USB-C Firmware
| TPS6598X USB-C PD Firmware | Commands / Instructions |
|---|---|
| Check Version | sudo cat /sys/kernel/debug/tps6598x/0-003f/customer_use |
| My Output | 0x4c35445000000200 |
| Site of Firmware | TBD |
| Flash Firmware | TBD |
In theory, one should be able to upgrade the firmware on this component. To be determined.
Step 6. Updating SmartCardReader Firmware
| SmartCardReader Firmware | Commands / Instructions |
|---|---|
| Check Version | TBD |
| My Output | TBD |
| Site of Firmware | TBD |
| Flash Firmware | TBD |
In theory, one should be able to upgrade the firmware on this component. To be determined.
Turning on VoLTE Support
There are three (3) methods that I have used to turn on VoLTE. I believe all three are functional and do the same thing.
Step 1. Turn on VoLTE with bm818-tools
sudo apt install bm818-tools
Open the application BM818 Tool. If the application reads VoLTE as enabled, disable it. Reopen the application and enable VoLTE again. You may need to reboot the modem for these changes to take effect.
Step 2. Turn on VoLTE with bm818-tools from repository
sudo git clone https://source.puri.sm/Librem5/bm818-tools.git
Add user ‘purism’ to the dialout group if you haven’t already done so with the following command. You will need to logout or reboot for this to take effect.
sudo usermod -a -G dialout purism
Confirm this was a success by running id purism.
Move to the folder in the cloned repository /usr/bin/ and run the following commands as required.
| bm818-volte on | Turn on VoLTE. |
| bm818-volte off | Turn off VoLTE. |
| bm818-volte-check | Check status of VoLTE. A call must be active. |
| bm818-fw-check | Check firmware version of modem. |
Step 3. Turn on VoLTE with AT commands
Interface with the modem by connecting to it with screen.
sudo screen /dev/ttyUSB3
ATE #This will show you what you’re typing
AT+CGDCONT=2,"IPV4V6","ims"
AT$QCPDPIMSCFGE=2,1,0,0
ATE0 #To exit
Now you can power cycle the modem with the kill switch or reboot. Alternatively, you can turn off VoLTE using the following commands:
sudo screen /dev/ttyUSB3
ATE
AT$QCPDPIMSCFGE=2,0,0,0
ATE0
You can test whether VoLTE is active by running the following AT command while a call is ongoing. The output should be LTE.
sudo screen /dev/ttyUSB3
AT+BMRAT
In the end, I have yet to get VoLTE running on my phone after troubleshooting for a few hours. I contacted by cellular provider who informed me that, while I was sent a new 4G SIM cards with VoLTE support, the network has yet to turn on VoLTE. They expect to activate VoLTE in the coming months. I will update this entry, if and when that happens.
Managing GPS
Step 1. Turning off Assisted GPS
Librem 5 will geolocate you using three sources of information. The GPS data incoming from the modem is typically the most accurate, but issues arise when the GPS signal is weak or nonexistent. If you’re GPS antenna is less than ideal, as is the case with the Librem 5, you will find yourself located within a few blocks of their Wi-Fi router (ISP enabled in #1), or near the headquarters of your mobile service provider (Mobile data enabled in #2).
- Geolocation based on the IP address of your Wi-Fi connection
- Geolocation based on the IP address of your mobile data connection
- Geolocation based on GPS hardware built into the onboard BroadMobi modem.
In order to force the Librem 5 to use the GPS data from the modem when it is available, you can turn off other sources of GPS information. (I’m having some issues with this. I’m not sure anymore if its working. It may work for you. So, WIP)
sudo nano /etc/geoclue/geoclue.conf
Set 3G source, CDMA source, Modem-GPS source, and WiFi source to “false”. The only source of data that should read “true” is Network NMEA.
sudo systemctl restart geoclue.service
Test that your GPS data is coming off the modem by running the following command after turning on GPS in your Privacy Settings. You may need to wait a few minutes to get a fix.
sudo apt install socat
sudo socat unix-connect:/var/run/gnss-share.sock -
Be mindful that if you are playing around and want to try gpsd support, if you try installing gpsd it will automatically remove gnss-share. It would appear that they cannot live side-by-side. I have yet to find a way to move GPS data from gnss-share to programs that make use of gpsd. (WIP)
Installing Software
Step 1. PureOS Repository or Flatpaks
I try not to use Flatpaks on the Librem 5. The hardware is good but not good enough to provide a smooth and enjoyable experience with Flatpaks. I find that the additional storage space and ram usage of Flatpaks outweighs the slower user experience. This guide focuses on using the PureOS package repository.
To search for programs in the repository, head over to https://software.pureos.net/suites and search for your favorite programs. So far, these are the programs I recommend. If you are comfortable using Flatpaks, you will be able to install far more mobile-friendly apps.
| Program (sudo apt…) | Purpose |
|---|---|
| screen | Terminal multiplexer for interfacing with the BroadMobi modem |
| gpodder | This installs the adaptive version which is very usable on mobile. I link this to lollypop to listen to podcasts. Because the files play in lollypop, it does not remember where your last left off on the podcast. |
| gnome-feeds | A good RSS reader. |
| evolution | Geary is a good email client but it is buggy and not ideal. I have tweaked evolution to be usable on mobile and it works well. It’s important that you open the “Mobile Settings” app and setup Evolution to scale automatically. |
| lollypop | Solid audio player with options accessible in the lock screen. |
| mpv | Solid video player with hardware acceleration. |
| seahorse | Password and key manager. |
| gnome-authenticator | 2FA manager. |
| animatch | So much fun! I’m also a big fan of Shattered Pixel but it is not in the repository. It is available in a repackage .deb file at https://github.com/ebolalex/shattered-pixel-dungeon/releases/. |
| gnome-screenshot | Screenshot tool. |
| qbittorrent | Torrent client. One doesn’t refer to their torrent client very much, so it can be made to work by opening the “Mobile Settings” app and setting qBittorrent to scale automatically. |
| TBD | Matrix client (Chatty support is pretty good now) |
| dino | Dino v0.3 with audio and video calling support is only available at the moment in the test PureOS repository known as Octarine. You can install it safely on your Librem 5 by installing Dino from Octarine and nothing else. Run sudo nano /etc/apt/sources.list.d/octarine.listto create the file for the added repository. Paste the line deb https://repo.pureos.net/pureos octarine mainin the file, press Return to start a new line, and save on exit. Do not install anything else from Octarine or it will conflict with what you have already installed from Byzantium. Update repositories with sudo apt update and install Dino v0.3 with sudo apt install dino-im/octarine dino-im-common/octarine |
| TBD | Navigation (Marble is gpsd based. Pure Maps is not in the repo.) |
| VPN | Run the following commands to install wireguard and openresolv, copy your VPN providers .conf file, and create a symlink.sudo apt install wireguardTo go up and down on the VPN use the following commands. wg-quick up yourprovidedfile |
Step 2. Removing Junk
Maybe not quite junk, but certainly unnecessary for most users. This is how you remove the Parental Control app and the Librem 5 Tour app.
sudo apt purge malcontent && sudo apt autoremove
sudo apt purge phosh-tour && sudo apt autoremove
Building Software
Step 1. Building Millipixels from Source
The version of Millipixel found on the Librem 5 today is good, but not great for daily use. It lacks automatic gain, automatic exposure, automatic balance, and autofocus that we have come to expect from a camera on a mobile phone. Luckily, these features are in active development and are already much better at taking good pictures. If you plan on using your Librem 5 to take pictures, I strongly suggest you take the time to build the developmental release of Millipixels on your Librem 5.
Begin by connecting your phone to your computer and logging in via serial.
sudo picocom -b 115200 /dev/ttyACM0
The rest of the steps are based off information in https://source.puri.sm/Librem5/millipixels. Update your Librem 5 and install build dependencies. I prefer to install them individually to make sure they install properly.
sudo apt update
sudo apt upgrade
sudo apt install debhelper-compat
sudo apt install libbsd-dev
sudo apt install libcamera-dev
sudo apt install libgtk-3-dev
sudo apt install libtiff-dev
sudo apt install libzbar-dev
sudo apt install meson
sudo apt install rustc
sudo apt install libpulse-dev
Clone the Millipixels repository
sudo apt install git
sudo git clone https://source.puri.sm/Librem5/millipixels.git
Build Millipixels
cd millipixels
sudo meson build
cd build
sudo ninja
sudo ninja install
The development version of Millipixels with automated settings and video recording should boot when you launch the Camera app.
Step 2. Building Tooth Mastodon Client from Source (WIP)
Tooth is the best (maybe only) GTK-based Mastodon client currently in development. It works great already, and you can build at as follows. These steps are based off information in https://github.com/GeopJr/Tooth.
sudo apt update
sudo apt upgrade
sudo apt install meson valac libglib2.0-dev libjson-glib-dev libxml2-dev libgee-0.8-dev libsoup2.4-dev libgtk-4-dev libadwaita-1-dev libsecret-1-dev
git clone https://github.com/GeopJr/Tooth.git
cd Tooth
make
make install
This won’t build because libglib2.0-dev in the PureOS repository is version 2.66.8 which is not >=2.70. Sigh.
Step 3. Installing and/or building Signal Desktop (WIP)
https://gitlab.com/undef1/signal-desktop-builder/-/packages
https://github.com/0mniteck/Signal-Desktop-Builder
cd Downloads
sudo dpkg -i “signal-desktop_6.8.0_arm64.deb”
sudo dpkg -r “signal-desktop_6.8.0_arm64.deb”
Until I succeed in building Signal Desktop for the Librem 5, I continue to recommend the Flatpak by Adam Thiede.
sudo flatpak remote-add --user --if-not-exists signal-arm https://elagost.com/flatpak/signal.flatpakrepo
sudo flatpak install --user signal-arm org.signal.Signal
Quality of Life Settings
Step 1. Import Contacts
Importing your contacts as part of a .vcf file used to be tedious but is now much easier. The Contacts application supports the import of .vcf files with all your contacts.
Step 2. Import Feeds
GNOME Feeds supports importing .opml files, so don’t hesitate to export the .opml file from your desktop and import it into GNOME Feeds.
Step 3. Order a Case and a Screen Protector
I ordered @fiacco 3D model “Evergreen_new_case_1.1.stl” designed to be printed with flexible material. I ordered the print in TPU plastic using Multi-Jet Fusion (MJF) technology and a chemical finish for smoothness. It’s thin, light, and does a great job. The back may bulge a bit, but the sides should hold the phone effortlessly.
As for a screen protector, I ordered a 2-pack from Celicious from Amazon. I went with standard glossy and its reflection is not a problem.
Step 4. Screen Rotation
The Librem 5 is not well suited to landscape mode. The keyboard is too big making landscape mode basically irrelevant unless you want to watch a video. The Librem 5 gyroscope is also a little sensitive, so I suggest you lock screen rotation in vertical mode. You will be less frustrated over all and can unlock it anytime you want to watch a video.
Step 5. Firefox ESR Mobile Config
Firefox ESR does not come with the mobile config settings built-in. Technically it does but they aren’t working yet. You can achieve these by running the following commands. Don’t uninstall anything in this process.
sudo apt install git build-essential
git clone https://gitlab.com/postmarketOS/mobile-config-firefox
cd mobile-config-firefox
make
sudo make install
Step 6. Setup Samba
sudo apt install samba
Reboot your device and you should be able to connect to your Samba server with Files (Nautilus).