Android Hands-On Labs

Android Hands-On Labs

Introduction

This document walks you through the 5 Android hands-on labs with i.MX53 Quick Start Board for today’s session. The first part regards host preparation, which is not needed today as you are using a ready-to-go virtual machine with all dependencies, softwares and BSPs installed. The 5 labs will guide you through the process of downloading the available android BSP images to the SD card and running them on the board, then, they guide you over 4 necessary steps to build a new android application with access to GPIOs: BSP compilation with new kernel patch, creation of the graphical application with eclipse SDK, creation of C/C++ application to control the GPIO and debugging these steps. The last part integrates this new application into the image so you can build a custom BSP containing your new application.

We hope you enjoy the labs presented and in case of any question, feel free to stop one of us during the presentation.

Host Preparation

Install the Linux Host on your PC, Android recommends Ubuntu 10.04 64-bits, download it at

http://releases.ubuntu.com/lucid/.

Install Android SDK (r20 is the latest at this time), NDK (r8b is the latest) and ADT (20.0.0): Just as recommendation, you can install these tools on the following folders: /home/[USER]/Software/IDEs/eclipse, /home/[USER]/Software/SDKs/android-sdk-linux, /home/[USER]/Software/SDKs/android-ndk-linux.

To install SDK, follow instructions on developer.android.com/sdk/installing/index.html , in our case, Android 2.3.3 Gingerbread is being used as platform.

Install Eclipse IDE and ADT plugin as described here:

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

Then, install Android NDK, as decribed here: http://tools.android.com/recent/usingthendkplugin. Finnaly install Android BSP R4.3 from Adeneo, downloading it from Adeneo website:

You can unpack BSP content on your home folder.

Follow document “Release Notes r4.3.pdf” in doc folder inside the BSP for: Installing prerequisites, download, patch and build Android.

Also follow instructions on “i.MX_Android_R10.3_User_Guide.html”, chapter 5.9, “How to

setup PC (Windows) to support ADB/RNDIS” “For Linux PC” in doc folder, in order to

correctly setup USB to support ADB (Android Debug Bridge).

Laboratories

Please open the Virtual Machine. To do that, “Start” menu on Windows then find VirtualBox application.

Inside Virtual Box, you will see a virtual machine called “Ubuntu 10.04”, double click-it to open. Virtual Machine user: freescale pass: fsl .

Lab1 - Booting Gingerbread Android from Adeneo’s pre-built images

In this first lab, you will prepare an SD card to boot Android on the i.MX53 QSB.

Further during the training, you will have a better understanding of the BSP and the AOSP (Android Open Source Project). For now, the goal is to have a first contact with the OS running in an ARM device, so no details are presented.

Insert the SD card in the SD card reader and change to the Adeneo’s BSP scripts directory. The BSP is installed under ~/iMX53_training/Android/i.MX53_...:

# cd ~/iMX53_training/Android/i.MX53-QSB-Android-Gingerbread-Release4.3/scripts

Run the script to install Android prebuilt images to the SD card:

# ./flash_prebuilt_android.sh [NAME OF YOUR SD CARD DEVICE (e.g. /dev/mmcblk0 or /dev/sdb)]

Note: you can use dmesg command to see what /dev entry corresponds to your SD card

reader. Make sure you have the SD card reader available inside the virtual machine before executing the flash command.

After the script finishes flashing Android image to the SD card, removes the card from the reader and insert it into i.MX53 QSB micro SD card connector.

Connect an USB-Serial cable to your host machine USB port and to the serial port of the i.MX board. Open a new terminal inside the virtual machine and connect to the serial adapter using screen:

# screen /dev/ttyUSB0 115200n8

Note: you can use dmesg command to see what /dev entry corresponds to your USB-Serial

adapter. To disconnect screen, use Ctrl+a, k, y.

After all the setup has been done, plug the power supply to the i.MX53 QSB board. You should see the Android OS initializing on the terminal running screen.

During the first boot of the device, you will need to calibrate the touch screen. Calibration screen will be presented before the system finishes the boot process.

Note: in case you fail to calibrate the device, by marking an invalid point, for instance, you can

remove the calibration file and reboot the board in order to calibrate the device again. Calibration file is under /data/system/calibration.

Calibrate your touch and wait for Android to present you the home screen, it may take a couple of minutes when booting for the first time. You can play around with some of the native applications eventually.

Lab2 - Building Gingerbread Android from Adeneo’s BSP

