1USB_MODESWITCH(1)           General Commands Manual          USB_MODESWITCH(1)
2
3
4

NAME

6       usb_modeswitch - control the mode of 'multi-state' USB devices
7

SYNOPSIS

9       usb_modeswitch [-heWQDIvpVPmM23rwKdHSOBGTNALnsRiuagft] [-c filename]
10

DESCRIPTION

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
19       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
26       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
30       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
36       Note that usb_modeswitch itself has no specific Linux dependencies.
37
38

OPTIONS

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
44       -h --help Show summary of options.
45
46       -e --version
47                 Print version information and exit
48
49       -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
56       -p --default-product NUM
57                 Product ID to look for (mandatory)
58
59       -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
65       -j --find-mbim
66                 Return configuration number with MBIM interface and exit.
67
68       -P --target-product NUM
69                 Target product ID
70
71       -b --bus-num NUM
72
73       -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
79       -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
88       -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
93       -M --message-content STRING
94                 A  bulk message to send as a switching command. Provided as a
95                 hexadecimal string
96
97       -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
103       -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
108       -n --need-response
109                 Obsolete.  CSW  is  always attempted to being read after mass
110                 storage transfers. No downside
111
112       -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
117       -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
123       -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
129       -H --huawei-mode
130                 Send a special control message used by older Huawei devices
131
132       -J --huawei-new-mode
133                 Send a specific bulk message used by all newer Huawei devices
134
135       -X --huawei-alt-mode
136                 Send an alternative bulk message to Huawei devices
137
138       -S --sierra-mode
139                 Send a special control message used by Sierra devices
140
141       -G --gct-mode
142                 Send a special control message used by GCT chipsets
143
144       -T --kobil-mode
145                 Send a special control message used by Kobil devices
146
147       -N --sequans-mode
148                 Send a special control message used by Sequans chipset
149
150       -A --mobileaction-mode
151                 Send a special  control  message  used  by  the  MobileAction
152                 device
153
154       -B --qisda-mode
155                 Send a special control message used by Qisda devices
156
157       -E --quanta-mode
158                 Send a special control message used by Quanta devices
159
160       -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
164       -Z --blackberry-mode
165                 Send a special control message used by some newer  Blackberry
166                 devices
167
168       -S --option-mode
169                 Send a special control message used by all Option devices
170
171       -O --sony-mode
172                 Apply  a  special  sequence  used  by  Sony Ericsson devices.
173                 Implies option --check-success
174
175       -L --cisco-mode
176                 Send a sequence of bulk messages used by Cisco devices
177
178       -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
185       -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
191       -f --long-config STRING
192                 Provide  device  details in config file syntax as a multiline
193                 string on the command line
194
195       -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
199       -Q --quiet
200                 Don't show progress or error messages
201
202       -W --verbose
203                 Print  all settings before running and show libusb debug mes‐
204                 sages
205
206       -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
212       -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
218       -I --inquire
219                 Obsolete. Formerly obtained SCSI attributes, now ignored
220
221       -i --interface NUM
222                 Select initial USB interface (default: 0). Only  for  testing
223                 purposes
224
225       -u --configuration NUM
226                 Select  USB  configuration  (applied after any other possible
227                 switching actions)
228
229       -a --altsetting NUM
230                 Select  alternative  USB  interface  setting  (applied  after
231                 switching). Mainly for testing
232

AUTHOR

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
240
241       The  complete  text  of  the  current GNU General Public License can be
242       found in http://www.gnu.org/licenses/gpl.txt
243
244
245
246
247                                                             USB_MODESWITCH(1)
Impressum