Package rosmaster :: Module master_api :: Class ROSMasterHandler

Class ROSMasterHandler

object --+
         |
        ROSMasterHandler

XML-RPC handler for ROS master APIs. API routines for the ROS Master Node. The Master Node is a superset of the Slave Node and contains additional API methods for creating and monitoring a graph of slave nodes.

By convention, ROS nodes take in caller_id as the first parameter of any API call. The setting of this parameter is rarely done by client code as ros::msproxy::MasterProxy automatically inserts this parameter (see ros::client::getMaster()).

Instance Methods

__init__(self, num_workers=3)
ctor.

source code

[int, str, int]

shutdown(*args, **kwds)
Stop this server

source code

getUri(*args, **kwds)
Get the XML-RPC URI of this server.

source code

[int, str, int]

getPid(*args, **kwds)
Get the PID of this server

source code

[int, str, int]

deleteParam(*args, **kwds)
Parameter Server: delete parameter

source code

[int, str, int]

setParam(*args, **kwds)
Parameter Server: set parameter.

source code

[int, str, XMLRPCLegalValue]

getParam(*args, **kwds)
Retrieve parameter value from server.

source code

[int, str, str]

searchParam(*args, **kwds)
Search for parameter key on parameter server.

source code

[int, str, XMLRPCLegalValue]

subscribeParam(*args, **kwds)
Retrieve parameter value from server and subscribe to updates to that param.

source code

[int, str, int]

unsubscribeParam(*args, **kwds)
Retrieve parameter value from server and subscribe to updates to that param.

source code

[int, str, bool]

hasParam(*args, **kwds)
Check if parameter is stored on server.

source code

[int, str, [str]]

getParamNames(*args, **kwds)
Get list of all parameter names stored on this server.

source code

param_update_task(self, caller_id, caller_api, param_key, param_value)
Contact api.paramUpdate with specified parameters

source code

(int, str, int)

registerService(*args, **kwds)
Register the caller as a provider of the specified service.

source code

(int, str, str)

lookupService(*args, **kwds)
Lookup all provider of a particular service.

source code

(int, str, int)

unregisterService(*args, **kwds)
Unregister the caller as a provider of the specified service.

source code

(int, str, [str])

registerSubscriber(*args, **kwds)
Subscribe the caller to the specified topic.

source code

(int, str, int)

unregisterSubscriber(*args, **kwds)
Unregister the caller as a publisher of the topic.

source code

(int, str, [str])

registerPublisher(*args, **kwds)
Register the caller as a publisher the topic.

source code

(int, str, int)

unregisterPublisher(*args, **kwds)
Unregister the caller as a publisher of the topic.

source code

(int, str, str)

lookupNode(*args, **kwds)
Get the XML-RPC URI of the node with the associated name/caller_id.

source code

(int, str, [[str, str],])

getPublishedTopics(*args, **kwds)
Get list of topics that can be subscribed to.

source code

(int, str, [[str,str]] )

getTopicTypes(*args, **kwds)
Retrieve list topic names and their types.

source code

(int, str, [[str,[str]], [str,[str]], [str,[str]]])