You will end this lab with a new Android image, that contains kernel support for i.MX53 QSB user LED control, compiled and burnt into your SD card.

In order to enable IO control for the LED at kernel level, prior to compiling the new image, you need to apply a patch to the kernel source tree.

We suggest that you take a look at the patch content before you apply it:

# cd ~/iMX53_training/Android/labs/lab02 # cat add_leds_gpio.patch

Check what the patch does: it enables the GPIO control on the linux kernel def config files and on the initialization file for the QSB board; it creates a platform-device structure to control one user LED on the board; and then it initializes the structure during execution of the init function. Now, to apply the patch, run commands below:

# cd ~/iMX53_training/Android/i.MX53-QSB-Android-Gingerbread-Release4.3/src/kernel_imx

# patch -p1 < ~/iMX53_training/Android/labs/lab02/add_leds_gpio.patch

However, as Adeneo’s BSP checks for the presence of .config file inside the kernel source code tree to determine whether the kernel needs to be compiled or not, you need to remove this file to ensure BSP will run kernel compile task again:

# rm .config

Next step is to compile the kernel, and only the kernel to save time:

# cd ~/iMX53_training/Android/i.MX53-QSB-Android-Gingerbread-Release4.3/scripts # ./build_android.sh --board=imx53_qsb \

--build-choice=kernel --lunch-type=eng --cpus-kernel=4

Note: Android and uboot were previously compiled to save time for this lab, otherwise, you

would have to use --build-choice=all to build them too and build time would be extremely higher. Finally, you need to burn the new kernel image to the SD card, so first connect the SD card to the reader and be sure it is connected to the Virtual Machine, then run the commands:

# cd ~/iMX53_training/Android/i.MX53-QSB-Android-Gingerbread-Release4.3/out # sudo dd if=uImage of=/dev/sdb bs=1M seek=1; sync

Note: here, again for the sake of time, you are copying only the kernel image to the SD card, preserving all the filesystems that were previously created when flashing the prebuilt image. To flash the whole Android system, instead of using ./flash_prebuilt_android.sh, you could use ./flash_android.sh at this point.

After burning the new kernel image, you can reconnect the SD card to the i.MX board to test kernel level LED control.

At the terminal connected to the serial cable running screen, type the following commands:

# cd /sys/class/leds/mx53::user # echo 0 > brightness

# echo 1 > brightness

You can repeat the last two commands as many times as you want, and hopefully you will see the user LED changing its status.

Lab3 - Building first Java application for Android in Eclipse

After completing the first two labs for a first contact with the Android BSP and to add low level support for led control, you will switch to the other end of the application, the UI, using Android SDK through Eclipse IDE to start development.

The application that will be developed during this lab, in its first version, will not be able to control the actual user LED yet, as it will not include the native glue to the kernel LED driver

interface. But the resulting application will be reused in the next labs and will show you some concepts and tools behind Android.

To get started, open Eclipse:

# cd ~/Software/IDEs/eclipse # ./eclipse &

On Eclipse IDE, create a new Android Project by clicking File > New > Project... Android > Android Application Project:

● New Android Application

○ ApplicationName: LedControl ○ Project Name: LedControl

○ Package Name: com.freescale.android.ledcontrol ○ Build SDK: Android 2.3.3 (API 10)

○ Minimum Required SDK: API 8: Android 2.2 (Froyo) ● Configure Launcher Icon - Next

● Create Activity - Next ● New Blank Activity

○ Activity Name: LedControlActivity ○ Layout Name: activity_led_control ○ Title: LedControlActivity

○ Click Finish

Edit layout file of application just created (LedControl - res - layout - activity_led_control.xml): ● Add two buttons

● Name them LedOn and LedOff, by right-clicking them, then selecting “edit text”, then New String, then:

○ String: LedOn

○ New R.string: led_on ● for LedOn button and:

○ String: LedOff

○ New R.string: led_off ● for LedOff

● Set “On click” property to setLedOn for LedOn button and setLedOff for LedOff button, by left clicking on each button, going to the Outline view, then properties, and finding the “On Click” event on the end of the list.

Edit the main activity class (LedControl - src - com.freescale.android.ledcontrol - LedControlActivity.java) and add the following lines at the beginning:

import android.view.View; import android.widget.Toast;

/* Click handler for the On button */ public void setLedOn(View view) { displayLedStatus(1);

}

/* Click handler for the Off button */ public void setLedOff(View view) { displayLedStatus(0);

}

