Safely Stage a QMI Modem Firmware Update with qmi-firmware-update

You will finish with a checked set of modem images, an explicit device selection, and a command suited to your modem's current mode. The installed tool is qmi-firmware-update 1.35.2 from libqmi-utils 1.35.2-0ubuntu2.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Confirm the installed tool
2. Verify images before touching the modem
3. Identify one modem unambiguously
4. Run a normal-mode update
5. Use download mode only when the model requires it
6. Keep diagnostics separate from overrides

Allow 20 to 40 minutes, excluding any download time. You need the modem vendor's exact image files and release instructions, a QMI-capable Linux host, and permission to interrupt the modem. Most update commands need sudo. Read the vendor notes first: the examples below show the tool's syntax, not a substitute for a supported image package.

Warning

An update can disconnect the modem and can leave it unusable if the images, device, power or mode are wrong. Keep stable power connected, stop services that depend on the modem, and make sure you have another way into the host. There is no general undo command. Recovery normally means repeating the vendor's download-mode procedure with a known-good image.

1. Confirm the installed tool

Start with read-only checks. These do not need elevated privileges:

$ command -v qmi-firmware-update
/usr/bin/qmi-firmware-update
$ dpkg-query -W -f='${Package} ${Version}\n' libqmi-utils
libqmi-utils 1.35.2-0ubuntu2
$ qmi-firmware-update --version
qmi-firmware-update 1.35.2

The local manpage is dated March 2024 and documents this 1.35.2 build. Option details can differ between libqmi releases, so keep the installed version in any troubleshooting report.

Checkpoint

If the command is missing, stop here and install the distribution package through your normal change process. Do not download a replacement binary in the middle of a modem recovery.

2. Verify images before touching the modem

Use --verify for a non-flashing image check. It accepts one or more firmware files and does not select or reset a device:

$ qmi-firmware-update --verify \
    /path/to/MODEM_SYSTEM.cwe \
    /path/to/MODEM_CARRIER.nvu

Add --verbose if you need diagnostics:

$ qmi-firmware-update --verbose --verify /path/to/MODEM_IMAGE.spk

A successful run should return status 0. The exact messages depend on the image format and this build. A non-zero status means the files are not ready for the update; check that the files are complete, readable and intended for the same modem family. Do not treat a successful format check as proof that the image is compatible with your hardware.

Some vendor packages contain a pair of images, such as a system image and a carrier-specific image. The installed help examples show .cwe plus .nvu, or a combined .spk. Use the package's supplied combination and order. Do not mix files from different releases because their names look similar.

3. Identify one modem unambiguously

Choose one device selector. An explicit QMI control path is usually easiest when you already know it:

$ ls -l /dev/cdc-wdm0
$ sudo qmi-firmware-update --verify /path/to/MODEM_SYSTEM.cwe

The first command is only a presence check. Image verification does not need a modem. For an actual operation, select the control path with --cdc-wdm /dev/cdc-wdm0. Alternatively use --vid-pid VID:PID in hexadecimal or --busnum-devnum BUS:DEV in decimal. The manpage warns that a VID and PID match can fail when more than one device has that identity.

Record the selector and the image filenames before proceeding. Do not rely on a path that may move after reconnecting the modem, and do not use a broad selector when several modems are attached.

Checkpoint

The command should name exactly one physical modem. If you cannot prove that, disconnect other modems or use the explicit path and stop before adding --update.

4. Run a normal-mode update

Use normal mode when the modem is running and the vendor's package expects the updater to request the transition. This changes device state and needs elevated privileges:

$ sudo qmi-firmware-update \
    --update \
    --cdc-wdm /dev/cdc-wdm0 \
    /path/to/MODEM_SYSTEM.cwe \
    /path/to/MODEM_CARRIER.nvu

For a device that requires explicit firmware, configuration and carrier identifiers, add values supplied by the vendor:

$ sudo qmi-firmware-update \
    --update \
    --vid-pid 1199:68c0 \
    --firmware-version 05.05.58.00 \
    --config-version 005.025_002 \
    --carrier Generic \
    /path/to/SYSTEM.cwe \
    /path/to/CARRIER.nvu

The values above are the format used by the installed help examples, not universal values. Replace them only with identifiers documented for your exact release. The updater may reboot the modem, change its USB interfaces and take several minutes. Do not unplug it because progress appears quiet.

When the command returns, check its status and wait for the modem to re-enumerate:

$ printf 'update exit status: %s\n' "$?"
update exit status: 0
$ ls -l /dev/cdc-wdm0

Status 0 means the command reported success. It does not identify the installed firmware by itself. Confirm the modem's firmware with the vendor's supported query tool, such as the relevant qmicli operation, after the device is back. If the path does not return, inspect journalctl -k and the updater's verbose log before repeating anything.

5. Use download mode only when the model requires it

Download mode is a separate workflow. The installed program supports --reset to request download mode and --update-download to flash while the modem is already there. Both can interrupt service and need sudo.

Only use the reset form when the vendor's instructions say this device supports it:

$ sudo qmi-firmware-update \
    --vid-pid 1199:68a2 \
    --reset

Wait for the download-mode serial device to appear, then use the path reported by ls or udevadm:

$ ls -l /dev/ttyUSB*
$ sudo qmi-firmware-update \
    --tty /dev/ttyUSB0 \
    --update-download \
    /path/to/MODEM_IMAGE.cwe

Do not guess the serial path or substitute --update for --update-download. Some models enter download mode through a manual QMI or AT sequence instead. Follow the model-specific recovery instructions, then give this tool the mode and selector it documents.

If the update fails, leave the modem powered as instructed by the vendor and save the terminal output. Re-run verification on the original files, confirm the device identity, and use the vendor's recovery procedure. Do not add --ignore-version-errors or --skip-validation merely to force progress: those options remove safeguards.

6. Keep diagnostics separate from overrides

Use --verbose or --verbose-log PATH to capture diagnostics. The latter writes verbose messages to the path you provide:

$ sudo qmi-firmware-update \
    --verbose-log /tmp/qmi-firmware-update.log \
    --update \
    --cdc-wdm /dev/cdc-wdm0 \
    /path/to/MODEM_IMAGE.spk

Protect logs if they contain device identifiers. The options --override-download, --modem-storage-index and --ignore-version-errors change decision-making; use them only when the modem vendor explicitly requires the matching value. --skip-validation avoids waiting for post-update validation, so it is a poor default for a first attempt.

Done means

The installed version is recorded as qmi-firmware-update 1.35.2.
Every image was verified before an update was attempted.
The selector identifies one intended modem, not a class of devices.
The normal or download-mode command matches the vendor's model-specific procedure.
The update returned status 0 and the modem reappeared after its reset.
You have a recovery path and saved diagnostics if the modem does not return.