diff --git a/type_description_interfaces/CMakeLists.txt b/type_description_interfaces/CMakeLists.txt new file mode 100644 index 00000000..e860c778 --- /dev/null +++ b/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() diff --git a/type_description_interfaces/QUALITY_DECLARATION.md b/type_description_interfaces/QUALITY_DECLARATION.md new file mode 100644 index 00000000..c89ce403 --- /dev/null +++ b/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). diff --git a/type_description_interfaces/README.md b/type_description_interfaces/README.md new file mode 100644 index 00000000..d7b4731a --- /dev/null +++ b/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. diff --git a/type_description_interfaces/msg/Field.msg b/type_description_interfaces/msg/Field.msg new file mode 100644 index 00000000..c3881bf8 --- /dev/null +++ b/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 diff --git a/type_description_interfaces/msg/FieldType.msg b/type_description_interfaces/msg/FieldType.msg new file mode 100644 index 00000000..4952066c --- /dev/null +++ b/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 diff --git a/type_description_interfaces/msg/IndividualTypeDescription.msg b/type_description_interfaces/msg/IndividualTypeDescription.msg new file mode 100644 index 00000000..1adb0ebb --- /dev/null +++ b/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 diff --git a/type_description_interfaces/msg/TypeDescription.msg b/type_description_interfaces/msg/TypeDescription.msg new file mode 100644 index 00000000..5d35f4ea --- /dev/null +++ b/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 diff --git a/type_description_interfaces/package.xml b/type_description_interfaces/package.xml new file mode 100644 index 00000000..dd3fe970 --- /dev/null +++ b/type_description_interfaces/package.xml @@ -0,0 +1,26 @@ + + + + type_description_interfaces + 1.3.1 + A package containing message and service definitions for describing and communicating descriptions of other types. + + William Woodall + + Apache License 2.0 + + ament_cmake + + rosidl_core_generators + + rosidl_core_runtime + + ament_lint_auto + ament_lint_common + + rosidl_interface_packages + + + ament_cmake + +