Fwupd

From postmarketOS Wiki

This article is about upgrading firmware on your postmarketOS installation with fwupd. Several postmarketOS devices support firmware upgrades through fwupd such as the PinePhone (Pro), SHIFT6mq and more.

fwupd frontends

fwupd can be used with several frontends:

  • fwupdmgr (CLI)
  • KDE Discover
  • GNOME Software
  • GNOME Firmware Updater

For now it is recommended to make the firmware upgrades through fwupdmgr or GNOME Firmware Updater. Other interfaces are not tested as well, and may not yet support newer features of fwupd, such as swichting branches.

Upgrading ABL firmware on the SHIFT6mq

The SHIFT6mq uses, like other SDM845 devices, ABL (Android BootLoader) from Qualcomm as bootloader. It can be upgraded as on Android through fwupd with the android-boot plugin which is available from fwupd 1.8.5 or later.

To get the latest firmware for ABL on the SHIFT6mq, you can run:

$ sudo fwupdmgr upgrade

Upgrading Tow-Boot on the PinePhone (Pro)

fwupd 1.8.5 gained support for updating Tow-Boot on the PinePhone (Pro). It leverages either the mtd (SPI flash) or android-boot (eMMC boot partition) plugins to flash Tow-Boot. You need Tow-Boot with uSWID data embedded for this to work (Tow-Boot 2021.10-006 or higher), if you don't have this version yet, you need to flash it still with the Tow-Boot installer.

To get the latest Tow-Boot platform firmware for the Pine64 PinePhone (Pro), you can run:

$ sudo fwupdmgr upgrade

Upgrading Modem Firmware on the PinePhone (Pro)

The primary use case of fwupd for the PinePhone (Pro) is upgrading the EG25-G modem from the stock firmware to Biktor's alternative firmware that has several stability improvements. This feature is available in postmarketOS v22.06 and higher.

Preparations

  • Make sure your phone is charged
  • Plug the charger while doing this

fwupdmgr

Verify that fwupdmgr detects the EG25-G modem. If it does not, you may need to reboot first (e.g. if fwupd packages were just installed):

$ sudo fwupdmgr get-devices
WARNING: This package has not been validated, it may not work properly.
Pine64 PinePhone (1.2) 
│
└─QUECTEL Mobile Broadband Module:
      Device ID:          976c4a39e87f61e6940ea6a8d39c583cfa99615f
      Summary:            Quectel EG25-G modem
      Current version:    EG25GGBR07A08M2G_01.001.01.001
      Vendor:             QUALCOMM INCORPORATED (USB:0x2C7C)
      GUIDs:              db379a33-254f-5140-b37e-d36ae7e5c039
                          d18f31f1-a3fa-55a2-b4ed-decfbc1e004d
                          1a2996cb-f86e-5583-a464-e1b96e1c6ae9
                          587bf468-6859-5522-93a7-6cce552a0aa3
                          22ae45db-f68e-5c55-9c02-4557dca238ec
      Device Flags:       • Updatable
                          • System requires external power source
                          • Supported on remote server
                          • Device supports switching to a different branch of firmware
$ sudo fwupdmgr refresh --force
WARNING: This package has not been validated, it may not work properly.
Updating lvfs-testing
Downloading…             [***************************************]
Downloading…             [***************************************]
Updating lvfs
Downloading…             [***************************************]
Downloading…             [***************************************]
Successfully downloaded new metadata: 1 local device supported


Do the initial upgrade with switching the branch. This will take about 10 minutes (and yes, it says "downgrade" initially). You can find information about Biktor's releases here. Make sure to replace <DEVICE-ID> in the following command with the "Device ID:" from fwupdmgr get-devices output.

sudo fwupdmgr switch-branch <DEVICE-ID>                                                                                                                                                                                                                               
[sudo] password for user:                                                                                                                                      
WARNING: This package has not been validated, it may not work properly.                                                                                        
╔══════════════════════════════════════════════════════════════════════════════╗                                                                               
║ Switch branch from default to community?                                     ║                                                                               
╠══════════════════════════════════════════════════════════════════════════════╣                                                                               
║ The firmware from Pine64 is not supplied by QUALCOMM INCORPORATED, the       ║                                                                               
║ hardware vendor.                                                             ║                                                                               
║                                                                              ║                                                                               
║ Your hardware may be damaged using this firmware, and installing this        ║                                                                               
║ release may void any warranty with QUALCOMM INCORPORATED.                    ║                                                                               
║                                                                              ║                                                                               
║ This release brings the following fixes and improvements:                    ║                                                                               
║                                                                              ║                                                                               
║ • Allow calls to be delayed for more than 999 seconds                        ║                                                                               
║ • Ensure we send a RING_IN pulse to the Pinephone when making simulated      ║                                                                               
║ calls, to be able to wake the Pinephone from crust                           ║                                                                               
║ • Force resync of the RT5616 registers in the external codec (Pinephone      ║                                                                               
║ Pro) so call audio keeps working after suspend                               ║                                                                               
╚══════════════════════════════════════════════════════════════════════════════╝                                                                               
                                                                               
