BeagleBone-Android-DevKit Guide

What is BeagleBone

The BeagleBone is a low-cost, high-expansion hardware-hacker focused BeagleBoard. It is a bare-bones BeagleBoard that acts as a USB or Ethernet connected expansion companion for your current BeagleBoard and BeagleBoard-xM or works stand-alone. The BeagleBone is small even by BeagleBoard standards and with the high-performance ARM capabilities you expect from a BeagleBoard, the BeagleBone brings full-featured Linux to places it has never gone before.

http://beagleboard.org/bone

BeagleBone Features

	Feature
Processor	720MHZ AM3359 15x15
Memory	256MB DDR2 200MHz (128MB Optional)
PMIC TPS65217	Power Regulators LiION Single cell battery charger (via expansion) 20mA LED Backlight driver, 39V, PWM (via expansion)
Debug Support	USB to Serial Adapter, On Board JTAG via USB, miniUSB connector, 4 USER LEDs Optional 20-pin CTI JTAG
Power	5VDC External jack USB
PCB
Indicators	Power 4-User Controllable LEDs
HS USB 2.0 Client Port	Access to the USB1 Client mode
HS USB 2.0 Host Port	USB Type A Socket, 500mA LS/FS/HS
Ethernet	10/100, RJ45
SD/MMC Connector	microSD , 3.3V
User Interface	1-Reset Button
Overvolatage Protection	Shutdown @ 5.6V MAX
Expansion Connectors	Power 5V, 3.3V , VDD_ADC 3.3V I/O on all signals McASP0, SPI1, I2C, GPIO(65), LCD, GPMC, MMC1, MMC2, 7 AIN(1.8V MAX), 4 Timers, PRI_MII0, 3 Serial Ports, CAN0, EHRPWM(0,2),XDMA Interrupt, Power button, Battery Charger, LED Backlight, Expansion Board ID (Up to 3 can be stacked)

BeagleBone Unique Characteristics

Open Low Cost High Performance Board

BeagleBone has ARM CortexA8 720MHz + 3D graphics acceleration with SGX and priced at a very low $89 with Open community support from beagleboard.org and arowboat.org

Single Cable to provide Power, Debug and Serial

Mini USB Cable from BeagleBone to the Host Machine can provide Power, Debug and Serial connections at the same time.

BeagleBone offers an easy replacement  for underpowered micro-controller-based controller boards

BeagleBone offers extensive expansion, on-chip Ethernet, analog-to-digital data conversion and a lower cost. Much more applications are supported on BeagleBone since High level OS like Android and Linux is supported

Android on BeagleBone

BeagleBone is a very low cost EVM, equiped with ARM Cortex A8 processor and SGX.

This platform is well suited as a development platform for low-end and mid-end android solutions.

Moreover the Android solution on BeagleBone can be used as an Open Accessory Kit for connecting to other Android Devices.

Objective of this wiki page

This wiki page has mainly two objectives

1. Quickly evaluate Android GingerBread using pre-built images
2. Start develop using sources
   

IMPORTANT

A newer release of TI Android DevKit for BeagleBone is available. See TI-Android-ICS-4.0.3-DevKit-3.0.1 ReleaseNotes for more details.

Installation and Usage

This section explains how to prepare a micro-sd card for booting android on the BeagleBone. The details on booting the BeagleBone and evaluating Android is also explained.

Getting Prebuilt Images

BeagleBone Prebuilt SD card image from TI Android DevKit download page

Preparation of SD card

Connect a Micro SD card (Atleast 2GB size and Class 4) via a USB card reader on an Ubuntu Machine
From a terminal, type the below commands,

$ tar -xzvf BeagleBone.tar.gz
$ cd BeagleBone
$ sudo ./mkmmc-android.sh /dev/sd<device> 

The above step prepares the SD Card with three partitions.

1. boot - Boot Images (Boot Loaders, Boot Script and Kernel)
2. rootfs - File system (Android GingerBread 2.3.4)
3. data - Media Clips (Audio, Video and Images)

Now this card can be used to boot the BeagleBone

Hardware setup

