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.

A Guide to Interface Development

Introduction

The purpose of this guide is to server as an introduction to interface design within the RMS. It servers as an entry point into the powerful libraries and APIs that the RMS provides developers. If you are not proficient in PHP, have no fear; to create interfaces with the RMS, minimal knowledge of PHP is required. That said, it is advised that you have some experience with the Robot Web Tools libraries. For more information, see the tutorials for roslibjs, ros2djs, and ros3djs.

Environment Creation

Interfaces can be linked to RMS environments. Environments in the RMS are pairings of rosbridge and MJPEG servers. They represent a single robotic or Gazebo environment that a set of interfaces will access. By default, the RMS comes with an environment configured with localhost rosbridge and MJPEG servers. This is great for testing purposes, but will not generalize well on the web. In other words, client connections are made using the address configured in the environment. If the client is not on the same machine as the web server, localhost simply will not work. Therefore, a fully qualified domain name (FQDN) or IP address is required.

Start by creating or editing an existing rosbirdge setting in the admin panel (Admin > ROS Settings > rosbridge). Settings here are self explanatory. Next, create an associated MJPEG server in in the admin panel (Admin > ROS Settings > MJPEG Server). Again, settings here are self explanatory.

Finally, you can create or edit you environment in the admin panel (Admin > ROS Settings > Environments). You can choose any existing interfaces to link at this point, but we will create and link a new interface later in this tutorial.

Adding a New Interface

After you environment is configured, we can begin to add our new interface. This is a multi-step process which includes:

1. Adding the Interface to the RMS Database
2. Creating the Interface Controller
3. Creating the Interface View

Adding the Interface to the RMS Database

By adding the interface to the RMS database, you will be able to manage access control and schedule user studies with your interface/environment pairing. This can be done either before or after actually creating your interface HTML/PHP files, but adding it before will allow us to check our progress as we go. To begin, head to the interface admin panel (Admin > ROS Settings > Interfaces) and select the CREATE NEW ENTRY button in the center.

The following are hits for the entry fields:

• Name -- The name of the interface. This will be important when we create our view and controller, but can be arbitrary. It should contain letters and spaces only. For this tutorial, we will use Tutorial as the interface name.

• Environment(s) -- A list of the available environments are given. Select the environments you wish to use this interface with. This list can be edited at any point.

• Anonymous Access -- If enabled, your interface will allow non-registered users access to your interface. This is useful for certain types of crowdsourcing studies or sharing your interfaces with friends who wish to not create an account.

• Unrestricted Access -- If enabled, users (or anonymous clients if the above is enabled) will be allowed to access your interface without having a scheduled user study appointment. By default, admins are allowed unrestricted but this option can be enabled to allow all users this privilege. This could be useful for things like a tutorial interface which allow multiple users at once.

Once you have entered your information, you can select the SAVE button.

To view your interface, you can either access the URL directly based on the ID of the interface and environment (visible in the admin panel), or via the user menu. To access via the URL, if your interface ID is 2 and your environment ID is 1, your URL would be http://localhost/ifaces/view/2/1. This link is only useful if you have granted anonymous access and are posting a link to your interface somewhere. If a non-registered user attempts to access this link and anonymous access is disabled, they are given an error page instead.

In most cases, you, and users, will access the interface via the MY ACCOUNT page. For an admin, since you have unrestricted access by default, you can access the interface at any time. Users will only see an appropriate link if unrestricted access is enabled or if they are scheduled for a user study.

Once on the MY ACCOUNT page, you can select the INTERFACES button to scroll down to a list of interfaces. At the bottom you should see the Tutorial interface with the associated environment(s). Select the link next to the environment you wish to work with to continue (note: you will see an error page -- this is expected!).

Creating the Interface Controller

After clicking the link, you will notice you are presented with an error stating CONTROLLER CLASS TUTORIALINTERFACECONTROLLER COULD NOT BE FOUND. This is because we haven't written it yet!

The RMS is based on the popular model-view-controller paradigm. Specifically, RMS uses CakePHP 2.5.x to accomplish this. While knowing CakePHP and its associated tutorials will allow you to take advantage of some neat tricks and clean code, it is unnecessary for interface creation. Much of its magic is masked and automated within the RMS.

The model portion of interfaces is totally abstracted from the developer. Thus, all you need to do is create the controller (where custom variables are defined), and the view (the actual interface). To create a controller, you will need to create a PHP class based on the name of your interface. Remember that for this tutorial, our interface name is Tutorial.

In your favorite editor, create a PHP file in your RMS directory under rms/app/Controller and name the file TutorialInterfaceController.php. Dump the following into the file:

   1 <?php
   2 App::uses('InterfaceController', 'Controller');
   3 
   4 class TutorialInterfaceController extends InterfaceController {
   5 
   6         public function view() {
   7                 // set the title of the HTML page
   8                 $this->set('title_for_layout', 'Tutorial Interface');
   9                 // we will need some RWT libraries
  10                 $this->set('rwt', array('roslibjs' => 'current'));
  11         }
  12 }

