ros源码分析(5)—rosmaster xmlrpc api

The rosmaster package implements the ROS Master. Most programs will not need to interact with this package directly. The rosmaster is run automatically whenever roscore is run and all communication with the Master happens over XMLRPC APIs.

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'])
#调用getSystemState api
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.

注意这段话，例如ros_comm\tools\rosgraph\src\rosgraph\masterapi.py中的masterapi.py就对这些接口进行了简单的封装。

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

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