About ROS 2 Interfaces¶
Table of Contents
ROS applications typically communicate through interfaces of one of two types: messages and services. ROS uses a simplified description language to describe these interfaces. This description makes it easy for ROS tools to automatically generate source code for the interface type in several target languages.
In this document we will describe the supported types and how to create your own msg/srv files.
Messages description are defined in
.msg files in the
msg/ directory of a ROS package.
.msg files are composed of two parts: fields and constants.
Each field consists of a type and a name, separated by a space, i.e:
fieldtype1 fieldname1 fieldtype2 fieldname2 fieldtype3 fieldname3
int32 my_int string my_string
Field types can be:
- a built-in-type
- names of Message descriptions defined on their own, such as “geometry_msgs/PoseStamped”
Built-in-types currently supported:
|Type name||C++||Python||DDS type|
|uint64||uint64_t||builtins.int*||unsigned long long|
Every built-in-type can be used to define arrays:
|Type name||C++||Python||DDS type|
|static array||std::array<T, N>||builtins.list*||T[N]|
|unbounded dynamic array||std::vector||builtins.list||sequence|
|bounded dynamic array||custom_class<T, N>||builtins.list*||sequence<T, N>|
All types that are more permissive than their ROS definition enforce the ROS constraints in range and length by software
Example of message definition using arrays and bounded types:
int32 unbounded_integer_array int32 five_integers_array int32[<=5] up_to_five_integers_array string string_of_unbounded_size string<=10 up_to_ten_characters_string string[<=5] up_to_five_unbounded_strings string<=10 unbounded_array_of_string_up_to_ten_characters each string<=10[<=5] up_to_five_strings_up_to_ten_characters_each
Field names must be lowercase alphanumeric characters with underscores for separating words. They must start with an alphabetic character, they must not end with an underscore and never have two consecutive underscores.
Default values can be set to any field in the message type. Currently default values are not supported for string arrays and complex types (i.e. types not present in the built-in-types table above, that applies to all nested messages)
Defining a default value is done by adding a third element to the field definition line, i.e:
fieldtype fieldname fielddefaultvalue
uint8 x 42 int16 y -2000 string full_name "John Doe" int32 samples [-200, -100, 0, 100, 200]
- string values must be defined in single
'or double quotes
- currently string values are not escaped
Each constant definition is like a field description with a default value, except that this value can never be changed programatically. This value assignment is indicated by use of an equal ‘=’ sign, e.g.
int32 X=123 int32 Y=-123 string FOO="foo" string EXAMPLE='bar'
Constants names have to be UPPERCASE
Services description are defined in
.srv files in the
srv/ directory of a ROS package.
A service description file consists of a request and a response msg type, separated by ‘—’. Any two .msg files concatenated together with a ‘—’ are a legal service description.
Here is a very simple example of a service that takes in a string and returns a string:
string str --- string str
We can of course get much more complicated (if you want to refer to a message from the same package you must not mention the package name):
#request constants int8 FOO=1 int8 BAR=2 #request fields int8 foobar another_pkg/AnotherMessage msg --- #response constants uint32 SECRET=123456 #response fields another_pkg/YetAnotherMessage val CustomMessageDefinedInThisPackage value uint32 an_integer
You cannot embed another service inside of a service.