Code Explanation

Now, let's look at each component.

   2 App::uses('InterfaceController', 'Controller');

This link is a CakePHP convention which specifies that the class will be a Controller and, more specifically, an InterfaceController.

   4 class TutorialInterfaceController extends InterfaceController {

The important notes here are that the name of the class matches the file, which matches the name of our interface. That is, if our interface name was This Is A Test, then the name of the class would be ThisIsATestInterfaceController. It is also crucial to extend the InterfaceController class. This class is responsible for automatically setting interface variables for user studies, environments, and associated topics and camera streams. We will see how to use these variables in the next section.

   6         public function view() {
   7                 // set the title of the HTML page
   8                 $this->set('title_for_layout', 'Tutorial Interface');
   9                 // we will need some RWT libraries
  10                 $this->set('rwt', array('roslibjs' => 'current'));
  11         }

The controller itself only needs to implement the view function. Technically, you do not even need to implement this function if you do not need any custom variables since the InterfaceController implements a default function. In most cases, you will overwrite this. You can set and custom variables you want your view to have access to using the $this->set function. Here, we define the CakePHP title_for_layout variable which sets the HTML page title, and the rwt array specifying which Robot Web Tools libraries we will use in our interface. You can specify libraries such as roslibjs or ros3djs depending on what you are using. The value for each entry is the version to use (e.g., current or 0.0.8). See the libraries ROS wiki pages for associated version numbers.

Creating the Interface View

At this point, if you were to refresh your interface, you would see another error stating VIEW FILE "/VAR/WWW/RMS/APP/VIEW/TUTORIALINTERFACE/VIEW.CTP" IS MISSING.. Again, this is because we have not yet created it.

The view is responsible for creating the actual HTML for the interface. A number of helper functions are available in the RMS to help with this, although any HTML/JavaScript can be added here. This tutorial uses the default RMS layout and styles, although these can be disabled for blank or more custom design as well.

To create a view, create a CTP file (a type of PHP file) in your RMS directory under rms/app/View/TutorialInterface and name the file view.ctp. Dump the following into the file:

   1 <?php echo $this->Rms->ros($environment['Rosbridge']['uri']); ?>
   2 
   3 <script>
   4         var topic = new ROSLIB.Topic({
   5                 ros : _ROS,
   6                 name : '/echo',
   7                 messageType : 'std_msgs/String'
   8         });
   9 </script>
  10 
  11 <header class="special container">
  12         <span class="icon fa-cloud"></span>
  13         <h2>My Shiny New Interface</h2>
  14 </header>
  15 
  16 <section class="wrapper style4 container">
  17         <div class="content center">
  18                 <input id="message" value="Hello, World!"/>
  19                 <br />
  20                 <button id="send" class="button">Send Message</button>
  21                 <script>
  22                         $('#send').click(function() {
  23                                 var msg = new ROSLIB.Message({
  24                                         data : $('#message').val()
  25                                 });
  26                                 topic.publish(msg);
  27                         });
  28                 </script>
  29         </div>
  30 </section>

Code Explanation

Now, let's look at each component.

   1 <?php echo $this->Rms->ros($environment['Rosbridge']['uri']); ?>

This line automatically creates our rosbridge connection. We simply pass in the rosbridge variable that was defined by the InterfaceController class. As stated in the API documentation, this will create a global JavaScript variable named _ROS that we have access to.

   3 <script>
   4         var topic = new ROSLIB.Topic({
   5                 ros : _ROS,
   6                 name : '/echo',
   7                 messageType : 'std_msgs/String'
   8         });
   9 </script>

This block of code is standard in roslibjs. It is simply creating a ROS topic that we can later publish to.

  18                 <input id="message" value="Hello, World!"/>
  19                 <br />
  20                 <button id="send" class="button">Send Message</button>

Here, we are creating an input and button that we will use. The goal of this interface is to send a ROS message via the web. That is, whatever text is placed in the input field will be sent to the ROS topic /echo when the button is pressed.

  21                 <script>
  22                         $('#send').click(function() {
  23                                 var msg = new ROSLIB.Message({
  24                                         data : $('#message').val()
  25                                 });
  26                                 topic.publish(msg);
  27                         });
  28                 </script>

This block of code defines the button callback for the interface (note that the $ notation is making use of jQuery. Simply put, this when the button is pressed, a new roslibjs message is created with the value of the input field. It is then published.

Running The Interface

To run this interface, you will need to have rosbridge running. In your terminal, run the following:

• roslaunch rosbridge_server rosbridge_websocket.launch

In a new terminal, run the following to see the output of our new /echo topic:

• rostopic echo /echo

Refresh your interface and start sending messages. You should see them echoed in the terminal. To see some fancier examples of interfaces (e.g., with camera feeds), check out the Basic Interface source code.

Support

Please send bug reports to the GitHub Issue Tracker. Feel free to contact me at any point with questions and comments.

• Russell Toris

  • rctoris@wpi.edu

  • Academic Website