Annotating ROS enum fields

Annotate enum fields in your ROS message definitions to optimize visualizations inside Studio.

Since ROS messages do not have built-in support for enums, we've implemented a way for Studio to read annotated message definitions and display enum values (e.g. in the Plot, Raw Messages, and State Transitions panels) in a meaningful way.

Before annotating

Previously, Studio could only display the value for an enum field if that field provided its own enum mapping.

For example, let's consider the following message definitions:

// color_msgs/PrimaryColors
uint8 RED=1
uint8 YELLOW=2
uint8 BLUE=3

uint8 data

// my_msgs/MySettings
color_msgs/PrimaryColors my_color

The my_color field in a my_msgs/MySettings message would be interpreted as an enum of datatype color_msgs/PrimaryColors.

If Studio were to receive a my_msgs/MySettings message with my_color: 2, it would correctly display it as my_color: YELLOW.

After annotating

To annotate an enum field, convert it to a simple uint8 and add a comment (formatted as [enumDatatype] [enumField]__foxglove_enum) on the line before the field definition:

// my_msgs/MySettings
color_msgs/PrimaryColors my_color__foxglove_enum
uint8 my_color

You can now remove the unnecessary data field in color_msgs/PrimaryColors:

uint8 RED=1
uint8 YELLOW=2
uint8 BLUE=3

You can now access the enum value directly with mySettingsMsg.my_color, instead of mySettingsMsg.my_color.data. Studio will still correctly display a my_msgs/MySettings message with my_color: 2 as my_color: YELLOW.

This annotation will not add any bytes to the serialized ROS message, but it will add the necessary information (i.e. the constant values for RED, YELLOW, and BLUE) to the connection header.

Note: Studio can interpret multiple enum fields in the same message. Consider the message definitions below:

// color_msgs/PrimaryColors
uint8 RED=1
uint8 YELLOW=2
uint8 BLUE=3

// color_msgs/SecondaryColors
uint8 ORANGE=1
uint8 GREEN=2
uint8 PURPLE=3

// my_msgs/MySettings
color_msgs/PrimaryColors my_primary_color__foxglove_enum
uint8 my_primary_color
color_msgs/SecondaryColors my_secondary_color__foxglove_enum
uint8 my_secondary_color

For my_msgs/MySettings messages, Studio will display my_primary_color as RED, YELLOW, or BLUE, and my_secondary_color as ORANGE, GREEN, or PURPLE –  even though both fields contain 1, 2, and 3 as possible enum values.