231 lines
7.8 KiB
Plaintext
231 lines
7.8 KiB
Plaintext
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 (surprise!) a small mode switching tool for controlling
|
|
"flip flop" (multiple mode) USB devices.
|
|
|
|
Several new USB devices (especially high-speed WAN stuff, based on cell phone
|
|
chipsets containing that feature) have their MS Windows drivers onboard; when
|
|
plugged in for the first time they act like a flash storage and start
|
|
installing the driver from there.
|
|
After installation (and on every consecutive plugging) the driver switches the
|
|
mode internally, the storage device vanishes (in most cases), and a new device
|
|
(like an USB modem) shows up. 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 support available.
|
|
On the good side, most of the known devices are working out of the box in all
|
|
modes with the 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 intelligence, USB sniffing programs and
|
|
"libusb". It is possible to eavesdrop the communication of the MS Windows
|
|
driver, to isolate the command or action that does the switching, and to replay
|
|
the same sequence in Linux.
|
|
|
|
USB_ModeSwitch makes this process easy to handle by taking the relevant para-
|
|
meters from a configuration file and doing all the initialization and communi-
|
|
cation stuff, with heavy help from "libusb".
|
|
It is mainly used automatically - via udev events and rules - to do the switch
|
|
without any user interaction. But it can also be run as a command line tool,
|
|
usually when trying to make unknown devices work.
|
|
|
|
We have already collected a wide range of information on how to 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
|
|
==============
|
|
|
|
!! 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 package "libusb-dev" !!
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
|
|
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.
|
|
|
|
Note: Manual use is mainly intended for testing and analyzing !
|
|
|
|
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 as root!
|
|
##########
|
|
|
|
|
|
|
|
Known working hardware, Troubleshooting
|
|
=======================================
|
|
|
|
Please see the homepage. Read carefully.
|
|
For support questions use ONLY 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, 2008, 2009, 2010, 2011 Josua Dietze (mail to "usb_admin"
|
|
at the domain "draisberghof.de" or write a personal message through the forum
|
|
to "Josh")
|
|
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")
|
|
|
|
Code, fixes and ideas from:
|
|
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
|
|
|
|
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.berlios.de/
|
|
|
|
|
|
|
|
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: 2011-12-26, Josua Dietze
|