MAN page from OpenSuSE usb_modeswitch-1.2.5-7.5.x86_64.rpm


Section: Misc. Reference Manual Pages (1)


usb_modeswitch - switch mode of "multi-state" USB devices 


usb_modeswitch [-heWQDIvpVPmM23rwdHSOBGTNALnsRiuagft] [-c filename] 


Several new USB devices have their proprietary Windows drivers onboard,most of them WAN dongles. When plugged in for the first time, they actlike a flash storage and start installing the Windows driver from there.If the driver is already installed, it makes the storage device disappearand 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 shows up as"usb-storage" by default. usb_modeswitch can send a provided bulkmessage (most likely a mass storage command) to the device which is knownto initiate the mode switching.

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

Usually, the program is distributed with a set of configurations for manyknown devices, which in combination with a wrapper script launched from theudev daemon allows a fully automatic handling of a device upon insertion.



This program follows the usual GNU command line syntax,with long options starting with two dashes ('--'). A summary ofoptions 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 numberofficialy assigned to the vendor by the USB association and a number for therespective 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 initiallyfor information purposes. If success checking (option -s) is active,providing target IDs (vendor/product) or target class is recommended
-P --target-product NUM
Target product ID
-b --busnum NUM
-g --devnum NUM
If bus and device number are provided, the handling of a specific device ona specific USB port is guaranteed, in contrast to using only the USB ID. Thisis important if there are multiple similar devices on a system
-C --target-class NUM
Target Device Class according to the USB specification. Some devices keeptheir original vendor/product ID after successful switching. To preventthem from being treated again, the device class can be checked.For unswitched devices it is always 8 (storage class), for switchedmodems 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; usuallyendpoints 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 isstrongly 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 commandtransfer.Some devices have trouble switching if the response is not read; mostare disappearing right away. When sending multiple mass storage commandswith -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 thereif option -n is active. Only for testing purposes; usuallyendpoints are determined from the device attributes
-d --detach-only
Just detach the current driver. This is sufficient for some earlydevices to switch successfully. Otherwise this feature canbe used as a 'scalpel' for special cases, like separating thedriver 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
-T --sequans-mode
Send a special control message used by Sequans chipset
-T --mobileaction-mode
Send a special control message used by the MobileAction device
-B --qisda-mode
Send a special control message used by Qisda devices
-O --sony-mode
Apply a special sequence used by Sony Ericsson devices. Implies option --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 switchingmethod or stand alone. It is always done as the last step of all deviceinteractions.Few devices need it to complete the switching; apart from that it may beuseful during testing
-c --config FILENAME
Use a specific config file. If any ID or switching options are given ascommand line parameters, this option is ignored.In that case all mandatory parameters have to be provided onthe command line
-f --long-config STRING
Provide device details in config file syntax as a multiline stringon the command line
-t --stdinput
Read the device details in config file syntax from standard input, e.g. redirected froma 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 theeffective target device ID is put out and a syslog notice is issued. Mainly forintegration with a wrapper script
-s --success NUM
After switching, keep checking for the result up to max. NUM seconds. If target IDsor target class were provided, their appearance indicates certain success. Otherwisethe 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 identificationof 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). Mainlyfor testing


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

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




This document was created byman2html,using the manual pages.