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 the development package for
  64 "libusb". It may be called "libusb-dev" or similar in your distribution. From
  65 usb_modeswitch 2.0.0 it should have an "1.x" in the name to reflect the change
  66 to libusb-1.
  67
  68 To install the tool set, unpack and run the install command (see below) in the
  69 newly created directory.
  70
  71 From version 1.2.0, there are three flavours of installing. The only difference
  72 between those is the way the dispatcher is installed, but this affects the
  73 dependencies as well:
  74
  75 1. If you have the "Tcl" scripting language available on your system (packages
  76    "tcl" or "jimsh"), use the light-weight installation:
  77
  78    # make install
  79
  80 2. If you are size-constrained and have the Jimsh library on your system
  81    (package "libjim-dev"), you can have the Tcl interpreter embedded with the
  82    dispatcher, using its shared lib:
  83
  84    # make install-shared
  85
  86 3. If you are size-constrained and definitely don't need a Tcl interpreter
  87    for anything else, choose the statically embedded flavour. This will have
  88    no further dependency as it uses the included interpreter code, which is
  89    configured for small size:
  90
  91    # make install-static
  92
  93 Note that the "static"/"shared" targets are NOT referring to the usb_modeswitch
  94 program, only to the dispatcher!
  95 Any one of these commands will install a small posix shell script, the
  96 dispatcher (wrapper) as script or as binary, a global config file, the core
  97 program and a man page.
  98
  99 Install the data package as well and you are set.
 100
 101 NOTE: installing over (possibly outdated) Linux distribution packages of this
 102 program and the data collection should not be a problem.
 103
 104
 105 How to use
 106 ==========
 107
 108 If your device is known, you should be able to just plug it and use it. If
 109 it doesn't work - we will find out why.
 110
 111 For manual use just run "usb_modeswitch" (as root). Work with the command
 112 line interface or with a setup file. You can use any file and give its path
 113 with the "-c" parameter.
 114 The file named "device_reference.txt" that you can find on the home site of
 115 this package is a device and configuration reference containing most known
 116 devices; you can use it as a "database" to create your own configuration file.
 117 It's heavily commented and should tell you what to do. It also contains a
 118 thorough explanation of all the parameters.
 119
 120 Run "usb_modeswitch -h" to list the command line parameters.
 121 See also the provided man page.
 122
 123 Important note: Manual use is mainly intended for testing and analyzing!!
 124 The program puts no limits on what you can send to your USB device, so I
 125 assume it is possible to screw it up profoundly.
 126
 127 Once your new device is switching fine you can add it to the data files to
 128 make the process automatic.
 129
 130 For this to work, add a rule entry to the rules file to let udev run
 131 usb_modeswitch as soon as the default IDs are found (when the device is
 132 plugged). If you look into the rules file you will see immediately how
 133 your new entry should look like.
 134 The location is:
 135 /lib/udev/rules.d/40-usb_modeswitch.rules
 136
 137 Then add your new config file to the folder
 138 "/etc/usb_modeswitch.d" (only for custom config files!).
 139 And don't forget to report your success !!
 140
 141 Again, remember that the rules file and the default device config folder
 142 (/usr/share/usb_modeswitch) are installed by the usb_modeswitch data package.
 143
 144
 145 ##########
 146 Important: libusb programs - like this tool - want to be run as root!
 147 ##########
 148
 149
 150
 151 Known working hardware, Troubleshooting
 152 =======================================
 153
 154 Please see the homepage. Read carefully.
 155 For support questions use ONLY the forum.
 156
 157
 158
 159 Contribute
 160 ==========
 161
 162 USB_ModeSwitch comes quite handy for experimenting with your own hardware if
 163 not supported yet. You could try this approach:
 164
 165 Note the device's vendor and product ID from /proc/bus/usb/devices (or from the
 166 output of lsusb); the assigned driver is usually "usb-storage". Then try spying
 167 on the USB communication to the device with the same ID inside MS Windoze. I
 168 recommend this tool:
 169 "SniffUSB" (http://benoit.papillault.free.fr/usbsnoop/index.php.en).
 170
 171 PLEASE post any improvements, new device information and/or bug reports to the
 172 forum (see above) or send it to the author (see below)!
 173
 174
 175 Whodunit
 176 ========
 177
 178 Copyright 2007, 2008, 2009, 2010, 2011, 2012 Josua Dietze (mail to "usb_admin"
 179  at the domain "draisberghof.de" or write a personal message through the forum
 180  to "Josh")
 181
 182  !!! NO SUPPORT QUESTIONS VIA E-MAIL, use the forum !!!
 183
 184 Major contributions:
 185
 186 Command line parsing and other essential contributions:
 187  Joakim Wennergren
 188
 189 TargetClass parameter implementation to support new Option devices/firmware:
 190  Paul Hardwick (http://www.pharscape.org)
 191
 192 Created with initial help from:
 193  "usbsnoop2libusb.pl" by Timo Lindfors
 194  (http://iki.fi/lindi/usb/usbsnoop2libusb.pl)
 195
 196 Config file parsing code borrowed from:
 197  Guillaume Dargaud (http://www.gdargaud.net/Hack/SourceCode.html)
 198
 199 Hexstr2bin function borrowed from:
 200  Jouni Malinen (http://hostap.epitest.fi/wpa_supplicant, from "common.c")
 201
 202 Code, fixes and ideas contributed by:
 203  Aki Makkonen
 204  Denis Sutter
 205  Lucas Benedicic
 206  Roman Laube
 207  Luigi Iotti
 208  Vincent Teoh
 209  Tommy Cheng
 210  Daniel Cooper
 211  Andrew Bird
 212  Yaroslav Levandovskiy
 213  Sakis Dimopoulos
 214  Steven Fernandez
 215  Christophe Fergeau
 216  Nils Radtke
 217  Filip Aben
 218  Amit Mendapara
 219  Roman S. Samarev
 220  Chi-Hang Long
 221  Andrey Tikhomirov
 222  Daniel Mende
 223  Nicholas Carrier
 224  Adam Goode
 225  Leonid Lisovskiy
 226  Vladislav Grishenko
 227
 228 Device information contributors are named in the "device_reference.txt" file.
 229
 230 JimTcl is currently maintained by Steve Bennett; see README in subfolder
 231  for details. It is released under a FreeBSD-style license.
 232  Visit http://jim.tcl.tk/
 233
 234
 235
 236 Legal
 237 =====
 238
 239 This program is free software; you can redistribute it and/or modify it under
 240 the terms of the GNU General Public License as published by the Free Software
 241 Foundation; either version 2 of the License, or (at your option) any later
 242 version.
 243
 244 This program is distributed in the hope that it will be useful, but WITHOUT ANY
 245 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
 246 PARTICULAR PURPOSE.  See the GNU General Public License for more details:
 247
 248 http://www.gnu.org/licenses/gpl.txt
 249
 250 Or find it as the file COPYING in this folder.
 251
 252
 253
 254
 255 Last revised: 2013-09-01, Josua Dietze