ROS Custom Message Support

Custom Message Overview

Custom messages are user-defined messages that you can use to extend the set of message types currently supported in ROS Toolbox. If you are sending and receiving supported message types, you do not need to use custom messages. To see a list of supported message types, call rosmsg list in the MATLAB^® Command Window.

Custom message creation requires ROS packages, which are detailed in the ROS Wiki at Packages. After ensuring that you have valid ROS packages for custom messages, call rosgenmsg with the file path to the location containing the custom message package folders to generate the necessary MATLAB code to use custom messages. For an example on how to generate a ROS custom message in MATLAB, see Create Custom Messages from ROS Package.

If this is your first time using ROS custom messages, check ROS Toolbox System Requirements.

Custom Message Contents

ROS custom messages are specified in ROS package folders that contains msg, srv, and action directories.

Note

ROS Toolbox supports the existence of multiple custom messages folders on the MATLAB path at any given time. These folders can contain multiple custom message packages.

The custom message libraries generated for ROS are user-created files that integrate into the internal ROS workflow. To safeguard these files from unauthorized access and maintain system integrity, set appropriate directory permissions to restrict access to only intended user accounts.

The msg folder contains all your custom message type definitions. You should also add all custom service type definitions to the srv folder and add all custom action type definitions to the action folder. For example, the package custom_robot_msgs has this folder and file structure.

The package contains one custom message type in RobotTopic.msg and one custom service type in RobotService.srv, and one custom action type in RobotAction.action. MATLAB uses these files to generate the necessary files for using the custom messages contained in the package. For more information on creating msg and srv files, see Creating a ROS msg and srv and Defining Custom Messages on the ROS Wiki. The syntax of these files is described on the pages specific to msg and srv. For more information about ROS actions, see ROS Actions Overview.

Note

You must have write access to the custom messages folder.

Property Naming From Message Fields

When ROS message definitions are converted to MATLAB, the field names are converted to properties for the message object. Object properties always begin with a capital letter and do not contain underscores. The field names are modified to fit this naming convention. The first letter and the first letter after underscores are capitalized with underscores removed. For example, the sensor_msgs/Image message has these fields in ROS:

header
height
width
encoding
is_bigendian
step
data

The converted MATLAB properties are:

Header
Height
Width
Encoding
IsBigendian
Step
Data

This is also reflected when using ROS messages in Simulink^®. ROS message buses use the same properties names as MATLAB.

Custom Message Creation Workflow

Once you have your custom message structure set up as described in the previous section, you can create the code needed to use these custom messages. First, you call rosgenmsg with your known path to the custom message files to create MATLAB code.

The rosgenmsg function takes your custom message files (.msg, .srv, and .action) and converts each message type to working MATLAB code. The rosgenmsg function looks for .msg files in the msg folder, for .srv files in the srv folder, and for .action files in the action folder. This code is a group of classes that define the message properties when you create new custom messages. The function then creates the required MATLAB M-files for the different message classes.

After the rosgenmsg function creates these files, you must add the class files to the MATLAB path. These steps are given as prompts in the MATLAB Command Window.

1. Add location of class files to MATLAB path: Use addpath to add new locations of files with the .m extension to the MATLAB path and use savepath to save these changes.

2. Refresh all message class definitions, which requires clearing the workspace:

   clear classes
   rehash toolboxcache

3. Verify messages are available: Use rosmsg list or the rosmessage function to check that the new custom messages are available.

For an example of this procedure, see Create Custom Messages from ROS Package. This example uses sample custom message files to create custom messages in MATLAB.

You need to complete this procedure only once for a specific set of custom messages. After that, you can use the new custom messages like any other ROS message in MATLAB and take advantage of the full ROS functionality that ROS Toolbox provides. Repeat this generation procedure when you would like to update or create new message types.

You must maintain the MATLAB path that contain the files directories.

Code Generation with Custom messages

Custom message, service, and action types can be used with ROS Simulink blocks and MATLAB functions to generate C++ code for a standalone ROS node. The generated code (.tgz archive) will include the custom message definitions and the ROS custom message packages. When the generated code is built in the destination Linux System, the custom message packages are hence automatically available in the catkin workspace.

If you change the custom message definitions in MATLAB for your application, you must delete the custom message package on the destination Linux System, regenerate the C++ code, and redeploy it.

Replacing Definitions of Built-In Messages With Custom Definitions

MATLAB provides a lot of built-in ROS message types. You can replace the definitions of those message types with new definitions using the same custom message creation workflow detailed above. When you are replacing the definitions of a built-in message package, you must ensure that the custom message package folder contains new definitions (.msg files) for all the message types in the corresponding built-in message package.