1USB_MODESWITCH(1) General Commands Manual USB_MODESWITCH(1)
2
6 usb_modeswitch - control the mode of 'multi-state' USB devices
7
9 usb_modeswitch [-heWQDIvpVPmM23rwKdHSOBGTNALnsRiuagft] [-c filename]
10
12 Several new USB devices have their proprietary Windows drivers onboard,
13 most of them WWAN and WLAN dongles. When plugged in for the first
14 time, they act like a flash storage and start installing the Windows
15 driver from there. If the driver is installed, it makes the storage
16 device disappear and a new device, mainly composite (e.g. with modem
17 ports), shows up.
18 On Linux, in most cases the drivers are available as kernel modules,
20 such as "usbserial" or "option". However, the device initially binds to
21 "usb-storage" by default. usb_modeswitch can then send a provided bulk
22 message (most likely a mass storage command) to the device; this mes‐
23 sage has to be determined by analyzing the actions of the Windows
24 driver.
25 In some cases, USB control commands are used for switching. These cases
27 are handled by custom functions, and no bulk message needs to be pro‐
28 vided.
29 Usually, the program is distributed with a set of configurations for
31 many known devices, which allows a fully automatic handling of a device
32 upon insertion, made possible by combining usb_modeswitch with the
33 wrapper script usb_modeswitch_dispatcher which is launched by the udev
34 daemon. This requires a Linux-flavoured system though.
35 Note that usb_modeswitch itself has no specific Linux dependencies.
37
40 This program follows the usual GNU command line syntax, with long
41 options starting with two dashes ('--'). A summary of options is
42 included below.
43 -h --help Show summary of options.
45 -e --version
47 Print version information and exit
48 -v --default-vendor NUM
50 Vendor ID to look for (mandatory), usually given as hex num‐
51 ber (example: 0x12d1). Each USB device is identified by a
52 number officialy assigned to the vendor by the USB associa‐
53 tion and a number for the respective model (product ID) cho‐
54 sen by the vendor
55 -p --default-product NUM
57 Product ID to look for (mandatory)
58 -V --target-vendor NUM
60 Target vendor ID. When given will be searched for and
61 detected initially for information purposes. If success
62 checking (option -s) is active, providing target IDs (ven‐
63 dor/product) or target class is recommended
64 -j --find-mbim
66 Return configuration number with MBIM interface and exit.
67 -P --target-product NUM
69 Target product ID
70 -b --bus-num NUM
72 -g --device-num NUM
74 If bus and device number are provided, the handling of a spe‐
75 cific device on a specific USB port is guaranteed, in con‐
76 trast to using only the USB ID. This is important if there
77 are multiple similar devices on a system
78 -C --target-class NUM
80 Target Device Class according to the USB specification. Some
81 devices keep their original vendor/product ID after success‐
82 ful switching. To prevent them from being treated again, the
83 device class can be checked. For unswitched devices it is
84 always 8 (storage class), for switched modems it is often
85 0xff (vendor specific). In composite modes, the class of the
86 first interface is watched
87 -m --message-endpoint NUM
89 A specific endpoint to use for data transfers. Only for test‐
90 ing purposes; usually endpoints are determined from the
91 device attributes
92 -M --message-content STRING
94 A bulk message to send as a switching command. Provided as a
95 hexadecimal string
96 -2, -3 --message-content2, --message-content3 STRING
98 Additional bulk messages to send as switching commands. Pro‐
99 vided as hexadecimal strings. When used with mass storage
100 commands, setting --need-response is strongly advised to com‐
101 ply with specifications and to avoid likely errors
102 -w --release-delay NUM
104 After issuing all bulk messages, wait for NUM milliseconds
105 before releasing the interface. Required for some modems on
106 older systems (especially after an EJECT message)
107 -n --need-response
109 Obsolete. CSW is always attempted to being read after mass
110 storage transfers. No downside
111 -r --response-endpoint NUM
113 Try to read the response to a storage command from there.
114 Only for testing purposes; usually endpoints are determined
115 from the device attributes
116 -K --std-eject
118 Apply the standard SCSI sequence of "Allow Medium Removal"
119 and "Eject". Implies -n. One 'Message' can be added with -M
120 that will be transmitted after the eject sequence. Used by
121 many modems
122 -d --detach-only
124 Just detach the current driver. This is sufficient for some
125 early devices to switch successfully. Otherwise this feature
126 can be used as a 'scalpel' for special cases, like separating
127 the driver from individual interfaces
128 -H --huawei-mode
130 Send a special control message used by older Huawei devices
131 -J --huawei-new-mode
133 Send a specific bulk message used by all newer Huawei devices
134 -X --huawei-alt-mode
136 Send an alternative bulk message to Huawei devices
137 -S --sierra-mode
139 Send a special control message used by Sierra devices
140 -G --gct-mode
142 Send a special control message used by GCT chipsets
143 -T --kobil-mode
145 Send a special control message used by Kobil devices
146 -N --sequans-mode
148 Send a special control message used by Sequans chipset
149 -A --mobileaction-mode
151 Send a special control message used by the MobileAction
152 device
153 -B --qisda-mode
155 Send a special control message used by Qisda devices
156 -E --quanta-mode
158 Send a special control message used by Quanta devices
159 -F --pantech-mode NUM
161 Send a special control message used by Pantech devices.
162 Value NUM will be used in control message as 'wValue'
163 -Z --blackberry-mode
165 Send a special control message used by some newer Blackberry
166 devices
167 -S --option-mode
169 Send a special control message used by all Option devices
170 -O --sony-mode
172 Apply a special sequence used by Sony Ericsson devices.
173 Implies option --check-success
174 -L --cisco-mode
176 Send a sequence of bulk messages used by Cisco devices
177 -R --reset-usb
179 Send a USB reset command to the device. Can be combined with
180 any switching method or stand alone. It is always done as the
181 last step of all device interactions. Few devices need it to
182 complete the switching; apart from that it may be useful dur‐
183 ing testing
184 -c --config-file FILENAME
186 Use a specific config file. If any ID or switching options
187 are given as command line parameters, this option is ignored.
188 In that case all mandatory parameters have to be provided on
189 the command line
190 -f --long-config STRING
192 Provide device details in config file syntax as a multiline
193 string on the command line
194 -t --stdinput
196 Read the device details in config file syntax from standard
197 input, e.g. redirected from a command pipe (multiline text)
198 -Q --quiet
200 Don't show progress or error messages
201 -W --verbose
203 Print all settings before running and show libusb debug mes‐
204 sages
205 -D --sysmode
207 Changes the behaviour of the program slightly. A success mes‐
208 sage including the effective target device ID is put out and
209 a syslog notice is issued. Mainly for integration with a
210 wrapper script
211 -s --check-success NUM
213 After switching, keep checking for the result up to max. NUM
214 seconds. If target IDs or target class were provided, their
215 appearance indicates certain success. Otherwise the discon‐
216 nection of the original device is rated as likely proof
217 -I --inquire
219 Obsolete. Formerly obtained SCSI attributes, now ignored
220 -i --interface NUM
222 Select initial USB interface (default: 0). Only for testing
223 purposes
224 -u --configuration NUM
226 Select USB configuration (applied after any other possible
227 switching actions)
228 -a --altsetting NUM
230 Select alternative USB interface setting (applied after
231 switching). Mainly for testing
232
234 This manual page was originally written by Didier Raboud
235 (didier@raboud.com) for the Debian system. Additions made by Josua
236 Dietze. Permission is granted to copy, distribute and/or modify this
237 document under the terms of the GNU General Public License, Version 2
238 or any later version published by the Free Software Foundation.
239 The complete text of the current GNU General Public License can be
242 found in http://www.gnu.org/licenses/gpl.txt
243 USB_MODESWITCH(1)