Skip to content

Commit 18d891a

Browse files
wjwwoodwjwwood
authored
new package and interfaces for describing other types (#146)
* type_description_interfaces package Signed-off-by: William Woodall <[email protected]> Signed-off-by: Chris Lalancette <[email protected]>
1 parent 0aa8922 commit 18d891a

File tree

8 files changed

+374
-0
lines changed

8 files changed

+374
-0
lines changed

‎type_description_interfaces/CMakeLists.txt‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
cmake_minimum_required(VERSION 3.5)
2+
3+
project(type_description_interfaces)
4+
5+
# Default to C++14
6+
if(NOT CMAKE_CXX_STANDARD)
7+
set(CMAKE_CXX_STANDARD 14)
8+
endif()
9+
if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
10+
add_compile_options(-Wall -Wextra -Wpedantic)
11+
endif()
12+
13+
find_package(ament_cmake REQUIRED)
14+
# Depend on "core" generators instead of "default" generators
15+
# because other generators depend on this.
16+
find_package(rosidl_core_generators REQUIRED)
17+
18+
rosidl_generate_interfaces(${PROJECT_NAME}
19+
"msg/Field.msg"
20+
"msg/FieldType.msg"
21+
"msg/IndividualTypeDescription.msg"
22+
"msg/TypeDescription.msg"
23+
ADD_LINTER_TESTS
24+
)
25+
26+
if(BUILD_TESTING)
27+
find_package(ament_lint_auto REQUIRED)
28+
ament_lint_auto_find_test_dependencies()
29+
endif()
30+
31+
ament_export_dependencies(rosidl_core_runtime)
32+
33+
ament_package()

‎type_description_interfaces/QUALITY_DECLARATION.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
This document is a declaration of software quality for the `type_description_interfaces` package, based on the guidelines in [REP-2004](https://www.ros.org/reps/rep-2004.html).
2+
3+
# `type_description_interfaces` Quality Declaration
4+
5+
The package `type_description_interfaces` claims to be in the **Quality Level 1** category as long as it is used with a **Quality Level 1** middleware.
6+
7+
Below are the rationales, notes, and caveats for this claim, organized by each requirement listed in the [Package Requirements for Quality Level 1 in REP-2004](https://www.ros.org/reps/rep-2004.html).
8+
9+
## Version Policy [1]
10+
11+
### Version Scheme [1.i]
12+
13+
`type_description_interfaces` uses `semver` according to the recommendation for ROS Core packages in the [ROS 2 Developer Guide](https://docs.ros.org/en/rolling/Contributing/Developer-Guide.html#versioning).
14+
15+
### Version Stability [1.ii]
16+
17+
`type_description_interfaces` is at a stable version, i.e. `>= 1.0.0`.
18+
Its version can be found in its [package.xml](package.xml) and its change history can be found in its [CHANGELOG](CHANGELOG.rst).
19+
20+
### Public API Declaration [1.iii]
21+
22+
All message and service definition files located in `msg` and `srv` directories are considered part of the public API.
23+
24+
### API Stability Within a Released ROS Distribution [1.iv]/[1.vi]
25+
26+
`type_description_interfaces` will not break public API within a released ROS distribution, i.e. no major releases once the ROS distribution is released.
27+
28+
### ABI Stability Within a Released ROS Distribution [1.v]/[1.vi]
29+
30+
`type_description_interfaces` does not contain any C or C++ code and therefore will not affect ABI stability.
31+
32+
## Change Control Process [2]
33+
34+
`type_description_interfaces` follows the recommended guidelines for ROS Core packages in the [ROS 2 Developer Guide](https://docs.ros.org/en/rolling/Contributing/Developer-Guide.html#quality-practices).
35+
36+
### Change Requests [2.i]
37+
38+
This package requires that all changes occur through a pull request.
39+
40+
### Contributor Origin [2.ii]
41+
42+
This package uses DCO as its confirmation of contributor origin policy. More information can be found in [CONTRIBUTING](../CONTRIBUTING.md).
43+
44+
### Peer Review Policy [2.iii]
45+
46+
Following the recommended guidelines for ROS Core packages, all pull requests must have at least 1 peer review.
47+
48+
### Continuous Integration [2.iv]
49+
50+
All pull request must pass CI on all [tier 1 platforms](https://www.ros.org/reps/rep-2000.html#support-tiers)
51+
52+
### Documentation Policy [2.v]
53+
54+
All pull requests must resolve related documentation changes before merging.
55+
56+
## Documentation
57+
58+
### Feature Documentation [3.i]
59+
60+
`type_description_interfaces` has a list of provided [messages and services](README.md).
61+
New messages and services require their own documentation in order to be added.
62+
63+
### Public API Documentation [3.ii]
64+
65+
`type_description_interfaces` has embedded API documentation, but it is not currently hosted.
66+
67+
### License [3.iii]
68+
69+
The license for `type_description_interfaces` is Apache 2.0, the type is declared in the [package.xml](package.xml) manifest file, and a full copy of the license is in the repository level [LICENSE](../LICENSE) file.
70+
71+
There is an automated test which runs a linter that ensures each file has a license statement.
72+
73+
The nightly test can be found at [here](http://build.ros2.org/view/Rpr/job/Rpr__rcl_interfaces__ubuntu_focal_amd64/lastCompletedBuild/testReport)
74+
75+
### Copyright Statements [3.iv]
76+
77+
The copyright holders each provide a statement of copyright in each source code file in `type_description_interfaces`.
78+
79+
There is an automated test which runs a linter that ensures each file has at least one copyright statement.
80+
81+
The nightly test can be found at [here](http://build.ros2.org/view/Rpr/job/Rpr__rcl_interfaces__ubuntu_focal_amd64/lastCompletedBuild/testReport)
82+
83+
## Testing [4]
84+
85+
`type_description_interfaces` is a package providing strictly message and service definitions and therefore does not require associated tests and has no coverage or performance requirements.
86+
87+
## Dependencies [5]
88+
89+
### Direct Runtime ROS Dependencies [5.i]/[5.ii]
90+
91+
`type_description_interfaces` has the following ROS dependencies, which are at **Quality Level 1**:
92+
* `rosidl_core_runtime`: [QUALITY DECLARATION](https://github.com/ros2/rosidl_core/tree/master/rosidl_core_runtime/QUALITY_DECLARATION.md)
93+
94+
It has several "buildtool" dependencies, which do not affect the resulting quality of the package, because they do not contribute to the public library API.
95+
96+
### Direct Runtime Non-ROS Dependencies [5.iii]
97+
98+
`type_description_interfaces` does not have any runtime non-ROS dependencies.
99+
100+
## Platform Support [6]
101+
102+
`type_description_interfaces` supports all of the tier 1 platforms as described in [REP-2000](https://www.ros.org/reps/rep-2000.html#support-tiers), and tests each change against all of them.
103+
104+
Currently nightly results can be seen here:
105+
* [linux-aarch64_release](https://ci.ros2.org/view/nightly/job/nightly_linux-aarch64_release/lastBuild/testReport/builtin_interfaces/)
106+
* [linux_release](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/builtin_interfaces/)
107+
* [mac_osx_release](https://ci.ros2.org/view/nightly/job/nightly_osx_release/lastBuild/testReport/builtin_interfaces/)
108+
* [windows_release](https://ci.ros2.org/view/nightly/job/nightly_win_rel/lastBuild/testReport/builtin_interfaces/)
109+
110+
## Vulnerability Disclosure Policy [7.i]
111+
112+
This package conforms to the Vulnerability Disclosure Policy in [REP-2006](https://www.ros.org/reps/rep-2006.html).

‎type_description_interfaces/README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# type_description_interfaces
2+
3+
A package containing message and service definitions for describing and communicating descriptions of other types.
4+
5+
## Messages (.msg)
6+
7+
* [Field](msg/Field.msg): Represents a single field in a ROS Interface Type
8+
* [FieldType](msg/FieldType.msg): Represents the type of a single field in a ROS Interface Type
9+
* [IndividualTypeDescription](msg/IndividualTypeDescription.msg): Represents a single ROS Message Type by itself
10+
* [TypeDescription](msg/TypeDescription.msg): Represents a single ROS Message Type along with all referenced types
11+
12+
## Quality Declaration
13+
14+
See the [Quality Declaration](QUALITY_DECLARATION.md) for more details.
15+
16+
## TODO
17+
18+
* Should we pick limits (bounds) for strings in these types, e.g. type names, default values, etc?
19+
* Should we pick limits (bounds) for sequences in these types, e.g. number of referenced types?
20+
* Consider how to support constants and annotations (currently excluded) and potentially enums in the future.
21+
* Consider using padding in `IndividualTypeDescription.msg` to support back porting efforts.

‎type_description_interfaces/msg/Field.msg‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Represents a single field in a type.
2+
3+
# Name of the field.
4+
string name
5+
# Type of the field, including details about the type like length, nested name, etc.
6+
FieldType type
7+
# Literal default value of the field as a string, as it appeared in the original
8+
# message description file, whether that be .msg/.srv/.action or .idl.
9+
string default_value

‎type_description_interfaces/msg/FieldType.msg‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Represents the type of a field and related meta-data.
2+
3+
# A constant for each type supported according to:
4+
# http://design.ros2.org/articles/legacy_interface_definition.html
5+
# and:
6+
# http://design.ros2.org/articles/idl_interface_definition.html
7+
# Order is loosely coupled to the order of appearance in the IDL 4.2 spec:
8+
# https://www.omg.org/spec/IDL/4.2
9+
10+
# Layout of constants across the 0-255 decimal values in the uint8:
11+
#
12+
# - 000 : Reserved for "not set"
13+
# - 001-048: Primitive types, strings, and reserved space for future primitive types
14+
# - 049-096: Fixed sized array of primitive and string types
15+
# - 097-144: Bounded Sequences of primitive and string types
16+
# - 145-192: Unbounded Sequences of primitive and string types
17+
# - 193-255: Reserved space for future array/sequence-like types
18+
19+
uint8 FIELD_TYPE_NOT_SET = 0
20+
21+
# Nested type defined in other .msg/.idl files.
22+
uint8 FIELD_TYPE_NESTED_TYPE = 1
23+
24+
# Integer Types
25+
uint8 FIELD_TYPE_INT8 = 2
26+
uint8 FIELD_TYPE_UINT8 = 3
27+
uint8 FIELD_TYPE_INT16 = 4
28+
uint8 FIELD_TYPE_UINT16 = 5
29+
uint8 FIELD_TYPE_INT32 = 6
30+
uint8 FIELD_TYPE_UINT32 = 7
31+
uint8 FIELD_TYPE_INT64 = 8
32+
uint8 FIELD_TYPE_UINT64 = 9
33+
34+
# Floating-Point Types
35+
uint8 FIELD_TYPE_FLOAT = 10
36+
uint8 FIELD_TYPE_DOUBLE = 11
37+
uint8 FIELD_TYPE_LONG_DOUBLE = 12
38+
39+
# Char and WChar Types
40+
uint8 FIELD_TYPE_CHAR = 13
41+
uint8 FIELD_TYPE_WCHAR = 14
42+
43+
# Boolean Type
44+
uint8 FIELD_TYPE_BOOLEAN = 15
45+
46+
# Byte/Octet Type
47+
uint8 FIELD_TYPE_BYTE = 16
48+
49+
# String Types
50+
uint8 FIELD_TYPE_STRING = 17
51+
uint8 FIELD_TYPE_WSTRING = 18
52+
53+
# Fixed String Types
54+
uint8 FIELD_TYPE_FIXED_STRING = 19
55+
uint8 FIELD_TYPE_FIXED_WSTRING = 20
56+
57+
# Bounded String Types
58+
uint8 FIELD_TYPE_BOUNDED_STRING = 21
59+
uint8 FIELD_TYPE_BOUNDED_WSTRING = 22
60+
61+
# Fixed Sized Array Types
62+
uint8 FIELD_TYPE_NESTED_TYPE_ARRAY = 49
63+
uint8 FIELD_TYPE_INT8_ARRAY = 50
64+
uint8 FIELD_TYPE_UINT8_ARRAY = 51
65+
uint8 FIELD_TYPE_INT16_ARRAY = 52
66+
uint8 FIELD_TYPE_UINT16_ARRAY = 53
67+
uint8 FIELD_TYPE_INT32_ARRAY = 54
68+
uint8 FIELD_TYPE_UINT32_ARRAY = 55
69+
uint8 FIELD_TYPE_INT64_ARRAY = 56
70+
uint8 FIELD_TYPE_UINT64_ARRAY = 57
71+
uint8 FIELD_TYPE_FLOAT_ARRAY = 58
72+
uint8 FIELD_TYPE_DOUBLE_ARRAY = 59
73+
uint8 FIELD_TYPE_LONG_DOUBLE_ARRAY = 60
74+
uint8 FIELD_TYPE_CHAR_ARRAY = 61
75+
uint8 FIELD_TYPE_WCHAR_ARRAY = 62
76+
uint8 FIELD_TYPE_BOOLEAN_ARRAY = 63
77+
uint8 FIELD_TYPE_BYTE_ARRAY = 64
78+
uint8 FIELD_TYPE_STRING_ARRAY = 65
79+
uint8 FIELD_TYPE_WSTRING_ARRAY = 66
80+
uint8 FIELD_TYPE_FIXED_STRING_ARRAY = 67
81+
uint8 FIELD_TYPE_FIXED_WSTRING_ARRAY = 68
82+
uint8 FIELD_TYPE_BOUNDED_STRING_ARRAY = 69
83+
uint8 FIELD_TYPE_BOUNDED_WSTRING_ARRAY = 70
84+
85+
# Bounded Sequence Types
86+
uint8 FIELD_TYPE_NESTED_TYPE_BOUNDED_SEQUENCE = 97
87+
uint8 FIELD_TYPE_INT8_BOUNDED_SEQUENCE = 98
88+
uint8 FIELD_TYPE_UINT8_BOUNDED_SEQUENCE = 99
89+
uint8 FIELD_TYPE_INT16_BOUNDED_SEQUENCE = 100
90+
uint8 FIELD_TYPE_UINT16_BOUNDED_SEQUENCE = 101
91+
uint8 FIELD_TYPE_INT32_BOUNDED_SEQUENCE = 102
92+
uint8 FIELD_TYPE_UINT32_BOUNDED_SEQUENCE = 103
93+
uint8 FIELD_TYPE_INT64_BOUNDED_SEQUENCE = 104
94+
uint8 FIELD_TYPE_UINT64_BOUNDED_SEQUENCE = 105
95+
uint8 FIELD_TYPE_FLOAT_BOUNDED_SEQUENCE = 106
96+
uint8 FIELD_TYPE_DOUBLE_BOUNDED_SEQUENCE = 107
97+
uint8 FIELD_TYPE_LONG_DOUBLE_BOUNDED_SEQUENCE = 108
98+
uint8 FIELD_TYPE_CHAR_BOUNDED_SEQUENCE = 109
99+
uint8 FIELD_TYPE_WCHAR_BOUNDED_SEQUENCE = 110
100+
uint8 FIELD_TYPE_BOOLEAN_BOUNDED_SEQUENCE = 111
101+
uint8 FIELD_TYPE_BYTE_BOUNDED_SEQUENCE = 112
102+
uint8 FIELD_TYPE_STRING_BOUNDED_SEQUENCE = 113
103+
uint8 FIELD_TYPE_WSTRING_BOUNDED_SEQUENCE = 114
104+
uint8 FIELD_TYPE_FIXED_STRING_BOUNDED_SEQUENCE = 115
105+
uint8 FIELD_TYPE_FIXED_WSTRING_BOUNDED_SEQUENCE = 116
106+
uint8 FIELD_TYPE_BOUNDED_STRING_BOUNDED_SEQUENCE = 117
107+
uint8 FIELD_TYPE_BOUNDED_WSTRING_BOUNDED_SEQUENCE = 118
108+
109+
# Unbounded Sequence Types
110+
uint8 FIELD_TYPE_NESTED_TYPE_UNBOUNDED_SEQUENCE = 145
111+
uint8 FIELD_TYPE_INT8_UNBOUNDED_SEQUENCE = 146
112+
uint8 FIELD_TYPE_UINT8_UNBOUNDED_SEQUENCE = 147
113+
uint8 FIELD_TYPE_INT16_UNBOUNDED_SEQUENCE = 148
114+
uint8 FIELD_TYPE_UINT16_UNBOUNDED_SEQUENCE = 149
115+
uint8 FIELD_TYPE_INT32_UNBOUNDED_SEQUENCE = 150
116+
uint8 FIELD_TYPE_UINT32_UNBOUNDED_SEQUENCE = 151
117+
uint8 FIELD_TYPE_INT64_UNBOUNDED_SEQUENCE = 152
118+
uint8 FIELD_TYPE_UINT64_UNBOUNDED_SEQUENCE = 153
119+
uint8 FIELD_TYPE_FLOAT_UNBOUNDED_SEQUENCE = 154
120+
uint8 FIELD_TYPE_DOUBLE_UNBOUNDED_SEQUENCE = 155
121+
uint8 FIELD_TYPE_LONG_DOUBLE_UNBOUNDED_SEQUENCE = 156
122+
uint8 FIELD_TYPE_CHAR_UNBOUNDED_SEQUENCE = 157
123+
uint8 FIELD_TYPE_WCHAR_UNBOUNDED_SEQUENCE = 158
124+
uint8 FIELD_TYPE_BOOLEAN_UNBOUNDED_SEQUENCE = 159
125+
uint8 FIELD_TYPE_BYTE_UNBOUNDED_SEQUENCE = 160
126+
uint8 FIELD_TYPE_STRING_UNBOUNDED_SEQUENCE = 161
127+
uint8 FIELD_TYPE_WSTRING_UNBOUNDED_SEQUENCE = 162
128+
uint8 FIELD_TYPE_FIXED_STRING_UNBOUNDED_SEQUENCE = 163
129+
uint8 FIELD_TYPE_FIXED_WSTRING_UNBOUNDED_SEQUENCE = 164
130+
uint8 FIELD_TYPE_BOUNDED_STRING_UNBOUNDED_SEQUENCE = 165
131+
uint8 FIELD_TYPE_BOUNDED_WSTRING_UNBOUNDED_SEQUENCE = 166
132+
133+
# Identifying number for the type of the field, using one of the above constants.
134+
uint8 type_id 0
135+
136+
# Only used when the type is an array or a bounded sequence.
137+
# In the case of an array, this is the fixed capacity of the array.
138+
# In the case of a bounded sequence, this is the maximum capacity of the sequence.
139+
# In all other cases this field is unused.
140+
uint64 capacity
141+
142+
# Only used when the type is a fixed or bounded string/wstring, or a array/sequence of those.
143+
# In the case of a fixed string/wstring, it is the fixed length of the string.
144+
# In the case of a bounded string/wstring, it is the maximum capacity of the string.
145+
# In the case of an array/sequence of fixed string/wstring, it is the fixed length of the strings.
146+
# In the case of an array/sequence of bounded string/wstring, it is the maximum capacity of the strings.
147+
# It is not currently possible to have different string capacities per element in the array/sequence.
148+
uint64 string_capacity
149+
150+
# Only used when the type is a nested type or array/sequence of nested types.
151+
# This is limited to 255 characters.
152+
# TODO(wjwwood): this 255 character limit was chosen due to this being the limit
153+
# for DDSI-RTPS based middlewares, which is the most commonly used right now.
154+
# We lack a ROS 2 specific limit in our design documents, but we should update
155+
# this and/or link to the design doc when that is available.
156+
string<=255 nested_type_name

‎type_description_interfaces/msg/IndividualTypeDescription.msg‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Represents a single type, without the types it references, if any.
2+
3+
# Name of the type.
4+
# This is limited to 255 characters.
5+
# TODO(wjwwood): this 255 character limit was chosen due to this being the limit
6+
# for DDSI-RTPS based middlewares, which is the most commonly used right now.
7+
# We lack a ROS 2 specific limit in our design documents, but we should update
8+
# this and/or link to the design doc when that is available.
9+
string<=255 type_name
10+
# Fields of the type.
11+
Field[] fields

‎type_description_interfaces/msg/TypeDescription.msg‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Represents a complete type description, including the type itself as well as the types it references.
2+
3+
# Description of the type.
4+
IndividualTypeDescription type_description
5+
# Descriptions of all referenced types, recursively.
6+
IndividualTypeDescription[] referenced_type_descriptions

‎type_description_interfaces/package.xml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
<?xml version="1.0"?>
2+
<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
3+
<package format="3">
4+
<name>type_description_interfaces</name>
5+
<version>1.3.1</version>
6+
<description>A package containing message and service definitions for describing and communicating descriptions of other types.</description>
7+
8+
<maintainer email="[email protected]">William Woodall</maintainer>
9+
10+
<license>Apache License 2.0</license>
11+
12+
<buildtool_depend>ament_cmake</buildtool_depend>
13+
14+
<buildtool_depend>rosidl_core_generators</buildtool_depend>
15+
16+
<exec_depend>rosidl_core_runtime</exec_depend>
17+
18+
<test_depend>ament_lint_auto</test_depend>
19+
<test_depend>ament_lint_common</test_depend>
20+
21+
<member_of_group>rosidl_interface_packages</member_of_group>
22+
23+
<export>
24+
<build_type>ament_cmake</build_type>
25+
</export>
26+
</package>

0 commit comments

Comments
 (0)