Not using Kernel 2.6.28? Read the notes. »
If you plan on using a kernel > 2.6.30 then this guide is not 100% suitable for you. From Kernel 2.6.31 it is not recommended that you attempt to use a third party driver and simply stick to the included kernel one, although I experienced huge stability issues with this. For those brave souls who wish to try and get another driver working, it should be noted that the reason HSO v1.12 will not compile is that the net_device structure has been retired. Fredrik (Knaaleman) from the Pharscape Forums was able to provide this insight and offer a patch which he has allowed me to distribute, but I didn’t have any luck with it. If anybody does get a resolution to using adapters like the Icon 505 in a completely stable manner with kernels 2.6.31 or above, I’d be delighted to publish it.
This guide is aimed at Kernel 2.6.28 but should function on 2.6.29 & 30, although you should have some degree of out-of-the-box support. Likewise it should also compile and function on younger kernels. There have been circumstantial reports that it works as far back as 2.6.16. As always, YMMV. Add your experience in the article comments section.
Recently I received a new Option Icon 505 USB HSPA adapter through a project I am currently working on. I was quite excited (in a sad way) to get it working with my Linux setup as it is a much more competent piece of kit than the telco provided Huawei units that mobile broadband customers in the UK are given (up until this point a friend of mine had been lending me his Huawei E160G). As I plan on trialling various operators and their services it was clear that I needed to get my hands on a new adapter that was:
a) Unlocked
b) Had receive diversity
c) Had support for Class 10 HSPA and beyond
d) Was supported by Linux
At first glance the Option Icon 505 looked like the perfect choice and Option themselves list the device as Linux compatible. I soon learned that it isn’t quite as simple as that however…
So, I got the item home, installed a SIM & plugged it into my fully updated Ubuntu 9.04 (Kernel 2.6.28-15) machine. Having been spoilt by newer Linux releases and the fantastic updates with the Red Hat sponsored NetworkManager I was expecting a slick driver install, wizard popup, and subsequent quick dial-up to the net. All fine in theory, but things don’t always go to plan.
The first thing that you’ll know if you’re in any way acquainted with mobile broadband on Linux is that most adapters come with a delightful false CD or Mass Storage partition which, as you would expect, appears as a CD or USB drive in Windows Explorer. Yes, Windows. The logic behind this is relatively sane - to negate the need for an actual driver CD to install the modem, because the stick itself acts as a disk in the first instance. Also, early modems took the opportunity to include a microSD storage slot so you could (in theory) use the stick as a combo pendrive & modem but this idea didn’t really catch on.
- You plug the device in and an autorun popup appears
- You agree to run the setup program suggested
- The setup launches, installs the relevant software, and flicks the device over into modem mode
- Windows looks around for some drivers, and since it’s just had them installed it magically finds and installs the relevant modem ports
The initial problem here is that Linux doesn’t autorun CDs for security, and that the false CD or Mass Storage partition actually doesn’t include any installable driver package for Linux in any case, which is not surprising given that vendors would be expected to support every variant of the OS known to man. No problem, there are usually plenty of drivers in the kernel itself, and if not, we can probably locate some of our own and compile those. Unfortunately, the side effect of presenting a faux device to any operating system is that the device needs to be sent a signal to flip itself back into modem mode since Linux in particular will match up the device, find the relevant module, and claim it to act in whatever way it thinks it should. This of course prevents any other interaction occurring between the device and the correct driver. Enough of the theory, lets take a peek at what happens when we actually plug the Icon in. Here’s the output of dmesg:
[ 1538.245056] usb 2-1: new high speed USB device using ehci_hcd and address 8
[ 1538.377935] usb 2-1: configuration #1 chosen from 1 choice
[ 1538.393133] scsi15 : SCSI emulation for USB Mass Storage devices
[ 1538.393493] usb-storage: device found at 8
[ 1538.393499] usb-storage: waiting for device to settle before scanning
[ 1543.393577] usb-storage: device scan complete
[ 1543.394575] scsi 15:0:0:0: CD-ROM ZCOPTION Icon 505 1.00 PQ: 0 ANSI: 4
[ 1543.400526] sr1: scsi-1 drive
[ 1543.400778] sr 15:0:0:0: Attached scsi CD-ROM sr1
[ 1543.400928] sr 15:0:0:0: Attached scsi generic sg2 type 5
[ 1543.613518] sr 15:0:0:0: [sr1] Unhandled error code
[ 1543.613528] sr 15:0:0:0: [sr1] Result: hostbyte=DID_ERROR driverbyte=DRIVER_OK
[ 1543.613537] end_request: I/O error, dev sr1, sector 32
[ 1543.613548] Buffer I/O error on device sr1, logical block 32
[ 1543.613558] Buffer I/O error on device sr1, logical block 33
[ 1543.613566] Buffer I/O error on device sr1, logical block 34
[ 1543.613573] Buffer I/O error on device sr1, logical block 35
[ 1543.613579] Buffer I/O error on device sr1, logical block 36
[ 1543.613586] Buffer I/O error on device sr1, logical block 37
[ 1543.613593] Buffer I/O error on device sr1, logical block 38
[ 1543.613600] Buffer I/O error on device sr1, logical block 39
[ 1543.613612] Buffer I/O error on device sr1, logical block 40
[ 1543.613619] Buffer I/O error on device sr1, logical block 41
[ 1543.784057] usb 2-1: reset high speed USB device using ehci_hcd and address 8
[ 1543.937639] sr1: CDROM (ioctl) error, command: Get event status notification 4a 01 00 00 10 00 00 00 08 00
[ 1543.937673] sr: Sense Key : No Sense [current]
[ 1543.937683] sr: Add. Sense: No additional sense information
[ 1543.991049] usb 2-1: USB disconnect, address 8
[ 1544.924082] scsi 15:0:0:0: rejecting I/O to dead device
[ 1550.324178] usb 2-1: new high speed USB device using ehci_hcd and address 9
Ugh. Great. So it gets picked up erroneously as a CD Drive, spits out a load of read errors because it won’t play nice with the CD device driver under Linux, resets itself, and the cycle continues (trust me, this will loop). At this point you may fancy reading the official Option response to this issue instead of my guide, which is described in full within the Ozerocdoff readme file, and is…
Switch off ZERO-CD:
The new USB Option WWAN modem device support a CDROM device, which holds the needed Windows driver to use the WWAN modem.
Therefore the firmware of the WWAN modem announce during the USB enumeration process to work as a virtual CDROM device with
its vendor name “ZOPTION”. This device is now called ZERO-CD.
The Linux OS does currently not use this ZERO-CD, because the image can not hold all the needed binary kernel drivers, which
may exists in the world. Also it is often strange to identify the exact matching drivers to your system, because the 2.6.xx
kernel has today a lot of Distro specific patches. So we will currently not use this ZERO-CD device for Linux and have to switch
it off. Once you send this switch off command to the WWAN modem, another new USB enumeration will be requested by the WWAN modem
firmware. Afterwards the real WWAN modem interface is available on the USB bus.
Looking on the Linux USB core system, it has another restriction. If there are more than one possible drivers, which can work
successfully with that USB WWAN modem, the USB core system will allow probing the WWAN modem by these drivers in a special order.
First the already loaded driver will be allowed to do the probe. If then this driver do a successful probe, another potential
driver will never become a chance to do also a probing with that hardware. Therefore it is (currently) impossible to use the final
WWAN modem driver to send the ZERO-CD switch off command, because often the USB mass storge driver will be already loaded and
is working in your Linux system.
If the probing of an already loaded module is not successful or no module is loaded, the udev system will trigger a modeprobe
to load the needed driver(s). But the loading order of the drivers is not clear specified, although is may depends on the order
of the appearance in the modules dependency files created by depmod.
But this probe order is also important to know for some old Option WWAN modems, which could be handled by the mainstream ‘option’
kernel driver. Unfortunately this is a bug, because the mainstream ‘option’ driver looks on the wrong USB device ID.
Solution switch off the ZERO-CD:
The ZERO-CD switch off command is simple a SCSI ‘rezero’ command. The easiest way to send this command to the WWAN modem is by
using the standard Linux USB mass storage driver. Because the WWAN modem will initiate a hard disconnect from the SCSI bus
connection after receiving that rezero command and the USB mass storage driver is not prepared for such a situation, we risk
a possible system freeze.
Therefore we use a short C-program ‘ozerocdoff’, based on the Linux USB lib together with some special udev rules. These rules
ensure a USB mass storage disconnection in the very early communication state, often in the time frame, when this driver waits
for a bus stabilization. Naturally we test,
- if only a known USB device ID is used, which ensures the driver can support also the plugged-in WWAN modem
- if parts of the USB device address match, which ensures proper ZERO-CD disabling for the correct device
- if the device is really in ZERO-CD mode
The ozerocd can be easy compiled by calling the Makefile. You find also a short man page, which explains the usage of the ozerocdoff
tool. Note that you must call the ozerocdoff as root user.
The trick is now to tell the Linux udev hotplug system to look carefully on a new USB device, which announce to be a CDROM device.
We check here only the USB vendor and device ID and have not to wait for a CDROM vendor option like “ZOPTION” to guarantee starting
the ozerocdoff program as early as possible. Otherwise the USB SCSI mass storage driver would need to do communication to the WWAN-
modem which is here not really needed. If the udev system detects such a device, it has to start simply ozercdoff program, which
do additional test on that found USB device, disconnects the USB SCSI mass storage driver, sends the rezero command and finally checks
if the WWAN-modem has properly switch to its WWAN modem interface.
The automatic triggering will be done by a udev rule. An example can be found here in the file:
hso.udev
This file has to be copied as ‘049_hso-udev.rules’ file into the
/etc/udev/rules.d/
directory. Finally don’t forget to tell the udev system to reload its rule files. This can be done by
udevcontrol reload_rules
Solution use the correct HSO Option driver:
Because we have now two drivers for some Option WWAN-modems, we simply blacklist the mainstream ‘option’ kernel module driver, which
we do not like to use. Note that this ‘option’ driver does support only Option WWAN modem with Version 3 Interface, which support
only virtual serial modem ports. The new ‘hso’ driver supports the newer Version 4 Interface. Here also an IP network device is
available, which allow high speed communication also by using the slow USB 1.1 bus system. Note also that this network interface is
not identical to a virtual ethernet, because it “speaks” only IP. So e.g. running a dhcpclient is here not possible, because this would
require the support of the simple ether transport package frames.
The ‘option’ mainstream driver can be prevent to be automatically loaded be adding a line like:
blacklist option
in the blacklist file found here:
/etc/modprobe.d/blacklist
But note that this will not unload a currently running ‘option’ driver. This has to be done by the commands:
rmmod option
lsmod | grep option
The 2nd grep to the option kernel module should not find a ‘option’ driver still loader. Otherwise the driver maybe currently in usage
and the ‘option’ driver can not be successfully unloaded. Then please unplug your WWAN modem and repeat the procedure.
Auto Linking device node with self-explanatory names:
This ‘hso’ driver supports ’self-explanatory’ device node names. Because of the big number of different virtual serial device
nodes, which will be supported by some WWAN modems and modem firmware, specially optional ports will not always match to the same
numbered device node. E.g. the serial modem port can be /dev/ttyHS3 or for another firmware /dev/ttyHS4.
Some important links to device node names are:
/dev/wmodem0 : the /dev/tty modem interface
/dev/wapp0 : the /dev/tty application port
/dev/wctrl0 : the /dev/tty control port
Note that currently only one plugged-in WWAN modem is supported. In the future also more than one WWAN modem can be supported. The
2nd WWAN modem tty port would than be called ‘/dev/wmodem1′.
WWAN Net device:
This ‘hso’ driver supports the WWAN like an Ethernet device. Additionlly this ethernet port is registered in sysfs. Normerlly the
hald distinguish only between 802.03 wired Ethernet and 802.11 Wireless Ethernet. The 10-wwan-quirk.fdi enables now also support of
WWAN devices by the hald. this is especially needed fot the Network Manager. It detects the network category entry and would use
a WWAN modem as wireed device without that fdi quirk.
The 10-wwan-quirk.fdi should be copied into the /usr/share/hal/fdi/information/20thirdparty directory.
Naturally this fdi quirk should be exchanged by a new version of the hald. But the hald new a mechanism, how it can distguish
between wirless 802.11, wired 802.03 and wwan devices. Therefore and currently not enabled dpatch is part of the module package.
It could be enabled, if the following line will be part of the debian/patches/00list.hso_modules
02_hso_modules_sysfs_wwan_dir
Please add this line and rebuild the whole debian package. It will add a subdirectory “wwan” in the /sys/class/net/hso0/ sysfs
directory.
WWAM USB suspend:
The older driver package does not enable automatic entering USB suspend state after a short configurable timeout. But now the hso
driver will be load with the extra option “enable_autopm=1″. Although this option could be set after loading the driver, it is very
important to set it just _before_ the device will be probed. So enabling this module parameter by an udev rule would only work as
long as the WWAN device has an enabled ZERO-CD device. Only in that case the udev rule will be used processed twice and just before
the 2nd and final device WWAN modem device probe will be done.
Anyway a udev rule will setup the suspend timeout value found in the configuration file from
/etc/hso-suspend.conf
and copy it into the corresponding USB core sysfs /power/autosuspend property. The osetsuspend script will handle this. The same
script can be used to change manually the time value or disable automatic suspend.
The complete solution:
All that installation and configuration stuff will be done automatically, if you install the Debian hso-udev package in you system.
Because this little helper tool and script does not make you happy without the driver, the hso-udev package requires also to install
a Debian binary HSO kernel module, which is part of the hso-module package.
Note that the HSO kernel binary module has to match exactly you current Distro kernel sub release. Otherwise you system may crash.
Job 1 - I’m a modem, honest
USB Modeswitch used to be the undisputed king of flipping devices back into modem mode (the computing equivalent of a slap & shake) but it doesn’t work at all reliably with Option devices. Instead, Option released their own tool for this called rezero. Unfortunately rezero turned out to be pretty unreliable and so Ozerocdoff was born. Catchy. This enumerated CD mode is often referred to as ZeroCD you see, as some ironic reference to the fact that under Windows it requires ‘Zero’ configuration.
Ozerocdoff jumps in when it sees the modem, and prevents the USB Mass Storage module from claiming the device. It recognises the modem by virtue of the vendor and product ID, which you can retrieve by issuing the command lsusb. Note that if you are using a Linux machine that doesn’t play nice with this particular adapter you may need to repeatedly issue to the command to catch the system before it resets the device. Alternatively you get get the required info from Device Manager in Windows.
Bus 002 Device 040: ID 0af0:d055 Option
The first job therefore is to download Ozerocdoff. Once downloaded, place the file somewhere you can easily access it, like the desktop.
1. Switch to the terminal
2. Change directories to the desktop - cd Desktop
3. Extract the file you just downloaded - tar zxf udev.tar.gz
4. Change to the newly extracted directory - cd udev
5. Compile - sudo make
6. Install - sudo install
I, and many others have had issues compiling.
a) You need of course to make sure you have a compiler installed - build-essential
b)You need the kernel headers appropriate to your system. Issue uname -r and make a note of the output. Replace that command in the following with the output given - sudo apt-get install linux-headers-`uname -r`
c) You also need the USB headers, which can be found in libusb-dev
If you see errors similar to warning: implicit declaration of function then you’re affected by step c in particular.
A successful install should look something like the following:
richard@holly-jaunty:~/Desktop/udev$ sudo make
cc -c ozerocdoff.c -Wall -O
ozerocdoff.c: In function ‘main’:
ozerocdoff.c:243: warning: ‘usb_dev’ may be used uninitialised in this function
cc -l usb -o ozerocdoff ozerocdoff.o
richard@holly-jaunty:~/Desktop/udev$ sudo make install
install -d /usr/sbin
install -d /etc/udev/rules.d
install ozerocdoff /usr/sbin
cp hso.udev /etc/udev/rules.d/51-hso-udev.rules
install -d /usr/share/hal/fdi/preprobe/20thirdparty
cp 10-wwan-hso-preprobe.fdi /usr/share/hal/fdi/preprobe/20thirdparty
install -d /usr/share/hal/fdi/information/20thirdparty
cp 10-wwan-quirk.fdi /usr/share/hal/fdi/information/20thirdparty
install -d /usr/lib/hal/scripts/
install hal-serial-hsotype /usr/lib/hal/scripts/
install -d /etc
install osetsuspend /usr/sbin
cp hso-suspend.conf /etc
richard@holly-jaunty:~/Desktop/udev$
Also, now is a good time to check that your user is in the dialout group - grep dialout /etc/group dialout
Now, the Icon 505 is actually too new to be included by default in the list of devices that Ozerocdoff will act on behalf of, so we do need to tell it is how to identify our adapter. This is where the info gathered with lsusb comes in.
In the current version of Ozerocdoff, the file that we need to edit is called /etc/udev/rules.d/51-hso-udev.rules but it looks like this is incremented for every new version of the software. An easy way to find out the filename is to take a peek at the output given when you issued sudo make install during the installation process.
1. Switch to the terminal
2. sudo gedit /etc/udev/rules.d/51-hso-udev.rules
3. Under “New Syntax” you will see ten or more almost identical lines of code each referencing a different device (idProduct), albeit from the same vendor (idVendor). Copy and paste the last statement and alter it to suit the product ID for you device. Mine looks like the following:
ATTRS{idVendor}==”0af0″, ATTRS{idProduct}==”d055″, RUN+=”/usr/sbin/ozerocdoff -wi 0x%s{idProduct}”
GOTO=”hso_end”
4. Under “Old Syntax” you will see a similar arrangement, the only difference being a more obfuscated set of commands. Again, copy and paste the last statement and alter the product ID. Mine looks like the following:
SUBSYSTEM==”usb_device”, SYSFS{idVendor}==”0af0″, SYSFS{idProduct}==”d055″, SYSFS{bDeviceClass}==”00″, RUN+=”/usr/sbin/ozerocdoff -wi 0x%s{idProduct}”
5. Save and exit the file
6. Refresh the udev rules, so that the next time you plug in a device, it will read the freshly created rules and thus act upon them: sudo udevadm control –reload-rules
7. Plug in your Icon. Give the system ~20secs and then check the output of dmesg. You should notice that the device no longer gets claimed as scsi 15:0:0:0: CD-ROM ZCOPTION Icon 505 1.00 PQ: 0 ANSI: 4
8. Although in all likelyhood nothing else will step in to fill the void if you’re using another member of the Option family it may be that the Option driver steps in to try and cater to the device, but since the Icon 505 and others use a new IP only architecture it simply won’t work properly. We need to blacklist the Option driver by editing a configuration file. Issue sudo gedit /etc/modprobe.d/blacklist.conf and append the following:
# Blacklist the option modem driver. This will allow the HSO driver (when installed) to step in and provide functionality to the Icon 505 amongst others
blacklist option
Job 2 - Drivers please
1. At this point Ozerocdoff should be working and preventing the Icon from registering itself as a CD Device. However, it still needs some drivers in order to function. The drivers that cover these new WWAN devices are called HSO - High Speed Option, and have a new architecture to allow use of fast HSPA adapters. You can download the newest version (currently 1.12) here.
2. Download or move the archive to the desktop and extract it using tar zxf hso-1.12.tar.gz
3. Move into the new directory using cd hso_26-v1.12
4. Compile the driver using sudo make
5. Install the driver using sudo make install
6. Plug in your adapter and you should be up and running. As with any issues, I would heartily recommend a reboot or two, and a double-check of all steps before putting it down to a bad effort. As I was putting together the above steps I was trying it on my fresh 9.04 box and scratching my head as to why I was having no luck. Turns out I was using d055 as the product ID instead of d050! A successful installation should push out a dmesg log like this:
[ 111.852198] usb 2-2: new high speed USB device using ehci_hcd and address 4
[ 111.986505] usb 2-2: configuration #1 chosen from 1 choice
[ 113.194548] usb 2-2: USB disconnect, address 4
[ 113.468210] usb 2-2: new high speed USB device using ehci_hcd and address 5
[ 113.602299] usb 2-2: configuration #1 chosen from 1 choice
[ 114.293835] Initializing USB Mass Storage driver…
[ 114.294067] usbcore: registered new interface driver usb-storage
[ 114.294074] USB Mass Storage support registered.
[ 114.327312] hso: /home/richard/Desktop/hso_26-v1.12/hso.c: 1.12-Option Option Wireless
[ 114.330282] hso0: Disabled Privacy Extensions
[ 114.331628] usbcore: registered new interface driver hso
4 Comments
Oct 12th, 2009
You know, I have to tell you, I really enjoy this blog and the insight from everyone who participates. I find it to be refreshing and very informative. I wish there were more blogs like it. Anyway, I felt it was about time I posted, I
Oct 13th, 2009
Thanks Darryl. Sorry, Akismet thought you were spam but since you’re saying nice things I thought I’d overrule it.
Feb 16th, 2010
I’m trying to get this working for my mother-in-law running ubuntu 9.10
I’d love if you could point me to where I can find out more about getting the modem to work under kernel 2.6.31 (or later). The connection is actually listed in NM, but fails to connect. I get the following output:
usb 1-1: new high speed USB device using ehci_hcd and address 3
…kernel: [ 105.365942] usb 1-1: configuration #1 chosen from 1 choice
…kernel: [ 106.538198] usb 1-1: USB disconnect, address 3
…kernel: [ 106.812228] usb 1-1: new high speed USB device using ehci_hcd and address 4
…kernel: [ 106.950794] usb 1-1: configuration #1 chosen from 1 choice
…kernel: [ 107.563963] hso: /build/buildd/linux-2.6.31/drivers/net/usb/hso.c: 1.2 Option Wireless
…kernel: [ 107.567020] hso0: Disabled Privacy Extensions
…kernel: [ 107.569073] usbcore: registered new interface driver hso
…kernel: [ 107.617001] Initializing USB Mass Storage driver…
…kernel: [ 107.617319] usbcore: registered new interface driver usb-storage
…kernel: [ 107.617334] USB Mass Storage support registered.
Feb 16th, 2010
Hi Tomas.
The last I heard, we had an actually had a working driver under 2.6.31 (Check the Pharscape message boards for clarification).
From what I can see you’ve done everything correctly. The main line is where hso0 is registered as an interface. If NM sees it, can configure it, but fails to connect, then I would wager a simple configuration issue is to blame.
Set the device up under Windows if you get the chance and grab the settings. For example, my Voda card dials *99#, and has an arbitrary username & pass. The NM team have made great strides with their ‘wizard’ approach to telco settings but it pays to double-check simple things like the above, APN, compression settings, DNS, etc.
Incoming Links
Leave a Reply