TI Android GingerBread 2.3 DevKit 2.0 UserGuide

From Texas Instruments Wiki
Jump to: navigation, search


TI_Android_GingerBread_2.3_DevKit_2.0 User Guide

User Guide - April 30, 2011

NOTE: This document is applicable for Android on AM38xx/TI81xx devices.
The TI Android Development Kit for DM3730, AM37x and AM35x devices can be downloaded from http://focus.ti.com/docs/toolsw/folders/print/androidsdk-sitara.html

About this manual

This document describes how to install, use and work with Texas Instruments' Android Gingerbread DevKit release 2.0 for TI81xx/AM38xx platforms running Android. This release package provides a stable Android Gingerbread 2.3 distribution with integrated drivers for 3D graphics acceleration (SGX). The release consists of

  • Sources (Linux kernel, Boot loader, Android 2.3 distribution and test/sample apps)
  • Debug and Development tools (CCSv5 and Android plugins)
  • Documentation (Developers guide, user guide and release notes)
  • Test reports (CTS report, Test results, Performance and benchmarking)
  • Pre-built images for Out of the box demo and evaluation

The product forms the basis for all Android application development on TI814X and TI816X platforms. In this context, the document contains instructions to:

  • Install the release package
  • Setting up the hardware
  • Out of the box demo setup and evaluation steps
  • Configuring and enabling Android features
  • Running pre-packaged Android applications & TI's RowboPERF for performance & benchmarking
  • Dynamically installing Android applications using Android debugger “adb”


This section describes the list of Software and Hardware requirements to evaluate the DevKit release.

Hardware Requirements

This release of Android Gingerbread DevKit 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
TI81xx / AM38xx TI816X EVM Rev B HDMI Monitor, USB Keyboard, USB Mouse, Ethernet, UART Cable, Audio Speakers, MMC/SD Card (2GB min)

Software Host Requirements

To evaluate this release we recommend you to have a Linux "Ubuntu 10.04 or above" Host machine, See ubuntu installation notes, http://developer.android.com/sdk/installing.html#troubleshooting

If you are a Android application developer or would like to dynamically install Android applications or would like to use Android SDK Tools (for debugging) then refer to http://developer.android.com/sdk/requirements.html for Host PC requirements

Package Content

  |-- Android_Source_Manifest
  |   `-- TI-Android-GingerBread-2.3-DevKit-2.0.xml
  |-- Documents
  |   |-- RowboPERF_User_Guide.pdf
  |   |-- Software_Manifests
  |   |   |-- TI-Android-DevKit-FS-Manifest.doc
  |   |   |-- TI-Android-DevKit-Manifest-For-TSU-components.doc
  |   |   `-- TI-Android-DevKit-Software-Manifest.doc
  |   |-- Test_Performance_Results
  |   |   |-- CTS_Report.tar.gz
  |   |   |-- PerformanceResult.pdf
  |   |   `-- Test_Report.tar.gz
  |   |-- TI-Android-GingerBread-2.3-DevKit-2.0_DeveloperGuide.pdf
  |   |-- TI-Android-GingerBread-2.3-DevKit-2.0_ReleaseNotes.pdf
  |   `-- TI_Android_GingerBread_2.3_DevKit_2.0_UserGuide.pdf
  |-- Performance_Apps
  |   |-- 0xbench
  |   |-- 3D
  |   |-- install_rowboperf.sh
  |   |-- Launcher2
  |   |-- rowboatBench
  |   |-- RowboPERF
  |   |-- RowboPERF_User_Guide.pdf
  |   `-- StorageIO
  |-- Prebuilt_Images
  |   `-- AM389X_TI816X
  `-- Tools
      |-- android-sdk_r06-linux_86.tgz
      |-- mk-bootscr
      `-- mk-mmc

Out of the Box Demo

