usb_modeswitch - control the mode of ’multi-state’ USB devices


usb_modeswitch [−heWQDIvpVPmM23rwKdHSOBGTNALnsRiuagft] [−c filename]


Several new USB devices have their proprietary Windows drivers onboard, most of them WWAN and WLAN dongles. When plugged in for the first time, they act like a flash storage and start installing the Windows driver from there. If the driver is already installed, it makes the storage device disappear and a new device, mainly composite with modem ports, shows up.

On Linux, in most cases the drivers are available as kernel modules, such as "usbserial" or "option". However, the device initially binds to "usb-storage" by default. usb_modeswitch can then send a provided bulk message (most likely a mass storage command) to the device; this message has to be determined by analyzing the actions of the Windows driver.

In some cases, USB control commands are used for switching. These cases are handled by custom functions, and no bulk message needs to be provided.

Usually, the program is distributed with a set of configurations for many known devices, which allows a fully automatic handling of a device upon insertion, made possible by combining usb_modeswitch with the wrapper script usb_modeswitch_dispatcher which is launched by the udev daemon.

Note that usb_modeswitch itself has no specific Linux dependencies.


This program follows the usual GNU command line syntax, with long options starting with two dashes (’--’). A summary of options is included below.

-h −−help

Show summary of options.

-e −−version

Print version information and exit

-v −−default-vendor NUM

Vendor ID to look for (mandatory), usually given as hex number (example: 0x12d1). Each USB device is identified by a number officialy assigned to the vendor by the USB association and a number for the respective model (product ID) chosen by the vendor

-p −−default-product NUM

Product ID to look for (mandatory)

-V −−target-vendor NUM

Target vendor ID. When given will be searched for and detected initially for information purposes. If success checking (option −s) is active, providing target IDs (vendor/product) or target class is recommended

-j −−find-mbim

Return configuration number with MBIM interface and exit.

-P −−target-product NUM

Target product ID

-b −−bus-num NUM
-g −−device-num NUM

If bus and device number are provided, the handling of a specific device on a specific USB port is guaranteed, in contrast to using only the USB ID. This is important if there are multiple similar devices on a system

-C −−target-class NUM

Target Device Class according to the USB specification. Some devices keep their original vendor/product ID after successful switching. To prevent them from being treated again, the device class can be checked. For unswitched devices it is always 8 (storage class), for switched modems it is often 0xff (vendor specific). In composite modes, the class of the first interface is watched

-m −−message-endpoint NUM

A specific endpoint to use for data transfers. Only for testing purposes; usually endpoints are determined from the device attributes

-M −−message-content STRING

A bulk message to send as a switching command. Provided as a hexadecimal string

-2, -3 −−message-content2, −−message-content3 STRING

Additional bulk messages to send as switching commands. Provided as hexadecimal strings. When used with mass storage commands, setting −−need-response is strongly advised to comply with specifications and to avoid likely errors

-w −−release-delay NUM

After issuing all bulk messages, wait for NUM milliseconds before releasing the interface. Required for some modems on older systems (especially after an EJECT message)

-n −−need-response

Read the response (command status wrapper) to a mass storage command transfer. Some devices have trouble switching if the response is not read; most are disappearing right away. When sending multiple mass storage commands with −2 and −3, this may need to be set to avoid transfer errors

-r −−response-endpoint NUM

Try to read the response to a storage command from there if option −n is active. Only for testing purposes; usually endpoints are determined from the device attributes

-K −−std-eject

Apply the standard SCSI sequence of "Allow Medium Removal" and "Eject". Implies -n. One ’Message’ can be added with -M that will be transmitted after the eject sequence

-d −−detach-only

Just detach the current driver. This is sufficient for some early devices to switch successfully. Otherwise this feature can be used as a ’scalpel’ for special cases, like separating the driver from individual interfaces

-H −−huawei-mode

Send a special control message used by older Huawei devices

-S −−sierra-mode

Send a special control message used by Sierra devices

-G −−gct-mode

Send a special control message used by GCT chipsets

-T −−kobil-mode

Send a special control message used by Kobil devices

-N −−sequans-mode

Send a special control message used by Sequans chipset

-A −−mobileaction-mode

Send a special control message used by the MobileAction device

-B −−qisda-mode

Send a special control message used by Qisda devices

-E −−quanta-mode

Send a special control message used by Quanta devices

-F −−pantech-mode

Send a special control message used by Pantech devices

-Z −−blackberry-mode

Send a special control message used by some newer Blackberry devices

-O −−sony-mode

Apply a special sequence used by Sony Ericsson devices. Implies option −-check-success

-L −−cisco-mode

Send a sequence of bulk messages used by Cisco devices

-R −−reset-usb

Send a USB reset command to the device. Can be combined with any switching method or stand alone. It is always done as the last step of all device interactions. Few devices need it to complete the switching; apart from that it may be useful during testing

-c −−config-file FILENAME

Use a specific config file. If any ID or switching options are given as command line parameters, this option is ignored. In that case all mandatory parameters have to be provided on the command line

-f −−long-config STRING

Provide device details in config file syntax as a multiline string on the command line

-t −−stdinput

Read the device details in config file syntax from standard input, e.g. redirected from a command pipe (multiline text)

-Q −−quiet

Don’t show progress or error messages

-W −−verbose

Print all settings before running and show libusb debug messages

-D −−sysmode

Changes the behaviour of the program slightly. A success message including the effective target device ID is put out and a syslog notice is issued. Mainly for integration with a wrapper script

-s −−check-success NUM

After switching, keep checking for the result up to max. NUM seconds. If target IDs or target class were provided, their appearance indicates certain success. Otherwise the disconnection of the original device is rated as likely proof

-I −−no-inquire

do not obtain SCSI attributes from device (default is on). For proper identification of differing devices the attributes of the storage part provide valuable information. This is not needed for devices that are known and supported

-i −−interface NUM

Select initial USB interface (default: 0). Only for testing purposes

-u −−configuration NUM

Select USB configuration (applied after any other possible switching actions)

-a −−altsetting NUM

Select alternative USB interface setting (applied after switching). Mainly for testing


This manual page was originally written by Didier Raboud ( for the Debian system. Additions made by Josua Dietze. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 or any later version published by the Free Software Foundation.

The complete text of the current GNU General Public License can be found in

More Linux Commands

fmemopen(3) - open memory as stream - Linux manual page.....
The fmemopen() function opens a stream that permits the access specified by mode. The stream allows I/O to be performed on the string or memory buffer pointed t

fsck.ext4(8) - check a Linux ext2/ext3/ext4 file system.....
e2fsck is used to check the ext2/ext3/ext4 family of file systems. For ext3 and ext4 filesystems that use a journal, if the system has been shut down uncleanly

cabsf(3) - absolute value of a complex number (Man Page)....
The cabs() function returns the absolute value of the complex number z. The result is a real number. VERSIONS These functions first appeared in glibc in version

pam_deny(8) - The locking-out PAM module - Linux man page...
This module can be used to deny access. It always indicates a failure to the application through the PAM framework. It might be suitable for using for default (

Tk_GetUserInactiveTime(3) - discover user inactivity time...
Tk_GetUserInactiveTime returns the number of milliseconds that have passed since the last user interaction (usually via keyboard or mouse) with the respective d

pamstretch(1) - scale up a PNM or PAM image by interpolating
This program is part of Netpbm(1) pamstretch scales up pictures by integer values, either vertically, horizontally, or both. pamstretch differs from pamscale an

bsearch(3) - binary search of a sorted array (Man Page).....
The bsearch() function searches an array of nmemb objects, the initial member of which is pointed to by base, for a member that matches the object pointed to by

SDL_GetRelativeMouseState(3) - Retrieve the current state of
The current button state is returned as a button bitmask, which can be tested using the SDL_BUTTON(X) macros, and x and y are set to the change in the mouse pos

Tcl_StandardChannels(3) - How the Tcl library deals with the
This page explains the initialization and use of standard channels in the Tcl library. The term standard channels comes out of the Unix world and refers to the

Tcl_SetEnsembleFlags(3) - manipulate ensemble commands......
An ensemble is a command, bound to some namespace, which consists of a collection of subcommands implemented by other Tcl commands. The first argument to the en

glGetMaterialiv(3gl) - return material parameters (ManPage)
glGetMaterial returns in params the value or values of parameter pname of material face. Six parameters are defined: GL_AMBIENT params returns four integer or f

update-smart-drivedb(8) update smartmontools drive database
update-smart-drivedb updates /usr/share/smartmontools/drivedb.h or DESTFILE from smartmontools SVN repository. It tries to download first from the current branc

We can't live, work or learn in freedom unless the software we use is free.