The capability_server ROS Node

The capability_server ROS Node which is provided with this package uses the Python API’s provided by this package to serve the discovered capability specifications and manage the run time of capabilities.

With the capability_server you can list the available capability interfaces and providers, start and stop capabilities explicitly or using reference counting calls “use” and “free”.

It is recommended that you use The Client Module and/or The Service Discovery Module in conjunction with the capability_server.

ROS API

The capability_server provides most of its functionality via ROS services and topics and is configured with ROS parameters.

ROS Parameters

Using ROS Parameters you can control what is loaded by the capability server:

  • ~package_whitelist (list of strings Default: null)

    If not null then the packages listed will be the only packages from which specs are loaded.

  • ~package_blacklist (list of strings Default: null)

    If not null then the packages listed will be ignored when loading specs.

  • ~whitelist (list of strings Default: null)

    If not null then only the specs listed will be loaded (if found), specs must have fully qualified names, i.e. <package_name>/<spec_name>.

  • ~blacklist (list of strings Default: null)

    If not null then the listed specs will be ignored, specs must have fully qualified names, i.e. <package_name>/<spec_name>.

The easiest way to specify the above parameters is in YAML, either in a separate file, like this:

package_whitelist:
  - package1
  - package2
package_blacklist:
  - package2
whitelist:
  - 'package1/SomeCapability'
  - 'package2/some_capability_provider'
  - 'package2/some_capability_provider_faux'
blacklist:
  - 'package2/some_capability_provider_faux'

Which can be loaded in a launch file like this:

<rosparam command="load" file="$(find some_package)/black_and_white_lists.yaml" />

Or inline in the launch file like this:

<node pkg="capabilities" type="capability_server" name="capability_server" output="screen">
    <rosparam param="package_whitelist">
        - package1
        - package2
    </rosparam>
    <rosparam param="package_blacklist">
        - package2
    </rosparam>
    <rosparam param="whitelist">
        - 'package1/SomeCapability'
        - 'package2/some_capability_provider'
        - 'package2/some_capability_provider_faux'
    </rosparam>
    <rosparam param="blacklist">
        - 'package2/some_capability_provider_faux'
    </rosparam>
</node>

You can also control the behavior of the capability_server using these parameters:

  • ~debug (bool Default: false)

    If true debug level messages will be printed to the screen.

  • ~missing_default_provider_is_an_error (bool Default: false)

    If true then if any interfaces with no configured default provider will result in an error instead of a warning.

  • ~nodelet_manager_name (str Default: capability_server_nodelet_manager)

    Name of the internal nodelet manager which is managed by the capability_server.

  • ~use_screen (bool Default: false)

    If true the --screen option is passed to roslaunch when launching a capability provider’s launch file.

ROS Topics

There is only one ROS topic provided by the capability_server:

On this topic several types of events are published and the type is set in the type field of the message:

  • “server_ready”: fired once when the capability_server is done loading and ready
  • “launched”: fired each time a new capability is launched
  • “stopped”: fired each time a capability is asked to shutdown
  • “terminated”: fired each time a capability provider’s launch file terminates (expected or otherwise)

The capability, provider, and pid fields of the message are set only for the “launched”, “stopped”, and “terminated” event types.

ROS Services

Starts a given capability interface, with an optional preferred provider. If the preferred provider is not given, the default provider is used.

Stops a given capability interface.

Notifies the capability server that you use this capability. If not already running, the capability interface is started (using the preferred provider if provided), otherwise the reference count is simply incremented.

It is recommended to use The Client Module instead of using this service directly.

Notifies the capability server that you no longer need one of the “use“‘s you previously made on this capability. If the reference count goes to zero, then the capability will be stopped.

It is recommended to use The Client Module instead of using this service directly.

Generates and returns the bond_id on which a bond should be established. This bond_id is used by the ~use_capability and ~free_capability services.

It is recommended to use The Client Module instead of using this service directly.

Reloads the capabilities from the ROS_PACKAGE_PATH.

Returns a list of strings which are the names of the available Capability Interfaces.

Returns a list of strings which are the names of the available Capability Semantic Interfaces.

Returns a list of strings which are the names of the available Capability Providers.

Returns a list of capabilities/RunningCapability, each of which captures the running capabilities’ interface, provider, pid, and dependent capabilities.

Returns a list of capabilities/CapabilitySpec, each of which captures all the information necessary to represent that capability specification.

It is recommended to use The Service Discovery Module instead of using this service directly.

Returns a single capabilities/CapabilitySpec, which captures all the information necessary to represent that capabilities specification.

Returns the name of the nodelet manager node for this capability_server.

Returns a list of remappings for each ROS primitive (topics, services, actions, parameters) for the given capability interface.

This is useful for determining what the actual topic name is for a semantic interface or provider which has remappings.