Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

Creating an Application

Creating the Unary Stack

The first step to creating an app is to obtain a stack. Some code may have a stack that the app may be logically contained within. Adding an app to a stack does not create any new ROS dependencies. If you do not have a stack, you should create a new unary stack for your app.

Choosing or Creating a Stack

If you already have stack where you would like to place your app, choose a package within your stack to contain the app. You might want to create a new package if you wish. When finished, cd to the package directory.

If you do not have a pre-existing stack, please create one.

Show stack creation instructions Hide instructions

roscreate-package pr2_my_app
roscreate-stack pr2_my_app

Creating the Launch File

The next step is to create the roslaunch file for your application. This launch file will launch all the nodes needed on the robot side. The launch file must work with the "platform" of your robot. See your robot application manager page for more information.

Creating the Interface file

The interface file is a file that is essentially blank for now. In the future it will be more important. We recommend naming the interface "my_app.interface" where pr2_my_app is your app name. The interface file should be contained in the package/unary stack of your application. For now, place this in the file:

published_topics: {}
subscribed_topics: {}

Creating the Icon

The icon file is a visual description of your application that is displayed in the application chooser. The icon should be square and around 256 by 256 pixels - exact size is not important. The icon can be PNG or JPG format. If you do not wish to create an icon initially, you may use the ROS icon. We suggest changing this later to avoid confusion. The icon file must live in the package/unary stack of the application.

Creating the App File

The app file defines your application to the app manager. Your .app file must end in .app and live within the appropriate package. We recommend naming the .app file the same as the package name, for example pr2_my_app/pr2_my_app.app. Here is a simple example of a .app file to modify:

display: My Application
description: A really nice application for my robot.
platform: pr2
launch: pr2_my_app/pr2_my_app.launch
interface: pr2_my_app/pr2_my_app.interface
icon: pr2_my_app/pr2_my_app.png

Now, here are some oddities to be aware of. First, the path names are ROS path names, not normal path names, which means they should only contain one slash, no matter how many directories down the actual file is. For example, refer to pr2_my_app/launch/pr2_my_app.launch as pr2_my_app/pr2_my_app.launch in the .app file. Second, there must only be one file in the package that has the given name. Having two files will confuse the app_manager and cause it terminate. For example, pr2_my_app/launch/pr2_my_app.launch and pr2_my_app/pr2_my_app.launch will create problems.

Debug Installing your App

The next step is to test your app. On your robot, you should have two important directories. One is the applications ROS install directory, and the other is the local_apps directory. See your robot's application manager page for more info. Make sure you have the correct user for the given robot.

For PR2, the ROS install is located in ~applications/ros and the local_apps is in ~applications/local_apps. The correct user is applications.

Su to the correct user, or perhaps use sudo su

sudo su applications

Then cd to the ROS install directory.

Add the package/unary stack to the .rosinstall. Add these lines:

- other:
    local-name: <DIR>

Where <DIR> is the absolute path to your application. Once this is done,

rosinstall .

To generate the proper configuration files, and then add

echo "Sourcing /u/applications/ros/setup.bash"
. /u/applications/ros/setup.bash

to the .bashrc in the home directory of the applications user.

Next, add a .installed file to the local_apps directory. Name the file the same as the application name, in our example "my_app.installed". Add the following lines:

apps:
  - app: pr2_my_app/pr2_my_app
    display: My App

Note that we do not want to add the .app extension, as it is automatically added.

Testing the App

De-activate your robot by shutting down the app manager (on most robots, connect with an android device and hit the "deactivate" button). Restart your robot (on most robots, connect with your android device).

You should now see your application listed on your device. If you see no applications listed, this means that your application's formatting is invalid, and it has caused errors. If you do not see your application listed at all, this means that you have skipped a step or failed to restart the app manager.

If there is an error, deactivate your robot, and find the latest log in the ~/.ros directory of the applications user. The *app_manager* files should tell you a bit about what happened.

If you see your application, click it to start it. You should see the application highlight and see your ROS nodes running, just as if you launched the roslaunch file manually.

Adding Application Clients

You now have created a nice application, however users have no real means to interact with it outside of starting and stopping it. You can give your users a much deeper level of interaction with application clients. The first step is to add a clients array to your .app file by adding:

clients:

After that, you can start adding applications. See the list of application clients for more details on what to add.