new package and interfaces for describing other types

type_description_interfaces/CMakeLists.txt

@@ -0,0 +1,33 @@
+cmake_minimum_required(VERSION 3.5)
+
+project(type_description_interfaces)
+
+# Default to C++14
+if(NOT CMAKE_CXX_STANDARD)
+  set(CMAKE_CXX_STANDARD 14)
+endif()
+if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+  add_compile_options(-Wall -Wextra -Wpedantic)
+endif()
+
+find_package(ament_cmake REQUIRED)
+# Depend on "core" generators instead of "default" generators
+# because other generators depend on this.
+find_package(rosidl_core_generators REQUIRED)
+
+rosidl_generate_interfaces(${PROJECT_NAME}
+  "msg/Field.msg"
+  "msg/FieldType.msg"
+  "msg/IndividualTypeDescription.msg"
+  "msg/TypeDescription.msg"
+  ADD_LINTER_TESTS
+)
+
+if(BUILD_TESTING)
+  find_package(ament_lint_auto REQUIRED)
+  ament_lint_auto_find_test_dependencies()
+endif()
+
+ament_export_dependencies(rosidl_core_runtime)
+
+ament_package()

type_description_interfaces/QUALITY_DECLARATION.md

@@ -0,0 +1,112 @@
+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).
+
+# `type_description_interfaces` Quality Declaration
+
+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.
+
+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).
+
+## Version Policy [1]
+
+### Version Scheme [1.i]
+
+`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).
+
+### Version Stability [1.ii]
+
+`type_description_interfaces` is at a stable version, i.e. `>= 1.0.0`.
+Its version can be found in its [package.xml](package.xml) and its change history can be found in its [CHANGELOG](CHANGELOG.rst).
+
+### Public API Declaration [1.iii]
+
+All message and service definition files located in `msg` and `srv` directories are considered part of the public API.
+
+### API Stability Within a Released ROS Distribution [1.iv]/[1.vi]
+
+`type_description_interfaces` will not break public API within a released ROS distribution, i.e. no major releases once the ROS distribution is released.
+
+### ABI Stability Within a Released ROS Distribution [1.v]/[1.vi]
+
+`type_description_interfaces` does not contain any C or C++ code and therefore will not affect ABI stability.
+
+## Change Control Process [2]
+
+`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).
+
+### Change Requests [2.i]
+
+This package requires that all changes occur through a pull request.
+
+### Contributor Origin [2.ii]
+
+This package uses DCO as its confirmation of contributor origin policy. More information can be found in [CONTRIBUTING](../CONTRIBUTING.md).
+
+### Peer Review Policy [2.iii]
+
+Following the recommended guidelines for ROS Core packages, all pull requests must have at least 1 peer review.
+
+### Continuous Integration [2.iv]
+
+All pull request must pass CI on all [tier 1 platforms](https://www.ros.org/reps/rep-2000.html#support-tiers)
+
+### Documentation Policy [2.v]
+
+All pull requests must resolve related documentation changes before merging.
+
+## Documentation
+
+### Feature Documentation [3.i]
+
+`type_description_interfaces` has a list of provided [messages and services](README.md).
+New messages and services require their own documentation in order to be added.
+
+### Public API Documentation [3.ii]
+
+`type_description_interfaces` has embedded API documentation, but it is not currently hosted.
+
+### License [3.iii]
+
+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.
+
+There is an automated test which runs a linter that ensures each file has a license statement.
+
+The nightly test can be found at [here](http://build.ros2.org/view/Rpr/job/Rpr__rcl_interfaces__ubuntu_focal_amd64/lastCompletedBuild/testReport)
+
+### Copyright Statements [3.iv]
+
+The copyright holders each provide a statement of copyright in each source code file in `type_description_interfaces`.
+
+There is an automated test which runs a linter that ensures each file has at least one copyright statement.
+
+The nightly test can be found at [here](http://build.ros2.org/view/Rpr/job/Rpr__rcl_interfaces__ubuntu_focal_amd64/lastCompletedBuild/testReport)
+
+## Testing [4]
+
+`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.
+
+## Dependencies [5]
+
+### Direct Runtime ROS Dependencies [5.i]/[5.ii]
+
+`type_description_interfaces` has the following ROS dependencies, which are at **Quality Level 1**:
+* `rosidl_core_runtime`: [QUALITY DECLARATION](https://github.com/ros2/rosidl_core/tree/master/rosidl_core_runtime/QUALITY_DECLARATION.md)
+
+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.
+
+### Direct Runtime Non-ROS Dependencies [5.iii]
+
+`type_description_interfaces` does not have any runtime non-ROS dependencies.
+
+## Platform Support [6]
+
+`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.
+
+Currently nightly results can be seen here:
+* [linux-aarch64_release](https://ci.ros2.org/view/nightly/job/nightly_linux-aarch64_release/lastBuild/testReport/builtin_interfaces/)
+* [linux_release](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/builtin_interfaces/)
+* [mac_osx_release](https://ci.ros2.org/view/nightly/job/nightly_osx_release/lastBuild/testReport/builtin_interfaces/)
+* [windows_release](https://ci.ros2.org/view/nightly/job/nightly_win_rel/lastBuild/testReport/builtin_interfaces/)
+
+## Vulnerability Disclosure Policy [7.i]
+
+This package conforms to the Vulnerability Disclosure Policy in [REP-2006](https://www.ros.org/reps/rep-2006.html).

type_description_interfaces/README.md

@@ -0,0 +1,21 @@
+# type_description_interfaces
+
+A package containing message and service definitions for describing and communicating descriptions of other types.
+
+## Messages (.msg)
+
+* [Field](msg/Field.msg): Represents a single field in a ROS Interface Type
+* [FieldType](msg/FieldType.msg): Represents the type of a single field in a ROS Interface Type
+* [IndividualTypeDescription](msg/IndividualTypeDescription.msg): Represents a single ROS Message Type by itself
+* [TypeDescription](msg/TypeDescription.msg): Represents a single ROS Message Type along with all referenced types
+
+## Quality Declaration
+
+See the [Quality Declaration](QUALITY_DECLARATION.md) for more details.
+
+## TODO
+
+* Should we pick limits (bounds) for strings in these types, e.g. type names, default values, etc?
+* Should we pick limits (bounds) for sequences in these types, e.g. number of referenced types?
+* Consider how to support constants and annotations (currently excluded) and potentially enums in the future.
+* Consider using padding in `IndividualTypeDescription.msg` to support back porting efforts.

type_description_interfaces/msg/Field.msg

@@ -0,0 +1,9 @@
+# Represents a single field in a type.
+
+# Name of the field.
+string name
+# Type of the field, including details about the type like length, nested name, etc.
+FieldType type
+# Literal default value of the field as a string, as it appeared in the original
+# message description file, whether that be .msg/.srv/.action or .idl.
+string default_value

type_description_interfaces/msg/FieldType.msg

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

type_description_interfaces/msg/IndividualTypeDescription.msg

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

type_description_interfaces/msg/TypeDescription.msg

@@ -0,0 +1,6 @@
+# Represents a complete type description, including the type itself as well as the types it references.
+
+# Description of the type.
+IndividualTypeDescription type_description
+# Descriptions of all referenced types, recursively.
+IndividualTypeDescription[] referenced_type_descriptions

type_description_interfaces/package.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0"?>
+<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
+<package format="3">
+  <name>type_description_interfaces</name>
+  <version>1.3.1</version>
+  <description>A package containing message and service definitions for describing and communicating descriptions of other types.</description>
+
+  <maintainer email="william@openrobotics.org">William Woodall</maintainer>
+
+  <license>Apache License 2.0</license>
+
+  <buildtool_depend>ament_cmake</buildtool_depend>
+
+  <buildtool_depend>rosidl_core_generators</buildtool_depend>
+
+  <exec_depend>rosidl_core_runtime</exec_depend>
+
+  <test_depend>ament_lint_auto</test_depend>
+  <test_depend>ament_lint_common</test_depend>
+
+  <member_of_group>rosidl_interface_packages</member_of_group>
+
+  <export>
+    <build_type>ament_cmake</build_type>
+  </export>
+</package>