1USB_MODESWITCH(1) General Commands Manual USB_MODESWITCH(1)
2
6 usb_modeswitch - switch mode of "multi-state" USB devices
7
9 usb_modeswitch [-hvpVPmM23rdHn] [-c filename]
10
12 Several new USB devices have their proprietary Windows drivers onboard,
13 most of them WAN dongles. When plugged in for the first time, they act
14 like a flash storage and start installing the Windows driver from
15 there. If the driver is already installed, it makes the storage device
16 disappear and a new device, mainly composite with modem ports, shows
17 up.
18 On Linux, in most cases the drivers are available as kernel modules,
20 such as "usbserial" or "option". However, the device shows up as "usb-
21 storage" by default. usb_modeswitch can send a provided bulk message
22 (most likely a mass storage command) to the device which is known to
23 initiate the mode switching.
24 In some cases, USB control commands are used for switching. These cases
26 are handled by custom functions, and no bulk message needs to be pro‐
27 vided.
28 Usually, the program is distributed with a set of configurations for
30 many known devices, which in combination with a wrapper script launched
31 from the udev daemon allows a fully automatic handling of a device upon
32 insertion.
33
36 This program follows the usual GNU command line syntax, with long
37 options starting with two dashes ('--'). A summary of options is
38 included below.
39 -h --help Show summary of options.
41 -e --version
43 Print version information and exit.
44 -v --default-vendor NUM
46 Vendor ID to look for (mandatory), usually given as hex num‐
47 ber (example: 0x12d1). Each USB device is identified by a
48 number officialy assigned to the vendor by the USB associa‐
49 tion and a number for the respective model (product ID) cho‐
50 sen by the vendor
51 -p --default-product NUM
53 Product ID to look for (mandatory).
54 -V --target-vendor NUM
56 Target vendor ID. When given will be searched for and
57 detected initially for information purposes. If success
58 checking (option -s) is active, providing target IDs (ven‐
59 dor/product) or target class is recommended
60 -P --target-product NUM
62 Target product ID
63 -C --target-class NUM
65 Target Device Class according to the USB specification. Some
66 devices keep their original vendor/product ID after success‐
67 ful switching. To prevent them from being treated again, the
68 device class can be checked. For unswitched devices it is
69 always 8 (storage class), for switched modems it is often
70 0xff (vendor specific). In composite modes, the class of the
71 first interface is watched
72 -m --message-endpoint NUM
74 A specific endpoint to use for data transfers. Only for test‐
75 ing purposes; usually endpoints are determined from the
76 device attributes
77 -M --message-content STRING
79 A bulk message to send as a switching command. Provided as a
80 hexadecimal string
81 -2, -3 --message-content2, --message-content3 STRING
83 Additional bulk messages to send as switching commands. Pro‐
84 vided as hexadecimal strings. When used with mass storage
85 commands, setting --need-response is strongly advised to com‐
86 ply with specifications and to avoid likely errors
87 -w --message-delay NUM
89 If there is more than one message content, wait for NUM mil‐
90 liseconds before sending the next one. Otherwise it is
91 ignored. Note: this will release and reclaim the interface
92 -n --need-response
94 Read the response (command status wrapper) to a mass storage
95 command transfer. Some devices have trouble switching if the
96 response is not read; most are disappearing right away. When
97 sending multiple mass storage commands with -2 and -3, this
98 may need to be set to avoid transfer errors
99 -r --response-endpoint NUM
101 Try to read the response to a storage command from there if
102 option -n is active. Only for testing purposes; usually end‐
103 points are determined from the device attributes
104 -d --detach-only
106 Detach the storage driver as the only action. This is suffi‐
107 cient for some devices to switch successfully
108 -H --huawei-mode
110 Send a special control message used by older Huawei devices
111 -S --gct-mode
113 Send a special control message used by Sierra devices
114 -G --gct-mode
116 Send a special control message used by GCT chipsets
117 -O --sony-mode
119 Apply a special sequence used by Sony Ericsson devices.
120 Implies option -s
121 -R --reset-usb
123 Send a USB reset command to the device. Can be combined with
124 any switching method or stand alone. It is always done as the
125 last step of all device interactions. Few devices need it to
126 complete the switching; apart from that it may be useful dur‐
127 ing testing
128 -c --config filename
130 Use a specific config file. If any ID or switching options
131 are given as command line parameters, this option is ignored.
132 In that case all mandatory parameters have to be provided on
133 the command line
134 -Q --quiet
136 Don't show progress or error messages
137 -W --verbose
139 Print all settings before running and show libusb debug mes‐
140 sages
141 -D --sysmode
143 Changes the behaviour of the program slightly. A success mes‐
144 sage including the effective target device ID is put out and
145 a syslog notice is issued. Mainly for integration with a
146 wrapper script
147 -s --success NUM
149 After switching, keep checking for the result up to max. NUM
150 seconds. If target IDs or target class were provided, their
151 appearance indicates certain success. Otherwise the discon‐
152 nection of the original device is rated as likely proof
153 -I --no-inquire
155 do not obtain SCSI attributes from device (default is on).
156 For proper identification of differing devices the attributes
157 of the storage part provide valuable information. This is
158 not needed for devices that are known and supported
159 -i --interface NUM
161 Select initial USB interface (default: 0). Only for testing
162 purposes
163 -u --configuration NUM
165 Select USB configuration (applied after switching). Mainly
166 for testing
167 -a --altsetting NUM
169 Select alternative USB interface setting (applied after
170 switching). Mainly for testing
171
173 This manual page was originally written by Didier Raboud
174 (didier@raboud.com) for the Debian system. Additions made by Josua
175 Dietze. Permission is granted to copy, distribute and/or modify this
176 document under the terms of the GNU General Public License, Version 2
177 or any later version published by the Free Software Foundation.
178 The complete text of the current GNU General Public License can be
181 found in http://www.gnu.org/licenses/gpl.txt
182 USB_MODESWITCH(1)