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 work out of the box in all modes
  25 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 "make". Work with the command line interface or
  78 with a setup file. You can use any file and give its path with the "-c"
  79 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.
  84
  85 Run "usb_modeswitch -h" to list the command line parameters. If any of them
  86 except -W and -q are used, the default config file in /etc is NOT read.
  87 See also the provided man page.
  88
  89 To run the program use it from the source folder or put it somewhere into your
  90 path (preferably "/sbin" or "/usr/sbin").
  91
  92 Note: manual use is intended for testing and analyzing !
  93
  94 Once your new device is switching fine you can add a rule entry to the rules
  95 file to let udev run usb_modeswitch as soon as the default IDs are found
  96 (when the device is plugged). If you look into the rules file you will see
  97 immediately how your new entry should look like.
  98 The location is:
  99 /lib/udev/rules.d/40-usb_modeswitch.rules
 100
 101 Then add your new setup file to the folder
 102 "/etc/usb_modeswitch.d". And don't forget to report your success !!
 103
 104 ##########
 105 Important: libusb programs - like this tool - need to be run as root!
 106 ##########
 107
 108
 109
 110 Known working hardware, Troubleshooting
 111 =======================================
 112
 113 Please see the homepage. Read carefully.
 114 For support questions use ONLY the forum.
 115
 116
 117
 118 Contribute
 119 ==========
 120
 121 USB_ModeSwitch comes quite handy for experimenting with your own hardware if
 122 not supported yet. You could try this approach:
 123
 124 Note the device's Vendor and Product ID from /proc/bus/usb/devices (or from the
 125 output of lsusb); the assigned driver is usually "usb-storage". Then try spying
 126 on the USB communication to the device with the same ID inside M$ Windoze. I
 127 recommend this tool:
 128 "SniffUSB" (http://benoit.papillault.free.fr/usbsnoop/index.php.en).
 129
 130 PLEASE post any improvements, new device information and/or bug reports to the
 131 forum (see above) or send it to the author (see below)!
 132
 133
 134 Whodunit
 135 ========
 136
 137 Copyright 2007, 2008, 2009, 2010 Josua Dietze (mail to "usb_admin"
 138  at the domain "draisberghof.de" or write a personal message through the forum
 139  to "Josh"; NO SUPPORT QUESTIONS VIA E-MAIL, use the forum!)
 140
 141 Command line parsing, decent usage/config output and handling, advanced options
 142  and bugfixes:
 143  Joakim Wennergren (jokedst) (gmail.com)
 144
 145 TargetClass parameter implementation to support new Option devices/firmware:
 146  Paul Hardwick (http://www.pharscape.org)
 147
 148 Created with initial help from:
 149  "usbsnoop2libusb.pl" by Timo Lindfors
 150  (http://iki.fi/lindi/usb/usbsnoop2libusb.pl)
 151
 152 Config file parsing stuff borrowed from:
 153  Guillaume Dargaud (http://www.gdargaud.net/Hack/SourceCode.html)
 154
 155 Hexstr2bin function borrowed from:
 156  Jouni Malinen (http://hostap.epitest.fi/wpa_supplicant, from "common.c")
 157
 158 Code, fixes and ideas from:
 159  Aki Makkonen
 160  Denis Sutter
 161  Lucas Benedicic
 162  Roman Laube
 163  Luigi Iotti
 164  Vincent Teoh
 165  Tommy Cheng
 166  Daniel Cooper
 167  Andrew Bird
 168  Yaroslav Levandovskiy
 169  Sakis Dimopoulos
 170  Steven Fernandez
 171  Christophe Fergeau
 172  Nils Radtke
 173  Filip Aben
 174  Amit Mendapara
 175
 176 Device information contributors are named in the "device_reference.txt" file.
 177
 178
 179 Legal
 180 =====
 181
 182 This program is free software; you can redistribute it and/or modify it under
 183 the terms of the GNU General Public License as published by the Free Software
 184 Foundation; either version 2 of the License, or (at your option) any later
 185 version.
 186
 187 This program is distributed in the hope that it will be useful, but WITHOUT ANY
 188 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
 189 PARTICULAR PURPOSE.  See the GNU General Public License for more details:
 190
 191 http://www.gnu.org/licenses/gpl.txt
 192
 193 Or find it as the file COPYING in this folder.
 194
 195
 196
 197
 198 Last revised: 2011-02-24, Josua Dietze