fwupd/contrib/firmware_packager

Firmware Packager

This script is intended to make firmware updating easier until OEMs upload their firmware packages to the LVFS. It works by extracting the firmware binary contained in a Microsoft .exe file (intended for performing the firmware update from a Windows system) and repackaging it in a cab file usable by fwupd. The cab file can then be install using fwupdmgr install

Prerequisites

To run this script you will need

1. Python3.5, a standard install should include all packages you need
2. 7z (for extracting .exe files)
3. gcab (for creating the cab file)

Usage

To create a firmware package, you must supply, at a minimum:

1. A string ID to name the firmware (--firmware-id). You are free to choose this, but fwupd.org recommends using "a reverse-DNS prefix similar to java" and to "always use a .firmware suffix" (e.g. net.queuecumber.DellTBT.firmware)
2. A short name for the firmware package, again you are free to choose this (--firmware-name).
3. The unique ID of the device that the firmware is intended for (--device-unique-id). This must match the unique ID from fwupdmgr get-devices
4. The firmware version (--release-version), try to match the manufacturers versioning scheme
5. The path to the executable file to repackage (--exe)
6. The path relative to the root of the exe archive of the .bin file to package (--bin). Use 7z or archive-manager to inspect the .exe file and find this path. For example, if I want to package dell-thunderbolt-firmware.exe and I open the .exe with archive-manager and find that Intel/tbt.bin is the path to the bin file inside the archive, I would pass --exe dell-thunderbolt-firmware.exe --bin Intel/tbt.bin
7. The path to the cab file to output (--out).

Documentation

--firmware-name Short name of the firmware package can be customized (e.g. DellTBT) REQUIRED

--firmware-summary One line description of the firmware package (e.g. Dell thunderbolt firmware)

--firmware-description Longer description of the firmware package. Theoretically this can include HTML but I haven't tried it

--device-guid GUID ID of the device this firmware will run on, this must match the output from fwupdmgr get-devices (e.g. 72533768-6a6c-5c06-994a-367374336810) REQUIRED

--firmware-homepage Website for the firmware provider (e.g. http://www.dell.com)

-contact-info Email address of the firmware developer (e.g. someone@something.net)

--developer-name Name of the firmware developer (e.g. Dell) REQUIRED

--release-version Version number of the firmware package (e.g. 4.21.01.002) REQUIRED --release-description Description of the firmware release, again this can theoretically include HTML but I didn't try it.

--exe Executable file to extract firmware from (e.g. dell-thunderbolt-firmware.exe) REQUIRED

--bin Path to the .bin file inside the executable to use as the firmware image', relative to the root of the archive (e.g. Intel/tbt.bin) REQUIRED

--out Output cab file path (e.g. updates/firmware.cab) REQUIRED

Example

Let's say we downloaded Intel_TBT3_FW_UPDATE_NVM21_318RY_A01_4.21.01.002.exe (available here) containing updated firmware for Dell laptops thunderbolt controllers. Since Dell hasn't made this available on the LVFS yet, we want to package and install it ourselves.

Opening the .exe with archive manager, we see it has a single folder: Intel and inside that, a set of firmware binaries (along with some microsoft junk). We pick the file 0x07BE_secure.bin since we have a Dell XPS 9560 and that is its device string.

Next we use fwupdmgr to get the device ID for the thunderbolt controller:

$ fwupdmgr get-devices
Thunderbolt Controller
  Guid:                 72533768-6a6c-5c06-994a-367374336810
  DeviceID:             08001575
  Plugin:               thunderbolt
  Flags:                internal|allow-online
  DeviceVendor:         Intel
  Version:              21.00
  Created:              2017-08-16

The GUID field contains what we are looking for

We can then run the firmware-packager with the following arguments:

$ firmware-packager --firmware-id net.queuecumber.DellTBT.firmware --firmware-name DellTBT --device-unique-id 72533768-6a6c-5c06-994a-367374336810 --release-version 4.21.01.002 --exe ~/Downloads/Intel_TBT3_FW_UPDATE_NVM21_318RY_A01_4.21.01.002.exe --bin Intel/0x07BE_secure.bin --out firmware.cab
Using temp directory /tmp/tmpoey6_zx_
Extracting firmware exe
Locating firmware bin
Creating metainfo
Cabbing firmware files
Done

And we should have a firmware.cab that contains the packaged firmware. We can then install this firmware with

$ fwupdmgr install firmware.cab