From Texas Instruments Embedded Processors Wiki

TI-Android-JB-4.1.2-DevKit-4.0.0 UserGuide

User Guide - October 31, 2012

About this manual

This document describes how to install and work with Texas Instruments' Android JB DevKit release for AM37x platforms running Android. This release package provides a stable Android distribution with integrated SGX (3D graphics accelerated) drivers, TI hardware abstraction for WLAN, Bluetooth and standard applications from Android. The package also includes Linux Android kernel, boot loaders, debug & development tools and documentation to ease development, deployment and execution of Android based systems. The product also forms the basis for all Android application development on AM37x platforms.

This document contains instructions to:

• Install the release
• Set up the hardware
• Use the pre-built binaries in the package
• Run Android on the supported platforms
• Set up the Android debugger “adb” with the hardware platform
• Install and execute Android (out of market) applications on hardware platforms

Installation

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

Hardware Requirements

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

Software Host Requirements

The host and target software dependencies and requirements are described below.

Host PC 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.

To evaluate this release we recommend you to have a Linux "Ubuntu 10.04 or above" Host machine, See Ubuntu Linux installation notes

TI Android DevKit Software Release

The TI Android JB 4.1.2 DevKit 4.0.0 release for AM37x evm, Flashboard and BeagleBoard is available as online download from http://software-dl.ti.com/dsps/dsps_public_sw/sdo_tii/TI_Android_DevKit/TI_Android_JB_4_1_2_DevKit_4_0_0/index_FDS.html

Setup

This section gives the instructions to quickly prepare an SD Card image and get an experience of TI Android JB 4.1.2 DevKit 4.0.0 on TI AM37x platforms/devices.

Getting Pre-built Images

Prebuilt images can be obtained from

• TI_Android_JB_4_1_2_DevKit_4_0_0 Release Page, for the platform you own AM37x EVM, Flashboard or BeagleBoard

Use below commands to untar/uncompress the pre-built image

  $ tar -xzvf <Board Name>.tar.gz
  $ cd <Board Name>

