TI-Android-JB-4.1.2-DevKit-4.0.1 DeveloperGuide

From Texas Instruments Wiki
Jump to: navigation, search

TIBanner.png

Contents

TI Android JB-4.1.2-DevKit-4.0.1 Developer Guide

Developer Guide - November 20, 2012

About this manual

The objective of this document is to guide Android developers to get access to Android JB DevKit release sources for TI AM335x platforms, setting up host environment for compilation and enabling debug environment to ease the app development, debugging and deployment.

This document contains instructions to:

  • Hardware and Software requirement
  • Setup the hardware
  • Setup the toolchain
  • Download & Build the source
  • Set up the Android debugger with the hardware platform
  • Install and execute Android applications on hardware platforms

Hardware Requirements

This release of TI Android JB 4.1.2 DevKit 4.0.1 is evaluated on the platforms listed below. This package should be easily portable on other platforms on similar TI devices.


TI Device Platform Supported Version Other Accessories
AM335x AM335x Evaluation Module Rev 1.1A or greater USB HUB, USB Keyboard, USB Mouse, Ethernet, UART Cable, Audio Speakers, MMC/SD Card (2GB min)
AM335x BeagleBone Rev A3, A4, A5(expected to work), A6 USB HUB, USB Keyboard, USB Mouse, Ethernet, Mini-B USB Cable, MMC/SD Card (2GB min). Also tested with beaglebone cape for DVI-D and LCD.
AM335x AM335x Starter Kit Rev 1.2 Micro-USB cable, Ethernet cable, Audio Speakers, micro-SD Card (2GB min), USB Keyboard, USB Mouse, USB Camera Module


Host (PC) setup requirements

If you are an Android application developer or would like to use Android SDK Tools then refer to Android SDK Requirements for Host PC requirements.

The host development environment for Android is based on 64-bit Ubuntu, please install Ubuntu version 10.04 or later http://www.ubuntu.com/desktop/get-ubuntu/download.

IMPORTANT

This DevKit Release does not support 32-bit build host. Only 64-bit hosts are supported

The host installation would need few more Android specific dependencies, these can be installed dynamically over network using below commands.

For 64-bit Ubuntu 10.04

The following command installs the required packages for setting up the android build host:

  $ sudo apt-get install git-core gnupg flex bison gperf build-essential \
  zip curl zlib1g-dev libc6-dev lib32ncurses5-dev ia32-libs \
  x11proto-core-dev libx11-dev lib32readline5-dev lib32z-dev \
  libgl1-mesa-dev g++-multilib mingw32 tofrodos python-markdown \
  libxml2-utils xsltproc minicom tftpd uboot-mkimage expect

For 64-bit Ubuntu 12.04

The following command installs the required packages for setting up the android build host:

  $ sudo apt-get install git-core gnupg flex bison gperf build-essential \
  zip curl libc6-dev libncurses5-dev:i386 x11proto-core-dev \
  libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-glx:i386 \
  libgl1-mesa-dev g++-multilib mingw32 openjdk-6-jdk tofrodos \
  python-markdown libxml2-utils xsltproc zlib1g-dev:i386 \
  minicom tftpd uboot-mkimage expect
  $ sudo ln -s /usr/lib/i386-linux-gnu/mesa/libGL.so.1 /usr/lib/i386-linux-gnu/libGL.so

Install Oracle JDK 6

  1. Download the latest JDK 6 installer from Oracle http://www.oracle.com/technetwork/java/javase/downloads/index.html.
    Accept the license agreement and click on the Linux x64 bin installer. The downloaded file will be named jdk-6uXX-linux-x64.bin where XX is the JDK 6 update version.
  2. Follow the following steps to install JDK 6
  $ chmod a+x jdk-6uXX-linux-x64.bin
  $ ./jdk-6uXX-linux-x64.bin
  $ sudo mkdir -p /usr/lib/jvm
  $ sudo mv jdk1.6.0_XX /usr/lib/jvm/
  $ sudo update-alternatives --install "/usr/bin/java" "java" "/usr/lib/jvm/jdk1.6.0_XX/bin/java" 1
  $ sudo update-alternatives --install "/usr/bin/javac" "javac" "/usr/lib/jvm/jdk1.6.0_XX/bin/javac" 1
  $ sudo update-alternatives --config java
  $ sudo update-alternatives --config javac
