DW5821e firmware update integration in ModemManager and fwupd

The Dell Wireless 5821e module is a Qualcomm SDX20 based LTE Cat16 device. This modem can work in either MBIM mode or QMI mode, and provides different USB layouts for each of the modes. In Linux kernel based and Windows based systems, the MBIM mode is the default one, because it provides easy integration with the OS (e.g. no additional drivers or connection managers required in Windows) and also provides all the features that QMI provides through QMI over MBIM operations.

The firmware update process of this DW5821e module is integrated in your GNU/Linux distribution, since ModemManager 1.10.0 and fwupd 1.2.6. There is no official firmware released in the LVFS (yet) but the setup is completely ready to be used, just waiting for Dell to publish an initial official firmware release.

The firmware update integration between ModemManager and fwupd involves different steps, which I’ll try to describe here so that it’s clear how to add support for more devices in the future.

1) ModemManager reports expected update methods, firmware version and device IDs

The Firmware interface in the modem object exposed in DBus contains, since MM 1.10, a new UpdateSettings property that provides a bitmask specifying which is the expected firmware update method (or methods) required for a given module, plus a dictionary of key-value entries specifying settings applicable to each of the update methods.

In the case of the DW5821e, two update methods are reported in the bitmask: “fastboot” and “qmi-pdc“, because both are required to have a complete firmware upgrade procedure. “fastboot” would be used to perform the system upgrade by using an OTA update file, and “qmi-pdc” would be used to install the per-carrier configuration files after the system upgrade has been done.

The list of settings provided in the dictionary contain the two mandatory fields required for all devices that support at least one firmware update method: “device-ids” and “version”. These two fields are designed so that fwupd can fully rely on them during its operation:

  • The “device-ids” field will include a list of strings providing the device IDs associated to the device, sorted from the most specific to the least specific. These device IDs are the ones that fwupd will use to build the GUIDs required to match a given device to a given firmware package. The DW5821e will expose four different device IDs:
    • “USB\VID_413C“: specifying this is a Dell-branded device.
    • “USB\VID_413C&PID_81D7“: specifying this is a DW5821e module.
    • “USB\VID_413C&PID_81D7&REV_0318“: specifying this is hardware revision 0x318 of the DW5821e module.
    • “USB\VID_413C&PID_81D7&REV_0318&CARRIER_VODAFONE“: specifying this is hardware revision 0x318 of the DW5821e module running with a Vodafone-specific carrier configuration.
  • The “version” field will include the firmware version string of the module, using the same format as used in the firmware package files used by fwupd. This requirement is obviously very important, because if the format used is different, the simple version string comparison used by fwupd (literally ASCII string comparison) would not work correctly. It is also worth noting that if the carrier configuration is also versioned, the version string should contain not only the version of the system, but also the version of the carrier configuration. The DW5821e will expose a firmware version including both, e.g. “T77W968.F1.” (system version being F1. and carrier config version being “VF.001”)
  • In addition to the mandatory fields, the dictionary exposed by the DW5821e will also contain a “fastboot-at” field specifying which AT command can be used to switch the module into fastboot download mode.

2) fwupd matches GUIDs and checks available firmware versions

Once fwupd detects a modem in ModemManager that is able to expose the correct UpdateSettings property in the Firmware interface, it will add the device as a known device that may be updated in its own records. The device exposed by fwupd will contain the GUIDs built from the “device-ids” list of strings exposed by ModemManager. E.g. for the “USB\VID_413C&PID_81D7&REV_0318&CARRIER_VODAFONE” device ID, fwupd will use GUID “b595e24b-bebb-531b-abeb-620fa2b44045”.

fwupd will then be able to look for firmware packages (CAB files) available in the LVFS that are associated to any of the GUIDs exposed for the DW5821e.

The CAB files packaged for the LVFS will contain one single firmware OTA file plus one carrier MCFG file for each supported carrier in the give firmware version. The CAB files will also contain one “metainfo.xml” file for each of the supported carriers in the released package, so that per-carrier firmware upgrade paths are available: only firmware updates for the currently used carrier should be considered. E.g. we don’t want users running with the Vodafone carrier config to get notified of upgrades to newer firmware versions that aren’t certified for the Vodafone carrier.