private void displayLedStatus(int status) { String text = "Error while setting Led status!"; if(status != -1)

text = "Led is " + (status == 1 ? "On" : "Off");

Toast.makeText(getApplicationContext(), text, Toast.LENGTH_SHORT).show(); }

Connect a micro USB cable to the i.MX board micro conector and to the host PC, and run the Debugger from Eclipse IDE, by clicking the Debug button and selecting Debug as Android Application.

You can add breakpoints to the source code to interact with the debugging tool. It’s specially interesting to set a breakpoint at the following line of the activity source code, as it’s called every time one of the buttons is clicked:

Toast.makeText(getApplicationContext(), text, Toast.LENGTH_SHORT).show();

Pay special attention to logcat tab. It’s a helpful tool to debug software too.

Add more perspectives to the project like DDMS and Hierarchy View to get familiar with them. You can collect data from the running processes with the first and analyze the complete view hierarchy with the second.

Lab4 - Adding native code to the application in Eclipse

Now that you have a high level application to control LED status, you need to implement the low level glue to the actual kernel driver to effectively control the user LED status.

To start this lab, add Android Native Support to LedControl project by right clicking the project root folder on the Package Explorer tab and setting a library name as follows:

● Library Name: libled_control_jni.so (note that the “lib” prefix and the “.so” suffix are already set by default)

Note that you have been automatically switched to C/C++ perspective. Change back to Java perspective to create a new Java class with the following information:

● Package: com.freescale.android.ledcontrol ● Name: LedControlLib

public static native int setLedOn(); public static native int setLedOff();

Add also the following static block to the end of the class body:

static {

System.loadLibrary("led_control_jni"); }

Edit LedControlActivity.java and replace:

displayLedStatus(1); by: displayLedStatus(LedControlLib.setLedOn()); and: displayLedStatus(0); by: displayLedStatus(LedControlLib.setLedOff());

Now that you have a Java library, that is actually just a simple class for the purpose of this laboratory, you can try to launch the Debugger again.

You will notice that the application will run, but If you try to click on any of the buttons, you will get an "UnsatisfiedLinkError" exception, because although the high level class declared the two native methods that are now called from the LedControlActivity, they are not implemented yet in native code.

To add native code, note that Eclipse already created the first two files for you (jni/Android.mk and jni/led_control_jni.cpp) when you selected to Add Native Support to the project.

To make it easier to create the prototypes of the native functions in led_control_jni.cpp, it is possible to generate a native header file from the Java Library class using a tool called javah, that extracts meaningful data from a Java class to a C/C++ header file.

In a terminal, type the following commands to create the native header file:

# cd ~/Software/Workspace/LedControl # javah -jni \

-classpath bin/classes \

Back to Eclipse IDE, go back to C/C++ perspective and refresh the whole project so that the jni directory gets updated (either right click LedControl project and select Refresh or left click it and press F5). You will notice that the file com_freescale_android_ledcontrol_LedControlLib.h has been created under jni directory. Rename this file to led_control_jni.h and open it to see how it looks like. Note especially that:

● jni header file is included

● there is a block protecting the C function declarations to avoid problems with C++ compiler

● the full namespace from Java is adapted to C conventions to name functions and keep track of their relationship with the Java world

Now that the header file is ready to be used, you can finally open led_control_jni.cpp to implement the native functions. The end file can look like this:

#include "led_control_jni.h" #include <string.h>

#include <stdio.h> #include <android/log.h> #define DEBUG_TAG "LedControl"

static jint setLedStatus(jint status) {

const char *fname = "/sys/class/leds/mx53::user/brightness"; FILE* file = fopen(fname, "r+");

if(file) {

__android_log_print(ANDROID_LOG_DEBUG,DEBUG_TAG,

"Writing %d to file %s", status, fname); fprintf(file, (status ? "1" : "0"));

fflush(file); fclose(file);

return (jint) status; }

else {

__android_log_print(ANDROID_LOG_DEBUG, DEBUG_TAG,

"Failed to open file %s for writing %s", fname, status); return (jint) -1;

} }

JNIEXPORT jint JNICALL

Java_com_freescale_android_ledcontrol_LedControlLib_setLedOn (JNIEnv *env, jclass clazz) {

return setLedStatus((jint) 1); }

JNIEXPORT jint JNICALL

Java_com_freescale_android_ledcontrol_LedControlLib_setLedOff (JNIEnv *env, jclass clazz) {

return setLedStatus((jint) 0); }

Note that a native API (android/log.h) is being used to generate log messages. With this API in use, you need to tell the linker where to find its implementation. To pass this information to the C/C++ linker, edit jni/Android.mk file and add the following line in bold:

LOCAL_PATH := $(call my-dir) include $(CLEAR_VARS)

LOCAL_MODULE := libled_control_jni LOCAL_SRC_FILES := led_control_jni.cpp

LOCAL_LDLIBS := -llog

include $(BUILD_SHARED_LIBRARY)

Now you are ready to rebuild and rerun the application.

If you try to click one of the buttons on the application again, however, you will still get an error that this time will crash the application without even throwing an exception. This new error is related to the permissions associated with the node used to control the led brightness (/sys/class/leds/mx53::user/brightness).

As this node is owned by root and is not accessible for write operations to any other users, you need to workaround this limitation somehow.

For this lab, you can simply make this node globally accessible by executing the following command in the terminal running screen:

# chmod 0777 /sys/class/leds/mx53::user/brightness

After altering this device node permission, you will be able to see your full application in action, changing LED status by clicking each UI button.

Note: you should be able to debug the native code through Eclipse as well. To enable native

debugging, you need to enable some debugging features first. Add NDK_DEBUG=1 after ndk-build in the Build command of the C/C++ Build settings inside project properties. Then create a new Debug configuration, choosing to run debug as Android Native Application. You may face some problems to get native symbols resolved, as by the time of this writing there are some known issues with Android ADT plugin running on Eclipse Juno with CDT. Give it a try.

Lab5 - Adding application to Android BSP

Once you have your stable application developed, it’s common to want to embed it in a product as a system application instead of distributing it as a self contained package for pos installation. To start embedding LedControl application into Android BSP, create a vendor specific directory in the BSP root directory, where BSP scripts will look for applications by default:

# cd ~/iMX53_training/Android/i.MX53-QSB-Android-Gingerbread-Release4.3/src # mkdir -p vendor/fsl

# cd vendor/fsl

Add the LedControl application to the vendor specific directory:

# cp -r ~/Software/Workspace/LedControl . # cd LedControl

# rm -rf .settings bin libs obj gen assets .project .classpath .cproject

Create a top level Android.mk file inside vendor/fsl/LedControl:

LOCAL_PATH := $(call my-dir) include $(CLEAR_VARS)

LOCAL_MODULE_TAGS := optional

LOCAL_SRC_FILES := $(call all-java-files-under, src) LOCAL_SDK_VERSION := current

LOCAL_PACKAGE_NAME := LedControl

LOCAL_JNI_SHARED_LIBRARIES := libled_control_jni include $(BUILD_PACKAGE)

# Use the following include to make native implementation. include $(call all-makefiles-under,$(LOCAL_PATH))

And edit the other Android.mk file inside the jni directory, so that it looks like this:

LOCAL_PATH := $(call my-dir) include $(CLEAR_VARS) LOCAL_PRELINK_MODULE := false LOCAL_MODULE := libled_control_jni LOCAL_MODULE_TAGS := optional LOCAL_SRC_FILES := led_control_jni.cpp LOCAL_SHARED_LIBRARIES := liblog LOCAL_LDLIBS := -llog include $(BUILD_SHARED_LIBRARY)

Now, although the application is already recognized by the Android build environment, it’s also necessary to add a reference to this application into i.MX product packages list, editing file device/fsl/imx5x/imx5x.mk and adding lines in bold, otherwise, the application will not be included in the final image:

PRODUCT_MANUFACTUER := freescale

PRODUCT_PACKAGES += \ LedControl \

libled_control_jni.so

# Android infrastructures

Last implementation step is to edit init.rc (device/fsl/imx5x/init.rc) file to change permissions for /sys/class/leds/mx53::user/brightness during boot, adding the line in bold:

chown root radio /proc/cmdline # Chmod/chown FSL specific sys entry

chown system system /sys/class/backlight/pwm-backlight.0/brightness chmod 0660 /sys/class/backlight/pwm-backlight.0/brightness

chmod 0777 /sys/class/leds/mx53::user/brightness

# Define TCP buffer sizes for various networks

Finally you are ready to rebuild the BSP and reflash the SD card:

# cd ~/iMX53_training/Android/i.MX53-QSB-Android-Gingerbread-Release4.3/scripts # ./build_android.sh --board=imx53_qsb \

--build-choice=android --lunch-type=eng --cpus-android=4 # ./flash_android.sh /dev/sdb

Summary

Following picture summarizes some tools, processes and concepts you’ve learned during this hands on session. We hope you enjoyed!