160 lines
8.3 KiB
Groff
160 lines
8.3 KiB
Groff
.TH "USB_MODESWITCH" "1"
|
|
.SH "NAME"
|
|
usb_modeswitch - switch mode of "multi-state" USB devices
|
|
.SH "SYNOPSIS"
|
|
.PP
|
|
\fBusb_modeswitch\fR [\fB\-heWQDIvpVPmM23rwdHSOBGTNALnsRiuagft\fP] [\fB\-c \fIfilename\fP]
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
Several new USB devices have their proprietary Windows drivers onboard,
|
|
most of them WAN 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 shows up as
|
|
"usb-storage" by default. \fBusb_modeswitch\fR can send a provided bulk
|
|
message (most likely a mass storage command) to the device which is known
|
|
to initiate the mode switching.
|
|
.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 in combination with a wrapper script launched from the
|
|
udev daemon allows a fully automatic handling of a device upon insertion.
|
|
|
|
.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-P\fP \fB\-\-target-product NUM\fP " 10
|
|
Target product ID
|
|
.IP "\fB-b\fP \fB\-\-busnum NUM\fP " 10
|
|
.IP "\fB-g\fP \fB\-\-devnum 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-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-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-T\fP \fB\-\-sequans-mode\fP " 10
|
|
Send a special control message used by Sequans chipset
|
|
.IP "\fB-T\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-O\fP \fB\-\-sony-mode\fP " 10
|
|
Apply a special sequence used by Sony Ericsson devices. Implies option \--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 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\-\-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 (didier@raboud.com) 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 2011-10-23 for version 1.2.2
|