Each of the CAB files with multiple “metainfo.xml” files will therefore be associated to multiple GUID/version pairs. E.g. the same CAB file will be valid for the following GUIDs (using Device ID instead of GUID for a clearer explanation, but really the match is per GUID not per Device ID):

  • Device ID “USB\VID_413C&PID_81D7&REV_0318&CARRIER_VODAFONE” providing version “T77W968.F1.”
  • Device ID “USB\VID_413C&PID_81D7&REV_0318&CARRIER_TELEFONICA” providing version “T77W968.F1.”
  • Device ID “USB\VID_413C&PID_81D7&REV_0318&CARRIER_VERIZON” providing version “T77W968.F1.”
  • … and so on.

Following our example, fwupd will detect our device exposing device ID “USB\VID_413C&PID_81D7&REV_0318&CARRIER_VODAFONE” and version “T77W968.F1.” in ModemManager and will be able to find a CAB file for the same device ID providing a newer version “T77W968.F1.” in the LVFS. The firmware update is possible!

3) fwupd requests device inhibition from ModemManager

In order to perform the firmware upgrade, fwupd requires full control of the modem. Therefore, when the firmware upgrade process starts, fwupd will use the new InhibitDevice(TRUE) method in the Manager DBus interface of ModemManager to request that a specific modem with a specific uid should be inhibited. Once the device is inhibited in ModemManager, it will be disabled and removed from the list of modems in DBus, and no longer used until the inhibition is removed.

The inhibition may be removed by calling InhibitDevice(FALSE) explicitly once the firmware upgrade is finished, and will also be automatically removed if the program that requested the inhibition disappears from the bus.

4) fwupd downloads CAB file from LVFS and performs firmware update

Once the modem is inhibited in ModemManager, fwupd can right away start the firmware update process. In the case of the DW5821e, the firmware update requires two different methods and two different upgrade cycles.

The first step would be to reboot the module into fastboot download mode using the AT command specified by ModemManager in the “at-fastboot” entry of the “UpdateSettings” property dictionary. After running the AT command, the module will reset itself and reboot with a completely different USB layout (and different vid:pid) that fwupd can detect as being the same device as before but in a different working mode. Once the device is in fastboot mode, fwupd will download and install the OTA file using the fastboot protocol, as defined in the “flashfile.xml” file provided in the CAB file:

<parts interface="AP">
  <part operation="flash" partition="ota" filename="T77W968.F1." MD5="f1adb38b5b0f489c327d71bfb9fdcd12"/>

Once the OTA file is completely downloaded and installed, fwupd will trigger a reset of the module also using the fastboot protocol, and the device will boot from scratch on the newly installed firmware version. During this initial boot, the module will report itself running in a “default” configuration not associated to any carrier, because the OTA file update process involves fully removing all installed carrier-specific MCFG files.

The second upgrade cycle performed by fwupd once the modem is detected again involves downloading all carrier-specific MCFG files one by one into the module using the QMI PDC protocol. Once all are downloaded, fwupd will activate the specific carrier configuration that was previously active before the download was started. E.g. if the module was running with the Vodafone-specific carrier configuration before the upgrade, fwupd will select the Vodafone-specific carrier configuration after the upgrade. The module would be reseted one last time using the QMI DMS protocol as a last step of the upgrade procedure.

5) fwupd removes device inhibition from ModemManager

The upgrade logic will finish by removing the device inhibition from ModemManager using InhibitDevice(FALSE) explicitly. At that point, ModemManager would re-detect and re-probe the modem from scratch, which should already be running in the newly installed firmware and with the newly selected carrier configuration.

