Inspect a QMI Modem Safely with qmicli

qmicli talks to a QMI modem directly, and it is easy to reach for a start-network or reset option before you have even confirmed the device path. This guide builds a small, repeatable workflow for identifying a modem, checking its model and radio state, and reading packet-service information without changing anything. The examples match qmicli 1.35.2 from the Debian package libqmi-utils 1.35.2-0ubuntu2.

Allow about fifteen minutes. You need a Linux host with qmicli installed, a modem exposed as a QMI character device or QRTR URI, and permission to open it. Most inspection commands are ordinary user commands. Access to a device such as /dev/cdc-wdm0 may be restricted by udev, so use sudo only when the device permissions require it.

Safety boundary: this guide stays with read-only checks. Options that start a data connection, alter SIM protection, change profiles, reset services, select firmware or switch slots can affect connectivity or device state. Do not paste those options into a production modem until you have recorded the current settings and a recovery plan.

1. Confirm the installed qmicli

Check the executable and package before relying on an option. This does not open a modem:

$ command -v qmicli
/usr/bin/qmicli
$ qmicli --version
qmicli 1.35.2
Copyright (C) 2012-2023 Aleksander Morgado
License GPLv2+: GNU GPL version 2 or later <http://gnu.org/licenses/gpl-2.0.html>
$ dpkg-query -W -f='${Package} ${Version}\n' libqmi-utils
libqmi-utils 1.35.2-0ubuntu2

The installed manpage is generated from qmicli 1.35.2 and groups options by QMI service. Ask the binary for the same groups when you need a concise local reference:

$ qmicli --help-dms
$ qmicli --help-nas
$ qmicli --help-wds

Checkpoint: if qmicli --version is not 1.35.2, keep the installed output as the authority. Options and output details can differ between libqmi releases.

2. Find the modem device

qmicli accepts a device path with -d or --device. The manual also documents QRTR URIs such as qrtr://0. Look for device nodes first, without changing anything:

$ printf '%s\n' /dev/cdc-wdm* /dev/qcqmi*
/dev/cdc-wdm0
$ ls -l /dev/cdc-wdm0
crw-rw---- 1 root plugdev 180, 176 Sep 26 09:15 /dev/cdc-wdm0

The path is host-specific. If the glob prints itself, that pattern matched no file. Check how the modem was enumerated, and do not substitute a serial or network interface just because its name contains a similar number. A QMI control endpoint is normally a cdc-wdm device, but the driver and hardware can vary.

Set a shell variable once you have confirmed the path. Quoting it makes the boundary clear:

$ QMI_DEVICE=/dev/cdc-wdm0
$ test -r "$QMI_DEVICE" && test -w "$QMI_DEVICE" && echo 'device permissions look usable'
device permissions look usable

If the permission test fails, ask an administrator to fix the udev or group policy, or run only the specific read-only command with sudo. Do not make broad permission changes merely to get a diagnostic.

3. Identify the modem with DMS

The Device Management Service options are a good first query. Request the manufacturer, model and firmware revision separately so a failure tells you which part is unavailable:

$ qmicli --device="$QMI_DEVICE" --dms-get-manufacturer
$ qmicli --device="$QMI_DEVICE" --dms-get-model
$ qmicli --device="$QMI_DEVICE" --dms-get-revision

These print values supplied by the modem, so the text will differ by hardware. A successful query should return a manufacturer, model or revision and exit with status zero. Capture the result in your notes, but treat identifiers and firmware strings as inventory data rather than proof that the modem is ready for a data session.

For a broader read-only check, use service and device version information:

$ qmicli --device="$QMI_DEVICE" --get-service-version-info
$ qmicli --device="$QMI_DEVICE" --dms-get-operating-mode

qmicli normally opens a cdc-wdm device in automatic QMI or MBIM mode. If automatic detection is wrong for a known QMI endpoint, the manual provides --device-open-qmi; use it only after confirming the endpoint and driver. --device-open-proxy requests the qmi-proxy service, which can be useful when several processes need coordinated access, but it does not repair a missing or unsuitable device.

4. Check SIM and radio state without changing it

Read the UIM status before attempting any SIM operation. The status query does not verify a PIN, alter PIN protection or reveal the PIN itself:

$ qmicli --device="$QMI_DEVICE" --uim-get-card-status
$ qmicli --device="$QMI_DEVICE" --dms-uim-get-pin-status

Warning: do not put a real PIN, PUK or control key into a shell history entry. The manpage lists options for verifying, changing and unblocking PINs, but those are security-sensitive operations with lockout consequences. Stop if the card reports that a PIN or PUK is required and use the carrier or device owner's documented recovery process.

Read radio information through the NAS service:

$ qmicli --device="$QMI_DEVICE" --nas-get-signal-strength
$ qmicli --device="$QMI_DEVICE" --nas-get-serving-system
$ qmicli --device="$QMI_DEVICE" --nas-get-system-info

Signal strength and serving-system fields are modem and network dependent. A weak signal, no service or a roaming indication is a result to investigate, not a reason to run --nas-force-network-search immediately. A forced search can take time and can disturb an active connection.

5. Inspect packet service and profiles

Before touching data connectivity, establish whether the modem already has packet service and what profiles exist:

$ qmicli --device="$QMI_DEVICE" --wds-get-packet-service-status
$ qmicli --device="$QMI_DEVICE" --wds-get-current-settings
$ qmicli --device="$QMI_DEVICE" --wds-get-profile-list=3gpp
$ qmicli --device="$QMI_DEVICE" --wds-get-default-profile-number=3gpp

The profile list and default number are modem state, so save them before any maintenance work. A profile can contain an APN, authentication mode, username or password, so protect captured output and avoid putting it in a ticket or public log.

Warning: do not confuse inspection with activation. --wds-start-network starts a packet-data session and accepts values such as an APN, authentication mode, username, password and IP type; it can incur charges, alter routing and interrupt an existing setup. --wds-stop-network stops a session, and --wds-create-profile, --wds-modify-profile and --wds-delete-profile change persistent modem configuration. Those commands are deliberately absent from the copy-and-paste workflow above.

6. Diagnose failures without hiding useful evidence

When a query fails, rerun it without --silent. qmicli's default warnings and errors often distinguish a bad path, a permission problem, an unsupported service or a modem that is busy. Add --verbose for protocol-level diagnostics:

$ qmicli --device="$QMI_DEVICE" --verbose --dms-get-model
$ printf 'exit status: %s\n' "$?"
exit status: 0

Warning: the verbose trace can contain device-specific information. Do not use --verbose-full on output you plan to share: the manual says it includes personal information. Redact subscriber identifiers, SIM identifiers, phone numbers, APNs and credentials before storing logs.

If the device is absent, check the exact path and kernel enumeration first:

$ test -e "$QMI_DEVICE" && echo present || echo missing
$ lsusb
$ journalctl -k -b | tail -n 80

If the device exists but qmicli reports that it cannot open it, compare ls -l permissions with your groups, then check whether another modem manager owns the endpoint. Do not repeatedly reset the modem or kill unrelated services while an active mobile-broadband connection may be carrying traffic.

Done means