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 Several new USB devices (especially high-speed WAN stuff, based on cell phone
  14 chipsets containing that feature) have their MS Windows drivers onboard; when
  15 plugged in for the first time they act like a flash storage and start
  16 installing the driver from there.
  17 After installation (and on every consecutive plugging) the driver switches the
  18 mode internally, the storage device vanishes (in most cases), and a new device
  19 (like an USB modem) shows up. Modem maker "Option" calls that feature "ZeroCD
  20 (TM)" since it eliminates the need for shipping a separate driver carrier.
  21
  22 In the beginning, nothing of this was documented in any form and there was
  23 hardly any Linux support available.
  24 On the good side, most of the known devices are working out of the box in all
  25 modes with the available Linux modules like "usb-storage" or serial USB drivers.
  26 That leaves only the problem of the mode-switching from storage to whatever
  27 the thing is supposed to do.
  28
  29 Fortunately there are things like human intelligence, USB sniffing programs and
  30 "libusb". It is possible to eavesdrop the communication of the MS Windows
  31 driver, to isolate the command or action that does the switching, and to replay
  32 the same sequence in Linux.
  33
  34 USB_ModeSwitch makes this process easy to handle by taking the relevant para-
  35 meters from a configuration file and doing all the initialization and communi-
  36 cation stuff, with heavy help from "libusb".
  37 It is mainly used automatically - via udev events and rules - to do the switch
  38 without any user interaction. But it can also be run as a command line tool,
  39 usually when trying to make unknown devices work with it.
  40
  41 We have already collected a wide range of information on how to switch all
  42 sorts of devices. If you run into a new one that is unknown yet, don't despair:
  43 we can find out what you need to do!
  44
  45
  46 How to install
  47 ==============
  48
  49 !! You need the usb-modeswitch-data package from the same source as this !!
  50
  51 If you have an earlier version installed, de-installation is recommended ("make
  52 uninstall"). The wrapper script location changed in 1.1.0, old ones might be
  53 orphaned in /usr/sbin.
  54
  55 Important: you need "tcl" for the wrapper script to work; if you enter "tclsh"
  56 and you get a "%" prompt, you are set (to exit type "exit"). The "tcl" package
  57 is part of all distributions I know. Use version 8.4 and higher.
  58 If you are space-restricted you can also use the "jimsh" mini Tcl interpreter. The
  59 Tcl wrapper is compatible with the limited command set of this small shell. Since
  60 version 1.1.7 an alternative source package containing jimsh will be provided.
  61 The typical size of jimsh is 140 kB, or 70 kB in a compressed file system.
  62
  63 To install the tool set, unpack and in the newly created directory use this line
  64 at the shell (as root):
  65
  66 > make install
  67
  68 This installs the small shell script, the dispatcher (wrapper) script, a global
  69 config file, the binary and a man page. If you chose the package with jimsh, the
  70 Tcl shell is configured, built and installed in the same step, optimized for
  71 size.
  72
  73 Install the data package as well and you are set already; if your device is
  74 known, you should be able to just plug it and use it. If it doesn't work -
  75 we will find out why not.
  76
  77 For manual use just run "usb_modeswitch" (as root). Work with the command
  78 line interface or with a setup file. You can use any file and give its path
  79 with the "-c" parameter.
  80 The file named "device_reference.txt" that you can find in this package is
  81 a device and configuration reference containing most known devices; you can
  82 use it as a base to create your own configuration file.
  83 It's heavily commented and should tell you what to do. It also contains a
  84 thorough explanation of all the parameters.
  85
  86 Run "usb_modeswitch -h" to list the command line parameters.
  87 See also the provided man page.
  88
  89 Note: manual use is intended for testing and analyzing !
  90
  91 Once your new device is switching fine you can add a rule entry to the rules
  92 file to let udev run usb_modeswitch as soon as the default IDs are found
  93 (when the device is plugged). If you look into the rules file you will see
  94 immediately how your new entry should look like.
  95 The location is:
  96 /lib/udev/rules.d/40-usb_modeswitch.rules
  97
  98 Then add your new setup file to the folder
  99 "/usr/share/usb_modeswitch". And don't forget to report your success !!
 100
 101 Again, mind that the rules file and the config folder are installed by
 102 the usb_modeswitch data package.
 103
 104
 105 ##########
 106 Important: libusb programs - like this tool - want to be run as root!
 107 ##########
 108
 109
 110
 111 Known working hardware, Troubleshooting
 112 =======================================
 113
 114 Please see the homepage. Read carefully.
 115 For support questions use ONLY the forum.
 116
 117
 118
 119 Contribute
 120 ==========
 121
 122 USB_ModeSwitch comes quite handy for experimenting with your own hardware if
 123 not supported yet. You could try this approach:
 124
 125 Note the device's vendor and product ID from /proc/bus/usb/devices (or from the
 126 output of lsusb); the assigned driver is usually "usb-storage". Then try spying
 127 on the USB communication to the device with the same ID inside M$ Windoze. I
 128 recommend this tool:
 129 "SniffUSB" (http://benoit.papillault.free.fr/usbsnoop/index.php.en).
 130
 131 PLEASE post any improvements, new device information and/or bug reports to the
 132 forum (see above) or send it to the author (see below)!
 133
 134
 135 Whodunit
 136 ========
 137
 138 Copyright 2007, 2008, 2009, 2010 Josua Dietze (mail to "usb_admin"
 139  at the domain "draisberghof.de" or write a personal message through the forum
 140  to "Josh"; NO SUPPORT QUESTIONS VIA E-MAIL, use the forum!)
 141
 142 Command line parsing, decent usage/config output and handling, advanced options
 143  and bugfixes:
 144  Joakim Wennergren (jokedst) (gmail.com)
 145
 146 TargetClass parameter implementation to support new Option devices/firmware:
 147  Paul Hardwick (http://www.pharscape.org)
 148
 149 Created with initial help from:
 150  "usbsnoop2libusb.pl" by Timo Lindfors
 151  (http://iki.fi/lindi/usb/usbsnoop2libusb.pl)
 152
 153 Config file parsing stuff borrowed from:
 154  Guillaume Dargaud (http://www.gdargaud.net/Hack/SourceCode.html)
 155
 156 Hexstr2bin function borrowed from:
 157  Jouni Malinen (http://hostap.epitest.fi/wpa_supplicant, from "common.c")
 158
 159 Code, fixes and ideas from:
 160  Aki Makkonen
 161  Denis Sutter
 162  Lucas Benedicic
 163  Roman Laube
 164  Luigi Iotti
 165  Vincent Teoh
 166  Tommy Cheng
 167  Daniel Cooper
 168  Andrew Bird
 169  Yaroslav Levandovskiy
 170  Sakis Dimopoulos
 171  Steven Fernandez
 172  Christophe Fergeau
 173  Nils Radtke
 174  Filip Aben
 175  Amit Mendapara
 176
 177 Device information contributors are named in the "device_reference.txt" file.
 178
 179
 180 Legal
 181 =====
 182
 183 This program is free software; you can redistribute it and/or modify it under
 184 the terms of the GNU General Public License as published by the Free Software
 185 Foundation; either version 2 of the License, or (at your option) any later
 186 version.
 187
 188 This program is distributed in the hope that it will be useful, but WITHOUT ANY
 189 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
 190 PARTICULAR PURPOSE.  See the GNU General Public License for more details:
 191
 192 http://www.gnu.org/licenses/gpl.txt
 193
 194 Or find it as the file COPYING in this folder.
 195
 196
 197
 198
 199 Last revised: 2011-02-25, Josua Dietze