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