This section gives the instructions to quickly prepare an SD Card image and get an experience of Android Gingerbread 2.3 on AM38xx/TI81xx platforms.

  • Get an SD Card of minimum size 2GBytes and a USB Card reader
  • Insert the USB SD Card reader (with SD Card) in your host Linux PC
  • Prepare the MMC/SD card Image
Host$: tar -xzvf <Board name>.tar.gz
Host$: cd <Board name>
Host$: sudo ./mkmmc-android /dev/sd<device>
  • Setting up the hardware 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 HDMI monitor
    • Connect a USB keyboard and USB Mouse
    • Select Appropriate DIP Switch settings on EVM(s) to boot over MMC/SD

For MMC/SD boot - On TI814X EVM the DIP switch S1 and on TI816X EVM the DIP switch SW3 should be set as shown below


  • Insert the SD Card into the Board
  • Switch on the platform
  • Wait for 35sec to get Android up on the UI screen
  NOTE: For the first time boot the System might take few minutes to boot. 
  NOTE: If your NAND flash is not empty the system might not boot with MMC, 
      in that case do the following with Serial Console / Terminal prompt in u-boot 

u-boot#: mmc init
u-boot#: fatload mmc 0 0x81000000 boot.scr
u-boot#: source 0x81000000
  • Android home screen

Android 2.3 DevKit homescreen.jpg

  • Using browser and android applciations

Android 2.3 DevKit browser.jpg

  • Image browsing and media playback

Android 2.3 DevKit gallery.jpg

Android File system mount options

The Android file system can be located in MMC or on Network (mounted using NFS), the following steps describe the procedure to mount Android filesytem on MMC or NFS.

Booting Android over MMC

Prepare file system on MMC/SD card

Use the mk-mmc utility provided in the tools folder of this package to populate the SD Card. This utility helps users create a MMC/SD Card with required Images to boot Android on any given TI platform.

This will partition the SD card to three partitions namely boot, rootfs and data. 1) The boot partition will get populated with the images required for booting. 2) The rootfs partition will be used as android root filesystem partition. 3) The Media inside the folder Media_Clips will get copied to the data partition. The data partition will get mounted as EXTERNAL storage when Android boots up.

Execute the following command

   #>./mkmmc-android /dev/sdc MLO u-boot.bin uImage boot.scr rootfs.tar.bz2 Media_Clips

This populates the SD/MMC card with all the images.
    To create the boot.scr boot script use the mkbootscr tool found in the Tools directory provided in the DevKit.

If you want to use the pre built images in the DevKit you have to adjust the above mentioned command to take them into account, as a more direct example the commands below will generate a SD card for an TI816X EVM. Ensure you have your SD card connected to the Linux machine you are using and that it is in /dev/sdb for this command otherwise adjust the command accordingly (WARNING: if you get this wrong it can wipe your HDD). Note that this assumes you installed the SDK in your home (~) directory and that the command is run with sudo (or your preferred way of getting super user privileges) to allow for the reformatting of the SD card.

  HOST $ cd ~/TI_Android_GingerBread_2_3_DevKit_2_0/TI816X
  HOST $ sudo ../../Tools/mk-mmc/mkmmc-android.sh /dev/sdb

Configure and boot


u-boot#> setenv bootargs 'mem=166M@0x80000000 mem=256M@0xC0000000 console=ttyO0,115200n8 androidboot.console=ttyO0  root=/dev/mmcblk0p2 \
rw rootfstype=ext3 rootdelay=1 init=/init ip=off vram=50M'
u-boot#> mmc init
u-boot#> fatload mmc 0 81000000 uImage
u-boot#> bootm 0x81000000


u-boot#> setenv bootargs 'mem=166M@0x80000000 mem=768M@0x90000000 console=ttyO2,115200n8 androidboot.console=ttyO2  root=/dev/mmcblk0p2 \
rw rootfstype=ext3 rootdelay=1 init=/init ip=off'
u-boot#> mmc init
u-boot#> fatload mmc 0 81000000 uImage
u-boot#> bootm 0x81000000


