Safely Inspect and Connect an MBIM Modem with mbimcli

A modem that will not get online is far less mysterious once mbimcli lets you query it directly instead of guessing. You will use it to identify an MBIM modem, inspect its radio and registration state, and start or stop one data session without reaching for unsupported options. Allow about 15 minutes for a modem that is already attached to the host. The examples use /dev/cdc-wdm0 as a placeholder; swap in the device path that exists on your machine.

1. Check the installed command and device path

This guide follows the installed mbimcli 1.31.2 from the libmbim-utils package. Its October 2025 manual page lists the Basic Connect commands used here. The exact response still depends on the modem firmware, SIM, network and MBIM features it exposes.

$ mbimcli --version
mbimcli 1.31.2
$ command -v mbimcli
/usr/bin/mbimcli
$ ls -l /dev/cdc-wdm0

If the last command fails, find the actual character device before doing anything else:

$ ls -l /dev/cdc-wdm*

Reading modem state normally needs no root shell, provided your account can already open the device. Do not add sudo automatically. If the device exists but access is denied, check its group and your own group membership, then fix the host's device permissions through its normal policy.

2. Query capabilities without changing state

Start with a read-only capability query. --device selects the MBIM device, while --query-device-caps asks the modem what it supports:

$ mbimcli --device=/dev/cdc-wdm0 --query-device-caps

Expect a response with modem-specific details such as device identifiers and supported services. Do not copy one particular response into a script as if it were universal. If the command cannot open the device, check the path and permissions first. If it opens but reports an unsupported operation, keep the error and treat the modem's supported services as your boundary.

For a modem managed through the shared proxy, add --device-open-proxy:

$ mbimcli --device=/dev/cdc-wdm0 --device-open-proxy --query-device-caps

Stick to one opening method while diagnosing a device. The proxy option requests mbim-proxy; it does not install or start that service for you.

Checkpoint: confirm the modem is usable

• mbimcli --version reports the installed version.
• The selected device path exists and your account can open it.
• The capability query returns a modem response rather than a path or permission error.

3. Read radio, SIM and registration state

These queries are safe starting points because they do not request a network session or change the modem. Run them separately so a failure identifies one operation clearly.

$ mbimcli --device=/dev/cdc-wdm0 --query-radio-state
$ mbimcli --device=/dev/cdc-wdm0 --query-pin-state
$ mbimcli --device=/dev/cdc-wdm0 --query-subscriber-ready-status
$ mbimcli --device=/dev/cdc-wdm0 --query-registration-state
$ mbimcli --device=/dev/cdc-wdm0 --query-signal-state
$ mbimcli --device=/dev/cdc-wdm0 --query-packet-service-state

Use the responses to tell common problems apart. A radio that is off is not the same as a SIM waiting for a PIN, and both differ from a modem that is powered and registered but has no packet service. The field names and values come from the modem itself, so record the complete response if you need to ask an operator or vendor for help.

4. Register and attach only when required

If the modem is not registered, --register-automatic asks it to launch automatic registration. If the packet service is not attached, --attach-packet-service requests an attachment. Both actions affect the modem's network state and can take time.

$ mbimcli --device=/dev/cdc-wdm0 --register-automatic
$ mbimcli --device=/dev/cdc-wdm0 --query-registration-state
$ mbimcli --device=/dev/cdc-wdm0 --attach-packet-service
$ mbimcli --device=/dev/cdc-wdm0 --query-packet-service-state

Run the attach command only after checking the current state. A failure can mean no coverage, a blocked subscription, an unavailable data service, or a modem-specific limitation. Do not retry it in a tight loop while troubleshooting.

5. Connect one data session with explicit values

--connect takes a quoted comma-separated list of key=value fields. The manual allows session-id, access-string, ip-type, auth, username, password, compression and context-type. The operator or SIM provider has to supply the access string and any credentials. Do not paste real credentials into shell history or shared tickets.

$ mbimcli --device=/dev/cdc-wdm0 --connect="session-id=0,access-string=YOUR_APN,ip-type=ipv4v6"

This requests session 0 with an example access point name. Replace YOUR_APN with the value for your service. Add authentication fields only when the provider requires them, and treat the command line as sensitive whenever it contains a username or password.

After a successful response, query the session and its IP settings:

$ mbimcli --device=/dev/cdc-wdm0 --query-connection-state=0
$ mbimcli --device=/dev/cdc-wdm0 --query-ip-configuration=0
$ mbimcli --device=/dev/cdc-wdm0 --query-packet-statistics

A connected MBIM session is not the same thing as a configured host network interface. NetworkManager, ModemManager or another network service may own that next step. Avoid configuring the same interface from two managers, because they can disconnect or overwrite each other's state.

6. Disconnect and recover cleanly

Disconnecting is state-changing but reversible: it just ends the selected data session. Use the same session ID you connected with, since session 0 is the documented default when no ID is supplied.

$ mbimcli --device=/dev/cdc-wdm0 --disconnect=0
$ mbimcli --device=/dev/cdc-wdm0 --query-connection-state=0

If a command fails after changing state, query the state before retrying. That avoids creating a second session or repeatedly sending an operation whose first attempt actually succeeded. If the device becomes unresponsive, stop competing modem managers before investigating, and use the host's normal service recovery procedure rather than power-cycling hardware repeatedly.

For diagnostics, --verbose adds debug logging. --verbose-full also includes personal information, so keep it to a controlled terminal and redact its output before sharing it. --silent suppresses even error and warning logs, which makes it a poor choice while you are diagnosing a failure.