TI-AM1808-Android-FroYo-DevKit UserGuide

TI AM1808 Android User Guide

User Guide - January 4, 2011

About this manual

This document describes how to build, install and work with Texas Instruments' Android portal rowboat for AM1808 platform. The rowboat branch for AM1808 provides a stable Android code base with features like ADB over Ethernet,UART Console, USB Host for Mouse connectivity,Audio out,in and standard applications from Android. This portal forms the basis for all further Android application development on TI platforms. In this context, the document contains instructions to:

• Build the the code base
• Setting up the hardware
• Steps to use the built binaries
• Running Android on the AM1808 platform
• Setting up the Android debugger “adb” with the hardware platform
• Installing and executing Android (out of market) applications hardware platforms

Requirements

This section describes the list of Software and Hardware requirements to set-up Android on AM1808.

• Hardware Requirements:

• Target Platform Requirements

This build set-up is verified is evaluated on the below given list of platforms. This package should be easily portable on other platforms on similar TI devices.

TI Device	Platform Supported	Version	Other Accessories
AM1808	AM1808 EVM	Rev B	USB Keyboard, USB Mouse, Ethernet, UART Cable, Audio Speakers, MMC/SD Card (2GB min)

• Host Platform Requirements

If you are a Android application developer or would like to use Android SDK Tools then refer to http://developer.android.com/sdk/requirements.html for Host PC requirements. To build and evaluate the Android Images listed here, we recommend you to have a Linux "Ubuntu 8.04 or above" Host machine, See Ubuntu Linux installation notes

• Software requirements

• Refer to arowboat.org for software requirements at host side
• Installing the repo tool:

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

Building Android Sources

Android sources (filesystem) can be built by following the instructions documented here

Required packages

Git 1.5.4 or newer and the GNU Privacy Guard. JDK 5.0, update 12 or higher. Java 6 is not supported, because of incompatibilities with @Override. flex, bison, gperf, libsdl-dev, libesd0-dev, libwxgtk2.6-dev (optional), build-essential, zip, curl, minicom, tftp-server, uboot-mkimage

For Ubuntu 32-bit use such command:

  $ sudo apt-get install git-core gnupg sun-java5-jdk flex bison gperf libsdl-dev libesd0-dev libwxgtk2.6-dev build-essential zip curl libncurses5-dev zlib1g-dev minicom tftpd uboot-mkimage

Ubuntu Intrepid (8.10) users may need a newer version of libreadline:

  $ sudo apt-get install lib32readline5-dev

Configuring the HOST build environment

• Exporting top level Android root directory where Rowboat-Froyo sources are cloned.

  $ export ANDROID_ROOT=~/rowboat-android

• Adding Android and code-sourcery toolchain in the default PATH.

  Note: code-sourcery arm-2010q1 toolchain is used to build U-Boot and UBL.

  $ export PATH=$ANDROID_ROOT/prebuilt/linux-x86/toolchain/arm-eabi-4.4.0/bin:$PATH

• Exporting the Rootfs directory which can be used as a NFS share as well.

  $ export NFS_ROOT=$ANDROID_ROOT/out/target/product/am1808evm/android_rootfs

• Exporting the u-boot source directory.

  $ export UBOOT=~/u-boot-x.xxx

Downloading the AM1808EVM Android Froyo(Rowboat) sources

  $ mkdir $ANDROID_ROOT
  $ cd $ANDROID_ROOT
  $ ~/bin/repo init -u git://gitorious.org/rowboat/manifest.git -m rowboat-froyo-am1808.xml
  $ ~/bin/repo sync

In top level Makefile, add below three lines.

ifneq ($(TARGET_PRODUCT), am1808evm)
rowboat: sgx
endif 

Building AM1808EVM Android Froyo(Rowboat) rootfs

  $ cd $ANDROID_ROOT
  $ make TARGET_PRODUCT=am1808evm droid

