stop-overpopulation.org - Life could be so good if there'd be fewer of us ...
metabunk.org - Remove the bunk from scary claims
This site is powered by Greenpeace Energy; for details see the provider's page
USB_ModeSwitch - Handling Mode-Switching USB Devices on Linux
- Introduction
- Download
- How to install
- How to use
- Known working hardware
- Troubleshooting
- Contribute
- Whodunit
- History
If you don't like the text column width, adjust your browser window
Introduction
USB_ModeSwitch is (surprise!) a mode switching tool for controlling "flip flop" (multiple device) USB gear.
More and more 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 do work in both modes with the available
Linux drivers like "usb-storage" or "option" (an optimized serial driver for high-speed
modems).
That leaves only the problem of the mode switching from storage to modem or whatever
the thing is supposed to do.
Fortunately there are things like human reason, USB sniffing programs and "libusb". It is possible to eavesdrop the communication of the MS Windows driver, to isolate the command or action that triggers the mode switching and to reproduce the same thing under the rule of Linux or the BSD variants.
USB_ModeSwitch makes this process easy to handle by taking the important parameters
from a configuration file and doing all the initialization and communication 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 with it.
This tool is part of most major distributions; you should not be having to install
from the source packages here unless you run into problems and need the latest version.
Please read the information on this page carefully before you go around posting questions! If you encounter a new device, it really helps to understand the principle of what is happening, which in turn makes it easier to find out about the switching command and to add a new config entry.
For hints about doing your own sniffing see paragraph Contribute below.
Download
The latest release version is 1.2.3. The tar archive contains only the source. I used libusb-0.1.12 but the "compat" library from libusb-1.0 is working too.
Important: you need the data package as well !!
Changes and updates to the configuration data may happen more often than new releases; most of the
valuable knowledge about devices is contained in these files. That's why it is provided separately.
- Download usb-modeswitch-1.2.3.tar.bz2, dated from 2012-01-28;
a Debian package should be available soon at the
Debian Repository. Many architectures are supported there (like amd64 or ia64).
Note that the Debian package is not 100% compatible with recent Ubuntu versions. - Download the usb-modeswitch-data package (2012-01-20). It contains the device database and the rules file, including full paths. You can use this package with program releases from 1.0.3 upward, but the latest devices and features may require the most recent program release too.
- The optional device_reference.txt from 2012-01-20; this is a collection of most device setups with their respective contributors; you can use it as a first resource if you want to make a new device working.
- Don't forget libusb if it's not on your system. In most distributions there is most likely a package named "libusb-dev" or "libusb-devel". Choose the legacy version (0.1.12) or the "compatible" package from libusb-1.0; last time I checked it had the version number 0.1.14.
The compiler was gcc (arm-none-linux-gnueabi 3.4.4) with no special settings. Libusb 0.1.12 is compiled in.
If you are a system integrator (package maintainer) you can use this XML file to check for new
releases:
usb-modeswitch-versions.xml.
How to install
If you have an earlier version installed, de-installation is recommended ("make uninstall"). Several file locations changed in 1.1.0, old ones might be orphaned if not taken care of. If you have a version after 1.1.0 you can just update and overwrite all existing files.Unpack the source file of the program (who might have thought!). In the newly created directory run as root or superuser:
# make installThis installs a small shell script for udev, the larger wrapper script, a config file, the man page and the freshly compiled binary.
Important: if you install this way, you will need the "tcl" package for the large dispatcher script. There are more ways to install which do not depend on that package. Refer to the included README for further install options !
Now do the same procedure for the data package. It will install the config files in
"/usr/share/usb_modeswitch" and the udev rule file in "/lib/udev/rules.d". The earlier
"/etc/usb_modeswitch.d" is now reserved for custom config files (new or changed).
You are set already; if your device is known, you should be able to just plug it and use it.
If it doesn't work right away we'll find out why.
For manual use just install the program. Work with the command line interface or use a custom config file.
The "device_reference" file (see "Download") is a good starting point to create your own configuration.
It is heavily commented and should tell you what to do.
Your custom config file can have any name and place; just tell usb_modeswitch how to find it with the
-c parameter.
Manual use is intended for testing and analyzing. See next paragraph.
How to use
In most cases, you will be able to use your device without any interaction except plugging it in.
If you think your device is supported, but things are not working out as they should, turn on logging first as described in Troubleshooting.
For testing, debugging and taming new devices from the wild, you can use the binary
part of USB_ModeSwitch in manual mode.
There are two ways for that: using a config file or using the command line.
Run "usb-modeswitch -h" to list the command line parameters. If any of them except -W, -D, -I and -q are used, a config file given with -c is ignored and all mandatory parameters have to be provided on the command line. See also the included man page.
To work with a config file, use one of the little files in "/usr/share/usb_modeswitch" or create one yourself. Then give the path and file name to usb_modeswitch with the -c option. You also can have a look into the device_reference.txt for hints about model families and an explanation of the parameters.
Important: USB_ModeSwitch - like all programs using libusb - has to be run as root (or with "sudo") when calling it manually. Otherwise strange error messages turn up and things won't work. When trying out switching commands and strategies, it's probably easier to work at a root shell for a while ("sudo bash" or "su -").
The automatic approach consists of several components working together, listed in the logical order of usage:
- /lib/udev/rules.d/40-usb_modeswitch.rules - the udev rules starting the wrapper
if a known device ID (vendor/product) is recognized.
If the switched device provides standard serial ports, a second rule calls the wrapper again and adds a symbolic link to the correct connection port (see below) - /lib/udev/usb_modeswitch - a shell script forking to the real wrapper script. Since version 1.1.6 the script is fully compatible with the "dash" shell used in Ubuntu as well as with older "bash" variants.
- /usr/sbin/usb_modeswitch_dispatcher - this is doing additional device checking and
then using the binary to switch with the selected device config file.
If no drivers are taking care of the device after the mode switch, the dispatcher will try to load and bind the "option" serial driver, in order to make the device usable. - /etc/usb_modeswitch.conf - a global config file to enable extensive logging when troubleshooting, or to disable switching alltogether (mostly to access the install part of devices)
- /usr/share/usb_modeswitch - a folder containing the individual setup information files per device, named according to the IDs and possibly further identity tokens (to resolve known ambiguities). If your device ID shows up in one of the file names, chances are your device is supported even if the model or brand does not match.
- /usr/sbin/usb_modeswitch - the binary program effectively doing the switch
When dealing with wireless devices, there may be issues with NetworkManager (or its
ModemManager component) which up to now may run into touble when trying to
auto-detect a proper modem port.
Good results were reported by working with wvdial, UMTSmon and several tools
providing a user interface to PPP like kppp; some of these programs may require a bit
of basic knowledge though.
There is also a new - unusual but intriguing - concept which shortcuts the tedious path of putting
together all components for a successful wireless broadband connection. The Sakis3G tool
is a self-containing script (including among others the latest USB_ModeSwitch binary). It supports
quite a number of providers already and is rapidly expanding. The beauty of it is that no installation
is necessary and only a minimum of input required. Contrary to NetworkManager, it really delivers.
Check it out at Sakis' blog ToDo Forever. There
is even a HowTo for setting it up so that it connects right away when a modem is plugged in.
The main hurdle for NetworkManager and others to a fully automated use of a newly switched modem is to find the right port for connecting. Often more than one serial port is created after switching (even up to five). Generally, not all of them are really standard serial (the driver can't decide), some may look like it and even accept AT commands, but usually the right one is providing an interrupt transfer endpoint. Unfortunately, NetworkManager does rely on other ways of probing for the correct port and sometimes fails. It is worth to note that the said Sakis3G tool is able to find this port quite easily.
Starting from version 1.1.2, usb_modeswitch will add a symbolic link to the correct port with
interrupt transfer if the device provides standard serial ports. The link will have the name
/dev/gsmmodem, with a number appended if more than one device is attached.
You can use this name with connection helpers like wvdial. Note that in many cases you
may have to edit the configuration file manually.
If you managed to get a new or badly supported device to switch correctly in manual mode, you can add a udev rule and a config file yourself. But please report it back to share it !!
See Contribute.
Known working hardware
Very important note:Personally, I could not test the vast majority of supported devices; the list here - as well as the necessary data - relies on reports from third parties (people, that is). So it may happen that you hit sudden obstacles even with your device listed here.
That said, the user base of this little tool has grown considerably, so that any data related problems are generally surfacing quite soon.
There are hitherto three known methods for initiating the switching process:
- sending a rarely used or seemingly weird standard storage command (equivalent to those of SCSI) to the storage device ("eject" for example)
- sending one or more vendor-specific control messages to the device
- actively removing (detaching) the storage driver from the device (only some early devices)
Again, if you don't find the name of your device in the list, it may still be supported.
The important thing is that you find your device's USB ID in the config file folder. Have
a look into the latest data package (See Download).
Here is the list of devices, together with the respective contributors:
device_reference.txt.
Troubleshooting
Note: if you still need support after having followed the advice on this page, please use the forum! E-mail may be used for device/config contributions.Known issues:
- Automatic serial driver assignment will work with the 3G-optimized driver only for kernels from 2.6.27 and up. If you have an older kernel and your modem is not recognized by any driver after mode switching, then the generic "usbserial" driver is used as a fallback.
- There is a problematic handling of devices with ID 19d2:2000 in kernels 2.6.26 to 2.6.28. This affects mostly ZTE devices and makes the "usb-storage" driver ignore the ID. In turn this will prevent proper initialization and may cause switching to fail. There is no other way around this than compiling your own kernel with some tiny edits. See Kernel related issues below for details.
For debugging of the automated system integration, edit (as root or su) /etc/usb_modeswitch.conf in a text editor and change the line
EnableLogging=0to
EnableLogging=1This gives you a verbose output of the hotplug activity to /var/log/usb_modeswitch_<device>.
If you're next to certain that you have the right values for your device, followed all the hints (see Known working hardware), and USB_ModeSwitch seems to do something run after run but to no effect, there are most likely system issues involved.
The first suspects are existing system rules for modems which handle things not
quite correctly.
If you own a device with the unswitched ID of 05c6:1000, it may get a wrong switching
command in older systems. There are four different types of switching devices,
all with that same ID; in the big distributions they were all treated alike as a
model from "Option" (the manufacturer) which is wrong in four out of five cases.
There are even cell phones with that ID which wrongly get the same treatment when connected
to an USB port.
To fix problems like that you can try to remove rules files from "/lib/udev/rules.d"
which contain calls to "modem-modeswitch".
USB_ModeSwitch will do additional checks beside the USB ID and treat all known
ambiguous devices in the right way. For example, it will leave unknown devices with
the 05c6:1000 ID alone.
Annother notorious candidate is again 19d2:2000. It may be switched O.K. by an existing
rule, but there is no driver loading if your model is new and its ID is not yet added to
the "option" module.
Disable the rule running "eject" and the ID will be handled by usb_modeswitch.
Kernel related issues
In some newer kernels, certain devices (some Option, some Huawei, some ZTE as mentioned above) get a special treatment in the usb-storage code to enable switching right away. You would not need USB_ModeSwitch anymore for these specific devices; on the other hand you have no choice of accessing the "CD-ROM" part of your device. Plus, there were cases when the special treatment brought no results and furthermore prevented USB_ModeSwitch to work properly afterwards (happened with ZTE devices, error "-2").
In case of trouble, look into "unusual_devs.h" in the "drivers/usb/storage" folder of
your kernel source. If your default ID (vendor and product ID of the storage part) can be found there and
you get errors when running USB_ModeSwitch, try first to blacklist "usb-storage".
If that helps, you should consider rebuilding your kernel with the entry in "unusual_devs.h" deactivated.
The only thing that will happen is that usb-storage works in the default way afterwards.
I found a tip in the Russian Gentoo wiki to
do exactly what I just suggested for the ZTE MF626.
By the way, at one point there was an agreement among USB developers to keep all future mode switching code
out of the kernel drivers if the neccessary steps can be taken in "user space".
Annother way of influencing the kernel behaviour is the parameter "delay_use" of
"usb-storage" which sets the time in seconds after plugging when the storage device will
actually be used (and probably automounted). The default value is 5; this might affect
the switching result under certain conditions.
To change the default add in /etc/modprobe.conf:
options usb-storage delay_use=1 (or 10, or other)
Old systems (e.g. CentOS 5 or Xandros 6)
If you are running a not-quite-fresh system (with a kernel below 2.6.27), you may run into incompatibilities between versions of "udev", the device manager. If you get no indication of the usb_modeswitch components doing anything at all (no log files), follow these steps:- Check if there are other files alongside "40-usb_modeswitch.rules" in the folder
"/lib/udev/rules.d".
If this is not the case, move the file to the folder "/etc/udev/rules.d". - If there is still no action, see if other files in "/etc/udev/rules.d" contain the
string "ATTRS".
If this is not the case, edit the file "40-usb_modeswitch.rules" and replace all occurences of "ATTR" and "ATTRS" with "SYSFS". Save the changes and see if something happens when you plug in again. - In particularly tough cases of "non-action", it might be necessary to analyze udev's actions; this is done by editing "/etc/udev/udev.conf" and change the logging level to "debug".
Contribute
USB_ModeSwitch comes quite handy for experimenting with your own hardware if not supported yet.The first step would be to try widely used switching methods from known devices, like the "eject" sequence found in the BandLuxe configuration "1a8d:1000". If you have a hint that your device may be made by Huawei originally, try the sequence from "12d1:1446".
Don't worry, it's almost impossible to break anything by experimenting with possibly wrong sequences. Just make sure you re-plug your device after each attempt!
If all this has no effect you can 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 spy out the USB communication to the device with the same ID inside M$ Windoze, with the on-board
driver installed. The device must be switched there too, and you want to log that moment.
I recommend this tool: "SniffUSB" (
http://www.pcausa.com/Utilities/UsbSnoop/default.htm).
Alltel UM175AL USB EVDO under Ubuntu Hardy Heron
Please post any improvements, new device information and/or bug reports to the ModeSwitchForum !
If you don't need support you can also send me an old-fashioned - and at your demand
confidential - e-mail (see below).
Whodunit
Copyright (C) 2007, 2008, 2009, 2010, 2011, 2012- Josua Dietze (usb_admin at this domain)
Other contributors
Command line parsing, decent usage/config output and handling, bugfixes added by:- Joakim Wennergren
- Paul Hardwick (http://www.pharscape.org)
- "usbsnoop2libusb.pl" by Timo Lindfors (http://iki.fi/lindi/usb/usbsnoop2libusb.pl)
- Guillaume Dargaud (http://www.gdargaud.net/Hack/SourceCode.html)
- Jouni Malinen (http://hostap.epitest.fi/wpa_supplicant, from "common.c")
- Aki Makkonen
- Denis Sutter
- Lucas Benedičič
- Roman Laube
- Luigi Iotti
- Vincent Teoh
- Tommy Cheng
- Daniel Cooper
- Andrew Bird
- Yaroslav Levandovskiy
- Sakis Dimopoulos
- Steven Fernandez
- Christophe Fergeau
- Nils Radtke
- Andrei Nazarenko
- Filip Aben
- Amit Mendapara
- Roman S. Samarev
- Chi-Hang Long
History
Version 1.2.3, 2012/01/28fix for configuration setting race (thanks to Amit Mendapara); discovered incompatibility between Tcl versions <= 8.3 and >=8.4, so 8.4 is the minimum prerequisite now;
first availability of an alternative source pack which includes "jimsh", a fast Tcl mini shell, intended for resource-constrained systems
Success check bugs (and others) fixed
Version 1.0.3, 2009/08/20
Some output bugs fixed
Version 1.0.1, 2009/06/08
Added output of descriptor strings for further identification
Version 1.0.0, 2009/06/03
Updated SonyMode, MD 400 now stable; automatic default endpoint detection from Andrew Bird
Version 0.9.7beta, 2009/03/15
Major code clean up, optional success control (both suggested by Daniel Cooper), new devices
Version 0.9.6, 2009/01/08
Special modes added for Sierra and Sony Ericsson, new devices
Version 0.9.5, 2008/10/27
New options for USB tuning added (jokedst), lots of new devices, clean up
Version 0.9.4, 2008/06/09
Compat fix for libusb on FreeBSD quirks, more devices
Version 0.9.4beta2, 2008/03/19
Udev 'release' fix
Version 0.9.4beta, 2008/03/16
Multiple device support
Version 0.9.3, 2008/03/09
More devices, no other changes from 0.9.3beta
Version 0.9.3beta, 2007/12/30
New TargetClass parameter for recent Option firmware (Paul Hardwick), more devices
Version 0.9.2, 2007/11/02
New Huawei mode (code from Miroslav Bobovsky, added by Denis Sutter), more devices
Version 0.9.1beta, 2007/09/11
Added command line parsing (jokedst), cleaned up config stuff (jokedst), bug fixes, doc updates
Version 0.9beta, 2007/08/12
Name change from "icon_switch", parameter file and generalizing
Version 0.2, 2006/09/25
Code cleaning, more messages
Version 0.1, 2006/09/24
Just very basic functionality ...
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