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 --message-content2 STRING
98 -3 --message-content3 STRING
100 Additional bulk messages to send as switching commands. Pro‐
101 vided as hexadecimal strings. When used with mass storage
102 commands, setting --need-response is strongly advised to com‐
103 ply with specifications and to avoid likely errors
104 -w --release-delay <milliseconds>
106 After issuing all bulk messages, wait for the given time
107 before releasing the interface. Required for some modems on
108 older systems (especially after an EJECT message)
109 -n --need-response
111 Obsolete. CSW is always attempted to being read after mass
112 storage transfers. No downside
113 -r --response-endpoint NUM
115 Try to read the response to a storage command from there.
116 Only for testing purposes; usually endpoints are determined
117 from the device attributes
118 -K --std-eject
120 Apply the standard SCSI sequence of "Allow Medium Removal"
121 and "Eject". Implies -n. One 'Message' can be added with -M
122 that will be transmitted after the eject sequence. Used by
123 many modems
124 -d --detach-only
126 Just detach the current driver. This is sufficient for some
127 early devices to switch successfully. Otherwise this feature
128 can be used as a 'scalpel' for special cases, like separating
129 the driver from individual interfaces
130 -H --huawei-mode
132 Send a special control message used by older Huawei devices
133 -J --huawei-new-mode
135 Send a specific bulk message used by all newer Huawei devices
136 -X --huawei-alt-mode
138 Send an alternative bulk message to Huawei devices
139 -S --sierra-mode
141 Send a special control message used by Sierra devices
142 -G --gct-mode
144 Send a special control message used by GCT chipsets
145 -T --kobil-mode
147 Send a special control message used by Kobil devices
148 -N --sequans-mode
150 Send a special control message used by Sequans chipset
151 -A --mobileaction-mode
153 Send a special control message used by the MobileAction
154 device
155 -B --qisda-mode
157 Send a special control message used by Qisda devices
158 -E --quanta-mode
160 Send a special control message used by Quanta devices
161 -F --pantech-mode NUM
163 Send a special control message used by Pantech devices.
164 Value NUM will be used in control message as 'wValue'
165 -Z --blackberry-mode
167 Send a special control message used by some newer Blackberry
168 devices
169 -S --option-mode
171 Send a special control message used by all Option devices
172 -O --sony-mode
174 Apply a special sequence used by Sony Ericsson devices.
175 Implies option --check-success
176 -L --cisco-mode
178 Send a sequence of bulk messages used by Cisco devices
179 -R --reset-usb
181 Send a USB reset command to the device. Can be combined with
182 any switching method or stand alone. It is always done as the
183 last step of all device interactions. Few devices need it to
184 complete the switching; apart from that it may be useful dur‐
185 ing testing
186 -c --config-file FILENAME
188 Use a specific config file. If any ID or switching options
189 are given as command line parameters, this option is ignored.
190 In that case all mandatory parameters have to be provided on
191 the command line
192 -f --long-config STRING
194 Provide device details in config file syntax as a multiline
195 string on the command line
196 -t --stdinput
198 Read the device details in config file syntax from standard
199 input, e.g. redirected from a command pipe (multiline text)
200 -Q --quiet
202 Don't show progress or error messages
203 -W --verbose
205 Print all settings before running and show libusb debug mes‐
206 sages
207 -D --sysmode
209 Changes the behaviour of the program slightly. A success mes‐
210 sage including the effective target device ID is put out and
211 a syslog notice is issued. Mainly for integration with a
212 wrapper script
213 -s --check-success <seconds>
215 After switching, keep checking for the result up to the given
216 time. If target IDs or target class were provided, their
217 appearance indicates certain success. Otherwise the discon‐
218 nection of the original device is rated as likely proof
219 -I --inquire
221 Obsolete. Formerly obtained SCSI attributes, now ignored
222 -i --interface NUM
224 Select initial USB interface (default: 0). Only for testing
225 purposes
226 -u --configuration NUM
228 Select USB configuration (applied after any other possible
229 switching actions)
230 -a --altsetting NUM
232 Select alternative USB interface setting (applied after
233 switching). Mainly for testing
234
236 This manual page was originally written by Didier Raboud
237 (didier@raboud.com) for the Debian system. Additions made by Josua
238 Dietze. Permission is granted to copy, distribute and/or modify this
239 document under the terms of the GNU General Public License, Version 2
240 or any later version published by the Free Software Foundation.
241 The complete text of the current GNU General Public License can be
244 found in http://www.gnu.org/licenses/gpl.txt
245 USB_MODESWITCH(1)