[Documentation] [TitleIndex] [WordIndex

(!) 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.

Capabilities Demo

Description: Demonstrating the capabilities of the capability server.

Keywords: capabilities

Tutorial Level: INTERMEDIATE

You can setup a demo of sorts using one of the test fixtures.

Note: You must install the capabilities package sources into your catkin workspace for this demo to work.

Starting the capability server

Start the capability server with the demo.launch file:

This is equivalent to running a roscore and then this:

This starts the capability server which crawls the ROS_PACKAGE_PATH and looks for packages which export capabilities. In this case it should find the minimal_pkg package in the test/discovery_workspaces folder. You can look at the package.xml of minimal_pkg to see how it defines its capabilities:

   1 <?xml version="1.0"?>
   2 <package>
   3   ...
   4   <export>
   5     <capability_interface>
   6       interfaces/Minimal.yaml
   7     </capability_interface>
   8     <capability_provider>
   9       providers/minimal.yaml
  10     </capability_provider>
  11     <semantic_capability_interface>
  12       interfaces/SpecificMinimal.yaml
  13     </semantic_capability_interface>
  14     <capability_provider>
  15       providers/specific_minimal.yaml
  16     </capability_provider>
  17 
  18   </export>
  19 </package>

It defines one capability interface, minimal_pkg/Minimal, and a semantic interface called minimal_pkg/SpecificMinimal. It also provides a capability provider for each of those interfaces. Looking at the minimal_pkg/Minimal interface spec file:

   1 %YAML 1.1
   2 ---
   3 name: Minimal
   4 spec_version: 1
   5 spec_type: interface
   6 interface: {}

It basically fills out only the explicitly required fields (it's minimal after all).

You can also take a look at the minimal_pkg/minimal provider:

   1 %YAML 1.1
   2 ---
   3 name: minimal
   4 spec_version: 1
   5 spec_type: provider
   6 implements: minimal_pkg/Minimal
   7 launch_file: 'launch/minimal.launch'

You can see that this provider specifies that it implements the minimal_pkg/Minimal interface, and it has a launch file, which is specified relatively from the minimal_pkg/minimal spec file. This launch file simply runs a dummy script:

   1 <launch>
   2     <node name="minimal" pkg="minimal_pkg" type="minimal.py" output="screen" />
   3 </launch>

Which just prints and publishes a message periodically and then stops after 10 seconds:

   1 #!/usr/bin/env python
   2 
   3 import rospy
   4 from std_msgs.msg import String
   5 
   6 
   7 def minimal():
   8     pub = rospy.Publisher('chatter', String)
   9     rospy.init_node('minimal')
  10     start = rospy.Time.now()
  11     while not rospy.is_shutdown() and (rospy.Time.now() - start).to_sec() < 10:
  12         str = "hello world %s" % rospy.get_time()
  13         rospy.loginfo(str)
  14         pub.publish(String(str))
  15         rospy.sleep(1.0)
  16 
  17 
  18 if __name__ == '__main__':
  19     try:
  20         minimal()
  21     except rospy.ROSInterruptException:
  22         pass

Testing out the capability server

Now there should be some key ROS services available:

You can call these services to query, start, and stop capabilities.

You can list the available interfaces:

You can also list the providers for an interface:

Start one with this command line:

This is telling the capability server to start the minimal_pkg/Minimal capability, preferring the minimal_pkg/minimal provider.

You can switch back to the capability_server and see that it is printing the message to the screen. After 10 seconds this node should shutdown normally, but you will get an error message like this:

[INFO] [WallTime: 1374023441.816336] Request to start capability 'minimal_pkg/Minimal' with provider 'minimal_pkg/minimal'
... logging to /Users/william/.ros/log/901417f8-ee7d-11e2-9b39-542696cef915/roslaunch-dosa-90541.log
Checking log directory for disk usage. This may take awhile.
Press Ctrl-C to interrupt

started roslaunch server http://dosa:54017/

SUMMARY
========

PARAMETERS
 * /rosdistro
 * /rosversion

NODES
  /
    minimal (minimal_pkg/minimal.py)

ROS_MASTER_URI=http://localhost:11311

core service [/rosout] found
process[minimal-1]: started with pid [90564]
[INFO] [WallTime: 1374023442.906086] hello world 1374023442.91
[INFO] [WallTime: 1374023443.907306] hello world 1374023443.91
[INFO] [WallTime: 1374023444.909204] hello world 1374023444.91
[INFO] [WallTime: 1374023445.911004] hello world 1374023445.91
[INFO] [WallTime: 1374023446.912970] hello world 1374023446.91
[INFO] [WallTime: 1374023447.914730] hello world 1374023447.91
[INFO] [WallTime: 1374023448.916598] hello world 1374023448.92
[INFO] [WallTime: 1374023449.918565] hello world 1374023449.92
[INFO] [WallTime: 1374023450.919426] hello world 1374023450.92
[INFO] [WallTime: 1374023451.921269] hello world 1374023451.92
[minimal-1] process has finished cleanly
log file: /Users/william/.ros/log/901417f8-ee7d-11e2-9b39-542696cef915/minimal-1*.log
all processes on machine have died, roslaunch will exit
shutting down processing monitor...
... shutting down processing monitor complete
done
[ERROR] [WallTime: 1374023453.342853] Capability Instance 'minimal_pkg/minimal' terminated unexpectedly, it was previously in the 'running' state.
[INFO] [WallTime: 1374023453.343502] Capability Provider 'minimal_pkg/minimal' for Capability 'minimal_pkg/Minimal' has terminated.

This is because from the capability_server's perspective the launch file it ran shutdown unexpectedly. This is normal for this launch file, but probably an error for most launch files which are designed to run forever, until stopped.

Stopping a capability

If you run the capability again:

And then within 10 seconds call:

The capability_server will preempt the provider currently running for the minimal_pkg/Minimal interface, if one is running. In this case we just launched the minimal_pkg/minimal provider so it will be shutdown prematurely:

[INFO] [WallTime: 1374018047.353614] Request to start capability 'minimal_pkg/Minimal' with provider 'minimal_pkg/minimal'
... logging to /Users/william/.ros/log/dc556d54-ee70-11e2-b171-542696cef915/roslaunch-dosa-89740.log
Checking log directory for disk usage. This may take awhile.
Press Ctrl-C to interrupt

started roslaunch server http://dosa:53279/

SUMMARY
========

PARAMETERS
 * /rosdistro
 * /rosversion

NODES
  /
    minimal (minimal_pkg/minimal.py)

ROS_MASTER_URI=http://localhost:11311

core service [/rosout] found
process[minimal-1]: started with pid [89763]
[INFO] [WallTime: 1374018048.422365] hello world 1374018048.42
[INFO] [WallTime: 1374018049.423824] hello world 1374018049.42
[INFO] [WallTime: 1374018050.425631] hello world 1374018050.43
[INFO] [WallTime: 1374018051.427550] hello world 1374018051.43
[INFO] [WallTime: 1374018052.428946] hello world 1374018052.43
[INFO] [WallTime: 1374018053.430748] hello world 1374018053.43
[INFO] [WallTime: 1374018054.432479] hello world 1374018054.43
[INFO] [WallTime: 1374018055.433698] hello world 1374018055.43
[INFO] [WallTime: 1374018055.752547] Request to stop capability 'minimal_pkg/Minimal'
[minimal-1] killing on exit
shutting down processing monitor...
... shutting down processing monitor complete
done
[INFO] [WallTime: 1374018056.651382] Capability Provider 'minimal_pkg/minimal' for Capability 'minimal_pkg/Minimal' has terminated.

These are the basics, more details about the specifications and chaining capabilities in the future.


2019-09-14 12:34