Package rosgraph :: Module masterapi :: Class Master
[frames] | no frames]

Class Master

source code

object --+
         |
        Master

API for interacting with the ROS master. Although the Master is relatively simple to interact with using the XMLRPC API, this abstraction layer provides protection against future updates. It also provides a streamlined API with builtin return code checking and caller_id passing.

Instance Methods
 
__init__(self, caller_id, master_uri=None)
:param caller_id: name of node to use in calls to master, ``str`` :param master_uri: (optional) override default ROS master URI, ``str`` :raises: :exc:`ValueError` If ROS master uri not set properly
source code
 
is_online(self)
Check if Master is online.
source code
int
deleteParam(self, key)
Parameter Server: delete parameter
source code
int
setParam(self, key, value)
Parameter Server: set parameter.
source code
XMLRPCLegalValue
getParam(self, key)
Retrieve parameter value from server.
source code
str
searchParam(self, key)
Search for parameter key on parameter server.
source code
XMLRPCLegalValue
subscribeParam(self, caller_api, key)
Retrieve parameter value from server and subscribe to updates to that param.
source code
int
unsubscribeParam(self, caller_api, key)
Retrieve parameter value from server and subscribe to updates to that param.
source code
[int, str, bool]
hasParam(self, key)
Check if parameter is stored on server.
source code
[int, str, [str]]
getParamNames(self)
Get list of all parameter names stored on this server.
source code
int
getPid(self)
Get the PID of this server
source code
str
getUri(self)
Get the URI of this Master
source code
int
registerService(self, service, service_api, caller_api)
Register the caller as a provider of the specified service.
source code
 
lookupService(self, service)
Lookup all provider of a particular service.
source code
(int, str, int)
unregisterService(self, service, service_api)
Unregister the caller as a provider of the specified service.
source code
(int, str, list(str))
registerSubscriber(self, topic, topic_type, caller_api)
Subscribe the caller to the specified topic.
source code
(int, str, int)
unregisterSubscriber(self, topic, caller_api)
Unregister the caller as a publisher of the topic.
source code
[str]
registerPublisher(self, topic, topic_type, caller_api)
Register the caller as a publisher the topic.
source code
int
unregisterPublisher(self, topic, caller_api)
Unregister the caller as a publisher of the topic.
source code
str
lookupNode(self, node_name)
Get the XML-RPC URI of the node with the associated name/caller_id.
source code
[[str, str],]
getPublishedTopics(self, subgraph)
Get list of topics that can be subscribed to.
source code
(int, str, [[str,str]] )
getTopicTypes(self)
Retrieve list topic names and their types.
source code
[[str,[str]], [str,[str]], [str,[str]]]
getSystemState(self)
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, caller_id, master_uri=None)
(Constructor)

source code 

:param caller_id: name of node to use in calls to master, ``str`` :param master_uri: (optional) override default ROS master URI, ``str`` :raises: :exc:`ValueError` If ROS master uri not set properly

Overrides: object.__init__

is_online(self)

source code 

Check if Master is online.

NOTE: this is not part of the actual Master API. This is a convenience function.

Parameters:
  • master_uri (str) - (optional) override environment's ROS_MASTER_URI
Returns:
True if Master is available

deleteParam(self, key)

source code 

Parameter Server: delete parameter

Parameters:
  • key (str) - parameter name
Returns: int
0

setParam(self, key, value)

source code 

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:
  • key (str) - parameter name
  • value (XMLRPCLegalValue) - parameter value.
Returns: int
0

getParam(self, key)

source code 

Retrieve parameter value from server.

Parameters:
  • key (str getParam() will return a parameter tree.) - parameter to lookup. If key is a namespace, getParam() will return a parameter tree.
Returns: XMLRPCLegalValue
parameterValue. 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.

searchParam(self, key)

source code 

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:
  • key (str) - parameter key to search for.
Returns: str
foundKey

subscribeParam(self, caller_api, key)

source code 

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

Parameters:
  • key (str) - parameter to lookup.
  • caller_api (str) - API URI for paramUpdate callbacks.
Returns: XMLRPCLegalValue
parameterValue. parameterValue is an empty dictionary if the parameter has not been set yet.

unsubscribeParam(self, caller_api, key)

source code 

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

Parameters:
  • key (str) - parameter to lookup.
  • caller_api (str) - API URI for paramUpdate callbacks.
Returns: int
numUnsubscribed. If numUnsubscribed is zero it means that the caller was not subscribed to the parameter.

hasParam(self, key)

source code 

Check if parameter is stored on server.

Parameters:
  • key (str) - parameter to check
Returns: [int, str, bool]
[code, statusMessage, hasParam]

getParamNames(self)

source code 

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

Returns: [int, str, [str]]
[code, statusMessage, parameterNameList]

getPid(self)

source code 

Get the PID of this server

Returns: int
serverProcessPID
Raises:

getUri(self)

source code 

Get the URI of this Master

Returns: str
masterUri
Raises:

registerService(self, service, service_api, caller_api)

source code 

Register the caller as a provider of the specified service.

Parameters:
  • service, str - Fully-qualified name of service
  • service_api, str - Service URI
  • caller_api, str - XML-RPC URI of caller node
Returns: int
ignore
Raises:

lookupService(self, service)

source code 

Lookup all provider of a particular service.

Parameters:
  • service - fully-qualified name of service to lookup.
Raises:

unregisterService(self, service, service_api)

source code 

Unregister the caller as a provider of the specified service.

Parameters:
  • 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.
Raises:

registerSubscriber(self, topic, topic_type, caller_api)

source code 

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:
  • 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, list(str))
(code, message, publishers). Publishers is a list of XMLRPC API URIs for nodes currently publishing the specified topic.
Raises:

unregisterSubscriber(self, topic, caller_api)

source code 

Unregister the caller as a publisher of the topic.

Parameters:
  • topic (str) - Fully-qualified name of topic to unregister.
  • caller_api (str registration matches.) - API URI of service to unregister. Unregistration will only occur if current
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.
Raises:

registerPublisher(self, topic, topic_type, caller_api)

source code 

Register the caller as a publisher the topic.

Parameters:
  • 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: [str]
subscriberApis. List of current subscribers of topic in the form of XMLRPC URIs.
Raises:

unregisterPublisher(self, topic, caller_api)

source code 

Unregister the caller as a publisher of the topic.

Parameters:
  • 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
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.
Raises:

lookupNode(self, node_name)

source code 

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:
  • node (str) - name of node to lookup
Returns: str
URI
Raises:

getPublishedTopics(self, subgraph)

source code 

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:
  • 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: [[str, str],]
[[topic1, type1]...[topicN, typeN]]
Raises:

getTopicTypes(self)

source code 

Retrieve list topic names and their types.

New in ROS 1.2.

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

getSystemState(self)

source code 

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

Returns: [[str,[str]], [str,[str]], [str,[str]]]
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]] ... ]
Raises: