ROS2 Message Layout¶
The Capella ROS Tools API expects ROS2 messages to be organized in a specific way:
Package Definition¶
A package is a directory containing a msg directory.
The msg directory contains .msg files which contain class and enum definitions.
folders
├── package1
│ └── msg
│ ├── class1.msg
│ └── types
│ └── enum1.msg
└── package2
└── msg
└── class2.msg
The above folder structure would translate to the following package definition (assuming class1.msg, class2.msg contain class definitions and enum1.msg contains an enum definition):
packages
├── Package: package1
│ ├── Class: class1
│ └── Enum: enum1
└── Package: package2
└── Class: class3
Class Definition¶
A .msg file can contain one class definition.
The comment at the top of the file followed by an empty line is added to the class description.
Inline Comments: Comments on the same line as a property definition are directly added to that property’s description.
Indented Comment Lines: Comments on a line of their own but indented are added to the description of the last encountered property.
Block Comments: Comments on a line of their own and not indented are added to the description of the next properties until an empty line and the block comment has been used.
# SPDX-FileCopyrightText: Copyright DB InfraGO AG
# SPDX-License-Identifier: Apache-2.0
# SampleClass.msg
# The first comment block at the top of the file
# is added to the class description of SampleClass.
# This block comment is added to the
# property description of sample_field1.
# This block comment is also added to the
# property description of sample_field1.
uint8[<=10] sample_field1
# This block comment is added to the property
# descriptions of sample_field2 and sample_field3.
package2/SampleClassEnum[] sample_field2
uint8[3] sample_field3
# This block comment is added to the property
# descriptions of sample_field4 and sample_field5.
uint8 sample_field4 # Fields in SampleClass can reference
# enums in other files.
# The property sample_field4
# is of type SampleEnum.
# cf. SampleEnum
uint8 sample_field5 # This inline comment
# is added to the
# property description of
# sample_field5.
# The property sample_field5
# is of type SampleEnumValue.
# cf. SampleEnum, SAMPLE_ENUM_VALUE_XXX
Enum definition¶
A .msg file can contain multiple enum definitions.
Enum names are determined based on the common prefix of all enum literals in the enum definition.
If no common prefix exists, the enum name is derived from the file name (excluding the extension).
Two or more enums must not have literal names without a common prefix.
Inline Comments: Comments on the same line as an enum literal definition are directly added to the that enum literal’s description.
Indented Comment Lines: Comments on a line of their own but indented are added to the description of the last encountered enum literal.
Block Comments: Comments on a line of their own and not indented are added to the description of the next enum definition or the next enum literal definitions until an empty line and the block comment has been used.
# SPDX-FileCopyrightText: Copyright DB InfraGO AG
# SPDX-License-Identifier: Apache-2.0
# SampleEnum.msg
# This block comment is added to the
# enum description of SampleEnumValue.
uint8 SAMPLE_ENUM_VALUE_RED = 0
uint8 SAMPLE_ENUM_VALUE_BLUE = 1 # This inline comment
# is added to the
# enum literal
# description of BLUE.
# This block comment is added to the
# enum literal descriptions of YELLOW and GREEN.
uint8 SAMPLE_ENUM_VALUE_YELLOW = 2
uint8 SAMPLE_ENUM_VALUE_GREEN = 3
# This block comment is added to the
# enum description of SampleEnum.
# In a file, there can only be one or no enum
# whose literal names do not share a common prefix.
uint8 OK = 0
uint8 WARN = 1
uint8 ERROR = 2
uint8 STALE = 3
Enum and Class Definition¶
A .msg file can contain one class definition and multiple enum definitions.
Enums without a common literal name prefix are named using the file name plus the suffix “Type”.
There can only be one or no enum whose literal names do not share a common prefix.
Comments at the top of the file are added to the class description.
Inline Comments: Comments on the same line as a property or enum literal are directly added to the description of that element.
Indented Comment Lines: Comments on a line of their own but indented are added to the description of the last encountered property or enum literal.
Block Comments: Comments on a line of their own and not indented are added to the descriptions of the next properties, enum or enum literal until an empty line and the block comment has been used.
# SampleClassEnum.msg
# Properties in SampleClassEnum can reference
# enums in the same file.
# This block comment is added to the
# enum description of SampleClassEnumType.
byte OK = 0
byte WARN = 1
byte ERROR = 2
byte STALE = 3
# This block comment is added to the
# enum description of Color.
byte COLOR_RED = 0
byte COLOR_BLUE = 1
byte COLOR_YELLOW = 2
uint8 field1 # This inline comment is added to
# the description of field1.
uint8 field2
Referencing enums¶
In the Same File¶
In files that define a class along with enums, the class properties can reference enums defined in the same file. This can be achieved in two ways:
Name Match: The property name matches the enum name.
Type Match: The property type matches the enum literals type, in which case the updated enum name is derived from the file name plus the property name.
Name matching takes precedence over type matching.
# SPDX-FileCopyrightText: Copyright DB InfraGO AG
# SPDX-License-Identifier: Apache-2.0
# SampleClassEnum.msg
# Properties in SampleClassEnum can reference
# enums in the same file.
# This block comment is added to the
# enum description of SampleClassEnumStatus.
uint8 OK = 0
uint8 WARN = 1
uint8 ERROR = 2
uint8 STALE = 3
# This block comment is added to the
# enum description of Color.
uint8 COLOR_RED = 0
uint8 COLOR_BLUE = 1
uint8 COLOR_YELLOW = 2
uint8 status # The property status is of type
# SampleClassEnumStatus.
uint8 color # The property color is of type Color.
uint8 field
In another file¶
If a property definition references an enum in the comments, the property type is updated based on this reference.
The reference should follow either of the following formats:
cf. <File Name>: The enum name was derived from the file name (excluding the extension).
cf. <File Name>, <Common Prefix>_XXX: The enum name was derived from the longest common prefix of all enum literals in the definition.
# SPDX-FileCopyrightText: Copyright DB InfraGO AG
# SPDX-License-Identifier: Apache-2.0
# SampleClass.msg
# The first comment block at the top of the file
# is added to the class description of SampleClass.
# This block comment is added to the
# property description of sample_field1.
# This block comment is also added to the
# property description of sample_field1.
uint8[<=10] sample_field1
# This block comment is added to the property
# descriptions of sample_field2 and sample_field3.
package2/SampleClassEnum[] sample_field2
uint8[3] sample_field3
# This block comment is added to the property
# descriptions of sample_field4 and sample_field5.
uint8 sample_field4 # Fields in SampleClass can reference
# enums in other files.
# The property sample_field4
# is of type SampleEnum.
# cf. SampleEnum
uint8 sample_field5 # This inline comment
# is added to the
# property description of
# sample_field5.
# The property sample_field5
# is of type SampleEnumValue.
# cf. SampleEnum, SAMPLE_ENUM_VALUE_XXX