See also:

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.

Wiki: ROS/Master_API (last edited 2023-03-21 21:14:30 by Carter Schultz)