Bering-uClibc 6.x - User Guide - Advanced Topics - Setting Up a Wireless Internet Connection

From bering-uClibc
Jump to: navigation, search
Advanced Topics - Setting Up a Wireless Internet Connection
Prev Bering-uClibc 6.x - User Guide Next


A common use case for a Bering-uClibc installation is to act as a router / firewall serving a local network and providing a connection to the Internet. Most often the Internet connection takes the form of a hard-wired link, for example via a Cable or ADSL modem. This has the advantage of offering a high-quality connection, often also with a high bandwidth. However in some cases a hard-wired Internet connection is not available but Internet connectivity is still desired. Many locations now have 3G (or even 4G) mobile telephony signals available and it is increasingly practical to use these to provide Internet connectivity as a temporary or permanent alternative to a hard-wired connection. Sometimes this is referred to as Mobile Broadband.

This article describes how to use a Mobile Broadband Modem (sometimes informally referred to as a "3G dongle" or "modem stick") with Bering-uClibc 6.x in order to provide an external network connection, either as the only source of Internet connectivity or as a secondary fall-back alongside a hard-wired primary connection.

A fundamental requirement is a hardware device which can connect to a mobile telephony network. Typically these are USB devices containing mobile telephony circuitry and an antenna of some sort (either internal or external). Older devices generally present themselves as a USB Modem which can be configured to run a Point-To-Point TCP/IP network link. Some more modern (higher-speed) devices present themselves as a USB Ethernet adaptor and include a built-in router and DHCP server.

A common complication is that the devices initially present themselves as USB storage devices (containing Windows device drivers) and need to be forced to switch to a different USB "mode" before they will work properly. This switching is performed automatically by Windows device drivers but under Linux a different approach is required using the USB_Modeswitch utility.

Once switched to the correct USB mode these devices seem to stay in that mode unless disconnected from the USB bus or powered off. Typical behaviour is therefore that a reboot of the host machine will not require them to be re-switched, but powering the host machine off and on again will require a re-switch, as will physically disconnecting and reconnecting the device.

On the "big" Linux distributions it is common to use the udev daemon to manage devices and USB_Modeswitch integrates with this mechanism via a set of udev "rules". On Bering-uClibc udev is not used so USB_Modeswitch is configured manually.

Software Installation

The main non-standard software Package required is usb-ms.lrp which provides the usb-modeswitch utility. This relies on libusb.lrp but that will be installed automatically if not already present.

The data files which specify the mode switching messages for specific device types are distributed in a separate Package called usb-ms-data.lrp (following the approach adopted for the upstream USB_Modeswitch distribution, where the data files are maintained separately from the utility software). In most cases this needs to be installed as well (and installing it will load usb-ms.lrp too if that is not already installed).

As with any new hardware device, the relevant kernel Modules also need to be present in directory /lib/modules/. Provided these are present they will typically be loaded automatically when the device switches to the new USB mode.

Software Configuration

All Devices

The first step is to check which USB ID is being used by the device when first connected. The ID of all connected USB devices can be displayed with the lsusb command:

# lsusb
Bus 001 Device 001: ID 1d6b:0001
Bus 001 Device 002: ID 12d1:1f01

Typically Device 001 on any USB bus is the Host Controller so in this example the second entry is the Mobile Broadband Modem (actually a Huawei E3131) with Vendor ID 12d1 and Product ID 1f01. If there is any doubt as to which Device is which then check in file /var/log/messages for the Device number reported just after the device is physically connected.

Assuming the device type is already "known" to USB_Modeswitch there will be a file named with the exactly matching USB ID in directory /usr/share/usb_modeswitch/. For the example above the full filename is therefore /usr/share/usb_modeswitch/12d1:1f01 This file contains the data which will be sent to switch the device to the new USB mode.

If there is no matching file for your device then the best place to seek help is the USB_Modeswitch Forum.

To actually switch the device it is necessary to run the usb_modeswitch utility with several arguments. The syntax is:


so for the example above it would be:

usb_modeswitch -v 0x12d1 -p 0x1f01 -c /usr/share/usb_modeswitch/12d1:1f01

The usb_modeswitch utility is rather verbose and will typically report something like the following:

# usb_modeswitch -v 0x12d1 -p 0x1f01 -c /usr/share/usb_modeswitch/12d1:1f01
Looking for target devices ...
 No devices in target mode or class found
Looking for default devices ...
   found matching product ID
   adding device
 Found device in default mode, class or configuration (1)
Accessing device 002 on bus 001 ...
Getting the current device configuration ...
 OK, got current device configuration (1)
Using interface number 0
Using endpoints 0x01 (out) and 0x81 (in)
Inquiring device details; driver will be detached ...
Looking for active driver ...
 OK, driver found ("usb-storage")
 OK, driver "usb-storage" detached

SCSI inquiry data (for identification)
  Vendor String: HUAWEI  
   Model String: Mass Storage    
Revision String: 2.3 1

USB description data (for identification)
Manufacturer: HUAWEI
     Product: HUAWEI HiLink
  Serial No.: not provided
Setting up communication with interface 0
Using endpoint 0x01 for message sending ...
Trying to send message 1 to endpoint 0x01 ...
 OK, message successfully sent
Resetting response endpoint 0x81
 Could not reset endpoint (probably harmless): -84
Resetting message endpoint 0x01
 Could not reset endpoint (probably harmless): -71
 Device is gone, skipping any further commands
-> Run lsusb to note any changes. Bye.

Such verbose output is useful for testing. If desired it can be switched off by adding the -Q or --quiet arguments.

At this point re-running the lsusb command should tell a different story:

# lsusb
Bus 001 Device 001: ID 1d6b:0001
Bus 001 Device 003: ID 12d1:14db

Checking file /var/log/messages should also show the old driver being removed and the new one being added.

Devices Which Act Like USB Modems

Running usb_modeswitch manually should result in the USB mode being switched and the device presenting itself as a USB-connected serial modem. Assuming the correct device driver files are installed in directory /lib/modules/ these should be loaded automatically and a device like /dev/ttyUSB0 should become available. This can then be configured just like any other serial modem interface - see this page for further details. Note that additional options will probably be required compared to a more conventional dial-up modem.

Devices Which Act Like USB Ethernet Adaptors

Running usb_modeswitch manually should result in the USB mode being switched and the device presenting itself as a USB Ethernet adaptor. Assuming the correct device driver files are installed in directory /lib/modules/ these should be loaded automatically and an extra Ethernet interface should show up when running command: ip link list This can then be configured just like any other Ethernet interface.

In order to automatically run usb_modeswitch the recommended approach is to add a pre-up entry to file /etc/network/interfaces against the relevant interface - something like the following:

auto eth1
iface eth1 inet dhcp
        pre-up usb_modeswitch -v 0x12d1 -p 0x1f01 -c /usr/share/usb_modeswitch/12d1:1f01 ; sleep 1

(The sleep 1 was found to be necessary in order to allow time for the mode to switch and the new driver to load before proceeding.)

If for some reason the device is already "switched" before this command runs it won't match the -p argument so will have no effect.

Watch out for the order in which the kernel detects Ethernet interfaces and numbers them eth0, eth1 etc. If the USB device is already "switched" at boot time (e.g. the machine is rebooted rather than being powered off and on again) then it may show up as eth0 instead.

Known Working Devices


Huawei E3131

The Huawei E3131 is one of the more modern HSPA+ devices that presents itself as a USB Ethernet adaptor. This uses the cdc_ether kernel Module which depends on the usbnet kernel Module.

When initially connected, this device reports USB ID (Vendor:Product) 12d1:1f01 which is a Mass Storage device using the Uniform CD-ROM driver.

When switched to the Ethernet Adaptor mode it reports USB ID (Vendor:Product) 12d1:14db.

One complication is that the DHCP server built into this device uses network address which clashes with the default network address for the "internal" network on Bering-uClibc, so the default internal network address needs to be changed to e.g. by editing file /etc/network/interfaces. Note that this will also change the internal address of "firewall" so that also needs to be reflected in /etc/hosts and other places.

The device seems to use IPv4 address for itself and allocates DHCP-managed address to the host.

During basic testing by davidMbrooke this device delivered more than 20 Mb/s of Download and 2.5 Mb/s of Upload bandwidth on the O2 3G network in the UK.

Huawei E586

The Huawei E586 or "MiFi" Mobile WiFi contains a battery and combines a Mobile Broadband Modem with a Wireless Access Point. A common use case is to enable multiple Tablet Computers without USB ports to access Mobile Broadband over a WiFi connection, but it can also be connected via a USB cable in which case it behaves like other Mobile Broadband Modem devices.

This device presents itself as a USB Modem and relies on the following kernel Modules: option, usb_wwan, cdc_ncm and usbserial.

When initially connected, this device reports USB ID (Vendor:Product) 12d1:14fe.

When switched to Modem mode it reports USB ID (Vendor:Product) 12d1:1c1f.

When successfully connected, /var/log/messages should include a line like:

usb 1-2: GSM modem (1-port) converter now attached to ttyUSB0

Data Quota Usage Montoring

In order to access a Mobile Broadband network it is necessary to use a SIM card which is linked to either a pre-pay (Pay-As-You-Go) or credit contract funding source. The data quota associated with mobile telephony networks is generally much lower than for fixed-line network technologies and a limit of 1GB or less per month is typical, with usage over any limit often being charged at higher rate. Unless the data throughput is very low it can be useful to monitor how much of the data quota has been used and to predict whether the monthly quota will be exceeded, and a good tool for doing that is vnstat. This is available for Bering-uClibc by installing Package vnstat.lrp

Once installed and configured, the vnstat command can be used to generate reports like the following, which is predicting a 3.00 GiB monthly usage based on two days' worth of monitoring:

firewall# vnstat
Database updated: Sat Jun  6 15:10:30 2015

   eth3 since 06/05/15

          rx:  450.00 MiB      tx:  127.19 MiB      total:  577.18 MiB

                     rx      |     tx      |    total    |   avg. rate
       Jun '15    450.00 MiB |  127.19 MiB |  577.18 MiB |    9.72 kbit/s
     estimated      2.33 GiB |     676 MiB |    3.00 GiB |

                     rx      |     tx      |    total    |   avg. rate
     yesterday    158.35 MiB |   30.45 MiB |  188.80 MiB |   17.90 kbit/s
         today    291.64 MiB |   96.74 MiB |  388.39 MiB |   58.24 kbit/s
     estimated       460 MiB |     151 MiB |     611 MiB |

Debugging Hints and Tips

  • Can switch on debug output from libusb by setting environment variable USB_DEBUG to 1 (and turn it off again by setting to 0).
  • The command-line argument for verbose output from usb-modeswitch is -W (or --verbose).

Prev Up Next