Installing the rootfs to the NFS share

  $ mkdir $NFS_ROOT
  $ cp -rf $ANDROID_ROOT/out/target/product/am1808evm/root/* $NFS_ROOT
  $ cp -rf $ANDROID_ROOT/out/target/product/am1808evm/system $NFS_ROOT

Building UBL and u-boot

For u-boot and ubl you can refer to official AM1808 Linux Getting Started Guide. http://processors.wiki.ti.com/index.php/GSG:_Building_Software_Components_for_OMAP-L1

Building AM1808EVM kernel

  $ cd $ANDROID_ROOT/kernel
  $ make ARCH=arm CROSS_COMPILE=arm-eabi- clean
  $ make ARCH=arm CROSS_COMPILE=arm-eabi- da850_omapl138_android_defconfig
  $ make ARCH=arm CROSS_COMPILE=arm-eabi- uImage

Packaging the Rootfs

  $ cd $ANDROID_ROOT/out/target/product/am1808evm
  $ sudo ../../../../build/tools/mktarball.sh ../../../host/linux-x86/bin/fs_get_stats android_rootfs . rootfs rootfs.tar.bz2

Preparing the MMC card

To boot Android from SD/MMC card you must have it partitioned like following:

$ sudo fdisk /dev/<your sdcard,for example sdd> Command (m for help): p

Disk /dev/sdd: 1977 MB, 1977614336 bytes 64 heads, 63 sectors/track, 957 cylinders Units = cylinders of 4032 * 512 = 2064384 bytes Disk identifier: 0x00000000

Device Boot Start End Blocks Id System /dev/sdd1 * 1 30 60448+ b W95 FAT32 /dev/sdd2 31 957 1868832 83 Linux 

Format the partitions for use the commands:

$ sudo mkfs.msdos /dev/sdd1 $ sudo mkfs.ext3 /dev/sdd2 

You can place your media clips in the W95 FAT32 partition:

$ sudo mkdir -p /mnt/fat32
$ sudo mount /dev/sdd1 /mnt/fat32 $ sudo cp -r Media_Clips /mnt/fat32 

Unpack the Android tarball above onto the EXT3 partition:

$ cd $ANDROID_ROOT
$ sudo mkdir -p /mnt/ext3 
$ sudo mount /dev/sdd2 /mnt/ext3 
$ sudo tar jxfv out/target/product/am1808evm/rootfs.tar.bz2 --numeric-owner -C /mnt/ext3 

And the final step:

$ sync
$ sudo umount /mnt/fat32; sudo umount /mnt/ext3 

Setting up Hardware

Before booting up Android setup the platform

• Connect the UART port of the platform to the Host PC and have a Terminal software like TeraTerm, Minicom or Hyperterminal.
• Connect the Ethernet 
• Connect Audio Speakers
• Connect a USB keyboard or USB Mouse to the USB port
  

Booting Android

AM1808 EVM can be booted via TFTP or SPI FLASH. We follow and prefer SPI FLASH based booting of the platform.

Procedure to flash UBL and U-Boot

Please follow this guide on flashing UBL and U-Boot to SPI FLASH http://processors.wiki.ti.com/index.php/GSG:_OMAP-L138_DVEVM_Additional_Procedures#Flashing_images

Procedure to flash Kernel

Download kernel to C0700000 from tftp. Use 'sf' tools to flash it to the SPI FLASH.

U-boot>dhcp C0700000 [hostIPaddr:]uImage
U-boot>sf probe 0 
U-boot>sf erase C0000 300000 <till kernel size> 
U-boot>sf write C0700000 C0000 300000 <till kernel size> 
U-boot>setenv bootcmd 'sf probe 0; sf read C0700000 C0000 300000; bootm c0700000' 

Booting the platform

Booting Android with File System from MMC

Set the bootargs for MMC File System and set the boot command to load the Kernel from SPI FlASH. Then type boot

U-boot> setenv bootargs 'init=/init console=ttyS2,115200n8 ip=off rw root=/dev/mmcblk0p2 rootfstype=ext3 rootwait mem=128M mpurate=450 androidboot.console=ttyS2'
U-boot> setenv bootcmd 'sf probe 0; sf read C0700000 C0000 300000; bootm c0700000'
U-boot> boot

Booting Android with File System from NFS

Set the bootargs for Network File System and set the boot command to load the Kernel from SPI FlASH. Then type boot

U-boot> setenv bootargs 'init=/init console=ttyS2,115200n8 ip=off rw root=/dev/nfs nfsroot=<HostIpAddress>:<NFS Path>,nolock 
    mem=64M mpurate=450 androidboot.console=ttyS2'
U-boot> setenv bootcmd 'sf probe 0; sf read C0700000 C0000 300000; bootm c0700000'
U-boot> boot

What is today on AM1808

• LCD
• Touchscreen
• ADB over Ethernet
• Ethernet
• UART Console
• USB Host for Mouse connectivity
• Audio out
• Audio in
  

ADB Android Debugger & Downloader

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

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

Downloading "ADB" & Host setup

The adb tool is a part of Android SDK package located at http://developer.android.com/sdk/index.html. For an overview of how to install and set up the Android SDK, follow download & setup instructions from http://developer.android.com/sdk/index.html. Once you install Android SDK, the directory contents look like this.

  add-ons/
  docs/
  platforms/
    <platform>/
       data/
       images/
       skins/
       templates/
       tools/
       android.jar
  samples/
  tools/
SDK Readme.txt

The adb tool is located in tools/ directory under the Android SDK installation. Export the tools directory path as shown below.

  $> export PATH=${PATH}:<your_sdk_dir>/tools

Connecting Host machine & board through adb

This release of DevKit has been tested for three different methods of connecting a given board with host machine

• adb over USB
• adb over USB Ethernet
• adb over Ethernet

The below sections describe each of these methods and provides necessary instructions for the same.

adb over USB

• Not supported as of now

adb over USB Ethernet (Ethernet over USB)

• Not supported as of now

adb over Ethernet

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

    target #> netcfg                                                                        
       lo       UP    127.0.0.1       255.0.0.0       0x00000049                       
       eth0     UP    172.24.190.59   255.255.252.0   0x00001043                       

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

    target #> netcfg eth0 dhcp

• Configure the ADB Daemon to use an ethernet connection using setprop as shown below.

    target #> setprop service.adb.tcp.port 5555

• If network is configured successfully (above steps) then Restart service adbd on the target,

    target #> stop adbd
    target #> start adbd

• On the host machine use following commands to establish adb connection

    $> export ADBHOST=<target's ip address>
    $> adb kill-server
    $> adb start-server

• Verify for device connectivity, by executing the following commands

    $> adb devices If connected, you'll see the device name listed as a "emulator"

    $> adb devices

    If connected, find the device name listed as a "emulator"

    List of devices attached
    emulator-5554    device
    $ adb shell 

For more information about adb commands, see Android Debug Bridge page at http://developer.android.com/guide/developing/tools/adb.html

adb over USB on Windows Machine

Follow the below instructions to get ADB over USB work on a Windows PC

• Download latest Android SDK

(http://developer.android.com/sdk/index.html) and uncompress it in a local folder (i.e. c:\android_sdk).

• Optionally, you may want to add the location of the SDK's primary tools directory to your system PATH. Right-click on My Computer, and select Properties. Under the Advanced tab, hit the Environment Variables button, and in the dialog that comes up, double-click on Path (under System Variables). Add the full path to the tools\ directory to the path.

• Download Android USB Driver

(https://dl-ssl.google.com/android/repository/usb_driver_r03-windows.zip) and uncompress it in a local folder (i.e. c:\android_sdk\usb_driver)

• Edit (or create and then edit if it doesn't already exist) file in

"%USERPROFILE%\.android\adb_usb.ini":

  echo 0x18D1 > "%USERPROFILE%\.android\adb_usb.ini"

• Edit android_winusb.inf to match EVM/Beagle vendor and product ids:

Under [Google.NTx86] section add:

  ;TI EVM
  %SingleAdbInterface%        = USB_Install, USB\VID_18D1&PID_9018
  %CompositeAdbInterface%     = USB_Install, USB\VID_18D1&PID_9018&MI_01

Note: Be careful to add it under Google.NTx86 and not under Google.NTamd64 unless your machine is AMD 64 bits. If you skip this step you won't be able to later install the driver as windows will reject it.

• Boot the board as normal and wait until shell prompt is available (micro-B USB cable must be disconnected).

• Connect micro-B USB cable between board and Windows PC.

• If it is proceeding as planned, Windows will tell you it found a new hardware asks you to install the driver. Install driver that was downloaded as described in step 3 above:

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:\android_sdk\usb_driver). It will be looking of a .inf file so select "android_winusb.inf" and click "Open" then "OK". It's the only file there so you shouldn't go wrong.
  • Select "Android ADB Interface" then click the "Next" button.
  • A warning will appear, answer "Yes" but read the warning anyway.
  • Click the "Close" when the wizard is completed.

• Disconnect and reconnect micro-B USB cable from Board(probably reboot it as well).

• Open command prompt and restart adb server just to make sure it is in a proper state:

  adb kill-server
  adb start-server

• List the attached devices with "adb devices". It should show your board/device with a random number.

• Type "adb shell". You should see the "#" indicating it works.

Running Applications

The root File System provided in this DevKit releases contains only standard Android components and applications. User might be interested to download & run android applications (.apk) available in the market. The below procedure gives the steps to be followed to download any .apk file to the board and run it on the platform.

Installing (.apk files) application on Target Platform

• From the host: You can use adb tool for package installation.

    $> adb install <package>.apk. 
    

NOTE: Use -s option with the adb tool, to install the package on external storage.

On successful installation adb tool will report SUCCESS on host terminal, and the application would be listed on the android main menu.

Un-installing applications (.apk) using adb

• To un-install non-default components (that were installed later)
  • Method 1: On the host machine execute the following

    $> adb uninstall <package>.apk

• • Method 2: On target:

    Main menu -> Menu -> Settings -> Applications -> Manage applications -> Find the package 
    Tap on it -> Uninstall -> OK -> OK

• • On successful removal, the application would have been removed from the android main menu. All the short-cuts to the application also removed.

• To un-install default components, use the following commands from abd on host machine

    $ adb shell
    #rm /system/app/app.apk

On successful removal, the application would have been removed from the android main menu.

Setup ADB for application Debugging

ADB and Eclipse, with ADT( Android Development Tools plug-in) allow users to create and debug Android applications. Follow Developing In Eclipse, with ADT at http://developer.android.com/guide/developing/eclipse-adt.html

Steps to connect Eclipse to the board.

• Setup the adb connection with the board by following the instructions given above in connecting board ...

    Verify the connectivity by executing 
    $ adb devices

• Open Eclipse IDE. Eclipse, with ADT plugin enable users to
  • Create an android project.
  • Build and Run the project on a connected board.
  • Debug the project using the Debug perspective.
  • Use DDMS (Dalvik Debug Monitor Server) to monitor the connected board.

For more detailed and complete information on the above follow Developing In Eclipse, with ADT at http://developer.android.com/guide/developing/eclipse-adt.html

• Open DDMS(Dalvik Debug Monitor Server) perspective. This DDMS perspective can be opened from the eclipse menu via:

    Window -> Open Perspective -> Other -> DDMS; 
    Click on OK

• DDMS provides port-forwarding services, screen capture on the device, thread and heap information on the device, logcat, process, and radio state information,incoming call and SMS spoofing, location data spoofing, and more.

• For more information on DDMS and to use it, follow Using the Dalvik Debug Monitor page at http://developer.android.com/guide/developing/tools/ddms.html

Copy any files to and from the board over ADB

• Using the adb commands "pull" and "push" user can copy files to and from the board.
• Unlike the install command, which only copies an .apk file to a specific location, the pull and push commands let you copy arbitrary directories and files to any location on the board.

• To copy a file or directory (recursively) from the board, use

    adb pull <remote> <local>

• To copy a file or directory (recursively) to the board, use

    adb push <local> <remote>

In the commands, <local> and <remote> refer to the paths to the file or directory on your development host (local) and on the target instance (remote).

    Here's an example: 
    adb push foo.txt /sdcard/foo.txt

Adobe Flash 10 Integration

The Android version of Flash10 that runs on Froyo is now available for customer download (by registration) at, http://focus.ti.com/docs/toolsw/folders/print/adobeflash-a8.html

The below steps give the procedure to download the Adobe Flash 10 library for Android FroYo and installing the same in File system.

• Download the flashplayer installer “Flash10.1_Android_Webkit_Plugin-0.4-Linux-x86-Install.bin” from http://focus.ti.com/docs/toolsw/folders/print/adobeflash-a8.html

• Execute the installer

  #> ./ Flash10.1_Android_Webkit_Plugin-0.4-Linux-x86-Install.bin
  Will result in following instruction, press "Y" 

  This will install Flash10.1 Android Webkit Plugin on your computer.  Continue? [n/Y] Y
  Select the source install location
  Where do you want to install Flash10.1 Android Webkit Plugin? 
  [/home/user/flash10_androidplugin] /home/user/flash10_androidplugin

  Installing Flash10.1 Android Webkit Plugin...
  Installing Program
  Files...                                                                                                                                
  Installation complete.
  After Installation the following directory structure is resulted 

• Change to Flash installed directory on Host PC

  #> cd flash10_androidplugin 
  #> ls
  install_flash_player.apk  uninstall

• Install flash player plug in on target via adb

 #> adb install install_flash_player.apk

• Do the browser configuration
  • Explained in the below section

• Test the Adobe Flash installation
  • Browse the link http://www.adobe.com/software/flash/about/
  • Should display Adobe Flash Player Successfully Installed

Compatibility Test Suite (CTS)

This section describe the procedure to run CTS on any platform.

• Pre-requisites
  • Download and extract (untar) the CTS package from http://dl.google.com/dl/android/cts/android-cts-2.2_r3-x86.zip
  • Download and extract (untar) Google Android SDK from http://dl.google.com/android/android-sdk_r07-linux_x86.tgz
• Setup an ADB connection between Host and platform as mentioned in ADB section above.
• Setup your platform to run the accessibility tests:
  • adb install -r android-cts/repository/testcases/CtsDelegatingAccessibilityService.apk
  • On the device enable Settings > Accessibility > Accessibility > Delegating Accessibility Service
• Launch the CTS.
  • Edit android-cts/tools/startcts to point SDK_ROOT to android sdk installation location.
  • Run ./tools/startcts
  • On CTS prompt check the available plans

  cts_host > ls –plan 

• • Start a specific Test Plan

  cts_host > start --plan <plan name>

Once all the tests are executed, the results can be browsed in an browser by opening [android-cts/repository/results/session-name/testResult.xml] and use the results to adjust your design.

Configuring Android Applications

Browser Configuration

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

    #> 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 proxy, then following command should be executed to set the proxy settings

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

NOTE: If network is behind a proxy, in this DevKit release, we have NOT found a method to set the proxy server. We tried using "setprop net.eth0.http-proxy hostname:port" and "setprop net.gprs.http-proxy hostname:port", but neither could get us through the proxy. Also, the option of adding an entry of (99,'http_proxy','hostname:port") to the 'system' and 'secure' tables in the /data/data/com.android.providers.settings/databases/settings.db database has also been tried, but failed.

USB Mass Storage

The Android FroYo 2.2 supports USB Mass storage functionality, however the external storage can be mounted either on SD Card or a USB mass storage device. The user is allowed to choose one of the two options.

By default the TI Android DevKit chooses SD card as the external storage device.

If a user is interested to use storage over USB (USB mass storage) then following changes have to be done in the default root filesystem

1)Create some directory on Android Filesystem via adb shell or console

   # mkdir /partition

2) Insert the usb mass storage device, Assume the device node created at /dev/block/sda1 and the device has fat partition.

   #mount –t vfat /dev/block/sda1 /partition

3) Now usb mass storage device is mounted at /partition. You can careate browse the filr

Limitation 1) Auto mounting usb mass storage device not supported 2) The gallery app/Android Settings doesn't recognize the mass storage mounted

Versioning

This is Release DevKit-V2. The release is available from http://software-dl.ti.com/dsps/dsps_public_sw/sdo_tii/TI_Android_DevKit/02_00_00/index_FDS.html

Technical Support and Product Updates

For further information or to report any problems, contact http://e2e.ti.com "Android" or http://support.ti.com.
For community support join http://groups.google.com/group/rowboat
For IRC #rowboat on irc.freenode.net