The tree structure for pre-built image directory should be as:

  .
  `-- <Board Name>
      |-- START_HERE
      |-- Boot_Images
      |   |-- MLO
      |   |-- u-boot.bin
      |   |-- boot.scr
      |   `-- uImage
      |-- Filesystem
      |   `-- rootfs.tar.bz2
      |-- Media_Clips
      |   |-- Audio
      |   |-- Images
      |   `-- Video
      |-- README.txt
      `-- mkmmc-android.sh

Procedure to populate MMC/SD Card

• Get an SD Card of minimum size 2GBytes (Class4 minimum) and a USB Card reader

• Insert the USB SD Card reader (with SD Card) in your host Linux PC

• Prepare the MMC/SD card with pre-built images:

  $ cd <Board name>
  $ sudo ./mkmmc-android.sh /dev/sd<device>

• Above step will create a bootable MMC/SD card which can be used to boot up the device.

Setting Up Hardware

This DevKit release supports three different platforms AM37x EVM, Beagleboard XM and Flashboard. While they are different devices the hardware setup will almost remain the same.

• 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
• For Beagleboard you need to connect DVI Monitor through HDMI connector.
• Use self powered USB HUB and connect it to USB Host port of the platform, mainly for Beagle. For AM37x evm and Flashboard, the onboard keypad can be used
  • Connect USB keyboard and USB Mouse to the USB HUB for use with Beagle or EVM
    

Since Beagleboard does not have keypad mappings, we recommended to use USB Keyboard over a self powered USB HUB connected to the Host port of Beagleboard.

• Select Appropriate DIP Switch settings on EVM(s) to boot over MMC/SD

For MMC/SD boot - On AM37x EVM the DIP switch SW4 should be set as shown below

Booting Android

• Setup the board/platform
  • Do the DIP switch settings to boot from SD Card, see the DIP switch setting under Setting Up Hardware section.
  • Insert the Micro/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

   #> mmc init
   #> fatload mmc 0 0x82000000 boot.scr
   #> source 0x82000000

Boot Arguments

  AM37X:
setenv bootargs 'console=ttyO0,115200n8 androidboot.console=ttyO0 mem=256M root=/dev/mmcblk0p2 rw rootfstype=ext4 rootwait init=/init ip=off omap_vout.vid1_static_vrfb_alloc=y vram=8M omapfb.vram=0:8M'

  Beagleboard-xm:
setenv bootargs 'console=ttyO2,115200n8 androidboot.console=ttyO2 mem=256M root=/dev/mmcblk0p2 rw rootfstype=ext4 rootwait init=/init ip=off omap_vout.vid1_static_vrfb_alloc=y vram=8M omapfb.vram=0:8M omapdss.def_disp=dvi omapfb.mode=dvi:1024x768MR-16'

  Flashboard:
setenv bootargs 'console=ttyO2,115200n8 androidboot.console=ttyO2 mem=256M root=/dev/mmcblk0p2 rw rootfstype=ext4 rootwait init=/init ip=off omap_vout.vid1_static_vrfb_alloc=y vram=8M omapfb.vram=0:8M'

Android Home Screen

Keys mapping

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

The below table lists the functions available on the navigation bar on AM37x evm and BeagleBoard display.

Soft Key	Feature	Remarks
	Back	Go back to previous screen
	Home	Switch to Home screen
	Recent Apps	Switch between recently opened Activities

UI Navigation

• There are three ways to navigate the UI screen:
  • Matrix Keypad (Not available on BeagleBoard)
  • USB Keyboard
  • USB Mouse

Out of the Box Demo

Multimedia Experience

• Using Browser and Android applications

• Image browsing and media playback

View Image

Select "App Launcher" -> "Gallery" -> "Images". Click any thumbnail to view the image.

Double click the image to zoom in/out. Slide the image to view next image.

Play Video

Select "App Launcher" -> "Gallery" -> "Video". Click any thumbnail to play the video.

You can use the UI controls to Pause/Play/Seek the video. To stop playback and exit press the back key button.

Play Music

Select "App Launcher" -> "Music" -> "<Artist>" -> "<song-name>" to experience the music.

Control Volume

There are two ways to control volume:

• Using volume up/down keys
• Select "App Launcher" -> "Settings" -> "Sound" -> "Volumes"

Record Sound

Select "App Launcher" -> "Sound Recorder". Press Record button to start recording audio. Press Stop button to stop recording.

Playback the recorded audio by pressing Play button on Sound Recorder GUI.

TI RowboPerf Experience

Running 2D/3D Demo

Select "RowboPERF" -> "3D" -> "Chameleon" or "App Launcher" -> "RowboPERF" -> "3D" -> "Chameleon" to view 3D demo.

Select "RowboPERF" -> "RowboatBench" -> "2D Tests" -> "Run" to view 2D demo.

Select "RowboPERF" -> "0xBenchmark" -> "2D" -> "Run" to view 2D demo.

Running CPU Benchmark

Select "RowboPERF" -> "ARM" -> "Dhrystone" to get CPU dhrystone values.

Refer to RowboPERF User Guide for more details.

Crank Demo applications

The demos provided were generated by Crank Software's Storyboard Suite. It provides UI Designers and Embedded Engineers a GUI development tool and embedded runtime to rapidly create rich animated user interfaces. Storyboard provides a drag and drop UI development environment that imports content directly from Photoshop and easily exports an Android APK that is completely accelerated through the Android NDK OpenGL ES 2.0 interface.

Storyboard from a single tool and runtime to prototype, develop and deploy embedded user interfaces. For more information or to obtain an evaluation license to the Storyboard suite, contact Crank Software at http://cranksoftware.com/

Storyboard 30 Day Evaluation

http://cranksoftware.com/products/eval.php

Storyboard on Android

http://cranksoftware.com/products/android.php

Storyboard Tutorial - Photoshop to Android APK

http://www.youtube.com/watch?v=xF8dRFvbB8w&feature=plcp

Crank Story-board Demo

Crank Thermostat Demo

Browser Experience

Ethernet Configuration

Connect the ethernet cable to the device before booting. Ethernet is automatically configured for DHCP. You can verify that ethernet connectivity is established in the Notification Bar.

Alternatively, use the following command on the console to verify Ethernet configuration

  # netcfg
  e.g.
  lo       UP                                   127.0.0.1/8   0x00000049 00:00:00:00:00:00
  sit0     DOWN                                   0.0.0.0/0   0x00000080 00:00:00:00:00:00
  eth0     UP                               172.24.191.26/22  0x00001043 96:cd:df:8b:c6:2b

• Optional If you need to set up proxy to access internet, configure this from Settings->Ethernet proxy settings:

Camera Support

Ti Android JB 4.1.2 Devkit 4.0.0 supports Camera sensor MT9V113 for Beagleboard-xm, Flashboard and Camera sensor mt9t111 for AM37x evm

Feature supported:

• Image Capture

1. Go to "App Launcher" -> "Camera"
2. Click on camera capture.By default images will get stored at - /storage/sdcard0/DCIM/Camera

Other Display Features

Using LCD output

On AM37x EVM and Flashboard the on board LCD is used as output device by default.

Using DVI Monitor

For enabling the DVI output, append the boot arguments with following text:

   omapdss.def_disp=dvi omapfb.mode=dvi:1024x768MR-16

BeagleBoard uses DVI output over HDMI port by default. It is possible to output display over DVI on AM37x evm and Flashboard with a change in the bootargs as follows:

AM37x evm

  setenv bootargs 'console=ttyO0,115200n8 androidboot.console=ttyO0 mem=256M root=/dev/mmcblk0p2 rw rootfstype=ext4 rootwait init=/init ip=off omap_vout.vid1_static_vrfb_alloc=y vram=8M omapfb.vram=0:8M omapdss.def_disp=dvi omapfb.mode=dvi:1024x768MR-16'

Flashboard

  setenv bootargs 'console=ttyO2,115200n8 androidboot.console=ttyO2 mem=256M root=/dev/mmcblk0p2 rw rootfstype=ext4 rootwait init=/init ip=off omap_vout.vid1_static_vrfb_alloc=y vram=8M omapfb.vram=0:8M omapdss.def_disp=dvi omapfb.mode=dvi:1024x768MR-16'

Enable FPS logs in Logcat

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

Wireless

AM37x EVM and Flashboard supports Wi-Fi and Bluetooth on Android.

Note: BeagleBoard doesn't support wireless (Wi-Fi and Bluetooth) module.

Wi-Fi

Enabling Wi-Fi

• To turn on Wi-Fi, browse to "App Launcher" -> "Settings" -> "Wi-Fi".
• Enable Wi-Fi by sliding the ON/OFF tab to the ON position and wait for few seconds.
• The device scans for the available APs and displays them.

• Connect to desired AP by clicking on its name and enter required details (username/key etc) and click Connect

• The following appears on console

root@android:/ # [15534.646545] wl12xx: loaded
[15534.963165] wl12xx: state: 0
[15535.513610] wl12xx: firmware booted (Rev 6.3.10.0.132)
[15535.530853] ADDRCONF(NETDEV_UP): wlan0: link is not ready
[15535.550750] wl12xx: state: 2
[15535.554870] wl12xx: adding p2p mgmt vif
[15535.611480] ADDRCONF(NETDEV_UP): p2p0: link is not ready

• When successfully connected, you will see status as connected under the respective AP name. The AP name is also shown in the Notification Bar.

Disabling Wi-Fi

• To turn off Wi-Fi, browse to "App Launcher" -> "Settings" -> "Wi-Fi".
• Disable Wi-Fi by sliding the ON/OFF tab to the OFF position.
• Following message appears on console and the Wi-Fi status is shown as OFF.

root@android:/ # [16587.530334] wl12xx: down
[16587.545227] wl12xx: down

Wi-Fi Hostspot (SoftAP)

TI-Android-JB-4.1.2-DevKit-4.0.0 supports Wi-Fi hostspot (SoftAP) feature with TI WL1271 Wireless module.

• To turn on Wi-Fi hotspot, browse to "App Launcher" -> "Settings" -> "More..." -> "Portable hotspot"

• Click "Configure Wi-Fi hotspot" to configure the hotspot settings..

• Click the checkbox next to "Portable Wi-Fi hotspot" to start hotspot. You will see the message "Tethering or hotspot active" in the notification bar once the hotspot is fully functional.

• The following screenshot shows the hotspot being detected from another evm.

Wi-Fi Direct

TI-Android-JB-4.1.2-DevKit-4.0.0 supports Wi-Fi Direct with TI WL1271 Wireless module.

• To turn on Wi-Fi direct, browse to "App Launcher" -> "Settings" -> "Wi-Fi" and enable Wi-Fi.
• Click on the Menu icon and select "Wi-Fi Direct".

• The resulting screen shows any nearby devices with Wi-Fi direct enabled.

Changing WLAN MAC address

The devices loaded with TI-Android-JB-4.1.2-DevKit-4.0.0 will have the same MAC address which is encoded in wl1271-nvs.bin file. This may result in Wi-Fi not operating correctly when multiple devices are simultaneously in use. For optimum results, we recommend to modify the MAC address to ensure unique MAC for the devices before use

To change the MAC address, perform the following on the serial console of device:

• First get the current MAC address for WLAN:

  root@android:/ # calibrator get nvs_mac /system/etc/firmware/ti-connectivity/wl1271-nvs.bin

• Then update the MAC address for WLAN:

  root@android:/ # calibrator set nvs_mac /system/etc/firmware/ti-connectivity/wl1271-nvs.bin <MAC Address>

You need to reboot the board after changing the MAC address.

Bluetooth

Enabling Bluetooth

• To turn on Bluetooth, browse to "App Launcher" -> "Settings" -> "Bluetooth".
• Enable Bluetoth by sliding the ON/OFF tab to the ON position and wait for few seconds.
• Bluetooth icon appears on taskbar.
• When BT is enabled the status shows Turning Bluetooth ON and lists out the available Bluetooth devices.

• Select the desired device to pair with.
• A popup dialog with pin will appear.

• Click Pair button to confirm pairing.
• Verify that the desired device shows the same pin. click OK. And then the device gets listed under the paired devices category.

Disabling Bluetooth

• To turn off Bluetooth, browse to "App Launcher" -> "Settings" -> "Bluetooth".
• Disable Bluetooth by sliding the ON/OFF tab to the OFF position.

Bluetooth Object Push profile

Using Bluetooth, it is possible to send / receive files (pictures, media files etc).

Sending files

'Share using Bluetooth' is not enabled by default in the Gallery app. You need to install a third party application like BlueFTP to enable the sharing option

• browse to "App Launcher" -> "Gallery" -> "Images".
• Select a picture to share.
• Click share icon (top bar), select bluetooth from the options
• select paired BT device to send to.
• The BT device will prompt to accept. Accept incoming file at the other device.
• Once download finishes, check file.

Receiving files

• On paired device (e.g. phone), select send via Bluetooth, click on Flashboard (or omap3evm).
• On evm, notification appears about incoming connection.

• Open the task bar and select "Bluetooth share: Incoming file".

• A pop up appears asking for confirmation. On popup click Accept.

• Once download completes, check file.

Bluetooth A2DP

You can listen to Media audio on Bluetooth A2DP headset.

• Pair A2DP capable bluetooth headset with device. Android uses the stereo headset icon to denote A2DP headset.
• After pairing succeeds, the status is updated to 'Connected'.

• Open Music player and play any audio clip.
• Audio will be heard on the Bluetooth headset.

Bluetooth HID

You can connect to Bluetooth keyboard or mouse.

Bluetooth Keyboard

• Pair with the Bluetooth keyboard, by providing the suitable pass-code from the keyboard matching to the code shown on the device.
• After the successful pairing of the keyboard with the device, the keyboard will be listed under the paired devices category.
• The supported functionality of the paired keyboard can be used on the device.
• For disconnecting the keyboard from the device, select the keyboard under paired devices category, and agree to disconnect message.

Bluetooth Mouse

• Pair with the Bluetooth mouse, by providing the suitable pass-code from the device, matching to the supported code of the mouse.
• After the successful pairing of the mouse with the device, the mouse will be listed under the paired devices category.
• The supported functionality of the paired mouse can be used on the device.
• For disconnecting the mouse from the device, select the mouse under paired devices category, and agree to the disconnect message.

Bluetooth AVRCP

You can control Media playback with Media player keys on Bluetooth headset with AVRCP capabilities.

NOTE: The following steps assume Bluetooth A2DP headset with AVRCP.

• Pair the BT headset
• The following text appears on the debug serial when the pairing is successfully completed. This confirms that AVRCP feature is registered with android

 [ 3291.281250] input: AVRCP as /devices/virtual/input/input4

• Open Music Player and go to playlist view. Check that there are multiple clips in the playlist.
• Press the Play/Pause button on the BT headset - The currently queued clip begins playing on the headset.
• Press the Play/Pause button again on the headset - The currently playing clip is paused.
• Press the Next button on the headset; the next clip in the playlist begins to play on the headset.
• Press the Prev button on the headset; the currently playing clip restarts from the beginning.

Accelerometer Sensor

TI Android JB 4.1.2 DevKit 4.0.0 supports the accelerometer sensor on Flashboard.

Auto-rotate screen

• Browse to the "App Launcher" -> "Settings" -> "Display".
• Enable the "Auto-rotate screen" feature. Ensure the Check box gets ticked.
• Now hold the device in horizontal or vertical orientation to find the screen getting rotated.

Amazed Application

• Launch the Amazed application by browsing to the "App Launcher" -> "Amazed".
• The game starts. Tap the screen to begin.
• Hold the device in different orientation to move the ball to the destination and hence test the accelerometer.

Power Management

Below are the features supported for AM37x in TI-Android-JB-4.1.2-DevKit-4.0.0:

• Change of LCD backlights based on Wake Locks and Screen Timeouts (DIM,OFF)
  
• LCD back light brightness control from Settings Application
  
• Suspending the device to Memory.The device can be suspended in two ways.

1. Pressing the POWER key on the keypad.
2. Allowing the system go to suspend after a screen timeout.

• Prevent Suspend based on Wake Locks.
• System Resume on Key Press 
• System Resume on Alarm 
• CPU Dynamic Voltage and Frequency Scaling (ondemand, performance, powersave and userspace governors).
• CPU Idle States.
• Enabling system for hitting retention during idle.
• Enabling system for hitting OFF.

Basic Settings

Enable PM

By default we have disabled PM with the setting "setprop hw.nopm true" in init.rc.

Replace the line with "setprop hw.nopm false" to enable suspend/resume features.

Remove the selection "App Launcher" -> "Settings" -> "Developer options" -> "Stay awake" if selected already.

To go in suspend mode

• Press POWER (R0C0) key on the keypad.

To resume from suspend mode

• Press any button on the keypad.

To set the Screen Timeout to go suspend

• Select "App Launcher" -> "Settings" -> "Display" -> "Sleep"
• Select one of the options from the list.

To set set the screen always on preventing suspend

• Select "App Launcher" -> "Settings" -> "Developer options" -> "Stay awake"

To set Screen Brightness

• Select "App Launcher" -> "Settings" -> "Display" -> "Brightness"

To set Alarm in Android

• Select "App Launcher" -> "Clock "
• Click "Set alarm" -> "Add Alarm". Set the alarm as per requirements.

Device will be woken up from suspend at Alarm Time.

Advanced Settings

To Disable Power Management

• Edit init.rc file on the root directory.
• Set the property hw.nopm to true
  .
• This will prevent POWER key suspend and screen timeout based suspend.

CPU Idle and OFF mode Settings

CPU Idle feature is enabled by default in the kernel. There are seven power states introduced by CPU Idle. Enable sleep_while_idle and enable off_mode to achieve all the possible idle states. For maximum power reduction set the UART console timeouts as well

   # echo 1 > /debug/pm_debug/sleep_while_idle
   # echo 1 > /debug/pm_debug/enable_off_mode
   # echo 5 > /sys/devices/platform/omap/omap_uart.0/sleep_timeout
   # echo 5 > /sys/devices/platform/omap/omap_uart.1/sleep_timeout
   # echo 5 > /sys/devices/platform/omap/omap_uart.2/sleep_timeout

The usage and time count for these different states can be checked via

   #cat /sys/devices/system/cpu/cpu0/cpuidle/state*/time
   #cat /sys/devices/system/cpu/cpu0/cpuidle/state*/usage

CPU Dynamic Voltage Frequency Scaling settings

Enabling ondemand frequency governor

The ondemand governor enables DVFS(frequency/OPP) transitions based on CPU load.

  #echo ondemand > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

Enabling performance frequency governor

The performance governor keeps the CPU always at the highest frequency.

  #echo performance > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

Enabling powersave frequency governor

The powersave governor keeps the CPU always at the lowest frequency.

  #echo powersave > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

Enabling userspace frequency governor

Once this governor is enabled, DVFS( frequency) transitions will be manually triggered by a userspace application by using the CPUfreq sysfs interface

  #echo userspace > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

See all the available operating points

  #cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies

Application can select any of the available frequency from the above

  #echo <Desired Frequency> > /sys/devices/system/cpu/cpu0/cpufreq/scaling_setspeed

To minimize the power consumption in runtime

The maximum power reduction in runtime is achieved when “enable_off_mode” and “sleep_while_idle” options are enabled and dvfs option is set to “power save”.

To minimize the power consumption in suspend

The maximum power reduction in suspend is achieved when “enable_off_mode” and “sleep_while_idle” options are enabled and UART console timeouts are set.

Please check the power consumption analysis at TI-Android-JB-4.1.2-DevKit-4.0.0 Performance Benchmark page

Limitations

• In BeagleBoard there is no keypad connected to the wake up domain. So wake up is not possible by pressing keys.
• In Suspend, If USB OTG cable is connected, it makes Powerdomain (core_pwrdm) not entering to sleep State
• Inserting and Removing USB OTG cable continuously after suspend-resume makes system hang sometimes

Power Management on BeagleBoard

Power management support for BeagleBoard has been recently added to gitorious.org/rowboat and the following features are supported.

Enable Power Management

By default we have disabled PM with the setting "setprop hw.nopm true" in init.rc.

• Replace the line with "setprop hw.nopm false"
• Remove the selection "App Launcher" -> "Settings" -> "Developer options" -> "Stay awake" if selected already

Suspending the device to Memory

The device can be suspended in two ways.

• Pressing the USER key on the board
• Allowing the system go to suspend after a screen timeout.

The device can be resumed in two ways.

• Pressing the USER key on the board
• System Resume on Alarm

CPU Dynamic Voltage and Frequency Scaling (CPU Freq)

All the CPU Freq governors (ondemand, performance, powersave and userspace) are available. Please check the CPU Freq settings above.

CPU Idle States

CPU Idle feature is enabled by default in the kernel. There are seven power states introduced by CPU Idle. Enable sleep_while_idle and enable off_mode to achieve all the possible idle states. For maximum power reduction set the UART console timeouts as well

   # echo 1 > /debug/pm_debug/sleep_while_idle
   # echo 1 > /debug/pm_debug/enable_off_mode
   # echo 5 > /sys/devices/platform/omap/omap_uart.0/sleep_timeout
   # echo 5 > /sys/devices/platform/omap/omap_uart.1/sleep_timeout
   # echo 5 > /sys/devices/platform/omap/omap_uart.2/sleep_timeout

Minimize Power Consumption

To minimize power consumption follow the same instructions in the above section on minimizing the power consumption

NAND Booting

Booting NAND Prebuilt Images

SD card image for installing NAND images (MLO, U-boot, kernel and ubi.img) is provided for AM37x EVM.

Steps to install NAND images on AM37x EVM

• Download SD card image AM37xEVM_UBIFS.tar.gz from TI_Android_JB_4_1_2_DevKit_4_0_0 Release Page
• Untar AM37xEVM_UBIFS.tar.gz

 $ tar -xzvf AM37xEVM_UBIFS.tar.gz
 $ cd AM37xEVM_UBIFS

• The tree structure for uncompressed pre-built image directory should be as:

 AM37xEVM_UBIFS
     |-- START_HERE
     |-- Boot_Images
     |   |-- MLO
     |   |-- u-boot.bin
     |   |-- boot.scr
     |   `-- uImage
     |-- Filesystem
     |   `-- ubi.img
     |-- Media_Clips
     |   |-- Audio
     |   |-- Images
     |   `-- Video
     |-- README.txt
     `-- mkmmc-android-ubifs.sh

• Prepare the MMC/SD card with pre-built images:

 $ sudo ./mkmmc-android-ubifs.sh /dev/sd<device>

• Follow the Steps in README.txt to proceed further

• After successfully installing NAND images
  • Change DIP Switch settings on AM37x EVM to boot over NAND
  • For NAND boot the DIP switch should be set as (SW4(1:8)=01111000) shown below:

NAND Image flashing from u-boot prompt

• The default ECC scheme is 1-bit hardware ECC with Kernel/FileSystem ECC layout. Before saving the environment to NAND flash, always select this scheme. This will ensure that U-boot can read the environment from NAND without any ECC mismatch.

The ECC algorithm supported in this release are:

# nandecc [ hw <hw_type> | sw | bch4_sw | bch8_sw ] 

Usage: 

   sw           - Set software ECC for NAND
   hw <hw_type> - Set hardware ECC for NAND
                  <hw_type> - 1 for Kernel/FileSystem ECC layout
                              2 for X-loader/U-boot ECC layout
   bch4_sw      - Set 4-bit BCH ECC for NAND
   bch8_sw      - Set 8-bit BCH ECC for NAND

  (hw 1 is set as the default nandecc)

Saving Environment Variables

For example, to set bootargs and save them to the environment, the following commands could be used:

OMAP3_EVM # nandecc hw 1
OMAP3_EVM # setenv nandboot 'nand read 0x82000000 0x280000 0x500000 ; bootm 0x82000000'
OMAP3_EVM # setenv bootcmd 'run nandboot'
OMAP3_EVM # setenv bootargs 'init=/init console=ttyO0,115200n8 noinitrd ip=off androidboot.console=ttyO0 rootwait mem=256M omap_vout.vid1_static_vrfb_alloc=y rw ubi.mtd=4,2048 rootfstype=ubifs root=ubi0:rootfs rootwait vram=8M omapfb.vram=0:8M'
OMAP3_EVM # saveenv

Flashing x-loader

To flash MLO (x-load.bin.ift) to the NAND Flash, execute the commands listed below:

OMAP3_EVM # tftp 0x82000000 MLO
OMAP3_EVM # nand erase 0x0 0x80000
OMAP3_EVM # nandecc hw 2
OMAP3_EVM # nand write 0x82000000 0x0 0x80000

Flashing U-boot

To flash u-boot.bin to the NAND Flash, execute the commands listed below:

OMAP3_EVM # tftp 0x82000000 u-boot.bin
OMAP3_EVM # nand erase 0x80000 0x1C0000
OMAP3_EVM # nandecc hw 2
OMAP3_EVM # nand write 0x82000000 0x80000 0x1C0000

Flashing Linux kernel

To flash uImage to the NAND Flash execute the commands listed below:

OMAP3_EVM # tftp 0x82000000 uImage
OMAP3_EVM # nand erase 0x280000 <kernel image size>
OMAP3_EVM # nandecc hw 1
OMAP3_EVM # nand write 0x82000000 0x280000 <kernel image size>

Flashing UBI filesystem

To flash UBI image to the NAND Flash execute the commands listed below:

OMAP3_EVM # mw.b 0x82000000 0xFF <file system size>
OMAP3_EVM # tftp 0x82000000 <file system image>
OMAP3_EVM # nand erase 0x780000 <file system size>
OMAP3_EVM # nandecc hw 1
OMAP3_EVM # nand write 0x80000000 0x780000 <file system size>

Fastboot and UBI rootfs

Fastboot flashing utility is for updating the different software components of Android. Here is a guide to reflash the xloader, u-boot, kernel and root-filesystem (UBIFS image). This guide assume that Rowboat has been compiled before trying out these instructions.

Establishing Fastboot connectivity

Setup on Device

• Connect serial port to host PC via null modem cable.
• Serial port settings: 115200 8N1, No flow control.
• Connect USB cable between USB OTG port of the board and host PC.
• Apply power to the board.
• Press any key in serial port utility during boot and get U-boot command prompt.
• Run "fastboot" on u-boot command prompt (u-boot will echo "fastboot initialized").

Setup on Linux host

• On command prompt, run

   $ export ANDROID_ROOT=<rowboat top level directory>

   $ cd $ANDROID_ROOT/out/host/linux-x86/bin

   $ sudo ./fastboot devices

if a device number is echoed, fastboot is working.

Setup on Windows host

• Refer ADB over USB on Windows Machine
• Edit android_winusb.inf - under section [Google.NTx86], add line as below:

   %SingleBootLoaderInterface% = USB_Install, USB\VID_0451

• Proceed installing, with the difference that device to be selected is "Android Bootloader Interface" instead of "Android ADB Interface".

Creating ubifs images

• Extract the built rootfs.tar.bz2 file with sudo permission:

    $ sudo tar -xjvf <path-to-rootfs.tar.bz2>/rootfs.tar.bz2

Important extract with sudo permissions, otherwise you may face issues with booting of Android.

• Install the following packages, required for building mtd-utils:

   $ sudo apt-get install uuid-dev libacl1-dev liblzo2-dev zlibc zlib1g-dev

• Download and build mtd-utils. For more information on mtd-utils, follow the link: http://processors.wiki.ti.com/index.php/MTD_Utilities

   $ git clone git://git.infradead.org/mtd-utils.git
   $ cd mtd-utils/
   $ git checkout v1.5.0
   $ make

Important Tested with the "v1.5.0" tagged version of mtd-utils.

• Creating ubifs image:

   $ sudo mkfs.ubifs/mkfs.ubifs -r <path_to_rootfs>/ -m 2048 -e 126976 -c X -o ubifs.img
      where X = 3991 for 512MB NAND and X = 1948 for 256MB NAND flash

• Create/Edit ubinize.cfg:

   $ vim ubinize.cfg
   [ubifs]
    mode=ubi
    image=ubifs.img
    vol_id=0
    vol_size=Y
      where Y=450MiB for 512MB NAND and Y=200MiB for 256MB NAND
    vol_type=dynamic
    vol_name=rootfs
    vol_flags=autoresize

• Creating ubi.img to be flashed:

   $ sudo ubi-utils/ubinize -o ubi.img -m 2048 -p 128KiB -s 512 -O 2048 ubinize.cfg

For more details on ubifs http://processors.wiki.ti.com/index.php/UBIFS_Support

Important Use either Fastboot to flash ubi.img over System partition of NAND or do it manually from u-boot prompt.

Fastboot commands

   $ export ANDROID_ROOT=<rowboat_top_level_build_directory>

   $ cd $ANDROID_ROOT/out/host/linux-x86/bin

• List connected devices:

   $ sudo ./fastboot devices
   679600029e380000016830c302	fastboot

• Update xloader:

   $ sudo ./fastboot flash xloader <xloader_binay_path>/MLO
   sending 'xloader' (18 KB)...
   OKAY [  0.031s]
   writing 'xloader'...
   OKAY [  0.259s]
   finished. total time: 0.290s

• Updating u-boot:

   $ sudo ./fastboot flash bootloader <uboot_binary_path>/u-boot.bin
   sending 'bootloader' (212 KB)...
   OKAY [  0.159s]
   writing 'bootloader'...
   OKAY [  0.312s]
   finished. total time: 0.471s

• Updating kernel:

   $ sudo ./fastboot flash boot <kernel_image_path>/uImage
   sending 'boot' (3260 KB)...
   OKAY [  2.266s]
   writing 'boot'...
   OKAY [  1.660s]
   finished. total time: 3.926s

• Updating filesystem:

   $ sudo ./fastboot flash system <rootfs_image_path>/ubi.img
   sending 'system' (117248 KB)...
   OKAY [ 81.792s]
   writing 'system'...
   OKAY [ 53.123s]
   finished. total time: 134.929s

• Erasing partition:

   $ sudo ./fastboot erase <partition name> (eg. xloader)

• Display fastboot variable:

   $ sudo ./fastboot getvar <variable>

• Exit fastboot mode in uboot:

   $ sudo ./fastboot continue
   resuming boot...
   OKAY [  0.001s]
   finished. total time: 0.001s continue

Booting with UBIFS rootfs

• Set the bootarguments from u-boot prompt.

   # setenv nandboot 'echo Booting from nand ... ; nand read ${loadaddr} ${boot_nand_offset} ${boot_nand_size} ; bootm ${loadaddr}'

   # setenv bootcmd 'run nandboot'

   # setenv bootargs 'init=/init console=ttyO0,115200n8 noinitrd ip=off androidboot.console=ttyO0 rootwait mem=256M omap_vout.vid1_static_vrfb_alloc=y rw ubi.mtd=4,2048 rootfstype=ubifs root=ubi0:rootfs vram=8M omapfb.vram=0:8M'

For example the boot arguments for the AM37x EVM, will look like:

   # setenv nandboot 'echo Booting from nand ... ; nand read 0x82000000 0x00280000 0x00500000 ; bootm 0x82000000'
   # setenv bootcmd 'run nandboot'
   # setenv bootargs 'init=/init console=ttyO0,115200n8 noinitrd ip=off androidboot.console=ttyO0 rootwait mem=256M omap_vout.vid1_static_vrfb_alloc=y rw ubi.mtd=4,2048 rootfstype=ubifs root=ubi0:rootfs vram=8M omapfb.vram=0:8M'

Demo applications Installation

The pre-built Image includes few demo applications,these applications were not developed by TI as such. The source sites and licensing for these apps is as given below:

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 & 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)-
  • Browse to "App Launcher" -> "Settings" -> "Developer options".
  • Enable "USB debugging". Select OK for confirmation. Ensure the Check box gets ticked.
• 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

   SUBSYSTEM=="usb", SYSFS{idVendor}=="18d1", MODE="0666"

• Execute the following to change the user mode for the rules file.

    $ chmod a+r /etc/udev/rules.d/51-android.rules

• Execute the following command to restart udev service.

    $ sudo service udev restart

• 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
    20100720    device

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/8   0x00000049 00:00:00:00:00:00
  sit0     DOWN                                   0.0.0.0/0   0x00000080 00:00:00:00:00:00
  eth0     UP                               172.24.191.26/22  0x00001043 96:cd:df:8b:c6:2b                       

• If Ethernet was not configured, ensure that Ethernet is enabled and configured correctly in Android Settings and reboot. See Ethernet Configuration section for more details.

• Configure the ADB Daemon on target 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 command:

  $ adb devices

If connected, find the device name listed

  List of devices attached 
  172.24.191.26:5555	device

Invoke the shell of the target

  $ adb shell 

For more information about adb commands, see Android Debug Bridge page at Android ADB

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

Compatibility Test Suite (CTS)

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

• Pre-requisites
  • Download and extract the CTS package from here
  • Android SDK is installed and adb command is in the $PATH . See ADB section above

• Refer to Google CTS Guide for information on setting up the host and android device for CTS testing.

• Setup an ADB connection between Host and platform as mentioned in ADB section above.
• Launch the CTS.
  • Change to android-cts directory
  • Start cts

  android-cts$ ./tools/cts-tradefed

• • On CTS prompt check the available plans

  cts-tf > list p 

• Start a specific Test Plan

  cts-tf > run  cts --plan <test 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.

   # stop adbd;sleep 1;start adbd;

Building Android Sources

Refer to TI Android DevKit Developer Guide at http://processors.wiki.ti.com/index.php/TI-Android-JB-4.1.2-DevKit-4.0.0_DeveloperGuide for building Android sources and setting up the platform for booting.

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 repo in the DevKitTI-Android-JB-4.1.2_AM37x_4.0.0.bin.

SD Card Recommendations

Some brands or models of SD cards are observed with poor performance on AM37x 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	SDHC	4	4GB
	SanDisk Ultra	SDHC	4	4GB
	SanDisk Ultra	SD	4	2GB
	Sony	SDHC	4	4GB
	Sony	SD	4	2GB
	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	micro SDHC	4	4GB
	Lexar MULTI-USE	SDHC	4	4GB
	Lexar PLANTINUM II	SDHC	6	4GB
	PNY Optima	SDHC	4	4GB

Versioning

This release is available from http://software-dl.ti.com/dsps/dsps_public_sw/sdo_tii/TI_Android_DevKit/TI_Android_JB_4_1_2_DevKit_4_0_0/index_FDS.html
The release notes is available at http://processors.wiki.ti.com/index.php/TI-Android-JB-4.1.2-DevKit-4.0.0_ReleaseNotes

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

For technical support please post your questions at http://e2e.ti.com. Please post only comments about the article TI-Android-JB-4.1.2-DevKit-4.0.0 UserGuide here.

	Links
	ARM Microcontroller MCU ARM Processor Digital Media Processor Digital Signal Processing Microcontroller MCU Multi Core Processor Ultra Low Power DSP 8 bit Microcontroller MCU 16 bit Microcontroller MCU 32 bit Microcontroller MCU