-
Notifications
You must be signed in to change notification settings - Fork 2
/
README
254 lines (181 loc) · 8.8 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
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.
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, the storage device vanishes (in most cases), and a new device
(like an USB modem) shows up.
At first this feature appeared on devices with cell phone chipsets, presumably
because some of them were able to change the mode of their USB port anyway
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 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 the Unix system.
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".
In Linux and friends it is intended to be used automatically - via udev events
and rules - and doing the mode switch without any user interaction.
However, the core program should be as portable als libusb itself; it does not
rely on specific Linux features.
It can be run as an interactive command line tool, particularly useful when trying
to manage hitherto unknown devices.
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 the development package for
"libusb". It may be called "libusb-dev" or similar in your distribution. From
usb_modeswitch 2.0.0 it should have an "1.x" in the name to reflect the change
to libusb-1.
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 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 - 2014 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 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
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: 2014-01-28, Josua Dietze