- If the board has bootargs configured already, then the board will not boot for Android automatically, 
- It is suggested to either delete the bootargs or use the following commands on u-boot prompt through UART console. 
 u-boot#>; mmc init
 u-boot#>; fatload mmc 0 0x81000000 boot.scr
 u-boot#>; source 0x81000000

If the board is not configured for bootargs, then it automatically boots.

Booting Android over NFS

Prepare file system on network machine (PC/server)

Android filesystem can be mounted over network.Following procedure explains the

  • Extact the android filesystem
  Host$: mkdir /home/workdir/Android_nfs
  Host$: cd /home/workdir/Android_nfs
  Host$: tar -jxvf ~/TI_Android_GingerBread_2_3_DevKit_2_0/TI816X/Filesystem/rootfs_ti814x.tar.bz2
  • Export filesystem using NFS

Edit /etc/exports file and add following line

  /home/workdir/Android_nfs *(rw,nohide,insecure,no_subtree_check,async,no_root_squash)
  • Run exportfs command
  Host$: sudo exportfs -a
  • Restart the NFS server

Run the following command to restart nfs server

  On Ubuntu 10.04 machine 
  Host$: sudo service nfs-kernel-server restart

Booting over Network Filesystem

Complete bootargs for AM389x/TI816X board using NFS

 u-boot#> setenv bootargs 'mem=166M@0x80000000 mem=768M@0x90000000 console=ttyO2,115200n8 androidboot.console=ttyO2 noinitrd ip=dhcp rw \
 init=/init root=/dev/nfs nfsroot= rootwait '

Complete bootargs for AM387x/TI814X board using NFS

  u-boot#> setenv bootargs 'mem=128M console=ttyO0,115200n8 noinitrd ip=dhcp rw init=/init root=/dev/nfs \
  nfsroot= rootwait vram=50M'

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.

Display Support

Component out

On AM389x/TI816x device HDMI is used as a default output device. To change output to Component, please configure sysfs entries by following below procedure.

  • Disbable graphics0
  #> echo 0 > /sys/devices/platform/vpss/graphics0/enabled
  • Switch output to HDCOMP
  #> echo 1:hdcomp > /sys/devices/platform/vpss/graphics0/nodes
  • Enable graphics0
  #> echo 1 > /sys/devices/platform/vpss/graphics0/enabled

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
|-- platforms
|-- platform-tools
|   |-- aapt
|   |-- adb
|   |-- aidl
|   |-- dexdump
|   |-- dx
|   |-- lib
|   |-- llvm-rs-cc
|   |-- NOTICE.txt
|   `-- source.properties
|-- SDK Readme.txt
|-- temp
`-- tools
    |-- adb_has_moved.txt
    |-- android
    |-- ant
    |-- apkbuilder
    |-- ddms
    |-- dmtracedump
    |-- draw9patch
    |-- emulator
    |-- etc1tool
    |-- hierarchyviewer
    |-- hprof-conv
    |-- layoutopt
    |-- lib
    |-- mksdcard
    |-- monkeyrunner
    |-- NOTICE.txt
    |-- proguard
    |-- source.properties
    |-- sqlite3
    |-- traceview
    `-- zipalign

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

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

Connecting Host machine & board through adb

This release of DevKit has been tested for adb over USB Ethernet for connecting a given board with host machine

The below sections describes this method and provides necessary instructions for the same.

adb over Ethernet

  • Make sure Ethernet port on board and host machine are connected to the network
  • Check Ethernet configuration for the board
    #> netcfg                                                                        
     lo       UP       0x00000049                       
     eth0     UP   0x00001043                       
  • If Ethernet was not configured, configure Ethernet of the board using ifconfig/netcfg as shown below.
    #> netcfg eth0 dhcp
  • Configure the ADB Daemon to use an ethernet connection using setprop as shown below.
    #> setprop service.adb.tcp.port 5555

  • If network is configured successfully (above steps) then Restart service adbd on the target,
    #> stop adbd
    #> start adbd
  • On the host machine use following commands to establish adb connection
    Host$: export ADBHOST=<target's ip address>
    Host$: adb kill-server
    Host$: adb start-server
  • Verify for device connectivity, by executing the following commands
    Host$: adb devices 

If connected, you'll see the device name listed as a "emulator-5554"

    List of devices attached
    emulator-5554    device
    Host$: adb shell 

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

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.
    Host$: 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
  Host$: 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
  Host$: 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.

  Verify the connectivity by executing 
  Host$: 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.

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
    Host$: adb pull <remote> <local>
  • To copy a file or directory (recursively) to the board, use
    Host$: 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: 
  Host$: adb push foo.txt /sdcard/foo.txt

Adobe Flash 10 Integration

The Android version of Flash10 that runs on Gingerbread 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 Gingerbread and installing the same in File system.

  • Execute the installer
Host$: ./ 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
Installation complete.
After Installation the following directory structure is resulted 
  • Change to Flash installed directory on Host PC
Host$: cd flash10_androidplugin 
Host$: ls
install_flash_player.apk  uninstall

  • Install flash player plug in on target via adb
 Host$: adb install install_flash_player.apk

Compatibility Test Suite (CTS)

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

  • Pre-requisites
  • 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.

  • NOTE: Sometimes when CTS is restarting the board, adb connection to CTS, may not happen automatically. In that case, execute the following command on the console, soon after the board has restarted.
  #> stop adbd;sleep 1;start adbd;

SD Card Recommendations

Some brands or models of SD cards are observed with poor performance on TI81xx EVMs and other platforms. The symptom could be one or some of the followings.

  • the boot-up time is much longer than normal (3x of normal or even longer);
  • the reaction of UI operations is unacceptably delayed;
  • the Gallery app cannot find the media files to create the albums;
  • the video playback is sluggish.

The table below lists the SD cards tested which have no issue on performance.

Brand/Model Type Class Capacity
Sandisk-C4-4GB.jpg SanDisk SDHC 4 4GB
Sandisk-ultra-C4-16GB.jpg SanDisk Ultra SDHC 4 4GB
Sandisk-ultra-C4-16GB.jpg SanDisk Ultra SD 4 2GB
SONY-C4-4GB.jpg Sony SDHC 4 4GB
SONY-C4-2GB.jpg Sony SD 4 2GB
SONY-micro-C4-4GB.jpg Sony micro SDHC 4 4GB

The table below lists the SD cards tested which have poor performance.

Brand/Model Type Class Capacity

HP Invent SDHC 4 4GB

Kingston SDHC 4 4GB
Kingston-C4-4GB.jpg Kingston micro SDHC 4 4GB
Lexar-Multi-Use-C4-4GB.jpeg Lexar MULTI-USE SDHC 4 4GB
Lexar-PlatinumII-C6-4GB.jpeg Lexar PLANTINUM II SDHC 6 4GB
PNY-Optima-C4-4GB.jpg PNY Optima SDHC 4 4GB


This is Release TI-Android-GingerBread-2.3-DevKit-2.0 for AM38xx/TI81xx devices. The release is available from http://software-dl.ti.com/dsps/dsps_public_sw/sdo_tii/TI_Android_DevKit/TI_Android_GingerBread_2_3_DevKit_2_0/index_FDS.html

Content Link Ref#
Developers Guide http://processors.wiki.ti.com/index.php/TI-Android-GingerBread-2.3-DevKit-2.0_DeveloperGuide
Release Notes http://processors.wiki.ti.com/index.php/TI-Android-GingerBread-2.3-DevKit-2.0_ReleaseNotes
Downloads http://focus.ti.com/docs/toolsw/folders/print/androidsdk-sitara.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