Usb - Modeswitch - Activating Switchable Usb Devices On Linux
Usb - Modeswitch - Activating Switchable Usb Devices On Linux
Introduction
Download
How to install
How to use
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.
Several new USB devices (especially high-speed wireless WAN stuff, there seems to be a chipset from
Qualcomm offering 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 that (and on every consecutive plugging) this driver switches the mode internally, the storage
device vanishes (in most cases), and a new device (like a USB modem) shows up. The WWAN gear
maker Option calls that feature "ZeroCD (TM)".
As you may have guessed, hardly anything of this is documented and Linux support by the better part of
the makers is non-existent.
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 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 does the
switching and to reproduce the same thing under the rule of Linux or the BSD variants.
USB_ModeSwitch makes the last step considerably easier by taking the important parameters from a
configuration file and doing all the initialization and communication stuff.
From version 1.0.3 upwards there is a simple framework for integrating the switching with udev (the
device manager) to make it fully automatic.
This tool is now on the way to be integrated into the big distributions; soon you should not be having to
install from the source packages here anymore.
But I strongly advise against using packaged versions before 1.1.0.
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.
Download
The latest release version is 1.1.3. The tar archive contains only the source. I used libusb-0.1.12 but the
"compat" library from libusb-1.0 is now working smoothly too.
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.13.
How to install
If you have an earlier version installed, de-installation is recommended ("make uninstall"). Several file
locations changed in 1.1.0 and after, old ones might be orphaned if not taken care of.
Important: you need "tcl" for the wrapper script to work; if you enter "tclsh" and you get a "%" prompt,
you are set (to exit enter "exit"). The "tcl" package is part of all distributions I know.
Unpack the source file of the program (who might have thought!). In the newly created directory run as
root or superuser:
# make install
This installs the wrapper script for udev, a config file, the man page and the freshly compiled binary.
Now do the same for the data package. It will install the config files in /etc/usb_modeswitch.d and the
udev rule file in /lib/udev/rules.d.
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 with the original setup
reference file. To do the latter you put "usb-modeswitch.setup" into "/etc" and edit it according to your
hardware. It's heavily commented and should tell you what to do.
The setup 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 should be able to use your device without any interaction except plugging
your device in.
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 /etc/usb_modeswitch.d 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.
/etc/usb_modeswitch.d - 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.
After switching and driver-loading, it is the responsibility of the system to discover the new (mostly
serial) device.
When dealing with wireless devices, there may be issues with NetworkManager (or
its ModemManager component) which does not seem to be overly reliable when trying to recognize 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 Sakis3Gtool 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, 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.
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.
There are hitherto three known methods for initiating the switching process:
1. sending a rarely used or seemingly weird standard storage command (equivalent to those of
SCSI) to the storage device ("eject" for example)
2. actively removing (rather detaching) the storage driver from the device
Again, if you don't find the name of your device in this 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.).
Huawei E220 (aka "Vodafone EasyBox II", aka "T-Mobile wnw Box Micro")
Huawei
E160, E160G, E169, E180, E230, E270(+), E280, E630, E870, E1550, E1612, E1662, E16
90, E1692, E1750, E1752, K3765, K4505, K4605, MTE WM610, R201
Huawei E630
There are reportedly modem-only variants around (without the storage part); for these no
switching is required.
ZTE AC581
ZTE AC8710, AC2710 (EVDO, featured by PTCL)
ZTE K3520-Z, K3565, K2525, K4505-Z, K3805-Z, K3570-Z, K3571-Z
ONDA MT503HS, MT505UP, MW833UP
Alcatel One touch X020 (aka OT-X020, aka "MBD-100HU", aka "Nuton 3.5G", works with
"Emobile D11LC")
Alcatel X200, X220L
BandLuxe C120, C170, C270
Solomon S3Gm-660
Seems to be related to the BandLuxe C120 above
C-motech CGU-628 (aka "Franklin Wireless CGU-628A" aka "4G Systems XS Stick W12")
C-motech CHU-629S
Toshiba G450
Hummer DTM5731
A-Link 3GU
Quanta/Royaltek MU-Q101, Q110
LG LDU-1900D, L-05A, LUU-2100TI, KP500 (experimental)
Cricket A600
Switches to ACM device. Might need a ResetUSB after switching - or not
D-Link DWM-162-U5
Nokia CS-10, CS-15
Note: if you still need support after having followed the advice on this page, please use the
forum!
Known quirks:
Switching may fail if the device is plugged upon cold boot. Driver assignment may fail upon a
warm boot. Both issues are rooted in the way distributions handle system initialization from a
initial ramdisk image where usb_modeswitch is not integrated yet.
Workaround: plug device after booting. If you need it plugged all the time you may have to write
a script for your respective device and run it from "rc.local".
Automatic serial driver assignment works only for kernels from 2.6.27 and up. If your modem is
not recognized by any driver (no ttyUSB device after switching) and you have an older kernel, the
only way is to use the generic serial driver where you can provide the USB ID as a parameter
when loading it as a module.
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=0
to
EnableLogging=1
This 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 will most likely get a wrong switching
command. There are four different types of switching devices, all with that same ID; in the big
distributions they are all treated alike as a model from "Option" (the manufacturer) which is wrong in
three out of four cases. There are even cell phones with that ID which 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. Furthermore, it leaves 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.
In some newer kernels, certain device families (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 dvices; 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.
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:
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 out the USB communication to the device with
the same ID inside M$ Windoze.
I recommend this tool: "SniffUSB" (http://www.pcausa.com/Utilities/UsbSnoop/default.htm).
This is the extremely short version. There is a very good case example from Mark A. Ziesemer here:
Alltel UM175AL USB EVDO under Ubuntu Hardy Heron
Please post any improvements, new device information and/or bug reports to the ModeSwitchForum !
If you know about a new device configuration you can also send me an old-fashioned - and at your
demand confidential - e-mail (see below).
Whodunit
Please use the forum for support questions! Only for personal/confidential messages mail me directly.
Other contributors
Command line parsing, decent usage/config output and handling, bugfixes added by:
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
More contributors (device specific) are listed in the device_reference.txt. Thanks to everyone at the
forum too! Sometimes it takes a considerable reservoir of patience until success ...
History
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
Page las