release/src/router/usbmodeswitch/usb_modeswitch.1

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