Skip to content

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
  • Don't prefix the units:
    • Bad: float32 kmph_velocity_vehicle
    • Good: float32 velocity_vehicle_kmph
  • Use recommended suffixes if they are available in the table:
    • Bad: float32 velocity_vehicle_km_h
    • Good: float32 velocity_vehicle_kmph