USB-MODESWITCH(1) General Commands Manual USB-MODESWITCH(1)
NAME
usb_modeswitch - switch mode of "multi-state" USB devices
SYNOPSIS
usb_modeswitch [-hvpVPmM23rdHn] [-c filename]
DESCRIPTION
Several new USB devices have their proprietary Windows drivers onboard, most of them WAN 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 shows up as "usb-
storage" by default. usb_modeswitch can send a provided bulk message (most likely a mass storage command) to the device which is known to
initiate the mode switching.
In some cases, USB control commands are used for switching. These cases are handled by custom functions, and no command needs to be pro-
vided.
Usually, the program is distributed with a set of configurations for many known devices, which in combination with a wrapper script
launched from the udev daemon allows a fully automatic handling of a device upon insertion.
OPTIONS
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
-P --target-product NUM
Target product ID
-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
-n --need-response
Read the response (containing the command status) 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 must 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
-d --detach-only
Detach the storage driver as the only action. This is sufficient for some devices to switch successfully
-H --huawei-mode
Send a special control message used by older Huawei devices
-S --gct-mode
Send a special control message used by Sierra devices
-G --gct-mode
Send a special control message used by GCT chipsets
-O --sony-mode
Apply a special sequence used by Sony Ericsson devices. Implies option -s
-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 filename
Use a specific config file. If any ID or switching options are given as command line parameters, no config file (default or spe-
cific) is used. In that case all mandatory and optional parameters have to be provided on the command line
-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 --success NUM
After switching, keep checking for the result up to max. NUM seconds. If target IDs or target class were provided, their appear-
ance 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 switching). Mainly for testing
-a --altsetting NUM
Select alternative USB interface setting (applied after switching). Mainly for testing
AUTHOR
This manual page was originally written by Didier Raboud (didier@raboud.com) for the Debian system. Additions made by Josua Dietze. Permis-
sion 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 http://www.gnu.org/licenses/gpl.txt
USB-MODESWITCH(1)