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, particularly 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) Linux distribution packages of this
|
program and the data collection should 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.
|
|
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.
|
|
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.
|
|
|
|
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. I
|
recommend this tool:
|
"SniffUSB" (http://benoit.papillault.free.fr/usbsnoop/index.php.en).
|
|
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 - 2015 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
|
Daniel Drake
|
|
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: 2016-06-12, Josua Dietze
|
