.. _getting-started: Getting started =============== Before diving into ROS enabled Android application development, you should be familiar with :ref:`rosjava ` 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