getSystemState(*args, **kwds)
Retrieve list representation of system state (i.e.

source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Properties
Inherited from `object`: `__class__`

Method Details

init(self, num_workers=3)
(Constructor)

ctor.

Overrides: object.__init__

shutdown(*args, **kwds)

Stop this server

Parameters:

caller_id (str) - ROS caller id
msg (str) - a message describing why the node is being shutdown.

Returns: [int, str, int]

[code, msg, 0]

Decorators:

@apivalidate(0, (None,))

getUri(*args, **kwds)

Get the XML-RPC URI of this server.

Parameters:

caller_id, str - ROS caller id

Decorators:

@apivalidate('')

getPid(*args, **kwds)

Get the PID of this server

Parameters:

caller_id (str) - ROS caller id

Returns: [int, str, int]

[1, "", serverProcessPID]

Decorators:

@apivalidate(-1)

deleteParam(*args, **kwds)

Parameter Server: delete parameter

Parameters:

caller_id (str) - ROS caller id
key (str) - parameter name

Returns: [int, str, int]

[code, msg, 0]

Decorators:

@apivalidate(0, (non_empty_str('key'),))

setParam(*args, **kwds)

Parameter Server: set parameter. NOTE: if value is a dictionary it will be treated as a parameter tree, where key is the parameter namespace. For example::

 {'x':1,'y':2,'sub':{'z':3}}

will set key/x=1, key/y=2, and key/sub/z=3. Furthermore, it will replace all existing parameters in the key parameter namespace with the parameters in value. You must set parameters individually if you wish to perform a union update.

Parameters:

caller_id (str) - ROS caller id
key (str) - parameter name
value (XMLRPCLegalValue) - parameter value.

Returns: [int, str, int]

[code, msg, 0]

Decorators:

@apivalidate(0, (non_empty_str('key'), not_none('value')))

getParam(*args, **kwds)

Retrieve parameter value from server.

Parameters:

caller_id (str) - ROS caller id
key (str getParam() will return a parameter tree.) - parameter to lookup. If key is a namespace, getParam() will return a parameter tree.

Returns: [int, str, XMLRPCLegalValue]

[code, statusMessage, parameterValue]. If code is not 1, parameterValue should be ignored. If key is a namespace, the return value will be a dictionary, where each key is a parameter in that namespace. Sub-namespaces are also represented as dictionaries.

Decorators:

@apivalidate(0, (non_empty_str('key'),))

searchParam(*args, **kwds)

Search for parameter key on parameter server. Search starts in caller's namespace and proceeds upwards through parent namespaces until Parameter Server finds a matching key.

searchParam's behavior is to search for the first partial match. For example, imagine that there are two 'robot_description' parameters:

  /robot_description
    /robot_description/arm
    /robot_description/base
  /pr2/robot_description
    /pr2/robot_description/base

If I start in the namespace /pr2/foo and search for 'robot_description', searchParam will match /pr2/robot_description. If I search for 'robot_description/arm' it will return /pr2/robot_description/arm, even though that parameter does not exist (yet).

Parameters:

caller_id (str), str - ROS caller id
key (str) - parameter key to search for.

Returns: [int, str, str]

[code, statusMessage, foundKey]. If code is not 1, foundKey should be ignored.

Decorators:

@apivalidate(0, (non_empty_str('key'),))

subscribeParam(*args, **kwds)

Retrieve parameter value from server and subscribe to updates to that param. See paramUpdate() in the Node API.

Parameters:

caller_id (str), str - ROS caller id
key (str) - parameter to lookup.
caller_api (str) - API URI for paramUpdate callbacks.

Returns: [int, str, XMLRPCLegalValue]

[code, statusMessage, parameterValue]. If code is not 1, parameterValue should be ignored. parameterValue is an empty dictionary if the parameter has not been set yet.

Decorators:

@apivalidate(0, (is_api('caller_api'), non_empty_str('key'),))

unsubscribeParam(*args, **kwds)

Retrieve parameter value from server and subscribe to updates to that param. See paramUpdate() in the Node API.

Parameters:

caller_id (str), str - ROS caller id
key (str) - parameter to lookup.
caller_api (str) - API URI for paramUpdate callbacks.

Returns: [int, str, int]

[code, statusMessage, numUnsubscribed]. If numUnsubscribed is zero it means that the caller was not subscribed to the parameter.

Decorators:

@apivalidate(0, (is_api('caller_api'), non_empty_str('key'),))

hasParam(*args, **kwds)

Check if parameter is stored on server.

Parameters:

caller_id (str), str - ROS caller id
key (str) - parameter to check

Returns: [int, str, bool]

[code, statusMessage, hasParam]

Decorators:

@apivalidate(False, (non_empty_str('key'),))

getParamNames(*args, **kwds)

Get list of all parameter names stored on this server. This does not adjust parameter names for caller's scope.

Parameters:

caller_id (str) - ROS caller id

Returns: [int, str, [str]]

[code, statusMessage, parameterNameList]

Decorators:

@apivalidate([])

param_update_task(self, caller_id, caller_api, param_key, param_value)

Contact api.paramUpdate with specified parameters

Parameters:

caller_id (str) - caller ID
caller_api (str) - XML-RPC URI of node to contact
param_key (str) - parameter key to pass to node
param_value (str) - parameter value to pass to node

registerService(*args, **kwds)

Register the caller as a provider of the specified service.

Parameters:

caller_id (str), str - ROS caller id
service (str) - Fully-qualified name of service
service_api (str) - Service URI
caller_api (str) - XML-RPC URI of caller node

Returns: (int, str, int)

(code, message, ignore)

Decorators:

@apivalidate(0, (is_service('service'), is_api('service_api'), is_api('caller_api')))

lookupService(*args, **kwds)

Lookup all provider of a particular service.

Parameters:

caller_id (str), str - ROS caller id
service - fully-qualified name of service to lookup.

Returns: (int, str, str)

(code, message, serviceUrl). service URL is provider's ROSRPC URI with address and port. Fails if there is no provider.

Decorators:

@apivalidate(0, (is_service('service'),))

unregisterService(*args, **kwds)

Unregister the caller as a provider of the specified service.

Parameters:

caller_id (str), str - ROS caller id
service (str) - Fully-qualified name of service
service_api (str) - API URI of service to unregister. Unregistration will only occur if current registration matches.

Returns: (int, str, int)

(code, message, numUnregistered). Number of unregistrations (either 0 or 1). If this is zero it means that the caller was not registered as a service provider. The call still succeeds as the intended final state is reached.

Decorators:

@apivalidate(0, (is_service('service'), is_api('service_api')))

registerSubscriber(*args, **kwds)

Subscribe the caller to the specified topic. In addition to receiving a list of current publishers, the subscriber will also receive notifications of new publishers via the publisherUpdate API.

Parameters:

caller_id (str) - ROS caller id
topic, str - Fully-qualified name of topic to subscribe to.
topic_type (str) - Datatype for topic. Must be a package-resource name, i.e. the .msg name.
caller_api (str) - XML-RPC URI of caller node for new publisher notifications

Returns: (int, str, [str])

(code, message, publishers). Publishers is a list of XMLRPC API URIs for nodes currently publishing the specified topic.

Decorators:

@apivalidate(0, (is_topic('topic'), valid_type_name('topic_type'), is_api('caller_api')))

unregisterSubscriber(*args, **kwds)

Unregister the caller as a publisher of the topic.

Parameters:

caller_id (str) - ROS caller id
topic (str) - Fully-qualified name of topic to unregister.
caller_api (str) - API URI of service to unregister. Unregistration will only occur if current registration matches.

Returns: (int, str, int)

(code, statusMessage, numUnsubscribed). If numUnsubscribed is zero it means that the caller was not registered as a subscriber. The call still succeeds as the intended final state is reached.

Decorators:

@apivalidate(0, (is_topic('topic'), is_api('caller_api')))

registerPublisher(*args, **kwds)

Register the caller as a publisher the topic.

Parameters:

caller_id (str) - ROS caller id
topic (str) - Fully-qualified name of topic to register.
topic_type (str) - Datatype for topic. Must be a package-resource name, i.e. the .msg name.
caller_api (str), str - ROS caller XML-RPC API URI

Returns: (int, str, [str])

(code, statusMessage, subscriberApis). List of current subscribers of topic in the form of XMLRPC URIs.

Decorators:

@apivalidate(0, (is_topic('topic'), valid_type_name('topic_type'), is_api('caller_api')))

unregisterPublisher(*args, **kwds)

Unregister the caller as a publisher of the topic.

Parameters:

caller_id (str) - ROS caller id
topic (str) - Fully-qualified name of topic to unregister.
caller_api (str), str - API URI of service to unregister. Unregistration will only occur if current registration matches.

Returns: (int, str, int)

(code, statusMessage, numUnregistered). If numUnregistered is zero it means that the caller was not registered as a publisher. The call still succeeds as the intended final state is reached.

Decorators:

@apivalidate(0, (is_topic('topic'), is_api('caller_api')))

lookupNode(*args, **kwds)

Get the XML-RPC URI of the node with the associated name/caller_id. This API is for looking information about publishers and subscribers. Use lookupService instead to lookup ROS-RPC URIs.

Parameters:

caller_id (str) - ROS caller id
node (str) - name of node to lookup

Returns: (int, str, str)

(code, msg, URI)

Decorators:

@apivalidate('', (valid_name('node'),))

getPublishedTopics(*args, **kwds)

Get list of topics that can be subscribed to. This does not return topics that have no publishers. See getSystemState() to get more comprehensive list.

Parameters:

caller_id (str) - ROS caller id
subgraph (str) - Restrict topic names to match within the specified subgraph. Subgraph namespace is resolved relative to the caller's namespace. Use '' to specify all names.

Returns: (int, str, [[str, str],])

(code, msg, [[topic1, type1]...[topicN, typeN]])

Decorators:

@apivalidate(0, (empty_or_valid_name('subgraph'),))

getTopicTypes(*args, **kwds)

Retrieve list topic names and their types.

Parameters:

caller_id (str) - ROS caller id

Returns: (int, str, [[str,str]] )

(code, statusMessage, topicTypes). topicTypes is a list of [topicName, topicType] pairs.

Decorators:

@apivalidate([])

getSystemState(*args, **kwds)

Retrieve list representation of system state (i.e. publishers, subscribers, and services).

Parameters:

caller_id (str) - ROS caller id

Returns: (int, str, [[str,[str]], [str,[str]], [str,[str]]])

(code, statusMessage, systemState).

System state is in list representation:

 [publishers, subscribers, services].

publishers is of the form:

 [ [topic1, [topic1Publisher1...topic1PublisherN]] ... ]

subscribers is of the form:

 [ [topic1, [topic1Subscriber1...topic1SubscriberN]] ... ]

services is of the form:

 [ [service1, [service1Provider1...service1ProviderN]] ... ]

Decorators:

@apivalidate([[], [], []])