Set Oracle JDK as default java/javac path

NOTE:

  1. Android Jelly Bean (4.1.2) needs Oracle JDK 6.
  2. The Hard Disk should have at least 30 GigaBytes of free space to complete the building of sources.
  3. Please refer to the AOSP documentation for latest information and instructions for setting up other Ubuntu versions http://source.android.com/source/initializing.html

Getting Source & Toolchain

TI provides Android sources for all the supported devices in multiple locations, developers can download the sources from the rowboat repository or use the pre-packaged sources in the DevKit.

Using Rowboat Gitorious

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 Android Version Control.
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 rowboat repository

  $ mkdir $HOME/rowboat-android
  $ cd $HOME/rowboat-android
  $ repo init -u git://gitorious.org/rowboat/manifest.git -m TI-Android-JB-4.1.2-DevKit-4.0.1.xml
  $ repo sync

TIP

You can update to latest sources later if you download the sources from rowboat gitorious repository

Using Pre-Packaged Sources

The above method is time consuming, so developers can use the pre-packaged Android sources in DevKit package.

IMPORTANT

The pre-packaged source installer provides only the checked-out sources for this release. It is not possible to update the sources to obtain the latest source revision

Download the pre-packaged DevKit sources from TI-Android-JB-4.1.2_AM335x_4.0.1.bin.

NOTE:The following steps assume that you have copied TI-Android-JB-4.1.2_AM335x_4.0.1.bin to $HOME

Run following commands to extract the pre-packaged source:

  $ cd $HOME
  $ chmod a+x TI-Android-JB-4.1.2_AM335x_4.0.1.bin
  $ ./TI-Android-JB-4.1.2_AM335x_4.0.1.bin
  • Accept the Licence when the installer prompts
  • This will generate following sources
    • Android File system : $HOME/TI-Android-JB-4.1.2_AM335x_4.0.1/
    • Android Linux Kernel: $HOME/TI-Android-JB-4.1.2_AM335x_4.0.1/kernel
    • Bootloader  : $HOME/TI-Android-JB-4.1.2_AM335x_4.0.1/u-boot
    • Toolchain location will be at $HOME/TI-Android-JB-4.1.2_AM335x_4.0.1/prebuilts/gcc/linux-x86/arm/arm-eabi-4.6/bin

Toolchain setup

  • Setup the toolchain path to point to arm-eabi- tools in prebuilts/gcc/linux-x86/arm/arm-eabi-4.6/bin
  $ export PATH=$HOME/rowboat-android/prebuilts/gcc/linux-x86/arm/arm-eabi-4.6/bin:$PATH
NOTE

We recommend to keep the add the toolchain path as shown above to avoid conflicts with any other installed toolchain

Build Procedure

To Build Bootloader

  • Change directory to u-boot
  $ cd <android source path>/u-boot
  • Execute 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 MLO and the u-boot Image u-boot.img

NOTE: The above command will work for AM335x EVM, AM335x Starter Kit and BeagleBone

To Build Android Linux Kernel

  • Change directory to kernel
  $ cd <android source path>/kernel
  • Execute following commands
  $ make ARCH=arm CROSS_COMPILE=arm-eabi- distclean
  $ make ARCH=arm CROSS_COMPILE=arm-eabi- am335x_evm_android_defconfig
  $ make ARCH=arm CROSS_COMPILE=arm-eabi- uImage

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

NOTE: Generated uImage can be run on AM335xevm, AM335x Starter Kit and BeagleBone.

To Build Android Filesystem

Ensure that you switch to the top directory of the Android sources in case you are not already there.

  $ cd <android source path>

Filesystem with SGX

  • To Build the root filesystem for AM335x EVM, AM335x Starter Kit and BeagleBone
  $ make TARGET_PRODUCT=<product-name> OMAPES=4.x -j<N>
Where <product-name> is:
  • am335xevm for AM335x EVM
  • am335xevm_sk for AM335x Starter Kit
  • beaglebone for BeagleBone


e.g: To build the full filesystem for AM335x EVM:

  $ make TARGET_PRODUCT=am335xevm OMAPES=4.x -j4

NOTE:

  • <N> should be twice the number of processors on your host machine. For example, a dual core machine would use -j4
  • The above command will build Android filesystem, kernel, <product_name> related modules,
  • Drivers and modules for SGX and WLAN will be built and installed in android rootfs for AM335x EVM and AM335x Starter Kit
  • Android rootfs components (root and system directories) will be located in out/target/product/<product-name>.

Filesystem without SGX

  • If filesystem is already built with SGX, then the projects need to be cleaned using the following command:
  $ make TARGET_PRODUCT=<product-name> clean
Where <product-name> is:
  • am335xevm for AM335x EVM
  • am335xevm_sk for AM335x Starter Kit
  • beaglebone for BeagleBone
To build the root file system for AM335x without SGX accelerated graphics support
  • AM335x EVM
  $ make TARGET_PRODUCT=am335xevm droid kernel_build wl12xx_compat  -j<N> 
  • AM335x Starter Kit
  $ make TARGET_PRODUCT=am335xevm_sk droid kernel_build wl12xx_compat  -j<N> 
  • BeagleBone
  $ make TARGET_PRODUCT=beaglebone droid kernel_build  -j<N> 


NOTE:

  • <N> should be twice the number of processors on your host machine. For example, a dual core machine would use -j4
  • droid will build basic Android filesystem
  • kernel_build will build the kernel
  • wl12xx_compat will build and install WLAN drivers into Android filesystem (for AM335x EVM and AM335x Starter Kit only)
  • The kernel image can be found at kernel/arch/arm/boot/uImage.
  • Android rootfs components (root and system folders) will be located in out/target/product/<product-name>.

NOTE: BeagleBone doesn't have WLAN support.

IMPORTANT

Some applications (e.g. Gallery) may not work correctly without SGX libraries

Create root filesystem tarball

NOTE

Make sure that the android filesystem build is completed without any errors before creating the tarball

The root filesystem tarball can be create in two ways.

1. Run the following command:

  make TARGET_PRODUCT=<product name> fs_tarball</code>

