Thursday, August 30, 2012

How to install a 3G/4G cellular modem on my Android BeagleBoard setup

A lot of folks have been asking me about this one, so I figured it’s about time to pull together my notes on the tutorial and get started…

In this case, I used an Android Ultimate Pro Kit, which runs Android 2.3.4 on the BeagleBoard xM/BeagleTouch/BeagleJuice, 2nd Gen.
Note: There’s a much sleeker (beta) way to get cell modems running in Android with the new PPP widget from Draisberghof. I haven’t tried it out yet, and hooking up modems the old-fashioned way helped me learn a few useful tips and tricks in navigating ADB, so I’m writing it all out here. Enjoy!

Hardware I used
1 BeagleBoard xM
1 BeagleTouch
1 BeagleJuice, 2nd Gen (optional – a 5V power supply works fine too)
1 Android Ambrosia SD card
1 Linux or Mac computer (cygwin for Windows could also do the job, with a little bit of toolchain setup. I used a dedicated Ubuntu EeePC)
1 T-mobile Rocket 3.0 4G laptop stick (but most will work – see below)
1 Type B-mini USB cable for connecting the computer to Amber

Software I used
Android SDK with Android Debug Bridge
Linux terminal (Asus Eee PC is *perfect* for this)

This tutorial assumes that you already have Android SDK with Android Debug Bridge set up, and that you’re communicating to the BeagleBoard/Android device from a Terminal program.

Connecting your Android device
1. Switch on your BeagleJuice, 2nd Gen to power on the Android Ultimate Pro Kit.

2. Once the BeagleBoard is booted into Android, plug in a USB cable from the Linux terminal to the BeagleBoard’s OTG type B-mini port.

3. Open up Terminal in Linux.

4. I have the Android SDK and Android Platform Tools installed, so I can access Android Debug Bridge right from the prompt. The first thing I do is make sure my device is connected by typing:

adb devices

A list of connected and available Android devices should come up.

Tools you’ll need on the Android device

Most USB 3G/4G cellular modems are actually several “devices” rolled into one – the most notable being some form of onboard data storage.

USB_ModeSwitch is a fantastic utility that essentially does the heavy lifting of separating all these devices, so we can talk to the modem over USB serial directly.

5. Download and unzip the static binary for ARM processors: usb_modeswitch-1.1.9-arm-static.bz2

From your working directory, push the usb_modeswitch application to /system/xbin/ on your Android device:

adb push usb_modeswitch-1.1.9-arm-static /system/xbin/usb_modeswitch

6. Download the usbserial.ko kernel module from the Liquidware site. The reason I have it set up as a separate module is so that we can install usbserial as the driver for our modem, which is necessary to communicate. Then push usbserial.ko to your Android device:

adb push usbserial.ko usbserial.ko

This will put the usbserial.ko file in the root folder on your Android device, which is fine for our purposes.
We’ll create the usb_modeswitch config file you’ll need later.

Find your modem identification information

7. Go into Android shell:

adb shell

Now you can issue commands as if you’re in a terminal application on the Android device.

8. To see details about attached USB devices, first mount the usbfs file system.

mount -t usbfs usbfs /proc/bus/usb

Now type in:

cat /proc/bus/usb/devices

You should see a list of devices appear. Each USB device will have a Vendor ID and a Product ID. This detailed information also clues you in by telling you what Driver the USB device is currently using.


The one I’m looking for is the T-Mobile Rocket 4G, made by ZTE. Three relevant pieces of information:


Each device has a vendor and product code identifier. The Driver is “usb-storage”, meaning that the composite modem is recognized as a USB mass storage device. Not very useful for our purposes. That’s where USB ModeSwitch comes in. You’ll tell USB ModeSwitch to send a special string of characters, which then splits the composite device into 6 independently communicating USB serial devices – one of which is our modem.

Write down your Vendor and Product ID, as well as your Manufacturer, Product, and SerialNumber info. These will all be helpful in finding the correct string that you’ll need to send to the modem via ModeSwitch.

7. In order for USB ModeSwitch to run properly, you’ll need to create USB modeswitch config file in the right format that has the correct string of characters. I started by looking on Draisberghof’s extensive list of device references. For the T-Mobile Rocket 4G 3.0 by ZTE, copy the following text into gedit on your Linux terminal, and create a file called usb_modeswitch.conf

# ZTE devices
DefaultVendor=  0x19d2
DefaultProduct= 0x2000
TargetVendor=   0x19d2

8. Push usb_modeswitch.conf down to your Android device.

adb push usb_modeswitch.conf /system/xbin/usb_modeswitch.conf

9. There is one additional file you’ll need, which is known as a chat script. It secures the connection with T-Mobile. Open up gedit again and copy the following text, creating a file called

SAY 'Starting GPRS connect script\n'
SAY 'Setting APN\n'
SAY 'Dialing...\n'
OK 'ATD*99***1#'

10. Push the file down to your Android device:

adb push

This will put into your root directory.

Turn on your 3G/4G cellular modem for Android


Now that all the right files are in the right places, we can execute all the commands at once.

11. Plug in your 3G/4G USB cellular modem. It should start blinking

12. Go into shell on your Android device:

adb shell

13. At the Android shell prompt, enter the following:

/system/xbin/usb_modeswitch -I -W -c usb_modeswitch.conf


The output will tell me whether the operation was successful, and if it was, you’ll see something like the above screenshot.

14. Notice that the “matching” vendor/product ID is 19d2:0157. We can now install the usbserial kernel directly to that device. Make sure you are in the root directory, since that’s where we put the kernel file. The vendor ID and product ID need to be written in hex.

insmod usbserial.ko vendor=0x19d2 product=0x0157

15. Now check to see what devices are attached to USB at this point:

cat /proc/bus/usb/devices

You should see something like the following:


Compare this to the original screenshot, where usb-storage was the only device and driver under this product.

If you’d like, you can check this under the list of serial devices by typing:

ls /dev/tty*


If you see ttyUSB0-5, you’re good to go!

16. This part usually takes a little experimenting to figure out which USB device you want to call with the pppd command. This is the correct one. It will execute the script that you put on the device earlier. (If you’re looking closely, I put my script in a different folder, but that’s not really a big issue as long as you have the right path)

pppd /dev/ttyUSB1 persist defaultroute usepeerdns -detach crtscts noauth debug connect "/system/xbin/chat -v -s -f"


Be sure to leave this terminal window open to maintain the connection.

The above screen shot shows what happens on a successful initiation of the chat script. You are now ready to go online. ifconfig tells me what my network connections are. Note that ppp0 has an IP address, which means we’re connected to T-Mobile.



And the beautiful turquoise beacon, and confirms that I’m online!


I’m sure there are going to be questions – email me at or find me on twitter @liquidware. Or just comment below, and I’ll get back to you immediately.

Next up after the Labor Day Weekend, I’ll explain how to roll this all up into a boot script, so it can run instantly, every time you power on the Android device.

A big thanks to freedune for an excellent and well-written blog post, which steered me through most of this effort!

No comments: