Difference between revisions of "Bering-uClibc 4.x - User Guide - Advanced Topics - Setting Up a Wireless Internet Connection"

From bering-uClibc
Jump to: navigation, search
(Major enhancements to many sections)
(remove orphaned page)
 
Line 1: Line 1:
{| summary="Navigation header" width="100%"
 
! colspan="3" align="center" | [[Bering-uClibc 4.x - User Guide - Advanced Topics - Setting Up a Wireless Internet Connection|Advanced Topics - Setting Up a Wireless Internet Connection]]
 
|-
 
| width="20%" align="left"  | [[Bering-uClibc 4.x - User Guide - Advanced Topics - Setting Up TODO|Prev]]
 
! width="60%" align="center" | [[Bering-uClibc 4.x - User Guide]]
 
| width="20%" align="right"  | [[Bering-uClibc 4.x - User Guide - Advanced Topics - Setting Up TODO|Next]]
 
|}
 
----
 
  
 
WARNING - THIS PAGE REFERS TO NEW FUNCTIONALITY THAT IS CURRENTLY UNDER DEVELOPMENT AND NOT YET INCLUDED IN BERING-UCLIBC 4.X - WARNING
 
[[User:Davidmbrooke|Davidmbrooke]] 19:55, 21 June 2013 (UTC)
 
 
 
==Introduction==
 
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 [http://en.wikipedia.org/wiki/Mobile_broadband Mobile Broadband].
 
 
This article describes how to use a [http://en.wikipedia.org/wiki/Mobile_broadband_modem Mobile Broadband Modem] (sometimes informally referred to as a "3G dongle" or "modem stick") with [[Bering-uClibc 4.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 [http://www.draisberghof.de/usb_modeswitch/ 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 [http://en.wikipedia.org/wiki/Udev 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 <code class="filename">usb-ms.lrp</code> which provides the <code class="filename">usb-modeswitch</code> utility.
 
This relies on <code class="filename">libusb.lrp</code> 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 <code class="filename">usb-ms-data.lrp</code> (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 <code class="filename">usb-ms.lrp</code> too if that is not already installed).
 
 
As with any new hardware device, the relevant kernel Modules also need to be present in directory <code class="filename">/lib/modules/</code>.
 
Provided these are present they will typically be loaded automatically when the device switches to the new USB mode.
 
 
Another pre-requisite is a populated directory under <code class="filename">/proc/bus/usb/</code>.
 
If this is not present add the following to file <code class="filename">/etc/fstab</code>:
 
usbfs              /proc/bus/usb  usbfs  defaults    0      0
 
and either reboot or run command: <tt>mount /proc/bus/usb</tt>
 
 
==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 <code class="filename">lsusb</code> command:
 
# lsusb
 
Bus 001 Device 001: ID 1d6b:0001
 
Bus 001 Device 002: ID 12d1:1f01
 
Typically <tt>Device 001</tt> 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 <tt>12d1</tt> and Product ID <tt>1f01</tt>.
 
If there is any doubt as to which Device is which then check in file <code class="filename">/var/log/messages</code> 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 <code class="filename">/usr/share/usb_modeswitch/</code>. For the example above the full filename is therefore <code class="filename">/usr/share/usb_modeswitch/12d1:1f01</code>
 
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 [http://www.draisberghof.de/usb_modeswitch/bb/ USB_Modeswitch Forum].
 
 
To actually switch the device it is necessary to run the <code class="filename">usb_modeswitch</code> utility with several arguments.
 
The syntax is:
 
usb_modeswitch -v ''VENDOR'' -p ''PRODUCT'' -c ''CONFIGURATION_FILE_FOR_DEVICE''
 
so for the example above it would be:
 
usb_modeswitch -v 0x12d1 -p 0x1f01 -c /usr/share/usb_modeswitch/12d1:1f01
 
The <code class="filename">usb_modeswitch</code> 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 <tt>-Q</tt> or <tt>--quiet</tt> arguments.
 
 
At this point re-running the <code class="filename">lsusb</code> command should tell a different story:
 
# lsusb
 
Bus 001 Device 001: ID 1d6b:0001
 
Bus 001 Device 00'''3''': ID 12d1:'''14db'''
 
Checking file <code class="filename">/var/log/messages</code> should also show the old driver being removed and the new one being added.
 
 
===Devices Which Act Like USB Modems===
 
TODO
 
 
===Devices Which Act Like USB Ethernet Adaptors===
 
Running <code class="filename">usb_modeswitch</code> 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 <code class="filename">/lib/modules/</code> these should be loaded automatically and an extra Ethernet interface should show up when running command: <tt>ip link list</tt>
 
This can then be configured just like any other Ethernet interface.
 
 
In order to automatically run <code class="filename">usb_modeswitch</code> the recommended approach is to add a <tt>pre-up</tt> entry to file <code class="filename">/etc/network/interfaces</code> 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 <tt>sleep 1</tt> 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 <tt>-p</tt> argument so will have no effect.
 
 
==Known Working Devices==
 
===Huawei===
 
====Huawei E3131====
 
The [http://www.huaweidevice.co.uk/mobile-broadband/Huawei-E3131/ Huawei E3131] is one of the more modern HSPA+ devices that presents itself as a USB Ethernet adaptor. This uses the <code class="filename>cdc_ether</code> kernel Module which depends on the <code class="filename>usbnet</code> kernel Module.
 
 
When initially connected, this device reports USB ID (Vendor:Product) <tt>12d1:1f01</tt> 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) <tt>12d1:14db</tt>.
 
 
One complication is that the DHCP server built into this device uses network address 192.168.1.0/24 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. 192.168.10.0/24 by editing file <code class="filename">/etc/network/interfaces</code>.
 
 
The device seems to use IPv4 address 192.168.1.1 for itself and allocates DHCP-managed address 192.168.1.100 to the host.
 
 
====Huawei E586====
 
The [http://www.huaweidevice.co.uk/mobile-broadband/Huawei-E586-Black/ 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 short USB cable in which case it behaves like other Mobile Broadband Modem devices.
 
 
==Debugging Hints and Tips==
 
* Can switch on debug output from <tt>libusb</tt> by setting environment variable <tt>USB_DEBUG</tt> to 1 (and turn it off again by setting to 0).
 
* The command-line argument for verbose output from <code class="filename">usb-modeswitch</code> is <tt>-W</tt> (or <tt>--verbose</tt>).
 
 
 
----
 
{| summary="Navigation footer" width="100%"
 
| width="40%" align="left"  | [[Bering-uClibc 4.x - User Guide - Advanced Topics - Setting Up TODO|Prev]]
 
| width="20%" align="center" | [[Bering-uClibc 4.x - User Guide - Advanced Topics|Up]]
 
| width="40%" align="right"  | [[Bering-uClibc 4.x - User Guide - Advanced Topics - Setting Up TODO|Next]]
 
|}
 
 
[[Category:Bering-uClibc 4.x]]
 
[[Category:User Guide]]
 

Latest revision as of 17:16, 1 May 2016