222 lines
10 KiB
HTML
222 lines
10 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of USB_MODESWITCH</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>USB_MODESWITCH</H1>
|
|
Section: User Commands (1)<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
usb_modeswitch - control the mode of 'multi-state' USB devices
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<P>
|
|
|
|
<B>usb_modeswitch</B> [<B>-heWQDIvpVPmM23rwKdHSOBGTNALnsRiuagft</B>] [<B>-c </B><I>filename</I>]
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<P>
|
|
|
|
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 installed, it makes the storage device disappear
|
|
and a new device, mainly composite (e.g. with modem ports), shows up.
|
|
<P>
|
|
|
|
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. <B>usb_modeswitch</B> 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.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
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
|
|
<B>usb_modeswitch_dispatcher</B> which is launched by the udev daemon. This
|
|
requires a Linux-flavoured system though.
|
|
<P>
|
|
|
|
Note that <B>usb_modeswitch</B> itself has no specific Linux dependencies.
|
|
<P>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<P>
|
|
|
|
This program follows the usual GNU command line syntax,
|
|
with long options starting with two dashes ('--'). A summary of
|
|
options is included below.
|
|
<DL COMPACT>
|
|
<DT id="1"><B>-h</B> <B>--help</B> <DD>
|
|
Show summary of options.
|
|
<DT id="2"><B>-e</B> <B>--version</B> <DD>
|
|
Print version information and exit
|
|
<DT id="3"><B>-v</B> <B>--default-vendor NUM</B> <DD>
|
|
Vendor ID to look for (mandatory), usually given as hex number (example: 0x12d1).
|
|
Each USB device is identified by a number
|
|
officially assigned to the vendor by the USB association and a number for the
|
|
respective model (product ID) chosen by the vendor
|
|
<DT id="4"><B>-p</B> <B>--default-product NUM</B> <DD>
|
|
Product ID to look for (mandatory)
|
|
<DT id="5"><B>-V</B> <B>--target-vendor NUM</B> <DD>
|
|
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
|
|
<DT id="6"><B>-j</B> <B>--find-mbim</B> <DD>
|
|
Return configuration number with MBIM interface and exit.
|
|
<DT id="7"><B>-P</B> <B>--target-product NUM</B> <DD>
|
|
Target product ID
|
|
<DT id="8"><B>-b</B> <B>--bus-num NUM</B> <DD>
|
|
<DT id="9"><B>-g</B> <B>--device-num NUM</B> <DD>
|
|
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
|
|
<DT id="10"><B>-C</B> <B>--target-class NUM</B> <DD>
|
|
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
|
|
<DT id="11"><B>-m</B> <B>--message-endpoint NUM</B> <DD>
|
|
A specific endpoint to use for data transfers. Only for testing purposes; usually
|
|
endpoints are determined from the device attributes
|
|
<DT id="12"><B>-M</B> <B>--message-content STRING</B> <DD>
|
|
A bulk message to send as a switching command. Provided as a hexadecimal string
|
|
<DT id="13"><B>-2, -3</B> <B>--message-content2, --message-content3 STRING</B> <DD>
|
|
Additional bulk messages to send as switching commands. Provided as hexadecimal strings.
|
|
When used with mass storage commands, setting <B>--need-response</B> is
|
|
strongly advised to comply with specifications and to avoid likely errors
|
|
<DT id="14"><B>-w</B> <B>--release-delay NUM</B> <DD>
|
|
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)
|
|
<DT id="15"><B>-n</B> <B>--need-response</B> <DD>
|
|
Obsolete. CSW is always attempted to being read after mass storage transfers. No downside
|
|
<DT id="16"><B>-r</B> <B>--response-endpoint NUM</B> <DD>
|
|
Try to read the response to a storage command from there. Only for testing purposes;
|
|
usually endpoints are determined from the device attributes
|
|
<DT id="17"><B>-K</B> <B>--std-eject</B> <DD>
|
|
Apply the standard SCSI sequence of "Allow Medium Removal" and
|
|
"Eject". Implies <B>-n</B>. One 'Message' can be added with <B>-M</B>
|
|
that will be transmitted after the eject sequence. Used by many modems
|
|
<DT id="18"><B>-d</B> <B>--detach-only</B> <DD>
|
|
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
|
|
<DT id="19"><B>-H</B> <B>--huawei-mode</B> <DD>
|
|
Send a special control message used by older Huawei devices
|
|
<DT id="20"><B>-J</B> <B>--huawei-new-mode</B> <DD>
|
|
Send a specific bulk message used by all newer Huawei devices
|
|
<DT id="21"><B>-X</B> <B>--huawei-alt-mode</B> <DD>
|
|
Send an alternative bulk message to Huawei devices
|
|
<DT id="22"><B>-S</B> <B>--sierra-mode</B> <DD>
|
|
Send a special control message used by Sierra devices
|
|
<DT id="23"><B>-G</B> <B>--gct-mode</B> <DD>
|
|
Send a special control message used by GCT chipsets
|
|
<DT id="24"><B>-T</B> <B>--kobil-mode</B> <DD>
|
|
Send a special control message used by Kobil devices
|
|
<DT id="25"><B>-N</B> <B>--sequans-mode</B> <DD>
|
|
Send a special control message used by Sequans chipset
|
|
<DT id="26"><B>-A</B> <B>--mobileaction-mode</B> <DD>
|
|
Send a special control message used by the MobileAction device
|
|
<DT id="27"><B>-B</B> <B>--qisda-mode</B> <DD>
|
|
Send a special control message used by Qisda devices
|
|
<DT id="28"><B>-E</B> <B>--quanta-mode</B> <DD>
|
|
Send a special control message used by Quanta devices
|
|
<DT id="29"><B>-F</B> <B>--pantech-mode NUM</B> <DD>
|
|
Send a special control message used by Pantech devices.
|
|
Value NUM will be used in control message as 'wValue'
|
|
<DT id="30"><B>-Z</B> <B>--blackberry-mode</B> <DD>
|
|
Send a special control message used by some newer Blackberry devices
|
|
<DT id="31"><B>-S</B> <B>--option-mode</B> <DD>
|
|
Send a special control message used by all Option devices
|
|
<DT id="32"><B>-O</B> <B>--sony-mode</B> <DD>
|
|
Apply a special sequence used by Sony Ericsson devices. Implies option --check-success
|
|
<DT id="33"><B>-L</B> <B>--cisco-mode</B> <DD>
|
|
Send a sequence of bulk messages used by Cisco devices
|
|
<DT id="34"><B>-R</B> <B>--reset-usb</B> <DD>
|
|
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
|
|
<DT id="35"><B>-c</B> <B>--config-file FILENAME</B> <DD>
|
|
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
|
|
<DT id="36"><B>-f</B> <B>--long-config STRING</B> <DD>
|
|
Provide device details in config file syntax as a multiline string
|
|
on the command line
|
|
<DT id="37"><B>-t</B> <B>--stdinput</B> <DD>
|
|
Read the device details in config file syntax from standard input, e.g. redirected from
|
|
a command pipe (multiline text)
|
|
<DT id="38"><B>-Q</B> <B>--quiet</B> <DD>
|
|
Don't show progress or error messages
|
|
<DT id="39"><B>-W</B> <B>--verbose</B> <DD>
|
|
Print all settings before running and show libusb debug messages
|
|
<DT id="40"><B>-D</B> <B>--sysmode</B> <DD>
|
|
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
|
|
<DT id="41"><B>-s</B> <B>--check-success NUM</B> <DD>
|
|
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
|
|
<DT id="42"><B>-I</B> <B>--inquire</B> <DD>
|
|
Obsolete. Formerly obtained SCSI attributes, now ignored
|
|
<DT id="43"><B>-i</B> <B>--interface NUM</B> <DD>
|
|
Select initial USB interface (default: 0). Only for testing purposes
|
|
<DT id="44"><B>-u</B> <B>--configuration NUM</B> <DD>
|
|
Select USB configuration (applied after any other possible switching actions)
|
|
<DT id="45"><B>-a</B> <B>--altsetting NUM</B> <DD>
|
|
Select alternative USB interface setting (applied after switching). Mainly
|
|
for testing
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
<P>
|
|
|
|
This manual page was originally written by Didier Raboud (<A HREF="mailto:didier@raboud.com">didier@raboud.com</A>) for
|
|
the <B>Debian</B> 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.
|
|
<P>
|
|
<P>
|
|
|
|
The complete text of the current GNU General Public
|
|
License can be found in <A HREF="http://www.gnu.org/licenses/gpl.txt">http://www.gnu.org/licenses/gpl.txt</A>
|
|
<P>
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="46"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="47"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="48"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="49"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT id="50"><A HREF="#lbAF">AUTHOR</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:29 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|