Switch a Known USB Modem Safely with usb_modeswitch

Plug in a USB modem and it often shows up as a storage drive, not a modem: usb_modeswitch is what flips it into working mode. This walkthrough moves a supported dongle from its initial storage mode to its working modem mode, then checks that the target device actually appeared. The examples match usb_modeswitch 2.6.1 from Debian package usb-modeswitch 2.6.1-3ubuntu3.

Allow about fifteen minutes, plus time to find the correct device configuration. You need a shell, the usb-modeswitch package, a supported USB device, and elevated privileges for the switch itself. A wrong message can reset, detach or otherwise disrupt a USB device, so do not guess hexadecimal commands from an internet post.

1. Check the installed tool

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

$ command -v usb_modeswitch
/usr/sbin/usb_modeswitch
$ usb_modeswitch --version
 * usb_modeswitch: handle USB devices with multiple modes
 * Version 2.6.1 (C) Josua Dietze 2017

The short and long option spellings are both available. This guide uses long options where they make the command's purpose clearer. The installed manpage is the authority for this machine; another distribution or release may ship a different version and configuration set.

Checkpoint: If the command is missing, stop here and install the distribution package through your normal change process. Do not copy a binary from an unrelated system.

2. Identify the device's initial mode

Read the USB IDs before changing anything. lsusb is an ordinary command and normally needs no privilege:

$ lsusb
Bus 001 Device 004: ID 12d1:1446 Example modem name

Record the four-digit vendor ID and product ID after ID: here they are 12d1 and 1446. The product ID reflects the device's current, initial mode, not necessarily the ID it will have after switching.

Your output will differ. Do not use the example IDs unless lsusb shows the same device. If several identical devices are connected, also record the bus and device numbers, because an ID-only command can select the wrong physical device.

3. Prefer the packaged device configuration

Known devices are normally handled with a configuration supplied by usb-modeswitch-data and the udev dispatcher. This is the safest route because the switching method and message were determined for that device, rather than invented at the shell.

First check whether the data package and dispatcher are present:

$ dpkg-query -W -f='${Package} ${Version}
' usb-modeswitch usb-modeswitch-data
usb-modeswitch 2.6.1-3ubuntu3
usb-modeswitch-data 20191128-6
$ command -v usb_modeswitch_dispatcher
/usr/sbin/usb_modeswitch_dispatcher

If a supported device is inserted, udev may invoke the dispatcher automatically. If it does not, do not jump straight to a custom MessageContent. Check the dispatcher and system logs, the package's device configuration directory, and the exact IDs first: a missing configuration is a compatibility problem, not evidence that an arbitrary mode command will work.

Checkpoint: Unplug the device and reconnect it once after confirming the packaged data is installed. Run lsusb again and note whether its ID changes automatically. If it already changed to the modem mode, no manual switch is needed.

4. Run a documented switch manually

Only do this when you have a known configuration or a vendor-specific procedure that matches the exact device. The manpage accepts a configuration file with --config-file. A configuration file takes precedence only when you do not also provide ID or switching options on the command line.

For a configuration file supplied by your administrator or the package, inspect it first:

$ sed -n '1,160p' /path/to/known-device.conf

Then run it with elevated privileges:

$ sudo usb_modeswitch --config-file /path/to/known-device.conf

Warning: This is the state-changing step. The USB device may disappear briefly, re-enumerate with a new ID, or cause a modem driver to bind. Close applications using the device first. Do not use --reset-usb, --std-eject, a vendor-specific mode option, or a hexadecimal --message-content merely because it appears in a different device's example.

The same tool can accept explicit IDs and a known vendor procedure, but those values must come from the matching device documentation. For example, this shape is valid, but the placeholders are deliberately not runnable:

$ sudo usb_modeswitch \
    --default-vendor 0xVENDOR \
    --default-product 0xPRODUCT \
    --KNOWN-MODE-OPTION

Replace --KNOWN-MODE-OPTION only with a real option documented for your device, such as a matching vendor mode. Do not combine a config file with guessed command-line values: the manpage says command-line IDs or switching options cause the file to be ignored.

5. Ask usb_modeswitch to check success

A command that exits without an obvious error is not enough. Give the tool the expected target ID or device class and ask it to check for up to a defined number of seconds:

$ sudo usb_modeswitch \
    --default-vendor 0xVENDOR \
    --default-product 0xPRODUCT \
    --target-vendor 0xTARGET_VENDOR \
    --target-product 0xTARGET_PRODUCT \
    --check-success 10

Use the real values from the device's known configuration. With target IDs supplied, their appearance is the useful success signal. Without target IDs or a target class, the program treats disconnection of the original device as likely proof, which is weaker because a disconnect can also indicate a fault.

Verify the result independently:

$ lsusb
Bus 001 Device 005: ID TARGET_VENDOR:TARGET_PRODUCT Working modem name

A new bus device number is normal. If the original storage ID remains, switching did not complete. If the target ID appears but the modem application still cannot use it, check kernel messages and the modem driver separately: usb_modeswitch changes the USB mode, it does not configure a mobile connection.

6. Recover from a failed or unwanted switch

Stop retrying if the device repeatedly disconnects, the wrong physical device was selected, or a production service lost its USB interface. Reconnect the device and check lsusb. If it remains in the target mode, there is usually no undo action in usb_modeswitch: switching is device-specific and the tool does not promise a generic reverse operation.

For a temporary test, physically unplugging and reconnecting the device is the least surprising recovery. If udev automatically switches it again, temporarily remove the device from the test host or disable the relevant dispatcher rule through your normal, reversible administration process. Do not edit packaged rules during an incident without recording the change and its rollback.

When multiple devices are present, use the matching --bus-num and --device-num values only after checking fresh lsusb output. Device numbers can change after re-enumeration, so do not reuse an old pair blindly.

Done means