ROS/Master

Contents

Using XMLRPC
API Listing
1. register/unregister methods
2. Name service and system state

Using XMLRPC

The Master API is implemented via XMLRPC, which has good library support in a variety of languages. For example, in Python:

import os
import xmlrpclib
caller_id = '/script'
m = xmlrpclib.ServerProxy(os.environ['ROS_MASTER_URI'])
code, msg, val = m.getSystemState(caller_id)
if code == 1:
  pubs, subs, srvs = val
else:
  print "call failed", code, msg

API Listing

Language-specific client APIs as well as tools may define convenience methods that make it unnecessary to call these APIs directly.

register/unregister methods

registerService(caller_id, service, service_api, caller_api)

Register the caller as a provider of the specified service.

Parameters
- caller_id (str)
  - ROS caller ID
  service (str)
  - Fully-qualified name of service
  service_api (str)
  - ROSRPC Service URI
  caller_api (str)
  - XML-RPC URI of caller node
Returns (int, str, int)
- (code, statusMessage, ignore)

unregisterService(caller_id, service, service_api)

Unregister the caller as a provider of the specified service.

Parameters
- caller_id (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, statusMessage, 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.

registerSubscriber(caller_id, topic, topic_type, caller_api)

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.
  topic_type (str)
  - Datatype for topic. Must be a package-resource name, i.e. the .msg name.
  caller_api (str)
  - API URI of subscriber to register. Will be used for new publisher notifications.
Returns (int, str, [str])
- (code, statusMessage, publishers)
  
  Publishers is a list of XMLRPC API URIs for nodes currently publishing the specified topic.

unregisterSubscriber(caller_id, topic, caller_api)

Unregister the caller as a publisher of the topic.

Parameters
- caller_id (str)
  - ROS caller ID
  topic (str)
  - Fully-qualified name of topic.
  caller_api (str)
  - API URI of subscriber 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.

registerPublisher(caller_id, topic, topic_type, caller_api)

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)
  - API URI of publisher to register.
Returns (int, str, [str])
- (code, statusMessage, subscriberApis)
  
  List of current subscribers of topic in the form of XMLRPC URIs.

unregisterPublisher(caller_id, topic, caller_api)

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 publisher 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.

Name service and system state

lookupNode(caller_id, node_name)

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, statusMessage, URI)

getPublishedTopics(caller_id, subgraph)

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 empty string to specify all names.
Returns (int, str, [[str, str],])
- (code, statusMessage, [ [topic1, type1]...[topicN, typeN] ])

getTopicTypes(caller_id)

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.

getSystemState(caller_id)

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]] ... ]
```

getUri(caller_id)

Get the URI of the master.

Parameters
- caller_id (str)
  - ROS caller ID
Returns (int, str, str)
- (code, statusMessage, masterURI)

lookupService(caller_id, service)

Lookup all provider of a particular service.

Parameters
- caller_id (str)
  - ROS caller ID
  service (str)
  - Fully-qualified name of service
Returns (int, str, str)
- (code, statusMessage, serviceUrl)
  
  service URL is provides address and port of the service. Fails if there is no provider.