About | Support | Discussion Forum | Index | Service Status | ros @ Robotics Stack Exchange

Adding an Application to the ROS Exchange

Description: Learn how to add an application to the ROS Exchange

Tutorial Level: BEGINNER

Releasing Your Stack

In order for the application to exist in the ROS Exchange, you must first release the Debians. You can do this by following the ROS tutorials for the stack that contains your applications. Obviously you must also release any dependencies for this to work.

It is critical to note the name in the .rosdistro file. For example,

arm_navigation: {_rules: wg-ros-pkg-trunk, version: null }

refers to the arm_navigation stack. For applications that have a unary stack, this is even more important, because all elements of the .app file and launch files must contain this exact package. If any confusion results, the application will not work properly because ROS will not be able to find any of the application resources. This can easily occur if the name of the development install is different of that in the .rosdistro file.

Now, you must wait until the application Debians are built. This time varies, but is dependent on the system load and any errors that may have occured. See the instruction for more information on the status of the Debians. For PR2, it is only necessary that the Debians be in the shadow-fixed repository.

Adding the Application to the ROS Exchange

Now that the Debians are built, you are ready to add your application to the ROS Exchange. The ROS Exchange consists of a set of YAML files hosted on the KForge server, inside of a repository. Different robots have different ROS Exchange repositories. For PR2, this exists in pr2_exchange repository.

First, you must make a local checkout of the repository so that you can modify the files. This is done using the source control commands on the kforge page. Once you have a local checkout, cd into it.

Second, you must add the application to the applications.yaml file. This file lists all the applications in the ROS Exchange. For your application, you must add three lines:

 - display: Tuck Arms
   app: pr2_tuck_arms_app/tuck_arms
   debian: ros-electric-pr2-tuck-arms-app 

The first line, display:, is the name of the application as it will appear in the ROS Exchange client. The second line, app:, is the ROS location of the application file, without the .app extension. Note that for unary stacks, the part before the / must be the line from the .rosdistro file. The third line, debian:, is the name of the debian. This is generated by prepending the distro name to the line from .rosdistro, and then changing every underscore to a dash. You can also find this name by querying the Debian repository using apt tools.

Third, if you have multiple applications in a single Debian, you must add additional blocks for each application in the Debian. These blocks should only vary in the display: and the app: line after the /. To avoid polluting the ROS Exchange list with an excess of applications, add:

   hidden: True

This will cause the applications to appear in the application chooser but not the ROS Exchange.

Fourth, you must add the additional information directory and file. These files contain data that is shown when the user clicks on an application in the ROS Exchange. You must first add a directory to the repository next to applications.yaml. This directory must be named the same as your application package, the name before the / on the app: line you added to applications.yaml. Now, you must create .yaml file in this directory. The .yaml file must have the same name as the application file in the package. That is, it must be the app: line of applications.yaml after the /. Inside this yaml file, you must add the following:

description: "Tuck the robot's arms so they do not interfere with navigation."
icon_url: "https://kforge.ros.org/pr2apps/pr2_tuck_arms_ap/raw-file/tip/icon.png"
icon_format: ".png" 

The first line is a long text description of what the application is and what it does. The second is a URL for the icon, which is usually extracted from the application's source control. The last line is the format of the icon, either ".png" or ".jpg".

Fifth, you must check in your changes to the ROS Exchange source control. This depends on the source control system used.

Sixth, you must test the system. Do this by starting a robot and connecting to an application chooser. You must then go to the chooser's ROS Exchange and click "update". The chooser should report any errors that occur on update in dialogs. If no errors occur, you should then be able to install and run your application from the ROS Exchange. If this does not work, then there is an error that is not being properly reported. You can find this by looking at the log files of the application manager in the ROS logs directory on the robot.

You are now finished adding your application to the ROS Exchange have finished the deployment process. You do not need to repeat this process if you update your application, as you can simply release a new Debian to make changes. The ROS Exchange will automatically sense this and update properly.