-
Notifications
You must be signed in to change notification settings - Fork 2
/
usb_modeswitch.1
176 lines (173 loc) · 9.33 KB
/
usb_modeswitch.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
.TH "USB_MODESWITCH" "1"
.SH "NAME"
usb_modeswitch - control the mode of 'multi-state' USB devices
.SH "SYNOPSIS"
.PP
\fBusb_modeswitch\fR [\fB\-heWQDIvpVPmM23rwKdHSOBGTNALnsRiuagft\fP] [\fB\-c \fIfilename\fP]
.SH "DESCRIPTION"
.PP
Several new USB devices have their proprietary Windows drivers onboard,
most of them WWAN and WLAN 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.
.PP
On Linux, in most cases the drivers are available as kernel modules,
such as "usbserial" or "option". However, the device initially binds to
"usb-storage" by default. \fBusb_modeswitch\fR can then send a provided bulk
message (most likely a mass storage command) to the device; this message
has to be determined by analyzing the actions of the Windows driver.
.PP
In some cases, USB control commands are used for switching. These cases are
handled by custom functions, and no bulk message needs to be provided.
.PP
Usually, the program is distributed with a set of configurations for many
known devices, which allows a fully automatic handling of a device upon
insertion, made possible by combining usb_modeswitch with the wrapper script
\fBusb_modeswitch_dispatcher\fR which is launched by the udev daemon.
.PP
Note that \fBusb_modeswitch\fR itself has no specific Linux dependencies.
.SH "OPTIONS"
.PP
This program follows the usual GNU command line syntax,
with long options starting with two dashes ('--'). A summary of
options is included below.
.IP "\fB-h\fP \fB\-\-help\fP " 10
Show summary of options.
.IP "\fB-e\fP \fB\-\-version\fP " 10
Print version information and exit
.IP "\fB-v\fP \fB\-\-default-vendor NUM\fP " 10
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
.IP "\fB-p\fP \fB\-\-default-product NUM\fP " 10
Product ID to look for (mandatory)
.IP "\fB-V\fP \fB\-\-target-vendor NUM\fP " 10
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
.IP "\fB-j\fP \fB\-\-find-mbim\fP " 10
Return configuration number with MBIM interface and exit.
.IP "\fB-P\fP \fB\-\-target-product NUM\fP " 10
Target product ID
.IP "\fB-b\fP \fB\-\-bus-num NUM\fP " 10
.IP "\fB-g\fP \fB\-\-device-num NUM\fP " 10
If bus and device number are provided, the handling of a specific device on
a specific USB port is guaranteed, in contrast to using only the USB ID. This
is important if there are multiple similar devices on a system
.IP "\fB-C\fP \fB\-\-target-class NUM\fP " 10
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
.IP "\fB-m\fP \fB\-\-message-endpoint NUM\fP " 10
A specific endpoint to use for data transfers. Only for testing purposes; usually
endpoints are determined from the device attributes
.IP "\fB-M\fP \fB\-\-message-content STRING\fP " 10
A bulk message to send as a switching command. Provided as a hexadecimal string
.IP "\fB-2, -3\fP \fB\-\-message-content2, \-\-message-content3 STRING\fP " 10
Additional bulk messages to send as switching commands. Provided as hexadecimal strings.
When used with mass storage commands, setting \fB\-\-need-response\fR is
strongly advised to comply with specifications and to avoid likely errors
.IP "\fB-w\fP \fB\-\-release-delay NUM\fP " 10
After issuing all bulk messages, wait for NUM milliseconds before releasing the interface.
Required for some modems on older systems (especially after an EJECT message)
.IP "\fB-n\fP \fB\-\-need-response\fP " 10
Read the response (command status wrapper) 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 \fB\-2\fR and \fB\-3\fR, this may need to be set to avoid transfer errors
.IP "\fB-r\fP \fB\-\-response-endpoint NUM\fP " 10
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
.IP "\fB-K\fP \fB\-\-std-eject\fP " 10
Apply the standard SCSI sequence of "Allow Medium Removal" and
"Eject". Implies \fB-n\fP. One 'Message' can be added with \fB-M\fP
that will be transmitted after the eject sequence
.IP "\fB-d\fP \fB\-\-detach-only\fP " 10
Just detach the current driver. This is sufficient for some early
devices to switch successfully. Otherwise this feature can
be used as a 'scalpel' for special cases, like separating the
driver from individual interfaces
.IP "\fB-H\fP \fB\-\-huawei-mode\fP " 10
Send a special control message used by older Huawei devices
.IP "\fB-J\fP \fB\-\-huawei-new-mode\fP " 10
Send a specific bulk message used by all newer Huawei devices
.IP "\fB-S\fP \fB\-\-sierra-mode\fP " 10
Send a special control message used by Sierra devices
.IP "\fB-G\fP \fB\-\-gct-mode\fP " 10
Send a special control message used by GCT chipsets
.IP "\fB-T\fP \fB\-\-kobil-mode\fP " 10
Send a special control message used by Kobil devices
.IP "\fB-N\fP \fB\-\-sequans-mode\fP " 10
Send a special control message used by Sequans chipset
.IP "\fB-A\fP \fB\-\-mobileaction-mode\fP " 10
Send a special control message used by the MobileAction device
.IP "\fB-B\fP \fB\-\-qisda-mode\fP " 10
Send a special control message used by Qisda devices
.IP "\fB-E\fP \fB\-\-quanta-mode\fP " 10
Send a special control message used by Quanta devices
.IP "\fB-F\fP \fB\-\-pantech-mode\fP " 10
Send a special control message used by Pantech devices
.IP "\fB-Z\fP \fB\-\-blackberry-mode\fP " 10
Send a special control message used by some newer Blackberry devices
.IP "\fB-O\fP \fB\-\-sony-mode\fP " 10
Apply a special sequence used by Sony Ericsson devices. Implies option \--check-success
.IP "\fB-L\fP \fB\-\-cisco-mode\fP " 10
Send a sequence of bulk messages used by Cisco devices
.IP "\fB-R\fP \fB\-\-reset-usb\fP " 10
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
.IP "\fB-c\fP \fB\-\-config-file FILENAME\fP " 10
Use a specific config file. If any ID or switching options are given as
command line parameters, this option is ignored.
In that case all mandatory parameters have to be provided on
the command line
.IP "\fB-f\fP \fB\-\-long-config STRING\fP " 10
Provide device details in config file syntax as a multiline string
on the command line
.IP "\fB-t\fP \fB\-\-stdinput\fP " 10
Read the device details in config file syntax from standard input, e.g. redirected from
a command pipe (multiline text)
.IP "\fB-Q\fP \fB\-\-quiet\fP " 10
Don't show progress or error messages
.IP "\fB-W\fP \fB\-\-verbose\fP " 10
Print all settings before running and show libusb debug messages
.IP "\fB-D\fP \fB\-\-sysmode\fP " 10
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
.IP "\fB-s\fP \fB\-\-check-success NUM\fP " 10
After switching, keep checking for the result up to max. NUM seconds. If target IDs
or target class were provided, their appearance indicates certain success. Otherwise
the disconnection of the original device is rated as likely proof
.IP "\fB-I\fP \fB\-\-no-inquire\fP " 10
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
.IP "\fB-i\fP \fB\-\-interface NUM\fP " 10
Select initial USB interface (default: 0). Only for testing purposes
.IP "\fB-u\fP \fB\-\-configuration NUM\fP " 10
Select USB configuration (applied after any other possible switching actions)
.IP "\fB-a\fP \fB\-\-altsetting NUM\fP " 10
Select alternative USB interface setting (applied after switching). Mainly
for testing
.SH "AUTHOR"
.PP
This manual page was originally written by Didier Raboud ([email protected]) for
the \fBDebian\fP system. Additions made by Josua Dietze. Permission 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.
.PP
The complete text of the current GNU General Public
License can be found in http://www.gnu.org/licenses/gpl.txt
.\" last edited 2014-05-29 for version 2.2.0