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:

 1service experimental.reynard_the_robot
 2
 3stdver 0.10
 4
 5struct ReynardState
 6    field double time
 7    field double[] robot_position
 8    field double[] arm_position
 9    field double[] robot_velocity
10    field double[] arm_velocity
11end
12
13object Reynard
14
15    function void teleport(double x, double y)
16
17    function void setf_arm_position(double q1, double q2, double q3)
18
19    function double[] getf_arm_position()
20
21    property double[] robot_position [readonly]
22
23    function void drive_robot(double vel_x, double vel_y, double timeout, bool wait)
24
25    function void drive_arm(double q1, double q2, double q3, double timeout, bool wait)
26
27    function void say(string message)
28
29    property double[] color
30
31    wire ReynardState state [readonly]
32
33    event new_message(string message)
34end

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:

 1
 2#Service to provide sample interface to the iRobot Create
 3#This example is for the original iRobot Create using the serial Open Interface (OI) protocol
 4service experimental.create3
 5
 6stdver 0.10
 7
 8enum CreateStateFlags
 9	unknown = 0,
10	bump_right = 0x1,
11	bump_left = 0x2,
12	wheel_drop_right = 0x4,
13	wheel_drop_left = 0x8,
14	wheel_drop_caster = 0x10,
15	wall_sensor = 0x20,
16	cliff_left = 0x40,
17	cliff_front_left = 0x80,
18	cliff_front_right = 0x100,
19	cliff_right = 0x200,
20	virtual_wall = 0x400,
21	play_button = 0x800,
22	advance_button = 0x1000,
23	error = 0x800000
24end
25
26struct CreateState
27	field double time
28	field uint32 create_state_flags
29	field double velocity
30	field double radius
31	field double right_wheel_velocity
32	field double left_wheel_velocity
33	field double distance_traveled
34	field double angle_traveled
35	field double battery_charge
36	field double battery_capacity
37end
38
39object Create
40	constant double DRIVE_STRAIGHT 32.767
41	constant double SPIN_CLOCKWISE -1e-3
42	constant double SPIN_COUNTERCLOCKWISE 1e-3
43
44	function void drive(double velocity, double radius)
45	function void drive_direct(double right_wheel_velocity, double left_wheel_velocity)
46	function void stop()
47	function void setf_leds(bool play, bool advance)
48
49	property double distance_traveled [readonly]
50	property double angle_traveled [readonly]
51	property uint8 bumpers [readonly]
52
53	event bump()
54
55	wire CreateState create_state [readonly]
56
57	# Callback to be called when the play button is pressed
58	# claim_play_callback() will assign the current client as the target for the callback
59	# Practical implementations will likely want to use a more sophisticated mechanism to assign the callback
60	function void claim_play_callback()
61	callback uint8[] play_callback(double distance_traveled, double angle_traveled)
62end

 1#Service to provide sample interface to webcams
 2
 3# This interface is for example only. Most cameras should use the standard com.robotraconteur.imaging.Camera interface
 4service experimental.simplewebcam3
 5
 6# The current version of Robot Raconteur robdef standards is 0.10
 7stdver 0.10
 8
 9struct WebcamImage
10    field int32 width
11    field int32 height
12    field int32 step
13    field uint8[] data
14end
15
16struct WebcamImage_size
17    field int32 width
18    field int32 height
19    field int32 step
20end
21
22object Webcam
23    property string name [readonly]
24    function WebcamImage capture_frame()
25
26    function void start_streaming()
27    function void stop_streaming()
28    pipe WebcamImage frame_stream [readonly]
29
30    function WebcamImage_size capture_frame_to_buffer()
31    memory uint8[] buffer [readonly]
32    memory uint8[*] multidimbuffer [readonly]
33
34end
35
36object WebcamHost
37    property string{int32} webcam_names [readonly]
38    objref Webcam{int32} webcams
39end

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.