Service Definitions

Overview

Robot Raconteur is a Remote Procedure Call (RPC) system that allows for “clients” to interact with “services.” The services and clients need to understand the data types and objects that are made available by the service. Since Robot Raconteur supports multiple programming languages, the available data types and objects are defined using Robot Raconteur “Service Definitions,” a form of Interface Definition Language (IDL). When stored as a file, these definitions are typically stored in a file with the extension .robdef. When a client connects, it downloads the service definition from the service. For dynamic languages like Python and Matlab, the service definition is used to generate the necessary objects and data types at runtime. For statically typed languages like C++ and C#, the service definition is used to generate the necessary objects and data types at compile time. The generated code is referred to as “thunk” code.

Robot Raconteur uses an advanced “Augmented Object-Oriented” model to define objects. This model extends the typical members of objects to include additional functionality specific to robotics and automation applications. See objects for a discussion on the additional functionality provided by the Augmented Object-Oriented model. See value-types for a discussion on the value types supported by Robot Raconteur.

The following is an example of the service definition used for Reynard the Robot:

The service definition begins with the line service experimental.reynard_the_robot. This line defines the name of the service. In this case, the experimental namespace is used to indicate that the service is experimental. The namespace follows “Java” package naming conventions, which is reverse domain names. For instance, the standard Robot Raconteur types begin with com.robotraconteur. Services by a university might begin with edu.universityname. The next line is stdver 0.10. This line defines the minimum version of Robot Raconteur required to use the service type. Future revisions to the Robot Raconteur standard may introduce new features that are not compatible with older versions. Currently, the most recent revision to the service definition standard is “0.10”. This version should be used until a future version of Robot Raconteur changes the service definition standard.

The service definition defines the structure ReynardState, and the object Reynard. Service definitions can also define enums, constants, namedarrays, pods, and exceptions. See the following pages for more information on the contents of service definitions and how to use them:

Note

“Values Types” are passed by value, while “Object Types” are passed by reference.

Note

Also see the Robot Raconteur Framework Service Definition Documentation and the Robot Raconteur Service Definition Standard for more detailed information on the service definition format.

The following are additional examples of service definitions for the iRobot Create and Simple Webcam examples:

Standard Service Definitions

Robot Raconteur provides a large number of standard service definitions that are used to define common data types and objects used by robotics and automation devices.

Standard Service Robot Raconteur Definitions

Standard Service Robot Raconteur Definitions Documentation

Frequently used standard service definitions include:

Note

The “Companion” libraries for Robot Raconteur are typically used to simplify the use of standard service definitions. For C++ and C# the companion libraries contain the “thunk” code for the standard service definitions, so it is not necessary to generate the code from the service definitions for each project.