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