Message guidelines#
Format#
All messages should follow ROS message description specification.
The accepted formats are:
.msg
.srv
.action
Naming#
Under Construction
Use Array
as a suffix when creating a plural type of a message. This suffix is commonly used in common_interfaces.
Default units#
All the fields by default have the following units depending on their types:
type | default unit |
---|---|
distance | meter (m) |
angle | radians (rad) |
time | second (s) |
speed | m/s |
velocity | m/s |
acceleration | m/s² |
angular vel. | rad/s |
angular accel. | rad/s² |
If a field in a message has any of these default units, don't add any suffix or prefix denoting the type.
Non-default units#
For non-default units, use following suffixes:
type | non-default unit | suffix |
---|---|---|
distance | nanometer | _nm |
distance | micrometer | _um |
distance | millimeter | _mm |
distance | kilometer | _km |
angle | degree (deg) | _deg |
time | nanosecond | _ns |
time | microsecond | _us |
time | millisecond | _ms |
time | minute | _min |
time | hour (h) | _hour |
velocity | km/h | _kmph |
If a unit that you'd like to use doesn't exist here, create an issue/PR to add it to this list.
Message field types#
For list of types supported by the ROS interfaces see here.
Also copied here for convenience:
Message Field Type | C++ equivalent |
---|---|
bool |
bool |
byte |
uint8_t |
char |
char |
float32 |
float |
float64 |
double |
int8 |
int8_t |
uint8 |
uint8_t |
int16 |
int16_t |
uint16 |
uint16_t |
int32 |
int32_t |
uint32 |
uint32_t |
int64 |
int64_t |
uint64 |
uint64_t |
string |
std::string |
wstring |
std::u16string |
Arrays#
For arrays, use unbounded dynamic array
type.
Example:
int32[] unbounded_integer_array
Enumerations#
ROS 2 interfaces don't support enumerations directly.
It is possible to define integers constants and assign them to a non-constant integer parameter.
Constants are written in CONSTANT_CASE
.
Assign a different value to each element of a constant.
Example from shape_msgs/msg/SolidPrimitive.msg
uint8 BOX=1
uint8 SPHERE=2
uint8 CYLINDER=3
uint8 CONE=4
uint8 PRISM=5
# The type of the shape
uint8 type
Comments#
On top of the message, briefly explain what the message contains and/or what it is used for. For an example, see sensor_msgs/msg/Imu.msg.
If necessary, add line comments before the fields that explain the context and/or meaning.
For simple fields like x, y, z, w
you might not need to add comments.
Even though it is not strictly checked, try not to pass 100 characters in a line.
Example:
# Number of times the vehicle performed an emergency brake
uint32 count_emergency_brake
# Seconds passed since the last emergency brake
uint64 duration
Example usages#
- Don't use unit suffixes for default types:
- Bad:
float32 path_length_m
- Good:
float32 path_length
- Bad:
- Don't prefix the units:
- Bad:
float32 kmph_velocity_vehicle
- Good:
float32 velocity_vehicle_kmph
- Bad:
- Use recommended suffixes if they are available in the table:
- Bad:
float32 velocity_vehicle_km_h
- Good:
float32 velocity_vehicle_kmph
- Bad: