See also:

• Master Slave APIs

• Slave API

• Parameter Server API

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.