2. To create the tarball manually, perform the following steps:

  $ cd out/target/product/<product-name>
  $ mkdir android_rootfs
  $ cp -r root/* android_rootfs
  $ cp -r system android_rootfs
  $ ../../../../build/tools/mktarball.sh ../../../host/linux-x86/bin/fs_get_stats android_rootfs . rootfs rootfs.tar.bz2
Where <product-name> is:
  • am335xevm for AM335x EVM
  • am335xevm_sk for AM335x Starter Kit
  • beaglebone for BeagleBone

rootfs.tar.bz2 is the Android filesystem, it can be put on a SD/MMC Card.

RowboPERF Integration

  • Download the sources from rowboat inside the rowboat android source tree.
   $ git clone git://gitorious.org/rowboat/rowboperf.git
   $ cd rowboperf
   $ git reset --hard origin/rowboat-jb
  • Refer the instructions in the README file for building and installing rowboperf components.
  • Refer to RowboPERF User Guide to know more about dependency, build procedure and how to run applications.

Generate SD/MMC card IMAGE to boot Android

This section walks you through the steps necessary to create a bootable SD card with for Android, using the binaries you built in the previous step.

Configure Boot Arguments

The boot script (uEnv.txt) helps the board to boot automatically (Provided the NAND environment is empty).

  • Create a boot script file named uEnv.txt file with following content:
File: uEnv.txt
bootargs=console=ttyO0,115200n8 androidboot.console=ttyO0 mem=256M root=/dev/mmcblk0p2 rw rootfstype=ext4 rootwait init=/init ip=off
bootcmd=mmc rescan ; fatload mmc 0 81000000 uImage ; bootm 81000000
uenvcmd=boot


NOTE: You can edit uEnv.txt to update bootargs and bootcmd.

  • Flash SD Card

Copy compiled Images to image folder and create a bootable SD card as follows.

  $ mkdir image_folder
  $ cp uEnv.txt 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/<product-name>/rootfs.tar.bz2 image_folder
  $ cp Media_Clips image_folder
Where <product-name> is:
  • am335xevm for AM335x EVM
  • am335xevm_sk for AM335x Starter Kit
  • beaglebone for BeagleBone

NOTE: Media_clips folder is available in the SD card prebuilt images

  • Copy the SDMMC card creation script
  $ cp <android-sources>/external/ti_android_utilities/am335x/mk-mmc/mkmmc-android.sh image_folder
  $ cd image_folder
  $ sudo ./mkmmc-android.sh /dev/sd<mount-point> MLO u-boot.img uImage uEnv.txt rootfs.tar.bz2 Media_Clips

NOTE:

  • mkmmc-android.sh is available at external/ti_android_utilities/am335x directory in the DevKit sources.
  • All the Images, Audio and Video can be put into Media_Clips directory and can be provided as an argument to the above script.

Booting Android over NFS

Android filesystem can be mounted over network. Follow the procedure explained below:

  • Build NFS bootable tarball
  $ make TARGET_PRODUCT=<product-name> nfs_tarball
The tarball will be created at <android-devkit>/out/target/product/<product-name>/nfs-rootfs.tar.bz2
  • Create NFS mountable filesystem on host
  $ mkdir /home/workdir/Android_nfs
  $ cd /home/workdir/Android_nfs
  $ tar -xjvf ~/nfs-rootfs.tar.bz2
  • Export filesystem using NFS

Edit /etc/exports file and add following line

  /home/workdir/Android_nfs *(rw,sync,no_subtree_check,no_root_squash)
  • Run exportfs command
  $ sudo exportfs -a
  • Restart the NFS server

Run the following command to restart NFS server

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

Booting over Network Filesystem

Below are the complete bootargs for different boards using NFS:

 setenv bootargs 'console=ttyO0,115200n8 androidboot.console=ttyO0 mem=256M root=/dev/nfs nfsroot=<server-ip>:/home/workdir/Android_nfs rw rootwait init=/init ip=dhcp'

Note:All devices are using the same boot argument.

Booting the Platform

Here are the instructions to boot the prepared SD card on the two platforms:

AM335x Starter Kit

  • Connect USB cable to the micro-USB port(J3) on AM335x Starter Kit to the Host PC and have a Terminal software like TeraTerm, Minicom or Hyperterminal.
  • Connect the Ethernet (J6 or J7).
  • Connect USB Host port (J5) to USB Keyboard or USB Mouse. (Optional)
    • You can connect USB keyboard and USB Mouse to the USB HUB for use with AM335x Starter Kit.
  • Insert Micro SD card into MMC/SD slot (J4).
  • Power ON AM335x Starter Kit by connecting power cable to (J9) and pressing PWRON button (SW5) for a few seconds.

AM335x EVM

  • Connect the UART port (J12 of base board) on AM335x EVM to the Host PC and have a Terminal software like TeraTerm, Minicom or Hyperterminal.
    • Baud rate settings: 115200 8-N-1
  • Connect the Ethernet (J15 of base board) on AM335x EVM.
  • Connect Audio Speakers (J26 on daughter card) on AM335x EVM.
  • Connect Audio Line-In cable (J27 on daughter card) on AM335x EVM.
  • Connect USB Host port (USB1) (J18 on base board) on AM335x EVM to USB Keyboard or USB Mouse.
  • Select Appropriate DIP Switch settings on AM335x EVM to boot over MMC/SD
    • For MMC/SD boot the DIP switch SW3 SYSBOOT 0-7 should be set as shown below:

AM335x EVM SD boot mode setting

Switch
1
2
3
4
5
6
7
8
State
OFF
OFF
OFF
ON
OFF
ON
ON
ON
  • Insert SD card into MMC/SD slot on AM335x EVM.
  • Connect power cable to J1 on AM335x EVM.
  • Switch ON the Power Switch (SW13) on AM335x EVM.

BeagleBone

  • Connect USB cable to the mini-USB port(P3) on BeagleBone to the Host PC and have a Terminal software like TeraTerm, Minicom or Hyperterminal.
  • Connect the Ethernet (P10) on BeagleBone.
  • Connect USB Host port (P2) on BeagleBone to USB Keyboard or USB Mouse.
    • Connect USB keyboard and USB Mouse to the USB HUB for use with BeagleBone.
  • Insert Micro SD card into MMC/SD slot on the BeagleBone.
  • Power ON the BeagleBone by connecting power cable to (P5).

Getting serial console on AM335x Starter Kit and BeagleBone

Serial console is provided via usb cable connection between the device and the Host. To establish a connection the serial console enter the following commands on the linux console after powering on the device:

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

For detailed instructions on setting up the serial console refer BeagleBone-Android-DevKit Guide


To exercise various Android DevKit features refer to:

  1. TI-Android-JB-4.1.2-DevKit-4.0.1 UserGuide
  2. RowboPERF User Guide

Android Display through VNC

Setup Ethernet and VNC server on BeagleBone

If you use BeagleBone without any LCD-cape you can use VNC connection from the Host to the BeagleBone. Here are the steps to establish VNC connection between the BeagleBone to the Host PC

Make sure Ethernet port on 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

Once Ethernet is up, VNC server service can be started.

  # start androidvncserver

Connecting to target from Host

Using VNC Viewer application user can connect to the Beagleboane at the target address [say 172.24.191.37] port 5901.

Boot Logs


BootLogs AM335x EVM BeagleBone AM335x Starter Kit
Kernel Boot Log BootLog-am335xevm.pdf BootLog-BeagleBone.pdf BootLog-EVM-SK.pdf
Logcat Log LogCat-am335xevm.pdf LogCat-BeagleBone.pdf LogCat-EVM-SK.pdf


Application Development and Debugging

Using TI's Code Composer Studio V5 (Eclipse based)

Code Composer Studio (CCS) is the integrated development environment for TI's DSPs, microcontrollers and application processors based on the Eclipse open source software framework which includes a suite of tools used to develop and debug embedded applications. Since CCS is based on Eclipse, it is possible to integrate the Android Development Tools (ADT) like Android Debug Bridge (ADB), Dalvik Debug Monitoring System (DDMS) and ndk-gdb in CCS to enable the debugging of Android Applications directly on Android Device (i.e TI EVM) along with the inherent CCS capability of Linux Aware Debug and DSP Debugging.

This wiki walks you through installation of Android Debugging Tools in CCS, connecting CCS with Android Device and illustrates a debugging session of an HelloWorld Application based on android NDK having a mix of Java and Native C Code.

Preparing CCS for Android Development

The steps below are condensed version of steps mentioned on http://developer.android.com/sdk/installing.html

  • Installing the ADT Plugin in CCS

Refer http://developer.android.com/sdk/eclipse-adt.html#installing

  • Adding Platforms and Other Components
  1. On Windows, double-click the SDK Manager.exe file at the root of the Android SDK directory
  2. On Linux, run '<SDK>tools/android'
  3. Proxy Settings (If needed): Go to Settings and set the Proxy to work with your network
  4. To download components, use the graphical UI of the Android SDK and AVD Manager, shown in Figure below, to browse the SDK repository and select new or updated components. The Android SDK and AVD Manager will install the selected components in your SDK environment. Refer the list of Recommended Components: http://developer.android.com/sdk/installing.html#which

Android-sdk-manager.png

  1. To Install the Terminal (similar to Teraterm) in CCS, please follow the steps mentioned in the wiki: http://processors.wiki.ti.com/index.php/How_to_install_the_terminal_plugin_in_CCSv5
  2. For more information regarding CCSv5 and ADT plugin setup please refer CCSv5SetupGuide

Debugging Android with CCS

Hello World Application on Android Virtual Device (AVD)

  1. Hello World Using CCSv5
  2. Android Hello World

Hello-jni of Android NDK on Android Device

  • In CCS:
  1. Click File > New Android Project...
  2. Select the Create project from existing source radio button.
  3. Select any API level above Android 1.5.
  4. In the Location field, click Browse... and select the <ndk-root>/samples/hello-jni directory.
  5. Click Finish.
  6. Go to C/C++ Perspective. Click File->New->Convert to C/C++ Project
  • Edit jni/Android.mk and add the following line before BUILD_SHARED_LIBRARY: APP_CFLAGS := -g. This will add debugging symbols in to your native C code.
  • Compile the native code using the ndk-build command from cmd prompt:
  cd <ndk-root>/samples/hello-jni
  <ndk_root>/ndk-build
  • In CCS, create a debug configuration for a C/C++ application:
    • Create a new debug configuration for a C/C++ application. Click Run->Debug Configurations.
    • Set the process launcher to “Standard Create Process Launcher”
    • On “Main” tab, set:
      C/C++ Application: android-ndk-r5-windows\android-ndk-r5\samples\hello-jni\obj\local\armeabi\app_process
      Select Disable auto build
    • On “Debugger” tab, set:
      • Debugger: gdbserver
      • Stop on startup at: Java_com_example_hellojni_HelloJni_stringFromJNI (It is the entry function of the native C code)
      • Main Tab:
        • GDB debugger: android-ndk-r5-windows\android-ndk-r5\toolchains\arm-eabi-4.4.0\prebuilt\windows\bin\arm-eabi-gdb.exe
        • GDB command file: android-ndk-r5-windows\android-ndk-r5\samples\hello-jni\libs\armeabi\gdb.setup
        • GDB command set: Standard
        • Protocol: mi
        • Select only Verbose console mode
      • Connection Tab:
        • Type: TCP
        • Host name or IP address: localhost
        • Port number: 5039
  • Open the ndk-gdb script that came with the android NDK and comment the last line (we are not calling the usual gdb client, but we will attach an Eclipse gdb session instead)
  # $GDBCLIENT -x $GDBSETUP -e $APP_PROCESS
  • Only For Windows: Run dos2unix.exe on ndk-gdb from cygwin after editing to make sure that we do not have any unwanted dos symbols in the script
  • Starting Java Debugger:
    • Make sure you are in Java Perspective.
    • Click Run->Debug Configurations.
    • Place a breakpoint in Java code just before the native code call
    • Select Android Debug Configuration instance “HelloJni” and click “Debug”
    • It will prompt you to switch and open to CCS Debug Perspective. Select “yes”
  • Starting GDB Debugger:
    • In cygwin, make sure that the root of android-ndk is in PATH.
    • In cygwin, Go to /android-ndk-r5-windows/android-ndk-r5/samples/hello-jni and execute the following and wait until you get a prompt again:
  ndk-gdb –adb=<PATH_TO_android-sdk-windows/platform_tools/adb.exe>
sample command: $ ndk-gdb --adb=/cygdrive/c/PROGRA~1/Android/android-sdk-windows/platform-tools/adb.exe
    • CCS, go to C/C++ Perspective and click Run->“Debug”. This will launch the gdbserver in CCS Debug Perspective.
    • Now, you can seamlessly debug between Java and Native C code

Using 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.

  .
  |-- SDK Readme.txt
  |-- add-ons
  |-- google-market_licensing
  |-- platform-tools
  |   |-- NOTICE.txt
  |   |-- aapt
  |   |-- adb
  |   |-- aidl
  |   |-- dexdump
  |   |-- dx
  |   |-- lib
  |   `-- source.properties
  |-- platforms
  |-- temp
  `-- tools
      |-- NOTICE.txt
      |-- adb_has_moved.txt
      |-- android
      |-- ant
      |-- apkbuilder
      |-- ddms
      |-- dmtracedump
      |-- draw9patch
      |-- emulator
      |-- etc1tool
      |-- hierarchyviewer
      |-- hprof-conv
      |-- layoutopt
      |-- lib
      |-- mksdcard
      |-- monkeyrunner
      |-- proguard
      |-- source.properties
      |-- sqlite3
      |-- traceview
      `-- zipalign

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

  $ export PATH=<android_sdk_path>/platform-tools/:<android_sdk_path>/tools/:$PATH

Connecting Host machine to 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

  • Make sure that the mini-usb cable is connected between the host usb port and the target’s USB OTG port
  • Turn on "USB Debugging" on your board. On the board (UI screen)-
    • Go to home screen, press MENU,
    • Select Applications, select Development, then enable USB debugging.
    • Alternatively, you can navigate to Settings->Applications->Development and then enable the "USB debugging" option.
  • Setup host machine to detect the board. On Ubuntu Linux host machines this is done by adding a rules file to configure device vendor ID of on-board OMAP device.
  • For the EVMs and Boards covered here, the vendor ID is "18d1".
    • Log in as root and create this file: /etc/udev/rules.d/51-android.rules
    For Gusty/Hardy, edit the file to read:
    SUBSYSTEM=="usb", SYSFS{idVendor}=="18d1", MODE="0666"
    SUBSYSTEM=="usb", SYSFS{idVendor}=="0451", MODE="0666"
  • Execute the following to change the user mode for the rules file.
    $ chmod a+r /etc/udev/rules.d/51-android.rules
  • Verify the adb connectivity between host and target board
    $ adb devices 

If device is connected, then output on screen should list the device, example:

       List of devices attached
       0123456789ABCDEF    device

adb over USB Ethernet (Ethernet over USB)

  • Make sure that the usb cable is connected between the host usb port and the target's USB OTG port.
  • Configure the Linux kernel to use Ethernet gadget. Enable USB support, configure the Inventra controller, and add USB gadget support.

IMPORTANT NOTE: Inventra configuration must occur in two places as shown below.

    $ make ARCH=arm CROSS_COMPILE=arm-eabi- menuconfig
  • Select Device Drivers from the main menu.
  ...
  Power management options --->
  [*] Networking support --->
  Device Drivers --->
  File systems --->
  Kernel hacking --->
  ...
  • Select USB support as shown here:
  ...
  <*> Sound card support --->
  [*] HID Devices --->
  [*] USB support --->
  <*> MMC/SD/SDIO card support --->
  ...
  • Select Inventra Highspeed Dual Role Controller (TI, ADI, ...) as shown here:
  ...
  < >   R8A66597 HCD support
  < >   Host Wire Adapter (HWA) driver (EXPERIMENTAL)
  <*>   Inventra Highspeed Dual Role Controller (TI, ADI, ...)
          *** Platform Glue Layer ***
  < >     TUSB6010
  ...
  • Select USB Gadget Support as shown here:
  ...
  < >   iSight firmware loading support
  < >   USB YUREX driver support
  <*>   USB Gadget Support  --->
        *** OTG and related infrastructure ***
  [ ]   Hold a wakelock when USB connected
  ...
  • Select USB Gadget Drivers (Ethernet Gadget (with CDC Ethernet support)) as shown here:
  ...
  <*>   USB Peripheral Controller (Inventra HDRC USB Peripheral (TI, ADI, ...))  --->
  < >   Select one gadget as builtin for one port
  <*>   USB Gadget Drivers (Ethernet Gadget (with CDC Ethernet support))  --->
          Ethernet Gadget (with CDC Ethernet support)
  [*]       RNDIS support (NEW)
  [ ]       Ethernet Emulation Model (EEM) support (NEW)
  • Build the Kernel with the above configuration changes and use the uImage to boot the board. Refer to Kernel compiling instructions above.
  • Establish network connection
    • Assign an IP address to the usb ethernet adapter.

The USB network gadget g_ether is named usb0 (instead of eth0 or other network interface names). The normal set of Ethernet configuration tools should work, such as ifconfig, netstat, and route.

For example, the following commands will assign the network address 192.168.194.2 to the target. Run this on the target:

  $ ifconfig usb0 192.168.194.2 netmask 255.255.255.224 up

On Host machine, run the following commands to establish the connection to the target:

  $ sudo ifconfig usb0 192.168.194.1 netmask 255.255.255.224 up
  $ sudo route add 192.168.194.2 dev usb0

The target and the host machine should be connected, run ping command to test the same:

  $ ping -c 3 192.168.194.2
  PING 192.168.194.2 (192.168.194.2) 56(84) bytes of data.
  64 bytes from 192.168.194.2: icmp_seq=1 ttl=64 time=6.08 ms
  64 bytes from 192.168.194.2: icmp_seq=2 ttl=64 time=0.511 ms
  64 bytes from 192.168.194.2: icmp_seq=3 ttl=64 time=0.485 ms
  --- 192.168.194.2 ping statistics ---
  3 packets transmitted, 3 received, 0% packet loss, time 2000ms
  rtt min/avg/max/mdev = 0.485/2.361/6.089/2.636 ms

  • Establish ADB connection

On the host machine execute following commands to establish adb connection

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

Verify the connection by executing

  $ adb devices 

If connected, device name should be listed as a "emulator"

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

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    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.
  # 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
  $ export ADBHOST=<target's ip address>
  $ adb kill-server
  $ adb start-server
  $ adb connect <target_ip_address>:5555
  • Verify for device connectivity, by executing the following commands
    • If connected, find the device name listed as a "emulator"
  $ adb devices
    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.

Operations over ADB

The Root File System provided in this DevKit release contain only standard Android components and applications.

To install and run Android application follow steps mentioned below:

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 shell pm list packages
  $ adb uninstall <package name>
  • 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.

Copy any files to and from the board over ADB

  • Using the adb commands "pull" and "push" 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

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.

Others

How to set media volume?

Main Menu->Settings->Sound->Volume

How to show fps in logcat messages?

To print the FPS in logcat dump, type this command on the console before starting playback:
#setprop debug.video.showfps 1

To disable the prints, type:
#setprop debug.video.showfps 0

How to set longer screen timeout ?

Main Menu->Settings->Display->Screen timeout->30 minutes

Acronyms

  • SDK – Software Development Kit
  • NDK – Native Development Kit (For more information, refer http://developer.android.com/sdk/ndk/overview.html)
  • ADT – Android Development Tools
  • ADB – Android Debug Bridge
  • DDMS – Dalvik Debug Monitoring System
  • AVD – Android Virtual Device

Quick References

Content Link Ref#
User Guide http://processors.wiki.ti.com/index.php/TI-Android-JB-4.1.2-DevKit-4.0.1_UserGuide
Release Notes http://processors.wiki.ti.com/index.php/TI-Android-JB-4.1.2-DevKit-4.0.1_ReleaseNotes
Porting Guides http://processors.wiki.ti.com/index.php/TI-Android-JB-4.1.2-DevKit-4.0.1_PortingGuide
Downloads http://focus.ti.com/docs/toolsw/folders/print/androidsdk-sitara.html

Support

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