Connect MiniB USB Cable, Ethernet Cable and 5V DC Power to the BeagleBone and have it powered. Windows or Linux Host can be used to connect and evaluate BeagleBone. We prefer to use Ubuntu 10.04 as the host to connect to BeagleBone.

Getting serial console

Serial console is provided via MiniB USB connection between the BeagleBone and the Host.

In Windows

Side note: it may be possible to download BONE_DRV.exe for 32-bit Windows or BONE_D64.exe for 64-bit Windows to avoid needing to manually edit the driver entries, but this has not yet been validated.

For Windows XP, Download FTDI driver from http://www.ftdichip.com/Drivers/CDM/CDM20814_WHQL_Certified.zip

Extract the contents and edit the ftdibus.inf file

Replace the section between

[FtdiHw]

and

[FtdiHw.NTamd64]

with the following content

%USB\VID_0403&PID_A6D0.DeviceDesc%=FtdiBus.NT,USB\VID_0403&PID_A6D0
%USB\VID_0403&PID_A6D0&MI_00.DeviceDesc%=FtdiBus.NT,USB\VID_0403&PID_A6D0&MI_00
%USB\VID_0403&PID_A6D0&MI_01.DeviceDesc%=FtdiBus.NT,USB\VID_0403&PID_A6D0&MI_01
%USB\VID_0403&PID_A6D0&MI_00.DeviceDesc%=FtdiBus.NT,USB\VID_0403&PID_A6D0&MI_00
%USB\VID_0403&PID_A6D0&MI_01.DeviceDesc%=FtdiBus.NT,USB\VID_0403&PID_A6D0&MI_01
%USB\VID_0403&PID_A6D0&MI_02.DeviceDesc%=FtdiBus.NT,USB\VID_0403&PID_A6D0&MI_02
%USB\VID_0403&PID_A6D0&MI_03.DeviceDesc%=FtdiBus.NT,USB\VID_0403&PID_A6D0&MI_03
%USB\VID_0403&PID_A6D0.DeviceDesc%=FtdiBus.NT,USB\VID_0403&PID_A6D0

Also

Replace the section between

DriversDisk="FTDI USB Drivers Disk"

and

SvcDesc="USB Serial Converter Driver"

with the following content

USB\VID_0403&PID_A6D0.DeviceDesc="USB Serial Converter"
USB\VID_0403&PID_A6D0&MI_00.DeviceDesc="USB Serial Converter A"
USB\VID_0403&PID_A6D0&MI_01.DeviceDesc="USB Serial Converter B"
USB\VID_0403&PID_A6D0&MI_00.DeviceDesc="USB Serial Converter A"
USB\VID_0403&PID_A6D0&MI_01.DeviceDesc="USB Serial Converter B"
USB\VID_0403&PID_A6D0&MI_02.DeviceDesc="USB Serial Converter C"
USB\VID_0403&PID_A6D0&MI_03.DeviceDesc="USB Serial Converter D"
USB\VID_0403&PID_A6D0DeviceDesc="USB Serial Converter"

Then follow these steps

• Boot the board
• Connect Mini B USB cable between board and Windows PC.
• If it is proceeding as planned, Windows will tell you it found a new hardware and asks you to install the driver. Install the driver that was downloaded as described in the above step.
• Answer "No, not this time" to the question about running Windows Update to search for software.
• Choose "Install the hardware that I manually select from a list (Advanced)" this is the 2nd option, then click "Next"
• Select "Show All Devices", then click "Next"
• You are going to see a grayed-out text box with "(Retrieving a list of all devices)", click the "Have Disk..." button.
• Browse to your driver folder (c:\...\_driver). It will be looking of a .inf file so select "ftdibus.inf" and click "Open" then "OK".
• Select "USB Serial Port" then click the "Next" button.
• A warning will appear, answer "Yes" but read the warning anyway.
• Click on "Close" when the wizard is completed.
• Disconnect and reconnect Mini B USB cable from Board (probably reboot it as well).
• Serial COM port will be listed on the Terminal Utility menu.
• Adjust the baud rate to 115200 to connect to the BeagleBone serial.

In Linux

To get serial console output on Ubuntu follow these steps:

$ sudo modprobe ftdi_sio vendor=0x0403 product=0xa6d0
$ minicom -D /dev/`dmesg | grep FTDI | grep "now attached to" | tail -n 1 | awk '{ print $NF }'`

Note:

• You might need to make sure minicom's serial port setup is for 115200n8 with hardware flow control. You can get into the minicom configuration menu by invoking 'minicom -s' and selecting serial port setup -> Serial Device (option A).
• You may have to run minicom with sudo in case sufficient permission is not available for the USB serial node

Verifying Serial Connection

Once you finish setting up serial console, you can test the connection via the below steps

• Push the small black reset button beside Ethernet port
• If your serial connection is proper, you can see the sequence 'CCCC' appearing on the serial console.

Powering on to Android Terminal

Put the Micro SD card into the slot on the BeagleBone. Press the reset button again. See X-loader and Uboot loading. Allow the boot loader to run the boot script uEve.txt to run.Kernel boots up and Android shell is activated. Wait for Android init to start the zygote thread.
See the below message appearing on the shell.

warning: `zygote' uses 32-bit capabilities (legacy support in use) 

Android Display through VNC

Since the BeagleBone currently does not have a display output, we rely on a VNC connection from the Host to the BeagleBone. Here are the steps to establish a VNC connection between the BeagleBone and the Host PC

Setup Ethernet and VNC server

Make sure the Ethernet port on the board and host machine are connected to the network. Check Ethernet configuration for the board

  # netcfg
  lo UP 127.0.0.1 255.0.0.0 0x00000049
  eth0 DOWN 0.0.0.0 0.0.0.0 0x00001002

If Ethernet was not configured, configure Ethernet on the board using ifconfig/netcfg as shown below.

  # netcfg eth0 up
  # netcfg eth0 dhcp

Wait for the Ethernet configuration to complete. If you see the above command taking too much time the Ethernet cable may be loose. Attach the Ethernet cable once again on the port and type the command again. You can check the Configuration again via type netcfg command to see the Ethernet is configured.

  # netcfg
  lo UP 127.0.0.1 255.0.0.0 0x00000049
  eth0 UP 172.24.191.37 255.255.252.0 0x00001043

Now the VNC server can be started in the background.

  # androidvncserver &

Connecting to target from Host

Using VNC Viewer application, the user can connect to the Beaglebone at the target address [e.g. 172.24.191.37] port 5901.

USB Debugging

Android Debug Bridge (adb) is a versatile tool lets you manage the state of the Android-powered device. For more information about what is possible with adb, see Android Debug Bridge page at http://developer.android.com/guide/developing/tools/adb.html. The ADB tool can be used to

1. Download an application from a host machine, install & run it on the target board.
2. Start a remote shell in the target instance.
3. Debug applications running on the device using the debugging tool DDMS ( Dalvik Debug Monitor Server) which runs on top of adb connection.
4. Copy files to and from the board and host machine

Please visit http://processors.wiki.ti.com/index.php/Android_ADB_Setup for setting up ADB on BeagleBone

Running Android Applications

Keypad mappings

The below table lists the keypad and USB Keyboard mappings for Android UI functionality

Functionality	USB Keyboard/Mouse
Home Screen	Home
Left	Left Arrow
Right	Right Arrow
Up	Up Arrow
Down	Down Arrow
Volume Up	Volume Up
Volume Down	Volume Down
Contacts	F3
Power
Select	Enter
Back / Previous screen	Mouse right
Menu	F1

Android Home Screen

After the first boot, the user will see an unlocked Android home screen. On subsequent boots, a locked screen will be displayed. The user needs to unlock the screen via Mouse/Keyboard [Either HOST or TARGET]. You can easily unlock the screen via pressing the F1 key on the keyboard. Once the screen is unlocked, the user can navigate to Google Search, Tips, Browser or Application Launcher. Click the Application Launcher to see all pre-built applications.

Gallery Application

In Gallery, the user can view the images and play videos.

RowboPERF and 3D graphics applications

RowboPERF is a comprehensive set of benchmarks and Demos.
Select the RowboPERF icon to get into the app directory. For more information on RowboPERF, please check RowboPERF User Guide

Browser Configuration

To browse web pages, the user should configure the Internet connection as given below.

  # netcfg eth0 up
  # netcfg eth0 dhcp
  # getprop net.eth0.dns1

This prints the DNS for the Ethernet port, do the following to configure the DNS entries on board.

  # setprop net.dns1 <your_dns_server_ip>

If the platform is behind a proxy, the following command should be executed to set the proxy settings

  # setprop net.gprs.http-proxy http://proxyurl:80

USB Mouse/Keyboard

Connect the USB Mouse/Keyboard to USB HOST port . The keyboard/mouse will be functional if it was plugged in while booting.
Otherwise type the below command to make it functional

  # echo F > /proc/driver/musb_hdrc.1

Developing with source code

This section show the steps to obtain the complete source code for the android images(Boot loader, Kernel and File System) and to build the same.

Host (PC) setup requirements

The host development environment for Android is based on Ubuntu, please install Ubuntu version 10.04 or later http://www.ubuntu.com/desktop/get-ubuntu/download. The host installation would need a few more Android specific dependencies, these can be installed dynamically over the network using the below commands.
For Ubuntu on 32-bit machines

$ sudo add-apt-repository "deb http://archive.canonical.com/ lucid partner"
$ sudo add-apt-repository "deb-src http://archive.canonical.com/ubuntu lucid partner"
$ sudo apt-get update
$ sudo apt-get install git-core gnupg sun-java6-jdk flex bison gperf libsdl-dev libesd0-dev libwxgtk2.6-dev build-essential zip curl libncurses5-dev zlib1g-dev minicom tftpd uboot-mkimage expect
$ sudo update-java-alternatives -s java-6-sun

NOTE: Android Gingerbread (2.3.4) needs Java 6 on ubuntu, whereas the previous version FroYo (2.2) was using Java 5.
Getting Source Code

Developers can download the sources from the gitorious.org/rowboat repository.

A tool called 'Repo' helps to fetch the android sources from gitorious.org/rowboat. Repo is a tool that makes it easier to work with Git in the context of Android.
For more information about Repo, see the link http://source.android.com/source/version-control.html.
To install, initialize, and configure Repo, follow these steps:
Make sure you have a bin/ directory in your home directory, and that it is included in your path:

$ mkdir ~/bin
$ PATH=~/bin:$PATH

Download the Repo script and ensure it is executable:

$ curl https://dl-ssl.google.com/dl/googlesource/git-repo/repo > ~/bin/repo
$ chmod a+x ~/bin/repo

The following commands help developers to clone sources from www.gitorious.org/rowboat repository

$ mkdir $HOME/rowboat-android
$ cd $HOME/rowboat-android
$ repo init -u git://gitorious.org/rowboat/manifest.git -m rowboat-gingerbread-am335x.xml
$ repo sync

Building Source Code

Tool chain setup

Setup the tool-chain path to point to arm-eabi- tools in prebuilt/linux-x86/toolchain/arm-eabi-4.4.3/bin

$ export PATH=$HOME/rowboat-android/prebuilt/linux-x86/toolchain/arm-eabi-4.4.3/bin:$PATH

Compilation procedure

To build MLO and boot loader (u-boot)

• Change directory to u-boot

  $ cd u-boot

• Execute the following commands

  $ make CROSS_COMPILE=arm-eabi- distclean
  $ make CROSS_COMPILE=arm-eabi- am335x_evm_config
  $ make CROSS_COMPILE=arm-eabi-

• This command will generate the MLO and the u-boot Image "u-boot.img"

NOTE: Copy the "mkimage" from "tools" folder to /usr/bin folder on your host machine, this is needed for kernel uImage generation

To build Linux kernel

• Change directory to kernel

  $ cd kernel

• Do the following to build kernel sources for BeagleBone

  $ make ARCH=arm CROSS_COMPILE=arm-eabi- distclean
  $ make ARCH=arm CROSS_COMPILE=arm-eabi- beaglebone_android_defconfig
  $ make ARCH=arm CROSS_COMPILE=arm-eabi- uImage

• This will generate uImage (kernel image) in kernel/arch/arm/boot folder

To build the Android file system

• RowboPERF Integration
  • Download the sources from rowboat

  $ git clone -b rowboat-gingerbread git://gitorious.org/rowboat/rowboperf.git $ cd rowboperf

NOTE: Clone RowboPERF sources inside the rowboat-android tree.

• Have Android SDK in the PATH of the host machine
• Android file system build will take care of the integration of rowboperf applications

• Android VNC Server Integration

• Download the sources from rowboat

  $ git clone -b rowboat-gingerbread git://gitorious.org/rowboat/droid-vnc-server.git

NOTE: Clone droid-vnc-server sources inside the rowboat-android tree.

• Android file system build will take care of the integration of android vnc server application

To Build the root file system for BeagleBone, from android source top directory, type the following command

  $ make TARGET_PRODUCT=beaglebone OMAPES=4.x

The above command will build Android FS, kernel, SGX drivers. After successful build, the kernel image can be found at kernel/arch/arm/uImage. Android rootfs components (root and system folders) will be located in out/target/product/beaglebone. SGX drivers and libraries are installed in Android rootfs components.

Create root file system tarball

Prepare the root file system as follows:

  $ cd out/target/product/beaglebone
  $ mkdir android_rootfs
  $ cp -r root/* android_rootfs
  $ cp -r system android_rootfs
  $ sudo ../../../../build/tools/mktarball.sh ../../../host/linux-x86/bin/fs_get_stats android_rootfs . rootfs rootfs.tar.bz2

The rootfs.tar.bz2 is the android file system, it can be put on a SD/MMC Card or used over NFS.

To generate SD/MMC card to boot Android

These compiled Images can be copied to a SD / MMC card to boot Android on the BeagleBone.

The text file uEnv.txt is required to provide the boot commands and boot arguments.

Generate a text file uEnv.txt with the following contents

  bootargs=console=ttyO0,115200n8 androidboot.console=ttyO0 mem=256M root=/dev/mmcblk0p2 rw rootfstype=ext3 rootwait init=/init ip=off
  bootcmd=mmc rescan ; fatload mmc 0 81000000 uImage ; bootm 81000000
  uenvcmd=boot

Copy all the images to one folder

  $ mkdir image_folder
  $ cp kernel/arch/arm/boot/uImage image_folder
  $ cp u-boot/u-boot.img image_folder
  $ cp u-boot/MLO image_folder
  $ cp out/target/product/beaglebone/rootfs.tar.bz2 image_folder
  $ cp Media_clips image_folder

NOTE: Get the Media_clips folder from the SD card prebuilt image

  $ cp mkmmc-android.sh image_folder

NOTE: Get the mkmmc-android.sh script from the SD card prebuilt image

Connect an SD card to the Host machine

Invoke the mkmmc-android.sh script to prepare the card for booting

  $ cd image_folder
  $ sudo ./mkmmc-android.sh <sd card mounted dev folder example:/dev/sdc> MLO u-boot.img uImage uEnv.txt rootfs.tar.bz2 Media_Clips

Wait for the script to complete.
Safely remove the SD card and put it on the BeagleBone for Booting.

References

1. More about the AM3358/9 device used on the BeagleBone at http://www.ti.com/am335x.
2. AM335x Technical Reference Manual at http://www.ti.com/lit/ug/spruh73/spruh73.pdf
   
3. Android Sources for BeagleBone is hosted at www.gitorious.org/rowboat with manifest rowboat-gingerbread-am335x.xml
   
4. Android on BeagleBone community support at arowboat.org
   
5. BeagleBoard.org design materials, including BeagleBone
6. BeagleBone Rev A3 System Reference Manual
7. BeagleBone Rev A3 Schematic
8. BeagleBone Rev A3 Bill Of Materials

Observations

1. Ethernet is now limited to 10Mbits, So the display resolution is lowered to get a faster refresh rate on the VNC screen.
   
2. Host Mouse/Keyboard event responses will be slower compared to target side Mouse/Keyboard events
   
3. Serial Connection may occasionally not be established properly. But it is reliable on Linux host.
   
4. If target side mouse-keyboard is connected to the board after bootup, the command "echo F > /proc/driver/musb_hdrc.1" can be issued to detect them.
   
5. External Power is required as USB connection power supply sometimes goes off unexpectedly.