release/src/router/usbmodeswitch/README

   1 README for USB_ModeSwitch
   2
   3 For up-to-date and more detailed information (plus a friendly forum) visit
   4 http://www.draisberghof.de/usb_modeswitch
   5
   6
   7 What it is
   8 ==========
   9
  10 USB_ModeSwitch is - hardly surprising -  a mode switching tool for controlling
  11 USB devices with multiple "modes". Now, what does THAT mean?
  12
  13 More and more USB devices have their MS Windows drivers onboard; when plugged
  14 in for the first time they act like a flash storage and offer their driver
  15 installation from there.
  16 After installation (and on every consecutive plugging) the driver switches the
  17 mode internally by sending a certain command sequence; the storage device
  18 vanishes (in most cases) and a different device - like a USB modem - shows up.
  19 To the host, this is like unplugging one device and then plugging annother.
  20
  21 At first this feature appeared on devices with cell phone chipsets, presumably
  22 because some of them were already able to change the mode of their USB port
  23 from storage to communication - so why not make use of this in a modem stick?
  24 Modem maker "Option" calls that feature "ZeroCD (TM)" since it eliminates the
  25 need for shipping a separate driver carrier.
  26
  27 In the beginning, nothing of this was documented in any form and there was
  28 hardly any Linux/Unix support available.
  29 On the good side, most of the known devices are working out of the box in all
  30 modes with available Linux modules like "usb-storage" or serial USB drivers.
  31 That leaves only the problem of the mode-switching from storage to whatever
  32 the thing is supposed to do.
  33
  34 Fortunately there are things like human smartness, USB sniffing programs and
  35 LibUSB. The obvious way is to eavesdrop on the communication of the MS Windows
  36 driver, to isolate the command or action that does the switching, and then re-
  37 play the same sequence in a non-Windows system.
  38
  39 In theory, this task could also be handled on the kernel driver level, but a
  40 userspace program is much more flexible and can easily be disabled if access
  41 to the initial mode of those devices should be desired. There has been a
  42 principle decision by kernel developers to keep mode-switching outside of the
  43 kernel.
  44
  45 So USB_ModeSwitch has evolved to make this process easy to handle by taking the
  46 relevant parameters from configuration files and handling all initialization
  47 and communication business, with essential help from "libusb".
  48
  49 In Linux and friends it is intended to work automatically - via udev events
  50 and rules - and doing the mode switch without any user interaction.
  51 However, the core C program should be as portable als libusb itself; it does not
  52 rely on specific Linux features.
  53 It can also be run as an interactive command line tool, particularly useful when
  54 trying to tinker with hitherto unknown devices.
  55
  56 We have already collected a wide range of information on how to mode-switch all
  57 sorts of devices. If you run into a new one that is unknown yet, don't despair:
  58 we can find out what you need to do!
  59
  60
  61 How to install
  62 ==============
  63
  64 If you only need the core C program, just run "make". All further steps de-
  65 scribed below are referring to a common, fairly current Linux system where
  66 USB_ModeSwitch is expected to do its work automatically.
  67
  68 !! You need the usb-modeswitch-data package from the same source as this !!
  69
  70 If you have an earlier version installed, de-installation is recommended ("make
  71 uninstall") but not mandatory. The wrapper script location changed in 1.1.0;
  72 old files might be orphaned but will not do any harm.
  73
  74 The main prerequisite for installing from source is the development package for
  75 "libusb". It may be called "libusb-dev" or similar in your distribution. From
  76 usb_modeswitch 2.0.0 on, it should have an "1.x" in the name to reflect the change
  77 to libusb-1. There are also variants around called "libusbx" if libusb-1 is not
  78 available on your distribution.
  79
  80 To install the tool set, unpack and run the install command (see below) in the
  81 newly created directory.
  82
  83 From version 1.2.0, there are three flavours of installing. The only difference
  84 between those is the way the dispatcher is installed, but this affects the
  85 dependencies as well:
  86
  87 1. If you have the "Tcl" scripting language available on your system (packages
  88    "tcl" or "jimsh"), use the light-weight installation:
  89
  90    # make install
  91
  92 2. If you are size-constrained and have the Jimsh library on your system
  93    (package "libjim-dev"), you can have the Tcl interpreter embedded with the
  94    dispatcher, using its shared lib:
  95
  96    # make install-shared
  97
  98 3. If you are size-constrained and definitely don't need a Tcl interpreter
  99    for anything else, choose the statically embedded flavour. This will have
 100    no further dependency as it uses the included interpreter code, which is
 101    configured for small size:
 102
 103    # make install-static
 104
 105 Note that the "static"/"shared" targets are NOT referring to the usb_modeswitch
 106 program, only to the dispatcher!
 107 Any one of these commands will install a small posix shell script, the
 108 dispatcher (wrapper) as script or as binary, a global config file, the core
 109 program and a man page.
 110
 111 Install the data package as well and you are set.
 112
 113 NOTE: installing over (possibly outdated) Linux distribution packages of this
 114 program and the data collection should not be a problem.
 115
 116
 117 How to use
 118 ==========
 119
 120 If your device is known, you should be able to just plug it and use it. If
 121 it doesn't work - we will find out why.
 122
 123 For manual use just run "usb_modeswitch" (as root). Work with the command
 124 line interface or with a setup file. You can use any file and give its path
 125 with the "-c" parameter.
 126 The file named "device_reference.txt" that you can find on the home site of
 127 this package is a device and configuration reference containing most known
 128 devices; you can use it as a "database" to create your own configuration file.
 129 It's heavily commented and should tell you what to do. It also contains a
 130 thorough explanation of all the parameters.
 131
 132 Run "usb_modeswitch -h" to list the command line parameters.
 133 See also the provided man page.
 134
 135 Important note: Manual use is mainly intended for testing and analyzing!!
 136 The program puts no limits on what you can send to your USB device, so I
 137 assume it is possible to screw it up profoundly.
 138
 139 Once your new device is switching fine you can add it to the data files to
 140 make the process automatic.
 141
 142 For this to work, add a rule entry to the rules file to let udev run
 143 usb_modeswitch as soon as the default IDs are found (when the device is
 144 plugged). If you look into the rules file you will see immediately how
 145 your new entry should look like.
 146 The location is:
 147 /lib/udev/rules.d/40-usb_modeswitch.rules
 148
 149 Then add your new config file to the folder
 150 "/etc/usb_modeswitch.d" (only for custom config files!).
 151 And don't forget to report your success !!
 152
 153 Again, remember that the rules file and the default device config folder
 154 (/usr/share/usb_modeswitch) are installed by the usb_modeswitch data package.
 155
 156
 157 ##########
 158 Important: libusb programs - like this tool - want to be run with administrative
 159 privileges (as root or with sudo)!
 160 ##########
 161
 162
 163
 164 Known working hardware, Troubleshooting
 165 =======================================
 166
 167 Please go to the homepage (see link at the top). Read carefully.
 168 For support questions use ONLY public posts in the forum.
 169
 170
 171
 172 Contribute
 173 ==========
 174
 175 USB_ModeSwitch comes quite handy for experimenting with your own hardware if
 176 not supported yet. You could try this approach:
 177
 178 Note the device's vendor and product ID from /proc/bus/usb/devices (or from the
 179 output of lsusb); the assigned driver is usually "usb-storage". Then try spying
 180 on the USB communication to the device with the same ID inside MS Windoze. I
 181 recommend this tool:
 182 "SniffUSB" (http://benoit.papillault.free.fr/usbsnoop/index.php.en).
 183
 184 PLEASE post any improvements, new device information and/or bug reports to the
 185 forum (see above) or send it to the author (see below)!
 186
 187
 188 Whodunit
 189 ========
 190
 191 Copyright 2007 - 2015 Josua Dietze (for non-support notifications write a personal
 192 message through the forum to "Josh"; everything else only in a forum thread)
 193
 194  !!! NO SUPPORT QUESTIONS VIA E-MAIL, use the forum !!!
 195
 196 Major contributions:
 197
 198 Command line parsing and other essential contributions:
 199  Joakim Wennergren
 200
 201 TargetClass parameter implementation to support new Option devices/firmware:
 202  Paul Hardwick (http://www.pharscape.org)
 203
 204 Created with initial help from:
 205  "usbsnoop2libusb.pl" by Timo Lindfors
 206  (http://iki.fi/lindi/usb/usbsnoop2libusb.pl)
 207
 208 Config file parsing code borrowed from:
 209  Guillaume Dargaud (http://www.gdargaud.net/Hack/SourceCode.html)
 210
 211 Hexstr2bin function borrowed from:
 212  Jouni Malinen (http://hostap.epitest.fi/wpa_supplicant, from "common.c")
 213
 214 Indispensable help with device research and compilation:
 215  Lars Melin
 216
 217 Code, fixes and ideas contributed by:
 218  Aki Makkonen
 219  Denis Sutter
 220  Lucas Benedicic
 221  Roman Laube
 222  Luigi Iotti
 223  Vincent Teoh
 224  Tommy Cheng
 225  Daniel Cooper
 226  Andrew Bird
 227  Yaroslav Levandovskiy
 228  Sakis Dimopoulos
 229  Steven Fernandez
 230  Christophe Fergeau
 231  Nils Radtke
 232  Filip Aben
 233  Amit Mendapara
 234  Roman S. Samarev
 235  Chi-Hang Long
 236  Andrey Tikhomirov
 237  Daniel Mende
 238  Nicholas Carrier
 239  Adam Goode
 240  Leonid Lisovskiy
 241  Vladislav Grishenko
 242  Daniel Drake
 243
 244 Device information contributors are named in the "device_reference.txt" file.
 245
 246 JimTcl is currently maintained by Steve Bennett; see README in subfolder
 247  for details. It is released under a FreeBSD-style license.
 248  Visit http://jim.tcl.tk/
 249
 250
 251
 252 Legal
 253 =====
 254
 255 This program is free software; you can redistribute it and/or modify it under
 256 the terms of the GNU General Public License as published by the Free Software
 257 Foundation; either version 2 of the License, or (at your option) any later
 258 version.
 259
 260 This program is distributed in the hope that it will be useful, but WITHOUT ANY
 261 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
 262 PARTICULAR PURPOSE.  See the GNU General Public License for more details:
 263
 264 http://www.gnu.org/licenses/gpl.txt
 265
 266 Or find it as the file COPYING in this folder.
 267
 268
 269
 270
 271 Last revised: 2016-06-12, Josua Dietze