rosjava/0.0.0/_sources/getting_started.txt

.. _getting-started:

Getting started
===============

Before diving into ROS enabled Android application development, you should be
familiar with :ref:`rosjava <rosjava-core:getting-started>` and `Android
application development`_ in general.

.. _Android application development: http://developer.android.com/training/index.html

Creating a new Android application
----------------------------------

.. note:: This is still a work in progress. There are many obvious limitations
  and the process will be improved in the near future.

Currently, the easiest way to create a new application is to create your own
package in the android_core stack by copying one of the tutorial packages (e.g.
android_tutorial_pubsub).

.. code-block:: bash

  roscd android_core
  cp -a android_tutorial_pubsub my_package

After that, modify android_core/settings.gradle to include your new package.

.. code-block:: bash

  rosed android_core/settings.gradle
  ./gradlew my_package:clean my_package:debug

At this point, you may interact with your Android projects as described in the
`Android documentation`_. Please start there if the following quick start
instructions are insufficient for you.

Use `Apache Ant`_ to install your new Android application:

.. code-block:: bash

  roscd my_package
  ant installd

You can also use ant to build the application. However, if you add, remove, or
modify a dependency in the build.gradle file, you will need to execute the
`gradle wrapper`_ as described above in order to update the Android
application's external dependencies (located in the ``my_package/libs``
directory).

.. note:: You may also build and run your application from Eclipse. For more
  information, see :doc:`building`.

.. _Android documentation: http://developer.android.com/guide/developing/building/building-cmdline.html
.. _Apache Ant: http://ant.apache.org/
.. _gradle wrapper: http://gradle.org/docs/current/userguide/gradle_wrapper.html

.. _life-of-a-rosactivity:

Using RosActivity
-----------------

The :javadoc:`org.ros.android.RosActivity` class is the base class for all of
your ROS enabled Android applications. Let's consider the following example
from the android_tutorial_pubsub package. In this example, we create a
:javadoc:`org.ros.node.topic.Publisher` and a
:javadoc:`org.ros.node.topic.Subscriber` that will exchange "Hello, World"
messages.

.. literalinclude:: ../../../../android_tutorial_pubsub/src/org/ros/android/android_tutorial_pubsub/MainActivity.java
  :language: java
  :linenos:
  :lines: 17-
  :emphasize-lines: 14,22,28-30,42

On line 14, we extend :javadoc:`org.ros.android.RosActivity`.  When our
`activity`_ starts, the :javadoc:`org.ros.android.RosActivity` super class will:

* start the :javadoc:`org.ros.android.NodeMainExecutorService` as a `service`_
  in the `foreground`_,
* launch the :javadoc:`org.ros.android.MasterChooser` activity to prompt the
  user to configure a master URI,
* and display an ongoing `notification`_ informing the user that ROS nodes are
  running in the background.

.. _activity: http://developer.android.com/reference/android/app/Activity.html
.. _service: http://developer.android.com/reference/android/app/Service.html
.. _foreground: http://developer.android.com/reference/android/app/Service.html#startForeground(int, android.app.Notification)
.. _notification: http://developer.android.com/reference/android/app/Notification.html

On line 22 we call the super constructor with two strings that become the title
and ticker message of an Android `notification`_. The user may tap on the
notification to shut down all ROS nodes associated with the application.

Lines 28-30 should look familiar to Android developers. We load the `activity`_
layout and get a reference to our
:javadoc:`org.ros.android.view.RosTextView` (more on that later).

On line 42 we define the abstract method
:javadoc:`org.ros.android.RosActivity#init(org.ros.node.NodeMainExecutor)`.
This is where we kick off our :javadoc:`org.ros.node.NodeMain`\s and other
business logic.

And that's it. :javadoc:`org.ros.android.RosActivity` handles the rest of the
application's lifecycle management including:

* acquiring and releasing `WakeLocks`_ and `WifiLocks`_,
* binding and unbinding the :javadoc:`org.ros.android.NodeMainExecutorService`,
* and shutting down :javadoc:`org.ros.node.NodeMain`\s when the application exits.

.. _WakeLocks: http://developer.android.com/reference/android/os/PowerManager.WakeLock.html
.. _WifiLocks: http://developer.android.com/reference/android/net/wifi/WifiManager.WifiLock.html

Nodes and Views
---------------

The android_core stack provides a number of Android `Views`_ which implement
:javadoc:`org.ros.node.NodeMain`. For example, let's look at the implementation
of :javadoc:`org.ros.android.view.RosTextView`. The intent of this view is
to display the textual representation of published messages.

.. literalinclude:: ../../../../android_gingerbread/src/org/ros/android/view/RosTextView.java
  :language: java
  :linenos:
  :lines: 17-36,50-
  :emphasize-lines: 40,49,56

The view is configured with a topic name, message type, and a
:javadoc:`org.ros.android.MessageCallable`. On line 40, in the
:javadoc:`org.ros.node.NodeMain#onStart(Node)` method, we create a new
:javadoc:`org.ros.node.topic.Subscriber` for the configured topic and message
type.

When a new message arrives, we either use the configured callable to transform
the incoming message to a string (line 49), or we use the default
``toString()`` method if no callable was configured (line 56). We then set the
text of the view to the string representation of the incoming message.

As with any other :javadoc:`org.ros.node.NodeMain`, the
:javadoc:`org.ros.android.view.RosTextView` must be executed by the
:javadoc:`org.ros.node.NodeMainExecutor`. In the :ref:`life-of-a-rosactivity`
example, we execute it in
:javadoc:`org.ros.android.RosActivity#init(NodeMainExecutor)` and use the it to
display incoming messages from the
:javadoc:`org.ros.rosjava_tutorial_pubsub.Talker` node.

.. _Views: http://developer.android.com/reference/android/view/View.html
.. _TextView: http://developer.android.com/reference/android/widget/TextView.html