usb_modeswitch
switch mode of "multi-state" USB devices
Synopsis
usb_modeswitch
[-heWQDIvpVPmM23rwdHSOBGTNALnsRiuagft]
[-c filename]
add an example, a script, a trick and tips
examples
no example yet ...
... Feel free to add your own example above to help other Linux-lovers !
description
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.
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.
usb_modeswitch can send a provided bulk message (most
likely a mass storage command) to the device which is known
to initiate the mode switching.
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.
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.
options
This program
follows the usual GNU command line syntax, with long options
starting with two dashes (’--’). A summary of
options is included below.
-h --help
Show summary of options.
-e
--version
Print version information and
exit
-v
--default-vendor NUM
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
-p
--default-product NUM
Product ID to look for
(mandatory)
-V
--target-vendor NUM
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
-P
--target-product NUM
Target product ID
-b --busnum NUM
-g --devnum NUM
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
-C
--target-class NUM
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
-m
--message-endpoint NUM
A specific endpoint to use for
data transfers. Only for testing purposes; usually endpoints
are determined from the device attributes
-M
--message-content STRING
A bulk message to send as a
switching command. Provided as a hexadecimal string
-2, -3
--message-content2,
--message-content3 STRING
Additional bulk messages to
send as switching commands. Provided as hexadecimal strings.
When used with mass storage commands, setting
--need-response is strongly advised to
comply with specifications and to avoid likely errors
-w
--release-delay NUM
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)
-n
--need-response
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 -2 and -3,
this may need to be set to avoid transfer errors
-r
--response-endpoint NUM
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
-d
--detach-only
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
-H
--huawei-mode
Send a special control message
used by older Huawei devices
-S
--sierra-mode
Send a special control message
used by Sierra devices
-G
--gct-mode
Send a special control message
used by GCT chipsets
-T
--kobil-mode
Send a special control message
used by Kobil devices
-T
--sequans-mode
Send a special control message
used by Sequans chipset
-T
--mobileaction-mode
Send a special control message
used by the MobileAction device
-B
--qisda-mode
Send a special control message
used by Qisda devices
-O
--sony-mode
Apply a special sequence used
by Sony Ericsson devices. Implies option --success
-L
--cisco-mode
Send a sequence of bulk
messages used by Cisco devices
-R
--reset-usb
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
-c --config
FILENAME
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
-f --long-config
STRING
Provide device details in
config file syntax as a multiline string on the command
line
-t
--stdinput
Read the device details in
config file syntax from standard input, e.g. redirected from
a command pipe (multiline text)
-Q
--quiet
Don’t show progress or
error messages
-W
--verbose
Print all settings before
running and show libusb debug messages
-D
--sysmode
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
-s --success
NUM
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
-I
--no-inquire
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
-i --interface
NUM
Select initial USB interface
(default: 0). Only for testing purposes
-u
--configuration NUM
Select USB configuration
(applied after any other possible switching actions)
-a --altsetting
NUM
Select alternative USB
interface setting (applied after switching). Mainly for
testing
author
This manual
page was originally written by Didier Raboud
(didier[:at:]raboud[:dot:]com) for the Debian 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.
The complete
text of the current GNU General Public License can be found
in http://www.gnu.org/licenses/gpl.txt