/
116_legacy_interface_definition.md
321 lines (218 loc) · 11.4 KB
/
116_legacy_interface_definition.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
---
layout: default
title: Interface definition using .msg / .srv / .action files
permalink: articles/legacy_interface_definition.html
abstract:
This article specifies the file format coming from ROS 1 describing the data structures exchanged by ROS components to interact with each other.
published: true
author: '[Dirk Thomas](https://github.com/dirk-thomas)'
date_written: 2019-03
last_modified: 2021-02
categories: Interfaces
---
{:toc}
# {{ page.title }}
<div class="abstract" markdown="1">
{{ page.abstract }}
</div>
Authors: {{ page.author }}
Date Written: {{ page.date_written }}
Last Modified: {% if page.last_modified %}{{ page.last_modified }}{% else %}{{ page.date_written }}{% endif %}
## Scope
This article specifies the file format coming from ROS 1 describing the data structures which are being used to exchange information between components.
The data structures are defined in a programming language agnostic way.
The format is based on the [<code>.msg</code> format definition](http://wiki.ros.org/msg#Message_Description_Specification) from ROS 1.
Below only the mapping to IDL types is described.
Please see the [Interface Definition and Language Mapping](idl_interface_definition.html) article for the mappings to programming language specific types and API.
## Overview
A data structure is defined by a set of *fields*.
The order of the fields is irrelevant.
Each field is described by a *type* and a *name*.
### Messages
A single data structure is called *message*.
Each message has a *name*.
Together with the name of the *package* a message can be uniquely identified.
### Services
For request / reply style communication the two exchanged data structures are related.
These pairs of data structures are called *services*.
A service is identified by its *name* and the *package* it is in.
Each service describes two messages, one for the request data structure, one for the reply data structure.
### Actions
For longer running request / reply style communication with feedback about the progress the exchanged data structures are related.
These triplets of data structures are called *actions*.
An action is identified by its *name* and the *package* it is in.
Each action describes three messages, one for the goal data structure, one for the result data structure, and one for the feedback data structure.
### Field types
The type of a field can be either a primitive type or another data structure.
Each of these can optionally be a dynamically or statically sized array.
#### Primitive field types
The following primitive types are defined:
- `bool`
- `byte`
- `char`
- `float32`, `float64`
- `int8`, `uint8`
- `int16`, `uint16`
- `int32`, `uint32`
- `int64`, `uint64`
- `string`
<div class="alert alert-info" markdown="1">
While <code>byte</code> and <code>char</code> are deprecated in ROS 1 they are still part of this definition to ease migration.
</div>
<div class="alert alert-warning" markdown="1">
In ROS 1 <code>string</code> does not specify any encoding and the transport is agnostic to it.
This means commonly it can only contain ASCII.
For explicit support of wide character strings please consider migrating to [.idl files](http://design.ros2.org/articles/idl_interface_definition.html) which defines explicit types for that.
</div>
#### Non-primitive field types
Beside the primitive types other messages can be referenced to describe the type of a "complex" field.
A complex field type is identified by a package and a message name.
#### Arrays with static size
A static array has exactly `N` elements of the specified type.
`N` must be greater than `0`.
#### Arrays with dynamic size
A dynamic array can have between `0` and `N` elements of the specified type.
`N` might not have an upper bound and may only be limited by the memory or other system specific limitations.
#### Upper boundaries
<div class="alert alert-info" markdown="1">
This feature is not available in ROS 1.
</div>
The size of *strings* as well as *dynamic arrays* can be limited with an *upper boundary*.
This enables the preallocation of memory for data structures which use dynamically sized data.
### Default values
<div class="alert alert-info" markdown="1">
This feature is not available in ROS 1.
</div>
A field can optionally specify a default value.
If no default value is specified a common default value is used:
- for `bool` it is `false`
- for *numeric* types it is a `0` value
- for `string` it is an *empty* string
- for *static size arrays* it is an array of N elements with its fields zero-initialized
- for *bounded size arrays* and *dynamic size arrays* it is an empty array `[]`
#### Array default values
A field of type `array` can optionally specify a default value.
- default values for an array must start with an opening square bracket (`[`) and end with a closing square bracket (`]`)
- each value within the array must be separated with a comma (`,`)
- all values in the array must be of the same type as the field
- there cannot be a comma `,` before the first value of the array
- a trailing comma after the last element of the array is ignored
Additional rule for `string` arrays:
- string arrays must contain only `string`s respecting the following rules:
- a string value which can optionally be quoted with either single quotes (`'`) or double quotes (`"`)
- a double-quoted (`"`) string (respectively single-quoted (`'`)) should have any inner double quotes (respectively single quotes) escaped
<div class="alert alert-warning" markdown="1">
<b>TODO:</b> default values are currently not supported for <i>complex</i> fields
</div>
### Constants
Constants are defined by a *primitive type*, a *name*, and a *fixed value*.
If the *primitive type* is an integer type, the *fixed value* can be specified in one of the following ways:
- a decimal integer, e.g. 1
- a binary integer, e.g. 0b01 or 0B01
- an octal integer, e.g. 0o01 or 0O01
- a hexadecimal integer, e.g. 0x01 or 0X01
## Conventions
### Naming of messages and services
Each file contains a single message or service.
Message files use the extension `.msg`, service files use the extension `.srv`.
Both file names must use an upper camel case name and only consist of alphanumeric characters.
### Naming of fields
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.
### Naming of constants
Constant names must be uppercase 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.
## Syntax
The message and service definitions are text files.
### Comments
The character `#` starts a comment, which terminates at the end of the line on which it occurs.
### Message file format
A line can either contain a field definition or a constant definition.
While a single space is mandatory to separate tokens additional spaces can be inserted optionally between tokens.
#### Field definition
A field definition has the following structure:
<type> <name> <optional_default_value>
#### Constant definition
A constant definition has the following structure:
<type> <name>=<value>
#### Types
A `<type>` is defined by its *base type* and optional *array specifier*.
The *base type* can be one of the following:
- a primitive type from the list above: e.g. `int32`
- a string with an upper boundary: `string<=N` to limit the length of the string to `N` characters
- a complex type referencing another message:
- an *absolute* reference of a message: e.g. `some_package/SomeMessage`
- a *relative* reference of a message within the same package: e.g. `OtherMessage`
The *array specifier* can be one of the following:
- a static array is described by the suffix `[N]` where `N` is the fixed size of the array
- an unbounded dynamic array is described by the suffix `[]`
- a bounded dynamic array is described by the suffix `[<=N]` where `N` is the maximum size of the array
#### Values
Depending on the type the following values are valid:
- `bool`:
- `true`, `1`
- `false`, `0`
- `byte`:
- an opaque 8-bit quantity with a numerical value in the following interval `[0, 255]`
- `char`:
- an unsigned integer value in the following interval `[0, 255]`
- `float32` and `float64`:
- a decimal number using a dot (`.`) as the separator between the integer-part and fractional-part.
- `int8`, `int16`, `int32` and `int64`:
- an integer value in the following interval `[- 2 ^ (N - 1), 2 ^ (N - 1) - 1]` where `N` is the number of bits behind `int`
- `uint8`, `uint16`, `uint32` and `uint64`:
- an unsigned integer value in the following interval `[0, 2 ^ N - 1]` where `N` is the number of bits behind `uint`
- `string`:
- a string value which can optionally be quoted with either single quotes (`'`) or double quotes (`"`)
- a double-quoted (`"`) string (respectively single-quoted (`'`)) should have any inner double quotes (respectively single quotes) escaped:
- `string my_string "I heard \"Hello\""` is valid
- `string my_string "I heard "Hello""` is **not** valid
- `string my_string "I heard 'Hello'"` is valid
- `string my_string 'I heard \'Hello\''` is valid
- `string my_string 'I heard 'Hello''` is **not** valid
- `string my_string 'I heard "Hello"'` is valid
### Service file format
A service file contains two message definitions which are separated by a line which only contains three dashes:
---
## Conversion to IDL
Code is generated for defined interfaces to be usable by different client libraries.
Interfaces described using the above format are first converted to [IDL](idl_interface_definition.html).
Code generation uses the generated file.
<div class="alert alert-info" markdown="1">
A structure defined in the above format can be empty / contain no members.
In that case the generated `.idl` structure will have a dummy member
(`uint8 structure_needs_at_least_one_member`) to satisfy the requirement from
IDL of not being empty.
</div>
### Mapping to IDL types
| ROS type | IDL type |
| -------- | ------------------ |
| bool | boolean |
| byte | octet |
| char | uint8 |
| float32 | float |
| float64 | double |
| int8 | int8 |
| uint8 | uint8 |
| int16 | short |
| uint16 | unsigned short |
| int32 | long |
| uint32 | unsigned long |
| int64 | long long |
| uint64 | unsigned long long |
| string | string |
<div class="alert alert-info" markdown="1">
The mapping of <code>byte</code> uses a different type than in ROS 1 while still remaining an opaque 8-bit quantity.
[Definition in ROS 1](http://wiki.ros.org/msg#Field_Types): deprecated alias for <code>int8</code>.
Definition in IDL (7.4.1.4.4.2.6): an opaque 8-bit quantity.
</div>
<div class="alert alert-info" markdown="1">
While the mapping of <code>char</code> is unintuitive it preserves compatibility with the [definition in ROS 1](http://wiki.ros.org/msg#Field_Types):
"deprecated alias for <code>uint8</code>".
</div>
| ROS type | IDL type |
| ----------------------- | ---------------- |
| static array | array |
| unbounded dynamic array | sequence |
| bounded dynamic array | bounded sequence |
| bounded string | bounded string |