Tutorial: Tethering and Setting up an Ad-Hoc Network

From Humanitarian FOSS Summer Institute 2009

This tutorial will lead you through setting up your Android 1.5 (cupcake) phone so that:

it can be tethered to a laptop either through WiFi or Bluetooth, giving the laptop access to the network, and,
it can be used with similarly configured phones in an ad-hoc network.

The procedures described here merely pull together the excellent work of others. See the references below.

Obligatory disclaimer: Proceed at your own risk. If you are successful, you may be violating your service agreement. If you screw up, you may brick your phone.

1 Flashing your Android Dev Phone with a Factory System Image
2 Installing the ADP 1.5 - Kernel-Update
3 Installing Wireless Tether for Root Users
4 Setting up an Adhoc Network
5 References

Flashing your Android Dev Phone with a Factory System Image

The first step is to upgrade your phone to the 1.5 (cupcake) factory image provided by HTC. This is the official firmware from HTC for unlocked dev phones. Just follow the instructions provided here: http://www.htc.com/www/support/android/adp.html.

This upgrade will give you root access through android/tools/adb tool that comes with the Android SDK. However, it will not allow phone applications to run in root mode. For that you need the next step.

Installing the ADP 1.5 - Kernel-Update

The problem with the HTC image is that it does not let applications run in root mode. To verify this, download and install a terminal application to your phone, such as Terminal Emulator. Start the program and type su at the command line. It will report that you are not allowed to execute the su command.

Also, the HTC Factory image does not support netfilter/iptables' which are needed for the tethering application that we will be downloading.

To install the ADP 1.5 kernel update, follow the 7 easy steps given here: http://code.google.com/p/android-wifi-tether/wiki/ADP15KernelUpdate.

After you finishing installing the update, rerun the Terminal Emulator program. It should now allow you to enter superuser mode.

Installing Wireless Tether for Root Users

Download the wireless tether application from http://code.google.com/p/android-wifi-tether/. There is an excellent 4 minute YouTube video illustrating how to tether your laptop to the phone. Here are the basic steps:

Start the Tether App.
Using the program's Setup menu, turn on both Use bluetooth and Don't disable wifi. We want to use the activated Wifi connection rather than a mobile data connection.
Returning to the main view, press the start tethering button. (If it is unable to start tethering, use the menu to reinstall binaries and reconfigure and try again.
When the phone starts tethering you need to make it discoverable by other bluetooth devices. That's necessary for pairing with other devices. Use the phone's Settings App and select Wireless Controls > Bluetooth settings > Make device discoverable.
If this is the first time you are pairing your laptop to the phone, you need to pair the phone and your laptop. If you've done this before, you just need to connect the two already-paired devices.
1. Use your laptops control panel to Join a personal network.
2. Add a new bluetooth device. The laptop will start searching for your discoverable phone. Make sure it is still discoverable--it may have timed out.
3. When the phone appears to the laptop, select it.
4. The laptop will issue a pairing request and a unique PIN number. A dialog will pop up on the phone. Type in the number and Ok.
5. The devices should now be paired.
6. On the laptop, select the phone and connect to it.
7. All set. You should now be able to surf the web using the phone's Wifi connection.

Setting up an Adhoc Network

To set up the adhoc network, we will use software that was developed by David Gurecki at NCSU available here: http://moss.csc.ncsu.edu/~mueller/rt/rt09/readings/projects/g3/.

It might be a good idea to read David's Final Report to get all the details on the project. Or alternatively, check the README file for a brief summary:

Installing AdhocClient on the Phone(s)

Download AdhocClient.zip and unzip it.
Either copy the AdhocClient/bin/AdhocClient.apk to your phone using the adb tool (adb install AdhocClient.apk), or create an Eclipse project from the AdhocClient folder and Run the project on your phone.
Start the application.
The default view will be the Incoming Events view.

AdhocClient implements separate threads for UDP sending and receiving. The receiver binds a UDP Datagram Socket to port 8888 and accepts messages from other clients. The sender repeatedly sends Hearbeat messages to the broadcast address on the phone's current network. The network can change depending on the AdhocClient's mode--either DHCP Server or DHCP Client or Access Point (cell tower).

A network control thread invokes a network control script to alternate the Wifi radio configuration between DHCP Server and DHCP Client. Here's the protocol:

The DHCP Client mode runs for a maximum of 60 seconds if an IP address is obtained. If no IP address is obtained, it runs until the “dhcpcd” program returns after a timeout period, which appears to be 30 seconds. The DHCP Server mode runs for 60 seconds. If any heartbeat messages are received in these modes, the thread stops alternating and leaves the phone in the current mode until heartbeats cease to be received. This thread also responds to the Start Service / Stop Service buttons being pressed, driving transitions between the various states and starting up or shutting down services along the way.

That's not terribly clear. Perhaps it can be understood better after a look at the source code.

Running the AdhocClientTester

Download and unzip the AdhocClientTester.zip.
Create a new ad-hoc Wifi network on your laptop. Configure the network for ad-hoc mode and use the same SSID as the G1 phone (G1Tether by default).
Run the tester from the command line: java AdhocClientTester Laptop where Laptop is the user-name of the simulator program. There will be no output until you configure your laptop's WiFi radio is properly configure. And the Tester program may generate a bunch of IOExceptions if it cannot find a host.
Once the Tester receives the first heartbeat from the G1 phone, it will begin outputting messages to stdout and begin responding to the G1 phone using the source IP address of the heartbeat messages.
Use the phone's Friend List to see that it has connected with the Tester. By clicking on an entry in the Friend List, you can send a message to that friend. It should appear in the Tester's output.

Running on a Second Phone

Install AdhocClient on a second (or third...) phone and follow the same steps as above. You should be able to see the friends that are connected on each phone's Friend List and you should be able to send and receive messages between friends.