Posted on July 3, 2019, in Development, FreeDesktop Planet, GNOME Planet, GNU Planet, Planets and tagged , , , , . Bookmark the permalink. 16 Comments.

  1. Aleksander, thanks for the fantastically informative post–it was really helpful flashing my DW5821e.

    One question: what’s the model number of the M.2 to USB3 board (?) the DW5821e is mounted on in the picture?

  2. No idea, it’s a devkit that was sent to me.

  3. aleksander, would you be able to help me flash my DW5821e? I have very limited linux skills. I was hoping to flash this to the latest generic software.

  4. If using ModemManager and fwupd isn’t an option for you, the best thing you can do is to try to upgrade your module using the Dell-provided Windows firmware update program.

  5. what linux distro would you recommend to do this on?i tried ubuntu but I seem to have no luck. do I need a Dell compatible device (laptop) to make this work under linux? I don’t have a Dell, only an HP machine. I figred this shouldn’t matter under Linux but I could be wrong.

  6. The process was validated at least with Ubuntu 18.04 including this PPA: https://launchpad.net/~aleksander-m/+archive/ubuntu/modemmanager-next but please take into account that the upgrade will only work currently from a F1.0.0.x.x version to F1. If your firmware version is F0.0.0.x.x, this process won’t work properly.

  7. I think I have found my problem why I can’t flash with fwupd. My firmware is F0.
    ☹ now I need a Dell computer.

    Thank you for your help.

  8. F0.0.x.x is not an officially supported firmware, it was a pre-release firmware found on engineering samples :/ the only supported way to upgrade that (if at all possible) would be using the Windows firmware updater utilities for the DW5821e.

  9. What are the 4 antenna leads for?

  10. To be able to connect 4 antennas 😀

  11. Hi Aleksander

    I am in the process of trying to set up a dell DW5821e that i bought used
    After having tried to connect the card through a USB3adapter similar to this https://ltefix.com/shop/pcie-m-2/m-2-ngff/usb3-to-ngff-m-2-key-b-3050-5g-adapter-enclosure-with-sim-card-slot/

    And thereafter use it with a router flashed with openwrt rooter
    It didn\t get recognized, at all
    After several attempts of trying to set it up, it became apparent to me that my card has probably never been set up to begin with, even if used.
    The radio seems turned of and MBIM recognition isn\t happening
    I have tried to check with ubuntu 20. and it didnt show up in fwupdmgr
    I think it is locked and need the dell cuskit as per https://github.com/fwupd/fwupd/issues/2200
    I have no access to dell computers to do this operation over a windows PC, so i delved into how to compile your qimcli repot with dell cuskit, i managed to fumble my way through a lot of dependencies to install this version, only to get stuck at qmicli: symbol lookup error: qmicli: undefined symbol: qmi_message_uim_get_slot_status_output_get_result

    I am afraid i am way in over my head, while it has been a great learning experience, trying to compile a linux program, after creating a ubuntu disk with persistent memory and so on…
    I have to admit, i need some guidance, and help, and i ask kindly for a bit of guidance..

    On how to compile your version of libqmi with dell cuskit operation
    or if need be, how i can give quick ssh access to you in order to test your reverse engineering of the dell cuskit

    Kind regards

  12. I have never been able to unlock a DW5821e with my custom version of the Dell custkit tool :/ We’ve used that tool successfully in the newer SDX55 modules though (by pure luck), not really sure why it’s failing with the SDX20.

    It’s really sad, I worked on the integration of that module in ModemManager and fwupd, just to later learn the modules would come locked, and Dell hasn’t provided any unlock tool to use in Linux based distributions (that I know of) :/ The manufacturers have made it so the DW5821e is supposed to be used only in one set of Dell laptops, not even all, and that’s about it. If you don’t have one of those laptops, they won’t even hear your complain.

    My sad suggestion is that you should look for a different module… :/

  13. mefromthepast

    There has been an update release of the Customer Kit by Dell for their newer systems in January. https://www.dell.com/support/home/de-de/drivers/driversdetails?driverid=hp49x

    I guess that looking at the binary output and comparing it to the older 1.4 may indicate what properties are actually checked, but it’s certainly a very intense undertaking. Still trying to make activate my module from time to time, though.

  14. I just checked this morning the logs you sent me via email some time ago, and couldn’t find a reason why they tool would fail. Note that *the same tool* happened to work with the Foxconn SDX55 in Lenovo laptops, so it’s not like it’s totally wrong, we’re missing something.

  15. mefromthepast

    Glad to do a debugging session some time if you’d like to. Just hit me up.

  16. What a board on thumbnail?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: