Overview

The android application platform client lives in the android_app_chooser package. The android applications use libraries from the appmanandroid package.

Installation on to Android Devices

A simple way to install the applications platform is to download the ROS Applications Chooser from the Android market. You can do this by going to the android market place with the following link: app chooser

Or if you just open the Market and search Willow Garage then you'll see it come up as the ROS Application Chooser.

Or by scanning the QR code with your phone's barcode scanner app:

Using the Application Chooser

Once you open up the application chooser you will see some buttons at the bottom of the screen. If there's a robot nearby you can hit Add Robot to add it to your list of available robots.

There are a couple of different ways to add robots. To add a PR2 you need to know at least it's control URI and master URI. These (along with other information) can be encoded in a QR code (for more on that see pr2_app_manager]. If the robot has a QR code you can scan that by hitting the scan QR code button in the dialog. It should open a scanner application if it's installed. If it's not, you will be prompted to download it. Alternatively, if you know the master and control URIs, you can type them into those fields on in the Add Robot dialog. The other fields are optional.

If you want to control a turtlebot then you should probably see turtlebot/Tutorials/AndroidControl. If the turtlebot is already started then all you need is the turtlebot's IP. You should make sure the Create base is turned on by pressing the power button until the green light comes on. Then, you can enter the master URI for the turtlebot in the appropriate field in the Add Robot dialog. The master URI will be in the following form but with TURTLEBOT_IP replaced with your turtlebot's IP address:

http://TURTLEBOT_IP:11311

Hit enter.

Once you see the robot appear at the top of the screen you can click on it to connect. If someone else has already claimed the robot, you will be asked if you want to evict that user.

Assuming you've found an unoccupied robot and connected, the robot will start and your device should show you a list of apps. If you've only installed the Application Chooser so far then when you try to click those apps it will prompt you to download them from the Android Market. All of the apps by Willow Garage can also be found by just searching Willow Garage on the Android Market.

Once you've downloaded some apps, go back to the Application Chooser. Resist the temptation to click the "Open" button in the Market.

If you are using a PR2 or another robot that uses the ROS Exchange and no apps are shown when you start the robot, then they're probably not installed on the robot either. If you don't know what that is then you can find out here ApplicationsPlatform/ApplicationsPlatformOverview. If your robot uses the ROS Exchange then there will be an App Manager button at the bottom of the screen.

Anyway, if there is one, hit App Manager button. It should show you a list of installed apps first. You can hit the ROS Exchange button to see available apps that you could install. Select any that you want to install.

Once you've installed some ROS Android apps on your device you will see icons for things like Props and PanTilt amongst your other apps. Most users should only run the apps through the App Chooser application. If you select the icon for Props outside of the App Chooser it will not work. There is a file that needs to be launched manually if you would like to run it without the App Chooser. That is beyond the scope of this tutorial but more information can be found in ApplicationsPlatform/Clients/Android/Tutorials/HowToWritePr2Props in the section about writing Launch files.

Installing the Android Developer Tools

This step is only necessary if you are creating your own Android Application Client or making modifications to an existing one. If you simply want to use existing clients, please install the applications from the Android Market.

First, install all of the ROS dependencies with the following commands:

sudo apt-get update
sudo apt-get install ros-electric-common-msgs ros-electric-driver-common ros-electric-geometry ros-electric-joystick-drivers ros-electric-multimaster-experimental ros-electric-navigation ros-electric-pr2-common ros-electric-pr2-power-drivers ros-electric-ros ros-electric-ros-comm ros-electric-common-tutorials

Second, install all of the java dependencies:

sudo apt-get install ant1.8 ant-contrib maven-ant-helper

Third, download and unpack the Android SDK. If you are using Linux, download Android SDK Rev. 13 for x86 Linux. This SDK works for both 32 bit and 64 bit Linux. Unpack the Android SDK in a safe and easily accessible place. Take note of the absolute path. Add the following line to your ~/.bashrc file, where path_to_sdk is the absolute path to the SDK:

export PATH=$PATH:path_to_sdk/tools:path_to_sdk/platform_tools

Fourth, source your bashrc and run the following command to install the appropriate android components:

android update sdk -u -o -t "`android list sdk -o | grep "Android API 9" | awk "{ print \\\$1; } " | sed 's/-//g'`,`android list sdk -o | grep "SDK Platform Android 2.3.1, API 9" | awk "{ print \\\$1; } " | sed 's/-//g'`"

(Note: You need to add -o option since Android API 9 is obsoleted)

If any of the android components don't install, or you find out later that they did not install you can install them from the AVD Manager. Type:

android

And a GUI should come up to allow you to install anything you're missing. Remember to check the box for obsolete packages as well.

Fifth, install the specialized rosinstall file for android development, where ROS_DIR is the directory of choice for the ROS android toolchain:

rosinstall ROS_DIR https://kforge.ros.org/appmanandroid/hg/raw-file/tip/appman.rosinstall

Finally, test with:

source ROS_DIR/setup.bash
rosmake android_app_chooser --threads=1 --rosdep-install

If that completes successfully, you are ready to create your own Android app.

Troubleshooting

If your machine is 64-bit, you will also need to install:

sudo apt-get install ia32-libs

If you get an error that says something like 'target "nodeps" does not exist in the project "android_gingerbread"' then you can apply the patch located here: http://code.google.com/p/rosjava/issues/detail?id=76 .

It may be necessary to downgrade rosjava_android repository

roscd rosjava_android
hg update ec39ea3fbd22
roscd rosjava_core
hg update 820898407aa5

Creating Your Own Android App

Before starting, install the toolchain and ensure that you know what ROS_DIR is (see previous steps).

First, create a directory for your application client. This will become the package/unary stack name of the said client application, so be careful with respect to the name. We recommend that all Android apps be prefixed with "android_" to avoid confusion with other related application packages. Note the fully qualified path of the directory.

Second, cd to the directory, and use android_create to create the required files:

rosrun appmanandroid android_create --create <appname> <package> <rootclass> <icon> <display-name> <resource-name> <rosappname>

The parameters to this command are quite complex, and are explained as follows:

• appname is the name of the generated .apk files (no spaces)

• package is the name of the Java package used by the app, usually ros.android.<app_name>. It must be a valid Java package name.

• rootclass is the name of the root activity class, a Java class name
• icon is the name of the icon file, that is unique to the application (no spaces)
• display-name is a human-friendly name for the app
• resource-name is the prefix of the android resources for the app (no spaces)
• rosappname is the name of the application to be launched on the robot during startup of the application (this is currently not used)

After running the script, you should see a bunch of new files.

Third, create the icon file, located at res/drawable/<icon>.[png|jpg]. If you do not want to create your own icon, copy the ROS icon:

cp `rospack find android_gingerbread`/res/drawable-hdpi/icon.png res/drawable/<icon>.png

You may also copy the icon from the robot-side application.

Fourth, add the application to your tool chain install:

rosinstall ROS_DIR .
source ROS_DIR/setup.bash

Fifth, run rosmake to build the application:

rosmake --threads=1

If that completes successfully, you are now ready to begin development of your application. Use "ant" to compile your application quickly if you have not changed your manifest (if you have, use rosmake). Use "ant debug install" to install the application on a device using adb. Use "ant release" to create a release application. See https://home.willowgarage.com/wgwiki/Android for more information for WG Employees.

For more information on developing your own app see ApplicationsPlatform for documentation and tutorials. Or see Android Tutorials.

Adding an Android Client to Your App

Android clients are specified by their fully qualified class name. The app chooser will automatically connect to the android market when it cannot find an application client. Here is an example definition, which follows the "clients:" tag:

  - type: android
    manager:
      intent-action: ros.android.pantilt.PanTilt

The "type:" line specifies that the client is an android client. The "manager:" tags provide information to the app chooser to find the application code. The "intent-action:" specifies the fully qualified path.

Optionally, an "app:" tag may be added:

    app:
      camera_topic: /wide_stereo/left/image_color/compressed_throttle
      key: value

The "app:" tags define a set of key-value pairs for the application client. The behavior of the key-value pairs depends on the application client. We recommend that application clients use the key-value pair infrastructure to allow topic remapping.

Once you have added the tag, restart your robot's app manager and connect to it with an android device. Starting the application should launch the correct client with the correct parameters.