Android Development Environment

This installation procedure is intended for Ubuntu Linux systems. It has been developed and tested on Ubuntu 12.04 (precise) with ROS Groovy. Updates may be needed for other Ubuntu or ROS distributions.

Prerequisites

Before developing with rosjava or the android_core library, both ROS and Android SDK must be installed.

1. To install ROS, follow the usual instructions, and install at least the following (these packages specifically are needed to get message and service definitions that we'll be using):

$ sudo apt-get install ros-groovy-multimaster-experimental ros-groovy-pr2-power-drivers ros-groovy-turtlebot

Note: you may want to install other ROS packages at this point; specifically any packages that contain messages you want to use in Android apps.

1. If you are running with a 64bit machine, these 32bit libs were found necessary to be installed on some machines:

$ sudo apt-get install lib32z1 lib32gcc1 lib32stdc++6 ia32-libs

1. Install some tools that we'll need:

   $ sudo apt-get install -y ant python-pip python-six mercurial git openjdk-6-jre openjdk-6-jdk lib32ncurses5

   Note: It appears that you must use openjdk-6, not openjdk-7; using the latter version leads to Java compiler crashes in some cases. Use update-alternatives to see which one you're using:

   update-alternatives --config java

   You want to see something like:

   There is only one alternative in link group java: /usr/lib/jvm/java-6-openjdk-amd64/jre/bin/java
   Nothing to configure.

   Or

    There are 2 choices for the alternatives java (providing /usr/bin/java).

   If you can see the latter line, you should select openjdk-6,so use update-alternatives to choose version 6 (or use apt-get to remove the version 7 packages).

2. Install rosinstall, which we'll use to retrieve the Java source files:

   • Ubuntu:

     $ sudo apt-get install python-rosinstall

   • Other Linuxen:

     $ sudo pip install --upgrade rosinstall

3. Install the Android Developer Tools (ADT) bundle. Start here.

   1. Download the ADT bundle; on Linux it's named something like adt-bundle-linux-x86_64.zip

   2. Unpack the ADT bundle, e.g.:

      $ unzip adt-bundle-linux-x86_64.zip

   3. Add the sdk/tools and sdk/platform-tools directories to your system PATH, e.g.:

      $ export PATH=`pwd`/adt-bundle-linux-x86_64/sdk/tools:`pwd`/adt-bundle-linux-x86_64/sdk/platform-tools:$PATH

      Note: Be sure to do this every time you start doing development with this software.

   4. Install the latest API (at the time of writing, it's 17) using the android manager

      $ android

      This may take several minutes to complete.

Installation

1. Make a place to work, e.g.:

   $ mkdir work
   $ cd work

2. Get the source:

   $ rosinstall . /opt/ros/groovy https://bitbucket.org/osrf/rosandroid/raw/default/rosjava-android.rosinstall

3. Source the setup file that rosinstall created:

   $ . setup.bash

   Note: Be sure to do this every time you start doing development with this software.

4. Compile rosjava:

   $ roscd rosjava_core
   $ ./gradlew install

   Workaround to a common pitfall

5. Compile some libraries from android_core:

   $ roscd android_core
   # Note: you may need to adjut the argument to the `--target` option based
   # which Android API version you're using.
   
   # You may have to kill gradle if it's already running.
   
   $ android update project --path ./android_gingerbread_mr1/ --target android-17
   $ android update project --path ./android_honeycomb_mr2/ --target android-17
   $ cd android_gingerbread_mr1
   $ ../gradlew debug
   $ cd ../android_honeycomb_mr2
   $ ../gradlew debug

   Workaround to a common pitfall

Trying out the tutorials

Preparation

1. Connect your Android device (make sure that USB Debugging is enabled on the device).
2. Make sure that your Android device is connected to the same network as your Linux machine (e.g., on the same wifi network).

3. On the your Linux machine, start roscore:

   $ roscore

Building and loading a tutorial app

We'll take as an example the android_tutorial_camera app. The procedure is the same for the other apps.

1. Configure the app:

   $ roscd android_core
   $ android update project --path ./android_tutorial_camera/ --target android-17

2. Compile it:

   $ cd android_tutorial_camera
   $ ../gradlew debug

3. Load it onto your device:

   # You will enable developer mode on your device
   
   $ adb -d install -r ./bin/MainActivity-debug.apk

Running a tutorial app

1. To launch the camera tutorial app, on your Android device, touch "CameraTutorial" on your app list.

2. When prompted, enter the URI for the roscore that's running on your Linux machine, e.g., http://192.168.2.4:11311) and touch "OK". You should see the camera view fill the screen.

3. On your Linux machine, run image_view:

   $ rosrun image_view image_view image:=camera/image _image_transport:=compressed

   You should see the camera feed from the Android device in a window on your Linux machine.

   Workaround to a common pitfall

Trying out the new apps

The old apps are currently being ported to the new rosjava and android_core APIs. You can try them like so:

1. Get to the directory containing the apps:

   $ roscd osrf_rosandroid

2. If it's your first time using this working copy, configure it:

   $ ./tools/configure.py

   This script simply runs the android command on each project to configure it to know where the necessary android_core library projects are. In future versions of the Android tools, those library projects will become .jars and this step will no longer be needed.

3. To build all the apps:

   $ ./gradlew debug

You can build one app by invoking the gradlew wrapper from within that directory, e.g.:

$ cd teleop_video
$ ../gradlew debug

The old way

The old apps are currently being ported to the new rosjava and android_core APIs. You can try them like so:

1. Get to the directory containing the apps:

   $ roscd osrf_rosandroid

2. If it's your first time using this working copy, configure it:

   $ make conf

3. To build:

   $ make

4. (Optional) To load all built apps onto a connected Android device:

   $ make load

Creating your own collection of apps

If you want to create your own collection of apps (instead of adding a new app to existing collection):

1. Create a place to work, e.g.:

   $ mkdir myapps
   cd myapps

   More often, you'll create this directory by cloning a repository.

2. Create a build.gradle file with the the following content:

   task wrapper(type: Wrapper) {
     gradleVersion = '1.0-milestone-9'
   }
   
   allprojects {
     group 'com.mydomain'
     version = '0.0.0-SNAPSHOT'
   }
   
   subprojects {
     repositories {
       mavenLocal()
       mavenCentral()
     }
   
     configurations.add('compile') {
       exclude group: 'junit'
       exclude group: 'xml-apis'
     }
   
     task deployLibs(type: Copy) {
       from { configurations.compile }
       into "${projectDir}/libs"
     }
   
     task clean << {
       ant.delete file: "${projectDir}/local.properties"
       ant.delete file: "${projectDir}/proguard-project.txt"
       ant.delete file: "${projectDir}/build.xml"
       ant.delete dir: "${projectDir}/bin"
       ant.delete dir: "${projectDir}/gen"
       ant.delete dir: "${projectDir}/libs"
     }
   
     task debug(type: Exec) {
       dependsOn deployLibs
       commandLine 'ant', 'debug'
     }
   }

3. Create an empty settings.gradle file. You'll add an include line for each project that you create.

4. Create a gradle wrapper by running the existing gradle wrapper from android_core (it's important to run the right version of the wrapper), e.g.:

   ../android_core/gradlew wrapper

   You should commit the newly created gradlew, gradlew.bat, and gradle files/directories to your repository.

Now you're ready to add apps, following the instructions in the next section.

If you accumulate a lot of apps, you may find it convenient to copy the `configure.py` helper script from osrf_rosandroid. You would run this script each time you do a fresh checkout of your apps.

Writing a new app

1. Get to the directory where you want to create your Android app. Here we'll assume that you're adding an app to the osrf_rosandroid repo:

   $ roscd osrf_rosandroid

   If instead you want to create your own directory of apps, copy build.gradle and settings.gradle from osrf_rosandroid into your directory, then edit settings.gradle to enumerate your projects.

2. Create an Android app in the standard way, e.g.:

   $ android create project --target android-17 --path ./myproject --package com.mydomain.myproject --activity MainActivity

3. Add the required android_gingerbread_mr1 library project (see android_core), e.g.:

   $ android update project -p ./myproject --library ../../android_core/android_gingerbread_mr1

   Note that the path to the library project must be relative to `myproject`'s directory.

4. Add other library projects as needed, e.g.:

   $ android update project -p ./myproject --library ../../android_core/android_honeycomb_mr2

   Again, the path to the library project must be relative to `myproject`'s directory.

5. Add your new project to the list that gradle will build by editing settings.gradle and adding an include line, e.g.:

   include 'myproject'

6. Build your app:

   $ cd myproject
   $ ../gradlew debug

The old way

1. Use the create-app.py tool to create a skeleton to work from (much easier than creating all the needed files yourself):

   roscd osrf_rosandroid
   $ ./tools/create-app.py MyNewApp

   You'll now have a directory called mynewapp containing a basic app that includes a text widget subscribed to the chatter topic.

2. Add it to the list of projects to be built in Makefile.

3. Because you added a new project, do the configure step again

   $ make conf

4. Build:

   make

Eclipse configuration

1. Run through the installation instructions above, including building with gradle.

2. Set a workspace in eclipse launches and asks you to do so, example:

   /home/myusername/rosjava_workspace

3. If requried, click the "Go to Workbench" icon.

4. Install the ADT plugin: http://developer.android.com/sdk/installing/installing-adt.html

5. If you didn't, install Platforms and Packages for the ADT plugin: http://developer.android.com/sdk/installing/adding-packages.html

6. Import the required android_gingerbread_mr1 package:

   File->Import->Android->Existing Android Code Into Workspace->[Root directory of android_core]->Finish

7. Click on MasterChooser folder (This step is optional):

   File->Rename->"Android Gingerbread MR1"->OK

8. Import your apps:

   File->New->Android->Android Project from Existing Source->[Root directory of mynewapp]->Finish

9. Rename your app if you wish.
10. Make changes and click the "Run" button to build and deploy to an Android device or an emulator.