Do you understand the consequences of changing the firmware branch? [y|N]: y   
╔══════════════════════════════════════════════════════════════════════════════╗                                                                               
║ Downgrade QUECTEL Mobile Broadband Module from                               ║                                                                               
║ EG25GGBR07A08M2G_01.001.01.001 to 0.5.9?                                     ║                                                                               
╠══════════════════════════════════════════════════════════════════════════════╣                                                                               
║ This release brings the following fixes and improvements:                    ║                                                                               
║                                                                              ║                                                                               
║ • Allow calls to be delayed for more than 999 seconds                        ║                                                                               
║ • Ensure we send a RING_IN pulse to the Pinephone when making simulated      ║                                                                               
║ calls, to be able to wake the Pinephone from crust                           ║                                                                               
║ • Force resync of the RT5616 registers in the external codec (Pinephone      ║                                                                               
║ Pro) so call audio keeps working after suspend                               ║                                                                               
║                                                                              ║                                                                               
║ This firmware is provided by LVFS community members and is not provided (or  ║                                                                               
║ supported) by the original hardware vendor.                                  ║                                                                               
║                                                                              ║                                                                               
║ Installing this update may also void any device warranty.                    ║                                                                               
║                                                                              ║                                                                               
║ QUECTEL Mobile Broadband Module and all connected devices may not be usable  ║                                                                               
║ while updating.                                                              ║                                                                               
╚══════════════════════════════════════════════════════════════════════════════╝                                                                               
                                                                                                                                                               
Perform operation? [Y|n]: Y                                                                                                                                    
Downloading…             [***************************************] Less than one minute remaining…                                                             
Downloading…             [***************************************]                                                                                             
Decompressing…           [***************************************]                                                                                             
Decompressing…           [***************************************]                                                                                             
Authenticating…          [***************************************]                                                                                             
Authenticating…          [***************************************]                                                                                             
Restarting device…       [***************************************]                                                                                             
Writing…                 [***************************************]                                                                                             
Waiting…                 [***************************************] Less than one minute remaining…                                                             
Successfully installed firmware

Following upgrades can be done with fwupdmgr upgrade.

When there is nothing to do, you will see:

$ sudo fwupdmgr upgrade
WARNING: This package has not been validated, it may not work properly.
Devices with the latest available firmware version:
 • QUECTEL Mobile Broadband Module

Troubleshooting

If flashing fails for whatever reason, try hard rebooting the phone by powering off, taking the battery out, and powering the phone back on. Then you can use the flashall method as described in Biktor's release notes here.

Bringing up support for the Android Boot plugin

The Android Boot plugin is used to update hardware which uses partitions to store their firmware on.

In this example we want to bringup support for SHIFTphone 8's ABL.

First you need to get hold of the GUID of the device you want to add support for, which in the case of ABL needs the PARTUUID's of the updatable partitions:

$ sudo blkid | grep abl_
/dev/sde8: PARTLABEL="abl_a" PARTUUID="0072779b-8343-75c6-525f-44ff0e1d04db"
/dev/sde32: PARTLABEL="abl_b" PARTUUID="584e4f5f-6023-f6d6-eb3f-48bb7da59feb"

Next create a quirk file to locally support the devices. The format is [DRIVE\UUID_XXX&LABEL_YYY], where XXX needs to be replaced with the PARTUUID from the previous step and YYY with the partition label.

$ cat /var/lib/fwupd/quirks.d/otter.quirk
[DRIVE\UUID_0072779b-8343-75c6-525f-44ff0e1d04db&LABEL_abl-a]
Flags = updatable,signed-payload
Vendor = SHIFT GmbH
VendorId = eco.shift
AndroidBootVersionProperty = androidboot.abl.revision

[DRIVE\UUID_584e4f5f-6023-f6d6-eb3f-48bb7da59feb&LABEL_abl-b]
Flags = updatable,signed-payload
Vendor = SHIFT GmbH
VendorId = eco.shift
AndroidBootVersionProperty = androidboot.abl.revision

Once the quirk file is in place, restart the fwupd service and check if the ABL is recognized:

$ sudo service fwupd restart
$ fwupdmgr get-devices
WARNING: UEFI capsule updates not available or enabled in firmware setup
See https://github.com/fwupd/fwupd/wiki/PluginFlag:capsules-unsupported for more information.
WARNING: This package has not been validated, it may not work properly.
shift SHIFT SHIFTphone 8
│
├─KMJS9001RM-BG01:
│     Device ID:          38c11cd05c6cd47879f3b1173e68f04b52015c84
│     Summary:            UFS device
│     Current version:    0500
│     Vendor:             SAMSUNG (SCSI:SAMSUNG)
│     Serial Number:      SAMSUNG
│     GUIDs:              e56797c0-a400-529f-a473-eba1f1a82ed7 ← SCSI\VEN_SAMSUNG&DEV_KMJS9001RM-BG01
│                         ce4bd73c-4cc4-576d-b861-2eb47b2479ae ← SCSI\VEN_SAMSUNG&DEV_KMJS9001RM-BG01&REV_0500
│     Device Flags:       • Internal device
│                         • Updatable
│   
└─abl a:
      Device ID:          726f01ecc8a79cc9e05091ea825e4c304c936eef
      Summary:            Android Bootloader
      Current version:    6.0
      Vendor:             SHIFT GmbH (eco.shift)
      Serial Number:      31090a61
      Problems:           • Device requires AC power to be connected
      GUIDs:              32df84b5-af5f-512d-afbe-61a83b282962 ← DRIVE\UUID_0072779b-8343-75c6-525f-44ff0e1d04db
                          67c7794d-af25-565d-b5ce-9a42da0e93e8 ← DRIVE\UUID_0072779b-8343-75c6-525f-44ff0e1d04db&LABEL_abl-a
                          3943aaee-852f-5260-ba36-de41cc2bc863 ← DRIVE\UUID_0072779b-8343-75c6-525f-44ff0e1d04db&LABEL_abl-a&SLOT_a
      Device Flags:       • Internal device
                          • System requires external power source
                          • Needs a reboot after installation
                          • Cryptographic hash verification is available
                          • Updatable
                          • Signed Payload

Note: only the currently active slot will be displayed, e.g. if you want to check if abl_b is supported, you need to boot with Slot B being active.

You can then take the GUID and place it into your metainfo.xml.

See also