1 README for USB_ModeSwitch
3 For up-to-date and more detailed information (plus a friendly forum) visit
4 http://www.draisberghof.de/usb_modeswitch
10 USB_ModeSwitch is (surprise!) a small mode switching tool for controlling
11 "flip flop" (multiple mode) USB devices.
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.
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.
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.
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.
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!
49 !! You need the usb-modeswitch-data package from the same source as this !!
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.
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.
63 To install the tool set, unpack and in the newly created directory use this line
64 at the shell (as root):
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
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.
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"
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.
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.
89 To run the program use it from the source folder or put it somewhere into your
90 path (preferably "/sbin" or "/usr/sbin").
92 Note: manual use is intended for testing and analyzing !
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.
99 /lib/udev/rules.d/40-usb_modeswitch.rules
101 Then add your new setup file to the folder
102 "/etc/usb_modeswitch.d". And don't forget to report your success !!
105 Important: libusb programs - like this tool - need to be run as root!
110 Known working hardware, Troubleshooting
111 =======================================
113 Please see the homepage. Read carefully.
114 For support questions use ONLY the forum.
121 USB_ModeSwitch comes quite handy for experimenting with your own hardware if
122 not supported yet. You could try this approach:
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
128 "SniffUSB" (http://benoit.papillault.free.fr/usbsnoop/index.php.en).
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)!
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!)
141 Command line parsing, decent usage/config output and handling, advanced options
143 Joakim Wennergren (jokedst) (gmail.com)
145 TargetClass parameter implementation to support new Option devices/firmware:
146 Paul Hardwick (http://www.pharscape.org)
148 Created with initial help from:
149 "usbsnoop2libusb.pl" by Timo Lindfors
150 (http://iki.fi/lindi/usb/usbsnoop2libusb.pl)
152 Config file parsing stuff borrowed from:
153 Guillaume Dargaud (http://www.gdargaud.net/Hack/SourceCode.html)
155 Hexstr2bin function borrowed from:
156 Jouni Malinen (http://hostap.epitest.fi/wpa_supplicant, from "common.c")
158 Code, fixes and ideas from:
168 Yaroslav Levandovskiy
176 Device information contributors are named in the "device_reference.txt" file.
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
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:
191 http://www.gnu.org/licenses/gpl.txt
193 Or find it as the file COPYING in this folder.
198 Last revised: 2011-02-24, Josua Dietze