| blob | 1d842b5de5788ca1bed6c4cf9a77eec2fd5a70eb |
1 .TH "USB_MODESWITCH" "1"
2 .SH "NAME"
3 usb_modeswitch - switch mode of "multi-state" USB devices
4 .SH "SYNOPSIS"
5 .PP
6 \fBusb_modeswitch\fR [\fB\-heWQDIvpVPmM23rwdHSOBGTNALnsRiuagft\fP] [\fB\-c \fIfilename\fP]
7 .SH "DESCRIPTION"
8 .PP
9 Several new USB devices have their proprietary Windows drivers onboard,
10 most of them WAN dongles. When plugged in for the first time, they act
11 like a flash storage and start installing the Windows driver from there.
12 If the driver is already installed, it makes the storage device disappear
13 and a new device, mainly composite with modem ports, shows up.
14 .PP
15 On Linux, in most cases the drivers are available as kernel modules,
16 such as "usbserial" or "option". However, the device shows up as
17 "usb-storage" by default. \fBusb_modeswitch\fR can send a provided bulk
18 message (most likely a mass storage command) to the device which is known
19 to initiate the mode switching.
20 .PP
21 In some cases, USB control commands are used for switching. These cases are
22 handled by custom functions, and no bulk message needs to be provided.
23 .PP
24 Usually, the program is distributed with a set of configurations for many
25 known devices, which in combination with a wrapper script launched from the
26 udev daemon allows a fully automatic handling of a device upon insertion.
28 .SH "OPTIONS"
29 .PP
30 This program follows the usual GNU command line syntax,
31 with long options starting with two dashes ('--'). A summary of
32 options is included below.
33 .IP "\fB-h\fP \fB\-\-help\fP " 10
34 Show summary of options.
35 .IP "\fB-e\fP \fB\-\-version\fP " 10
36 Print version information and exit
37 .IP "\fB-v\fP \fB\-\-default-vendor NUM\fP " 10
38 Vendor ID to look for (mandatory), usually given as hex number (example: 0x12d1).
39 Each USB device is identified by a number
40 officialy assigned to the vendor by the USB association and a number for the
41 respective model (product ID) chosen by the vendor
42 .IP "\fB-p\fP \fB\-\-default-product NUM\fP " 10
43 Product ID to look for (mandatory)
44 .IP "\fB-V\fP \fB\-\-target-vendor NUM\fP " 10
45 Target vendor ID. When given will be searched for and detected initially
46 for information purposes. If success checking (option \-s) is active,
47 providing target IDs (vendor/product) or target class is recommended
48 .IP "\fB-P\fP \fB\-\-target-product NUM\fP " 10
49 Target product ID
50 .IP "\fB-b\fP \fB\-\-busnum NUM\fP " 10
51 .IP "\fB-g\fP \fB\-\-devnum NUM\fP " 10
52 If bus and device number are provided, the handling of a specific device on
53 a specific USB port is guaranteed, in contrast to using only the USB ID. This
54 is important if there are multiple similar devices on a system
55 .IP "\fB-C\fP \fB\-\-target-class NUM\fP " 10
56 Target Device Class according to the USB specification. Some devices keep
57 their original vendor/product ID after successful switching. To prevent
58 them from being treated again, the device class can be checked.
59 For unswitched devices it is always 8 (storage class), for switched
60 modems it is often 0xff (vendor specific). In composite modes,
61 the class of the first interface is watched
62 .IP "\fB-m\fP \fB\-\-message-endpoint NUM\fP " 10
63 A specific endpoint to use for data transfers. Only for testing purposes; usually
64 endpoints are determined from the device attributes
65 .IP "\fB-M\fP \fB\-\-message-content STRING\fP " 10
66 A bulk message to send as a switching command. Provided as a hexadecimal string
67 .IP "\fB-2, -3\fP \fB\-\-message-content2, \-\-message-content3 STRING\fP " 10
68 Additional bulk messages to send as switching commands. Provided as hexadecimal strings.
69 When used with mass storage commands, setting \fB\-\-need-response\fR is
70 strongly advised to comply with specifications and to avoid likely errors
71 .IP "\fB-w\fP \fB\-\-release-delay NUM\fP " 10
72 After issuing all bulk messages, wait for NUM milliseconds before releasing the interface.
73 Required for some modems on older systems (especially after an EJECT message)
74 .IP "\fB-n\fP \fB\-\-need-response\fP " 10
75 Read the response (command status wrapper) to a mass storage command
76 transfer.
77 Some devices have trouble switching if the response is not read; most
78 are disappearing right away. When sending multiple mass storage commands
79 with \fB\-2\fR and \fB\-3\fR, this may need to be set to avoid transfer errors
80 .IP "\fB-r\fP \fB\-\-response-endpoint NUM\fP " 10
81 Try to read the response to a storage command from there
82 if option \-n is active. Only for testing purposes; usually
83 endpoints are determined from the device attributes
84 .IP "\fB-d\fP \fB\-\-detach-only\fP " 10
85 Just detach the current driver. This is sufficient for some early
86 devices to switch successfully. Otherwise this feature can
87 be used as a 'scalpel' for special cases, like separating the
88 driver from individual interfaces
89 .IP "\fB-H\fP \fB\-\-huawei-mode\fP " 10
90 Send a special control message used by older Huawei devices
91 .IP "\fB-S\fP \fB\-\-sierra-mode\fP " 10
92 Send a special control message used by Sierra devices
93 .IP "\fB-G\fP \fB\-\-gct-mode\fP " 10
94 Send a special control message used by GCT chipsets
95 .IP "\fB-T\fP \fB\-\-kobil-mode\fP " 10
96 Send a special control message used by Kobil devices
97 .IP "\fB-T\fP \fB\-\-sequans-mode\fP " 10
98 Send a special control message used by Sequans chipset
99 .IP "\fB-T\fP \fB\-\-mobileaction-mode\fP " 10
100 Send a special control message used by the MobileAction device
101 .IP "\fB-B\fP \fB\-\-qisda-mode\fP " 10
102 Send a special control message used by Qisda devices
103 .IP "\fB-E\fP \fB\-\-quanta-mode\fP " 10
104 Send a special control message used by Quanta devices
105 .IP "\fB-O\fP \fB\-\-sony-mode\fP " 10
106 Apply a special sequence used by Sony Ericsson devices. Implies option \--success
107 .IP "\fB-L\fP \fB\-\-cisco-mode\fP " 10
108 Send a sequence of bulk messages used by Cisco devices
109 .IP "\fB-R\fP \fB\-\-reset-usb\fP " 10
110 Send a USB reset command to the device. Can be combined with any switching
111 method or stand alone. It is always done as the last step of all device
112 interactions.
113 Few devices need it to complete the switching; apart from that it may be
114 useful during testing
115 .IP "\fB-c\fP \fB\-\-config FILENAME\fP " 10
116 Use a specific config file. If any ID or switching options are given as
117 command line parameters, this option is ignored.
118 In that case all mandatory parameters have to be provided on
119 the command line
120 .IP "\fB-f\fP \fB\-\-long-config STRING\fP " 10
121 Provide device details in config file syntax as a multiline string
122 on the command line
123 .IP "\fB-t\fP \fB\-\-stdinput\fP " 10
124 Read the device details in config file syntax from standard input, e.g. redirected from
125 a command pipe (multiline text)
126 .IP "\fB-Q\fP \fB\-\-quiet\fP " 10
127 Don't show progress or error messages
128 .IP "\fB-W\fP \fB\-\-verbose\fP " 10
129 Print all settings before running and show libusb debug messages
130 .IP "\fB-D\fP \fB\-\-sysmode\fP " 10
131 Changes the behaviour of the program slightly. A success message including the
132 effective target device ID is put out and a syslog notice is issued. Mainly for
133 integration with a wrapper script
134 .IP "\fB-s\fP \fB\-\-success NUM\fP " 10
135 After switching, keep checking for the result up to max. NUM seconds. If target IDs
136 or target class were provided, their appearance indicates certain success. Otherwise
137 the disconnection of the original device is rated as likely proof
138 .IP "\fB-I\fP \fB\-\-no-inquire\fP " 10
139 do not obtain SCSI attributes from device (default is on). For proper identification
140 of differing devices the attributes of the storage part provide valuable information.
141 This is not needed for devices that are known and supported
142 .IP "\fB-i\fP \fB\-\-interface NUM\fP " 10
143 Select initial USB interface (default: 0). Only for testing purposes
144 .IP "\fB-u\fP \fB\-\-configuration NUM\fP " 10
145 Select USB configuration (applied after any other possible switching actions)
146 .IP "\fB-a\fP \fB\-\-altsetting NUM\fP " 10
147 Select alternative USB interface setting (applied after switching). Mainly
148 for testing
149 .SH "AUTHOR"
150 .PP
151 This manual page was originally written by Didier Raboud (didier@raboud.com) for
152 the \fBDebian\fP system. Additions made by Josua Dietze. Permission is
153 granted to copy, distribute and/or modify this document under
154 the terms of the GNU General Public License, Version 2 or any
155 later version published by the Free Software Foundation.
157 .PP
158 The complete text of the current GNU General Public
159 License can be found in http://www.gnu.org/licenses/gpl.txt
161 .\" last edited 2013-06-02 for version 1.2.6