1.1. Getting Started Guide

Welcome to the Android Getting Started Guide

Thanks for your interest in learning more about the Android Software Development Kit (SDK). The SDK as we affectionately call it is our attempt to provide a great starting point to develop an embedded system on a TI Processor running Android. Given this goal, we wanted to provide something that is more than just a typical Board Support Package (BSP) containing a bootloader, Linux kernel, and Android filesystem. While these are certainly necessary elements, we feel they are just a starting point, especially for those that aren’t experts in developing with Android. So, the SDK also contains tools for developing on TI Processors (a validated cross-compiling toolchain, for example), pre-built libraries that you can use without having to rebuild them yourself, and some documentation to help explain how all of these pieces work together. We package all of this together with a working Android Embedded System that has been built with all of the things mentioned above.

What it really serves as is a “known good” starting point. One of the big challenges with starting development on a new platform (not to mention, a new Operating System (OS) for many), is getting an environment set up where you can build and debug code on hardware. The SDK attacks this problem with providing everything you need to do development, and it is validated on standard TI hardware platforms (EVMs). It wraps all of this up into one simple installer that helps get everything you need in the right place to do development. For example, you can start off with simply re-building the Android Embedded System that we provide to validate that everything is working on your system. This simple step gives you confidence that you can move forward from a good baseline.

As you go along your development journey and have questions, there is documentation and support available to you. Make sure to save a pointer to the Android SDK Software Developer’s Guide (SDG). If you don’t find what you need, take a look at the active E2E Processor Support Forum and see if the topic has been covered before. If not, post a new thread and we’ll do our best to provide some guidance.

What would you like to do with the SDK?

As described above, the SDK has a lot to it. Let’s break it down to two pieces to simplify things a bit:

  • The example embedded Android system. Essentially, a working bootloader (U-Boot), Linux kernel, and Android filesystem that can be put on an SD card and ran on a TI AM57xx EVM.
  • Everything needed to create the above embedded system from “scratch”:
    • U-Boot sources and configuration files
    • Kernel sources and configuration files
    • An Android cross-compiling toolchain as well as other host binaries and components
    • The Android Open Source Project (AOSP) filesystem and sources for example applications (after syncing using the repo tool)
    • A variety of scripts and Makefiles to automate certain tasks
    • Other components needed to build an embedded Android system that don’t fit neatly into one of the above buckets

With these two pieces more clearly defined, we can now get back to that all important question, “What would you like to do with the SDK?”. If the answer is clearly “I want to build something and I’m ready to start developing now!”, then go ahead and skip down to the “I want to Develop!” (or, Developing with the SDK) section below for instructions on installing the SDK on a Linux Host System. This is a somewhat involved process focusing on the second of the two parts of the SDK listed above and may be more than some people want to start with. However, it provides access to the full spectrum of development from rebuilding the SDK from sources to fully adapting it with new device drivers and applications.

So, if you’re not quite there yet, let’s discuss some other options. Maybe you’d like to evaluate the SDK a bit to see if it is how you’d like to get started.

If this is not good enough and you really want to get your hands on something, check out the next section which shares how to play with the embedded Android system. All you’ll need is access to a Windows/Linux computer, an SD card, an SD card reader, some free, open-source software, and a supported Hardware platform.

Evaluating the SDK Embedded Android System

If you’re a hands on person, reading documentation and looking at presentations gets old fast. So, if you want to see an example of what you can build with the SDK and actually hold it in your hands and play with it (or show it to someone else that needs help understanding what you want to do with it), with minimal effort, you can simply run the SDK Embedded Android System on a supported Hardware platform. This will allow you to poke and prod and interact. It’s a powerful way to get the imagination active and engaged.

If you’ve recently purchased a TI AM572x GP EVM or an AM57xx IDK, move on to the next step to install the SDK and boot your board using the provided prebuilt images.

Start your Android Development

OK, you’re all in. Either you’ve known this is what you wanted to do, or you’ve gone through the above steps and you want to do more. It’s time to develop! Here’s a high level overview:

  • Get a Linux host up and running if you don’t already have one
  • Install the SDK and run some scripts to get everything set up
  • Put the SDK Embedded Android System on an Evaluation Module to play with
  • Build something to validate set up – the SDK for example
  • Add something to the SDK, like a simple Hello World app

After completing these steps, you’ll have a known good baseline from which you can start development.

  1. Configure a Linux Host - If you already have a Linux host machine, go to Step 2. To do Android development with the SDK, you’ll need a host PC running Linux. The Linux host is generally much faster and has a lot more memory (both RAM and hard disk space) than the typical embedded system. While it is certainly possible to do all development natively, we feel the advantages of using a host provide a better way to go and what is supported out of the box with the SDK. There are many, many ways to get access to a Linux host. We simply can’t validate all possibilities and iterations, therefore we focus on validating using Ubuntu as the host Linux distribution, running natively. We validate the Long-term Support (LTS) versions of Ubuntu at the time of a SDK release (Ubuntu 16.04 and Ubuntu 18.04 are the currently supported LTS version). Can you use other versions of Ubuntu or even other distributions? Theoretically, yes, as long as you can get it to work and there may be more “assembly” required. If you can use the Ubuntu version validated against the SDK, it will be the smoothest path and we will be able to help you more if you do run into trouble. Likewise, we would strongly recommend getting a native 64-bit Ubuntu LTS machine set up for development. For the cost of a little bit of hard drive space, Ubuntu can have direct access to the host’s hardware. Virtual Machines (VMs) have come a long way over the years, and many people use them daily without problems. However, when you are working with a target embedded system (that may be a prototype board), whether it be a TI board or eventually your own, removing the complexity of a VM from the get go can avoid a lot of frustration (i.e. wasted time). When using a VM while connecting and disconnecting hardware components, you have to be very diligent about making sure what is connected to what. You might prefer using an hour to get more work done than debugging a perceived problem caused by the fact the virtual host grabbed a USB port when you weren’t watching. When you’re ready to proceed, Ubuntu provides a great overview for how to install natively. If you eventually want to rebuild the Android filesystem from source, you’ll also need to follow the instructions from the official Android page here for setting up the packages required for building Android.

  2. Install the SDK - Within your Linux host machine, Install the Android SDK Processor SDK Installer is 64-bit, and installs only on 64-bit host machine. Support for 32-bit host is dropped as of the Gingerbread Android release At least 70 GB of free space is required on the host machine in order to pull and then rebuild the full AOSP filesystem

  3. Create an SD Card using the SDK Create SD Card Script You will need a >4GB SD Card and the capability to connect that card to your Linux Host machine (using a USB SD Card reader, for example). If using a virtual machine as your Linux host, you may need to import the SD Card reader into your virtual machine (disconnect it from the host and connect it to the VM so that the Linux VM can see it).

  4. Configure your development environment There are many ways to connect the host development platform and the target board. These connections will vary depending on how you like to develop and what you are trying to do. Here is an example of a common set up with a serial connection for console, an Ethernet for networking, and a USB connection for flashing and ADB:

    ../_images/Android_Dev_Environment_Cropped.png
  5. Run the Setup Script - Once the SDK has been installed and the SD card has been created and placed into the device, run the setup.sh Script on your host to guide you through the process of flashing the bootloader, kernel, and Android filesystem to the onboard eMMC.

Note

The eMMC flashing process utilizes the fastboot utility of U-Boot in order to place the bootloader (U-Boot), kernel, and Android filesystem into non-volatile eMMC memory. For this reason, U-Boot running on the SD card is only needed for the initial flashing procedure, after this, the bootloader can be run from the eMMC in order to flash updated bootloaders, kernels, or filesystems.

Note

Booting Android solely from the SD card is not supported on the Processor SDK Android v4.2 release. The SD card should only be used to run U-Boot in order to flash the onboard eMMC.

  1. Rebuild sources using the top-level makefile in the SDK root directory. For example:
  • make all rebuilds all components in the SDK
  • make linux configures and builds the kernel
  • make u-boot-spl builds u-boot and u-boot-spl

The Android filesystem can be rebuilt, and then flashed to the onboard eMMC, by following these instructions.

What Would You Like to do Next?

Now that you have a solid baseline set up, you can choose what you’d like to do next based on what you need to do. Here are some of the many possibilities:

Link Summary
AM57X Download the SDK
Processor SDK Android Software Developer’s Guide The SDK’s Homepage, a must have link for SDK users.
Processor SDK Android How-To Guides The SDK How-To pages. The Hands On with the SDK has some great information for developing your first Android application.

1.1.1. Install the Android SDK

1.1.1.1. Overview

The Processor SDK Installer (ti-processor-sdk-android-am57xx-evm-xx.xx.xx.xx-Linux-x86-Install.bin) will install the necessary components to start your development on the TI microprocessor. The SDK consists of source for the universal bootloader (u-boot), the Linux kernel, toolchain and board support package, ease of use scripts and documentation. The Android file system sources can also be cloned to the SDK using the provided repo tool and manifest file. The Processor SDK was built and tested against a specific Linux Distribution name and version. Note this does not prevent the user from installing the SDK on other Linux distributions.


1.1.1.2. How to Get the SDK Installer

Download from the Android SDK download page. This will always host the latest version of SDK.


1.1.1.3. How to Run the SDK Installer

Make sure that the execute permissions are set. Bring up a terminal window and change directories to the where the installer is located (probably the Downloads directory if downloaded) and run the following commands:

chmod +x
./ti-processor-sdk-android-am57xx-evm-xx.xx.xx.xx-Linux-x86-Install.bin**

Alternatively, you can give execute permissions and run the SDK Installer by double clicking on it within your Linux host PC.

Note

If nothing seems to happen, you are probably running a 32-bit version of Linux. The installer is 64-bit, and will not execute properly.


1.1.1.4. Additional Installer Options

Invoking the installer with argument –help will list available options for the installer (e.g. text installer, etc.):

./ti-processor-sdk-linux-[platformName]-evm-xx.xx.xx.xx-Linux-x86-Install.bin --help

1.1.1.5. SDK Installer Execution Steps

  1. Environment Support Message User is to acknowledge the host operating system recommendations.
  2. GPLv3 Components Notice User is to acknowledge the use of GPLv3 components in the SDK.
  3. Directory Install Location The user will be prompted for a location on where to put the Processor SDK. An example is given below.
  4. Review and Confirm User is to confirm if loading the Processor SDK is ok. This is important to note if the user is trying to over-install on an existing directory and has made changes to the directory.
  5. Installation of software The software is installed.

Where to install the Processor SDK package

The default selection of where to install is the user’s home directory. In this particular example the name of the user is ‘sitara’.

../_images/Processor_sdk_android_select_directory.png

1.1.2. SD Card Creation

The Android SDK includes a script in the <ANDROID SDK INSTALL DIR>/bin directory named create-sdcard.sh. The purpose of this script is to create SD cards using the boot files from the Processor SDK for Android.

The script will give you information about each step, but the following sections will go over the details and walk you through how to use the script.

1.1.2.1. Invoking the Script

The create-sdcard.sh script can be run from any location but must be run with root permissions. This usually means using the sudo command to start execution of the script. For example:

sudo <ANDROID SDK INSTALL DIR>/bin/create-sdcard.sh

If you fail to execute the script without root permissions you will receive a message that root permissions are required and the script will exit.

1.1.2.2. Select the SD Card Device

The first step of the script will ask you to select the drive representing the SD card that you want to format. In most cases your host root file system drive has been masked off to prevent damage to the host system. When prompted enter the device number corresponding to the SD card. For example if the output looks like:

Availible Drives to write images to:

#  major   minor    size   name
1:   8       16    7761920 sdb

Enter Device Number:

You would enter 1 to select the sdb device

Note

For most common installations, this script works fine. However, if you are using more advanced disk slicing and volume management, the presented list of device nodes are off by one; in the best case (picking the last item) it will flag a range error, and in the worst case (anything in the middle) the wrong DASD can be destroyed. The problem originates when it attempts to determine the $ROOTDRIVE to “mask” the volume where “/” is mounted from the selection list using a “grep -v $ROOTDRIVE” For the naive partitioning case, its heuristic is fine, yielding something like “sda” — but for LVM, it grabs some chunk of the device name, e.g. “mapp” (out of “/dev/mapper/kubuntu–vg-root on / type ...”)

1.1.2.3. Re-Partitioning the SD Card

Any partitions of the device that are already mounted will be un-mounted so that the device is ready for partitioning.

The SD card will be re-partitioned to create a single boot partition with the boot files copied later. The message below will show and you will be prompted whether you want to continue partitioning the SD card:

################################################################################

Partitioning will format the drive with boot partition

################################################################################


################################################################################

     ****WARNING**** continuing will erase all data on sdd

################################################################################

Would you like to continue? [y/n] :

Select y to continue with the partitioning. Select n if re-partitioning is not desired.

1.1.2.4. Installing SD Card Content

After the SD card is partitioned, you will be prompted whether you want to continue copying the boot files or safely exit the script.

  • Options:
    • y - Selecting yes here will begin the process of installing the SD card contents. This operation WILL ERASE any existing data on the SD card.
    • n - Selecting no here will allow you to have partitioned your card but will leave the partitions empty.

If you have selected y, you should now see a prompt like:

now installing:  ti-processor-sdk-android-am57xx-evm-06.00.00.05

0. BOOTFILEPATH = ....00.00.05//board-support/prebuilt-images
1. MLO          = GP_MLO
2. BOOTIMG      = u-boot-am57xx-evm.img
3. BOOTUENV     = uEnv.txt


Would you like to continue? [y/n] :

You should choose option y to create an SD card using the pre-built boot files from the SDK. If you choose n then the script will exit.

You should execute this script from within the SDK so the script can determine the SDK path automatically. The script will start copying the contents to the SD card. Once the files are copied the script will exit.

1.1.3. Run Setup Scripts

1.1.3.1. Overview

After installation of the SDK on the Linux host, the setup script can be run to flash the prebuilt images to the onboard eMMC. Some of the tasks require administrator privileges. The script will prompt you when these administrator privileges are required. The setup script does the following things:

  • Minicom setup (to create a serial connection to the board)
  • u-boot setup (to configure the environment variables for the fastboot process)
  • Flashes the prebuilt images to the onboard eMMC (to allow you to boot the board from the eMMC)

1.1.3.2. Prerequisites

To run the SDK’s setup script the following steps should be taken first:

  1. Install Minicom on your Linux host machine and add the current user to the dialout group. A Minicom script is used to configure the u-boot environment variables as well as put the device into fastboot mode.

    sudo apt-get install minicom
    sudo usermod -a -G dialout $username
    
  2. Run the create-sdcard.sh script provided in the SDK’s bin/ directory This will create an SD card using the prebuilt boot files, including a fastboot enabled u-boot.

  3. Put the newly created SD card into your EVM

  4. Connect a serial cable from your Linux host machine (the one from which you will run the setup.sh script) to your EVMs serial port. The AM572x GP EVM will require a 6-pin USB-to-serial cable. The 6-pin connection is on the underside of the board. FTDI Serial cable The AM57xx IDK boards have an onboard USB to serial IC so only a micro USB cable is required. The silkscreen next to the correct micro USB port will say ‘USB JTAG’ (both JTAG and serial connection are on the same port) and will be on the corner of the board that is opposite from the RJ-45 connectors.

  5. Connect a micro USB cable (used for fastboot and ADB connections) from your Linux host machine to your EVMs (other) micro USB port. The AM572x GP EVM only has one micro USB port and it is located next to the SD card slot The AM57xx IDK has two micro USB ports. The second port is located underneath the RJ-45 jacks.

  6. Connect the provided power cable to the barrel jack.

  7. Power up your board and use ls /dev/ | grep ttyUSB on your Linux host machine to find your serial port connection to your board The AM572x GP EVM will show up as a single connection (e.g. /dev/ttyUSB0) The AM57xx IDK boards will have two connections, one for serial communication and one for JTAG (e.g. /dev/ttyUSB0 and /dev/ttyUSB1). The higher numbered port is the serial connection that we are looking for.

  8. Note down the serial connection device path, for instance /dev/ttyUSB1

1.1.3.3. How to run the setup script

The Setup Script is located in the Processor SDK Android installation directory. By default, this directory has a name that has the form ti-processor-sdk-android-am57xx-<Version>. Navigate to that ti-processor-sdk-android install directory. Then run the script:

./setup.sh

Detailed description of what the script is doing is provided in the subsections below.

Minicom Setup

This step let’s the rest of the process now which serial port the board connection is on. You should respond to the following question with the device found in step #7 above.

Which serial port do you want to use with minicom?
[ /dev/ttyUSB0 ]
  • A minicom configuration will be saved for you at /home/user/.minirc.dfl
  • The old configuration if there was one will be saved at /home/user/.minirc.dfl.old

uboot Setup

This section will create a Minicom script to generate the necessary u-boot environment variables and commands to put your board into fastboot mode.

Would you like to create a minicom script to configure the board (y/n)?
[ y ]

If you answer ‘n’ to this question the script will exit.

Run the Setup Script

This section will run the remainder of the setup script and will create a series of action between the board and your Linux host that will configure the u-boot environment variables, put the EVM into fastboot mode, and then flash the prebuilt images to the eMMC on the device. You must select ‘y’ at the following question and then power cycle or reboot your board to start the process.

Would you like to run the setup script now (y/n)?
[ y ]

If you answer ‘n’ to this question the script will exit.

Boot Android

At the completion of the this process you will have a board that can boot Android through the newly flashed eMMC device. For AM57x IDKs, keep the SD card plugged in, power cycle the board to use MLO and u-boot.img from the SD card and the rest from the eMMC. For AM57x GP EVM, SD card can be removed before the power cycle to boot Android with everything from the eMMC.