X7ROOT File Manager
Current Path:
/usr/share/doc/usb_modeswitch-2.5.1
usr
/
share
/
doc
/
usb_modeswitch-2.5.1
/
📁
..
📄
COPYING
(17.57 KB)
📄
ChangeLog
(17.87 KB)
📄
README
(9.97 KB)
📄
device_reference.txt
(76.94 KB)
Editing: README
README for USB_ModeSwitch For up-to-date and more detailed information (plus a friendly forum) visit http://www.draisberghof.de/usb_modeswitch What it is ========== USB_ModeSwitch is - hardly surprising - a mode switching tool for controlling USB devices with multiple "modes". Now, what does THAT mean? More and more USB devices have their MS Windows drivers onboard; when plugged in for the first time they act like a flash storage and offer their driver installation from there. After installation (and on every consecutive plugging) the driver switches the mode internally by sending a certain command sequence; the storage device vanishes (in most cases) and a different device - like a USB modem - shows up. To the host, this is like unplugging one device and then plugging annother. At first this feature appeared on devices with cell phone chipsets, presumably because some of them were already able to change the mode of their USB port from storage to communication - so why not make use of this in a modem stick? Modem maker "Option" calls that feature "ZeroCD (TM)" since it eliminates the need for shipping a separate driver carrier. In the beginning, nothing of this was documented in any form and there was hardly any Linux/Unix support available. On the good side, most of the known devices are working out of the box in all modes with available Linux modules like "usb-storage" or serial USB drivers. That leaves only the problem of the mode-switching from storage to whatever the thing is supposed to do. Fortunately there are things like human smartness, USB sniffing programs and LibUSB. The obvious way is to eavesdrop on the communication of the MS Windows driver, to isolate the command or action that does the switching, and then re- play the same sequence in a non-Windows system. In theory, this task could also be handled on the kernel driver level, but a userspace program is much more flexible and can easily be disabled if access to the initial mode of those devices should be desired. There has been a principle decision by kernel developers to keep mode-switching outside of the kernel. So USB_ModeSwitch has evolved to make this process easy to handle by taking the relevant parameters from configuration files and handling all initialization and communication business, with essential help from "libusb". In Linux and friends it is intended to work automatically - via udev events and rules - and doing the mode switch without any user interaction. However, the core C program should be as portable als libusb itself; it does not rely on specific Linux features. It can also be run as an interactive command line tool, which can be useful when trying to tinker with hitherto unknown devices. We have already collected a wide range of information on how to mode-switch all sorts of devices. If you run into a new one that is unknown yet, don't despair: we can find out what you need to do! How to install ============== If you only need the core C program, just run "make". All further steps de- scribed below are referring to a common, fairly current Linux system where USB_ModeSwitch is expected to do its work automatically. !! You need the usb-modeswitch-data package from the same source as this !! If you have an earlier version installed, de-installation is recommended ("make uninstall") but not mandatory. The wrapper script location changed in 1.1.0; old files might be orphaned but will not do any harm. The main prerequisite for installing from source is the development package for "libusb". It may be called "libusb-dev" or similar in your distribution. From usb_modeswitch 2.0.0 on, it should have an "1.x" in the name to reflect the change to libusb-1. There are also variants around called "libusbx" if libusb-1 is not available on your distribution. To install the tool set, unpack and run the install command (see below) in the newly created directory. From version 1.2.0, there are three flavours of installing. The only difference between those is the way the dispatcher is installed, but this affects the dependencies as well: 1. If you have the "Tcl" scripting language available on your system (packages "tcl" or "jimsh"), use the light-weight installation: # make install 2. If you are size-constrained and have the Jimsh library on your system (package "libjim-dev"), you can have the Tcl interpreter embedded with the dispatcher, using its shared lib: # make install-shared 3. If you are size-constrained and definitely don't need a Tcl interpreter for anything else, choose the statically embedded flavour. This will have no further dependency as it uses the included interpreter code, which is configured for small size: # make install-static Note that the "static"/"shared" targets are NOT referring to the usb_modeswitch program, only to the dispatcher! Any one of these commands will install a small posix shell script, the dispatcher (wrapper) as script or as binary, a global config file, the core program and a man page. Install the data package as well and you are set. NOTE: installing over (possibly outdated) distribution packages of this program and the data collection should generally not be a problem. How to use ========== If your device is known, you should be able to just plug it and use it. If it doesn't work - we will find out why. For manual use just run "usb_modeswitch" (as root). Work with the command line interface or with a setup file. You can use any file and give its path with the "-c" parameter. The file named "device_reference.txt" that you can find on the home site of this package is a device and configuration reference containing most known devices; you can use it as a "database" to create your own configuration file. It's heavily commented and should tell you what to do. It also contains a thorough explanation of all the parameters. However, the device list in that reference file is no longer maintained. See the data package for the USB IDs of devices known to usb_modeswitch. Run "usb_modeswitch -h" to list the command line parameters. See also the provided man page. Important note: Manual use is mainly intended for testing and analyzing!! The program puts no limits on what you can send to your USB device, so I assume it is possible to screw it up profoundly. You have been warned. Once your new device is switching fine you can add it to the data files to make the process automatic. For this to work, add a rule entry to the rules file to let udev run usb_modeswitch as soon as the default IDs are found (when the device is plugged). If you look into the rules file you will see immediately how your new entry should look like. The location is: /lib/udev/rules.d/40-usb_modeswitch.rules Then add your new config file to the folder "/etc/usb_modeswitch.d" (only for custom config files!). And don't forget to report your success !! Again, remember that the rules file and the default device config folder (/usr/share/usb_modeswitch) are installed by the usb_modeswitch data package. ########## Important: libusb programs - like this tool - want to be run with administrative privileges (as root or with sudo)! ########## Known working hardware, Troubleshooting ======================================= Please go to the homepage (see link at the top). Read carefully. For support questions use ONLY public posts in the forum. Again - to see the USB IDs of known devices, see the data package. Contribute ========== USB_ModeSwitch comes quite handy for experimenting with your own hardware if not supported yet. You could try this approach: Note the device's vendor and product ID from /proc/bus/usb/devices (or from the output of lsusb); the assigned driver is usually "usb-storage". Then try spying on the USB communication to the device with the same ID inside MS Windoze. Nowadays the standard tool for this is Wireshark/USBPcap. PLEASE post any improvements, new device information and/or bug reports to the forum (see above) or send it to the author (see below)! Whodunit ======== Copyright 2007 - 2017 Josua Dietze (for non-support notifications write a personal message through the forum to "Josh"; everything else only in a forum thread) !!! NO SUPPORT QUESTIONS VIA E-MAIL, use the forum !!! Major contributions: Command line parsing and other essential contributions: Joakim Wennergren TargetClass parameter implementation to support new Option devices/firmware: Paul Hardwick (http://www.pharscape.org) Created with initial help from: "usbsnoop2libusb.pl" by Timo Lindfors (http://iki.fi/lindi/usb/usbsnoop2libusb.pl) Config file parsing code borrowed from: Guillaume Dargaud (http://www.gdargaud.net/Hack/SourceCode.html) Hexstr2bin function borrowed from: Jouni Malinen (http://hostap.epitest.fi/wpa_supplicant, from "common.c") Indispensable help with device research and compilation: Lars Melin Code, fixes and ideas contributed by: Aki Makkonen Denis Sutter Lucas Benedicic Roman Laube Luigi Iotti Vincent Teoh Tommy Cheng Daniel Cooper Andrew Bird Yaroslav Levandovskiy Sakis Dimopoulos Steven Fernandez Christophe Fergeau Nils Radtke Filip Aben Amit Mendapara Roman S. Samarev Chi-Hang Long Andrey Tikhomirov Daniel Mende Nicholas Carrier Adam Goode Leonid Lisovskiy Vladislav Grishenko Lubomir Rintel Device information contributors are named in the "device_reference.txt" file. JimTcl is currently maintained by Steve Bennett; see README in subfolder for details. It is released under a FreeBSD-style license. Visit http://jim.tcl.tk/ Legal ===== This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details: http://www.gnu.org/licenses/gpl.txt Or find it as the file COPYING in this folder. Last revised: 2017-01-16, Josua Dietze
Upload File
Create Folder